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.

Table of Contents

• Installation
  • Install from npm registry
  • Install from Github Packages registry
• Usages
• API References
• API Documentation
• Contributing
• Best Practices
• License
• History

Installation

Install from npm registry(Preference)

npm install diff-ymd-package

Install from Github Packages registry(require authentication)

npm install @farhan7reza7/diff-ymd-package

Steps to install from Github Packages registry:

See steps here

Usages

Initialize:

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

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

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: 104

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

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

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

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

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

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: 104
// Calculate the difference in weeks

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

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

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

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

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

API References

diff-ymd-package

• Classes
  • DatesYMD
    • Create an instance of DatesYMD
    • OR for version 2.x.x and above, Can use simplified function diffDates on module-object
    • Methods
      • diffArray()
      • formattedYMD()
      • customizeFormat(yearUnit, monthUnit, dayUnit, partSeparator)
      • diffInMonths()
      • diffInWeeks()
      • diffInDays()
      • diffInYears()
      • diffInHours()
      • diffInMinutes()
      • diffInSeconds()

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 information:

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 guidelines for more information.

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.

See mdn guidelines for more information.

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

Changelog

[v2.2.0] - [2024-02-17]

Added

• Simplification: README.md documentation of diff-ymd-package
• Updated corrected github registry description in README.md documentation
• Updated the README.md documentation for better presentation.
• Enhanced README.md for follwing best practices

Changed

• Corrected github registry description of README.md documentation
• Enhanced README.md for follwing best practices

Fixed

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

Documentation

• README.md updated: Added correction and consistent formating and recommended for best practices.

Testing

• Continuous Integration: Integrated automated testing with GitHub Actions for ongoing code quality assurance.