datetime-fcs/README.md

A library to format dates, track countdowns, and calculate durations.

# DateTime FCS

A lightweight JavaScript library for formatting dates, tracking countdowns, and calculating durations between two dates. This package is designed to work seamlessly with frontend JavaScript frameworks like **ReactJS**, **React Native**, **NextJS**, and **Vue.js**.

## Features

- **Countdown Timer**: Tracks the remaining time until a specified target date and time.
- **Date Formatting**: Formats a given date into a specified format (e.g., "YYYY-MM-DD HH:mm:ss").
- **Duration Calculation**: Calculates the duration between two dates in hours, minutes, and seconds.

## Installation

You can install the `datetime-fcs` library via **npm** or **GitHub**.

### npm

To install the library from npm:

```bash
npm install datetime-fcs
```

## GitHub

    To install the library directly from GitHub:

```
npm install github:zaynmiraj/datetime-fcs
```

## Usage

    Once installed, you can import the functions into your project and start using them. Below are the three primary functions included in the library.

1. Countdown Timer
   The countdown function tracks the time remaining until a target date.

```
import { countdown } from 'datetime-fcs';

// Example: Countdown to New Year's Eve
const countdownToNewYear = countdown('2026-01-01T00:00:00Z');
console.log(countdownToNewYear); // Output: 'X hours, Y minutes, Z seconds remaining'
```

## Date Formatting

The formatDate function formats a given date into a specific format.

```import { formatDate } from 'datetime-fcs';

// Example: Format a date string to 'YYYY-MM-DD HH:mm:ss'
const formattedDate = formatDate('2025-07-16T12:00:00Z', 'yyyy-MM-dd HH:mm:ss');
console.log(formattedDate); // Output: '2025-07-16 12:00:00'
```

## Duration Calculation

The durationBetweenDates function calculates the duration between two dates.

```
import { durationBetweenDates } from 'datetime-fcs';

// Example: Duration between two dates
const duration = durationBetweenDates('2025-07-16T12:00:00Z', '2025-07-17T12:00:00Z');
console.log(duration); // Output: '24 hours, 0 minutes, 0 seconds'
```

## Examples in Frontend Frameworks

ReactJS Example
Here’s an example of how to use the datetime-fcs library in a ReactJS project:

```
import React, { useState, useEffect } from 'react';
import { countdown, formatDate, durationBetweenDates } from 'datetime-fcs';

const App = () => {
  const [countdownTime, setCountdownTime] = useState('');
  const [formattedDate, setFormattedDate] = useState('');
  const [duration, setDuration] = useState('');

  useEffect(() => {
    // Example: Countdown to New Year's Eve
    const countdownToNewYear = countdown('2026-01-01T00:00:00Z');
    setCountdownTime(countdownToNewYear);

    // Example: Format Date
    const formatted = formatDate('2025-07-16T12:00:00Z', 'yyyy-MM-dd HH:mm:ss');
    setFormattedDate(formatted);

    // Example: Calculate Duration
    const durationResult = durationBetweenDates('2025-07-16T12:00:00Z', '2025-07-17T12:00:00Z');
    setDuration(durationResult);
  }, []);

  return (
    <div>
      <h1>Countdown to New Year</h1>
      <p>{countdownTime}</p>

      <h2>Formatted Date</h2>
      <p>{formattedDate}</p>

      <h2>Duration between Dates</h2>
      <p>{duration}</p>
    </div>
  );
};

export default App;
```

## Vue.js Example

Here’s how you can use the library in a Vue.js project:

```
<template>
  <div>
    <h1>Countdown to New Year</h1>
    <p>{{ countdownTime }}</p>

    <h2>Formatted Date</h2>
    <p>{{ formattedDate }}</p>

    <h2>Duration between Dates</h2>
    <p>{{ duration }}</p>
  </div>
</template>

<script>
import { countdown, formatDate, durationBetweenDates } from 'datetime-fcs';

export default {
  data() {
    return {
      countdownTime: '',
      formattedDate: '',
      duration: ''
    };
  },
  mounted() {
    // Example: Countdown to New Year's Eve
    this.countdownTime = countdown('2026-01-01T00:00:00Z');

    // Example: Format Date
    this.formattedDate = formatDate('2025-07-16T12:00:00Z', 'yyyy-MM-dd HH:mm:ss');

    // Example: Calculate Duration
    this.duration = durationBetweenDates('2025-07-16T12:00:00Z', '2025-07-17T12:00:00Z');
  }
};
</script>
```

## API Reference

countdown(endTime)

- Parameters: endTime (string) - The target date in ISO 8601 format.

- Returns: A string showing the countdown in hours, minutes, and seconds.

## formatDate(date, formatString)

- Parameters:

  date (string) - The date to format in ISO 8601 format.

  formatString (string) - The format string (e.g., "yyyy-MM-dd HH:mm:ss").

- Returns: A string with the formatted date.

## durationBetweenDates(startDate, endDate)

- Parameters:

  startDate (string) - The start date in ISO 8601 format.

  endDate (string) - The end date in ISO 8601 format.

- Returns: A string with the duration between the two dates in hours, minutes, and seconds.

## durationBetweenDates(startDate, endDate)

- Parameters:

  startDate (string) - The start date in ISO 8601 format.

  endDate (string) - The end date in ISO 8601 format.

- Returns: A string with the duration between the two dates in hours, minutes, and seconds.

## Contributing

    We welcome contributions to improve the library! If you have an idea for a new feature, bug fix, or improvement, please follow these steps:

    Fork the repository.

    Create a new branch (git checkout -b feature/your-feature).

    Make your changes and commit them (git commit -am 'Add new feature').

    Push to the branch (git push origin feature/your-feature).

    Create a pull request.

## License

## MIT License

    Copyright (c) 2025
    Permission is hereby granted, free of charge, to any person obtaining a copy