README.md

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
  • For Node environment
    • Install from npm registry
    • Install from Github Packages registry
  • For Browser environment(CDN based)
    • Include in html page from CDN
• Set up
  • For Node environment
  • For Browser environment(CDN based)
  • For diff as Global Date Object method
• Create an instance
  • For Node environment
  • For Browser environment(CDN based)
  • For diff as Global Date Object method
• Usages
  • For Node environment
  • For Browser environment(CDN based)
  • For diff as Global Date Object method
• API References
• API Documentation
• Contributing
• Best Practices
• License
• History

Installation

For Node environment:

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

For Browser environment(CDN based):

Include in html page from CDN

for version 2.2.1 and above

Can include in page using script tag from CDN

    <script src="https://cdn.jsdelivr.net/npm/diff-ymd-package@3.1.4/lib/index.min.js"></script>

Get any supported version script tag

Initialize

For Node environment:

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

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

For Browser environment(CDN based):

for version 2.2.1 and above

Can include in html page using script tag from CDN

    <script src="https://cdn.jsdelivr.net/npm/diff-ymd-package@3.1.4/lib/index.min.js"></script>

For diff as Global Date Object method in NODE/Browser(CDN based):

for version 3.1.0 and above

Can use simplified function diff as Global Date Object method

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

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

Create an instance

For Node environment:

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); 

For Browser environment(CDN based):

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); 

Note: For CDN based, only DatesYMD constructor name creates an instance, and can use diffDates as well, but only using global DatesYMD like DatesYMD.diffDates(...)

See an example of using CDN based

For diff as Global Date Object method in NODE/Browser(CDN based):

for version 3.1.0 and above

Can use simplified function diff as Global Date Object method

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

const DateInstance = new Date(date1); // create Global Date instance

const Formatter = DateInstance.diff(date2); //create an instance to `calculates the difference` between `Date instance` and the `date passed to it`

Note: For diff as Global Date method, only one date(the date to be subtracted from/to Global Date instance) passed to diff method

diff method create an instance of DatesYMD to calculates the difference between Date instance and the date passed to it

Usages for NODE/Browser(CDN based)/Date Object

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

Get Built in codes for using diff-ymd-package any Method on created instance(Formatter)

Get Built in codes here

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
    • OR for version 3.1.x and above, Can use simplified function diff as Global Date Object method
    • 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

OR for version 3.1.x and above

Can use simplified function diff as Global Date Object method

const DateInstance = new Date(firstDate); // create Global Date instance

const Formatter = DateInstance.diff(secondDate); //create an instance to `calculates the difference` between `Date instance` and the `date passed to it`

• 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, but not when passed to Global Date as firstDate above in Global Date; for creating current date Date instance using Date, just call empty like new Date()

• 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