diff-ymd-package

diff-ymd-package

diff-ymd-package a javascript library provides APIs to difference dates in formatted ways(like (aYears bMonths cDays) or (aY bM cD) etc., eg. age = 20Y 2M 23D or datesDifference = 2Years 11Months 20Days) or customized desired formats like aY-bM-cD or aYears-bMonths-cDays or kDays or mWeeks or nMonths etc.

Installation

Install from npm registry

npm install diff-ymd-package

Install from Github Packages registry

npm install @farhan7reza7/diff-ymd-package

Usages

Initialize

//const DatesYMD = require('@farhan7reza7/diff-ymd-package'); or

const DatesYMD = require('diff-ymd-package'); // can use any

Create an instance

const date1 = '2022-01-01';
const date2 = '2023-12-31';

const Formatter = new DatesYMD(date1, date2);

OR for version 2.x.x and above

Can use simplified function diffDates on module-object(DatesYMD here)

const date1 = '2022-01-01';
const date2 = '2023-12-31';

const Formatter = DatesYMD.diffDates(date1, date2); // can use any

Use methods to format difference

// format output in aY bM cD format
const result = Formatter.formattedYMD(); // Output: "1Y 11M 30D"

// create format of your choice
const customizedFormat = Formatter.customizeFormat('Y', 'Ms', 'Ds', '-'); // Output: "1Y-11Ms-30Ds"

// return an array having years, months, days, and the formatted difference
const resultArray = Formatter.diffArray(); // Output: [1, 11, 30, '1Y 11M 30D']

// Calculate the difference in months
const monthsDifference = Formatter.diffInMonths(); // Output: 23

// Calculate the difference in weeks
const weeksDifference = Formatter.diffInWeeks(); // Output: 164

// Calculate the difference in days
const daysDifference = Formatter.diffInDays(); // Output: 1143

// Calculate the difference in years
const yearsDifference = Formatter.diffInYears(); // Output: 1

// Calculate the difference in hours
const hoursDifference = Formatter.diffInHours(); // Output: 27432

// Calculate the difference in minutes
const minutesDifference = Formatter.diffInMinutes(); // Output: 1645920

// Calculate the difference in seconds
const secondsDifference = Formatter.diffInSeconds(); // Output: 98755200

Formatted Outputs

console.log(result); // Output: "1Y 11M 30D"
// formatted output in aY bM cD format

console.log(customizedFormat); // Output: "1Y-11Ms-30Ds"
// you can use this method for creating format of your choice

console.log(resultArray); // Output: [1, 11, 30, '1Y 11M 30D']
/* you can access each of Y, M, D separately from output array and can format as per your choice like aY-bM-cD or aYears-bMonths-cDays etc.*/

/*example: 
let Y, M, D;

Y = resultArray[0];
M = resultArray[1];
D = resultArray[2];

const customFormat = Y + 'year ' + M + 'months ' + D + 'days';
console.log(customFormat); // output: 1year 11months 30days
*/

console.log(monthsDifference); // Output: 23
// Calculate the difference in months

console.log(weeksDifference); // Output: 164
// Calculate the difference in weeks

console.log(daysDifference); // Output: 1143
// Calculate the difference in days

console.log(yearsDifference); // Output: 1
// Calculate the difference in years

console.log(hoursDifference); // Output: 27432
// Calculate the difference in hours

console.log(minutesDifference); // Output: 1645920
// Calculate the difference in minutes

console.log(secondsDifference); // Output: 98755200
// Calculate the difference in seconds

API Documentation

DatesYMD

Represents a utility class for calculating the formatted and desired customized difference between two dates in all cases.

Create an instance of DatesYMD:

const Formatter = new DatesYMD(firstDate, secondDate);

OR for version 2.x.x and above

Can use simplified function diffDates on module-object

//const DatesYMD = require('@farhan7reza7/diff-ymd-package'); or
const DatesYMD = require('diff-ymd-package');

const Formatter = DatesYMD.diffDates(firstDate, secondDate); // can use any

• firstDate: The first date in the format 'yyyy-mm-dd' or 'yyyy/mm/dd' or 'yyyy.mm.dd' or dateString or dateObject or Timestamp(epoch).

