Date-fran NPM | npm.io

Date and time functionalities for JavaScript projects (TypeScript enabled).

Use the date-fran module like so:

**initialise whichever function you'd need.**
import { 
    tomorrowsDate,
    yesterdaysDate, 
    givenDateAndCurrentTime,
    dateAcronym,
    todaysDate,
    differenceInDays,
    dateForwardBuild,
    dateConstrainer,
    sameDateComparator,
    varyingDatesComparator,
    tomorrowsDateByGivenDate, 
    yesterdaysDateByGivenDate,
    yesterdaysFormDate,
    tomorrowsFormDate,
    todaysFormDate
} from "date-fran";

This project was borne out of the need or necessity of eliminating discrepancies with time data on mongo-database. You must have observed that saving the normal "new Date()" value on mongo-database, would return date data inconsistent with what is actually expected.

Hence, with this module, we can put-off those inaccuracies and enhance manuevrability with time data, by making comparisons, getting future date values, all of which are consistent with the classical operations expected on a JavaScript date data.

Examples:

The tomorrowsDate function, gives tomorrows date

The yesterdaysDate function, gives yesterdays date

The givenDateAndCurrentTime function gives todays date and current time, when the optional parametre isn't provided. If provided (in the form: YYYY-MM-DD or YYYY/MM/DD or as JS's date object), it returns the appropriate date-data (date and time) representation of the provided string-date.

The sameDateComparator function checks if both given dates supplied, are equal and returns true if they are; otherwise, false. Arguments can be of the form "YYYY-MM-DD", "YYYY/MM/DD" or "Sun Sep 11 2022" (when you apply JS's toDateString() attribute to a date variable.).

Whenever possible, always use the sameDateComparator like so:

const datesAreSame = sameDateComparator(firstDate.toDateString(), secondDate.toDateString())

The varyingDatesComparator function checks if the second(future date) being supplied, is greater than the first(previous date) and returns true if they are; otherwise, false.

A more complex usage follows thus:

1. Get all hotel reservations for yesterday:

const yesterdaysReservations = hotelReservations.filter(reservations => reservations.dateCreated.toLocaleDateString() === yesterdaysDate().toLocaleDateString());

2. Get all hotel arrivals for tomorrow:

const tomorrowsArrival = hotelReservations.filter(reservations => reservations.dateCreated.toLocaleDateString() === tomorrowsDate().toLocaleDateString());

3. if an individuals arrival date as gotten from an html-form is stated as: 2022-09-04 or 2022/09/04 N.B: format remains year -> month -> day as JS standard

const requiredDate = givenDateAndCurrentTime("2022-09-04") 
returned date ====> 2022-09-04T07:12:46.000Z

for database models: 
await Users.create({
    ...,
    dateCreated: givenDateAndCurrentTime() 
})
// This surpreses mongodb's use of the ususal "00:00:00" time and discrepancies of date, 
if the creation was made at 12 am and rather use the correct date and time

4. The dateForwardBuild and differenceInDays function are useful as follows;

const arrivalDate = givenDateAndCurrentTime("2022-08-24")
const departureDate = givenDateAndCurrentTime("2022-09-14")
const stayPeriodOfGuest = differenceInDays(arrivalDate, departureDate)
let count = 1;
while(count <= stayPeriodOfGuest){
    const billingDate = dateForwardBuild(arrivalDate.getFullYear(), arrivalDate.getMonth(), count);
    const billDetails = roomBilling(billingDate) // a helper function for your application
    count++
}
* A simple way of understanding the function is by saying; give me the date of n days from now.

5. The dateConstrainer function is applicable to html forms as below. If you want the maximum and minimum choosable date on a form to be 2022-08-30 and 2022-08-24 respectively, (in React, for instance), you'd say;

const permissibleMinWelcomeDate = givenDateAndCurrentTime("2022-08-24")
const permissibleMaxWelcomeDate = givenDateAndCurrentTime("2022-08-30")

const maxDate = dateConstrainer(permissibleMaxWelcomeDate as Date);
const minDate = dateConstrainer(permissibleMinWelcomeDate as Date);

useEffect(() => {
    (document as any).querySelector(".arrival-date").max = maxDate;
    (document as any).querySelector(".arrival-date").min = minDate;
}, []);

It can as well be used to constrain date-data fields on MongoDB, to accept dates which fall within the
permissible defined max and min dates.

6 The yesterdaysFormDate tomorrowsFormDate and todaysFormDate functions, are specifically compatable for forms; and can be used thus:

ReactJS:
useEffect(() => {
    (document as any).querySelector(".arrival-date").min = yesterdaysFormDate;
    (document as any).querySelector(".arrival-date").max = todaysFormDate();
}, []);

Vanilla JS:
(document as any).querySelector(".arrival-date").max = todaysFormDate();
(document as any).querySelector(".arrival-date").min = yesterdaysFormDate;

ReactJS:
useEffect(() => {
    (document as any).querySelector(".arrival-date").max = tomorrowsFormDate();
    (document as any).querySelector(".arrival-date").min = yesterdaysFormDate();
}, []);

Vanilla JS:
(document as any).querySelector(".arrival-date").max = tomorrowsFormDate();
(document as any).querySelector(".arrival-date").min = yesterdaysFormDate();

7. You could use the sameDateComparator function, to check if a routine has been performed already; in order to allow or constrain, if the routine hasn't been performed.

e.g if a routine exists that should bill guests a certain amount daily, you could say; const guestHasBeenBilledForToday = sameDateComparator(guestBill.dateCreated.toDateString(), todaysDate().toDateString()) if(!guestHasBeenBilledForToday){ billguestForToday() // your routine }

8. The dateAcronym function is used like so:

const jsDate = new Date()
const preferredFormat = `${givenDateAndCurrentTime().getDate()}`.concat(dateAcronym(todaysDate().getDate())," ", monthAndIndex[jsDate.getMonth()], " ", `${jsDate.getFullYear()}`) 
// gives the date in the format: 11th Oct 2022 (for instance, with the appropriate acronym)

9. The tomorrowsDateByGivenDate function is used thus; say you'd like to calculate taxes payable, for the next thirty days and as well, append the dates for those days, you'd do thus:

let dayCount = 1;
const maxDaycount = 30;
let currentDate = yesterdaysDate() // if we start with yesterdays date, the first record date will be todays date
while(dayCount <= maxDayCount){
    const recordDate = tomorrowsDateByGivenDate(currentDate);
    const recordPayment = payTax({
        recordDate,
        index: dayCount,
        taxRate,
        .....
    });
    currentDate = recordDate;
    dayCount++
}

// if currentDate is say: 2022-05-17, 
// record date, when consoled, would give: 2022-05-18, 2022-05-19, 2022-05-20, ... to the 30th date

10. The yesterdaysDateByGivenDate function is used thus; say you'd like to subtract an overcharge for purchases in the past twenty days and record this with the reference date, you'd do thus:

let dayCount = 1;
const maxDaycount = 20;
let currentDate = givenDateAndCurrentTime() // if we start with todays date, the first record date will be yesterdays date
while(dayCount <= maxDayCount){
    const recordDate = yesterdaysDateByGivenDate(`${currentDate.getFullYear()}-${currentDate.getMonth()+1}-${currentDate.getDate()}`);
    const recordPayment = deductOverCharge({
        recordDate,
        index: dayCount,
        .....
    });
    currentDate = recordDate;
    dayCount++
};

// if currentDate is say: 2022-05-17, 
// record date, when consoled, would give: 2022-05-16, 2022-05-15, 2022-05-14, ... to the 20th date

11 The getMonth function: Get the actual (non-JS) month of a given date format

const productionMonth = getMonth(product.dateCreated)

12 The dateCountBuilder function: allows you to build past or future dates, according to the number of dates required. The function returns an array of dates in string or date type.