• secondDate: The second date in the format 'yyyy-mm-dd' or 'yyyy/mm/dd' or 'yyyy.mm.dd' or dateString or dateObject or Timestamp(epoch).

• Special case: empty string("" or '') is by default to current-date(today) for the parameters

• Returns: An instance of DatesYMD class.

Methods:

diffArray()

Calculates the difference between two dates and returns an array containing Y(years), M(months), D(days), and a formatted 'aY bM cD' difference string.

const result = Formatter.diffArray();

• Returns: An array containing the calculated years, months, days, and the formatted difference.

formattedYMD()

Returns the formatted difference between two dates in aY bM cD(aYears bMonths cDays) format.

const result = Formatter.formattedYMD();

• Returns: A string in the format 'aY bM cD'.

customizeFormat(yearUnit, monthUnit, dayUnit, partSeparator)

Customizes the difference using specified units and separators

const result = Formatter.customizeFormat(
  yearUnit,
  monthUnit,
  dayUnit,
  partSeparator,
);

• Returns: A customized formatted difference string of form (a + yearUnit + partSeparator + b + monthUnit + partSeparator + c + dayUnit), eg. aYs-bMs-cDs etc.

diffInMonths()

Calculates the difference in months between two dates.

const monthsDifference = Formatter.diffInMonths();

• Returns: The difference in months.

diffInWeeks()

Calculates the difference in weeks between two dates.

const weeksDifference = Formatter.diffInWeeks();

• Returns: The difference in weeks.

diffInDays()

Calculates the difference in days between two dates.

const daysDifference = Formatter.diffInDays();

• Returns: The difference in days.

diffInYears()

Calculates the difference in years between two dates.

const yearsDifference = Formatter.diffInYears();

• Returns: The difference in years.

diffInHours()

Calculates the difference in hours between two dates.

const hoursDifference = Formatter.diffInHours();

• Returns: The difference in hours.

diffInMinutes()

Calculates the difference in minutes between two dates.

const minutesDifference = Formatter.diffInMinutes();

• Returns: The difference in minutes.

diffInSeconds()

Calculates the difference in seconds between two dates.

const secondsDifference = Formatter.diffInSeconds();

• Returns: The difference in seconds.

For more informations, See diff-ymd-package documentation

Contributing

If you find any issues or have suggestions for improvement, please open an issue or create a pull request on the GitHub repository.

See CONTRIBUTING.md for more informations.

Best Practices:

The code adheres to recommended practices for readability and maintainability, including:

• Meaningful variable and function names for clarity.
• Clear and concise comments to enhance understanding.
• Proper indentation and formatting for visual organization.

License

This project is licensed under the MIT License - see the LICENSE file for details.

See License

History

For more details about what has changed in each version of this project.
See CHANGELOG.md.

Changelog

[v2.0.0] - [2024-01-24]

Added

• Simplification: Updated the DatesYMD class to accept dateString, epoch, and dateObject as well along with string as parameters.
• Added the method diffInMonths to calculate the difference in months between two dates.
• Added the method diffInWeeks to calculate the difference in weeks between two dates.
• Added the method diffInDays to calculate the difference in days between two dates.
• Added the method diffInYears to calculate the difference in years between two dates.
• Added the method diffInHours to calculate the difference in hours between two dates.
• Added the method diffInMinutes to calculate the difference in minutes between two dates.
• Added the method diffInSeconds to calculate the difference in seconds between two dates.
• Updated Unit tests: Included comprehensive Jest tests for the newly added methods.
• Updated the README.md documentation to include the new methods.

Changed

• Improved algorithm efficiency: Enhanced performance for existing methods to provide faster calculations.
• Modified internal structure: Refactored internal code for better readability and maintainability.

Fixed

• Fixed some issues related to the new changes.
• Configured files for publishing diff-ymd-package v2.0.0 on npm registry.

Documentation

• README.md updated: Added examples and use cases and api documentation for the new methods.
• Enhanced code comments: Provided thorough inline documentation for better codes understanding.

Testing

• Increased test coverage: Expanded Jest test suite to cover all scenarios, ensuring robust functionality.
• Continuous Integration: Integrated automated testing with GitHub Actions for ongoing code quality assurance.