chrono-utils - npm Package Compare versions

Comparing version 1.0.1 to 1.0.2

lib/convertDateToUnixTimestamp.d.ts

@@ -0,1 +1,9 @@
+/**
+ * @description Converts a regular date to (JS) Unix timestamp.
+ *
+ * @example convertDateToUnixTimestamp('2021-12-31T10:01:37Z');
+ * @example convertDateToUnixTimestamp('2022-01-10T08:42:43+00:00');
+ *
+ * @returns `1640944897000`
+ */
 export declare function convertDateToUnixTimestamp(time: Date | string): string;

lib/convertDateToUnixTimestamp.js

@@ -5,2 +5,10 @@ "use strict";
 const errors_1 = require("./errors");
+/**
+ * @description Converts a regular date to (JS) Unix timestamp.
+ *
+ * @example convertDateToUnixTimestamp('2021-12-31T10:01:37Z');
+ * @example convertDateToUnixTimestamp('2022-01-10T08:42:43+00:00');
+ *
+ * @returns `1640944897000`
+ */
 function convertDateToUnixTimestamp(time) {
@@ -7,0 +15,0 @@ if (!time)

lib/datesWithinMaximumRange.d.ts

@@ -0,1 +1,13 @@
+/**
+ * @description Checks if two date objects are within a accepted maximum day range.
+ *
+ * @example
+ * ```
+ * const startDate = new Date('2022-11-30');
+ * const endDate = new Date('2022-12-01');
+ * const response = datesWithinMaximumRange(startDate, endDate);
+ * ```
+ *
+ * @returns `true`
+ */
 export declare function datesWithinMaximumRange(startDate: Date, endDate: Date, maxDays?: number): boolean;

lib/datesWithinMaximumRange.js

@@ -6,2 +6,14 @@ "use strict";
 const errors_1 = require("./errors");
+/**
+ * @description Checks if two date objects are within a accepted maximum day range.
+ *
+ * @example
+ * ```
+ * const startDate = new Date('2022-11-30');
+ * const endDate = new Date('2022-12-01');
+ * const response = datesWithinMaximumRange(startDate, endDate);
+ * ```
+ *
+ * @returns `true`
+ */
 function datesWithinMaximumRange(startDate, endDate, maxDays = 365) {
@@ -12,2 +24,3 @@ const start = (0, zuluToUnix_1.zuluToUnix)(startDate.toISOString());
         throw new errors_1.InvalidDateOrderError();
+    // Divide by milliseconds and then by number of seconds in a day
     return Math.round((end - start) / 1000 / 86400) <= maxDays;
@@ -14,0 +27,0 @@ }

lib/errors.d.ts

@@ -0,12 +1,24 @@
+/**
+ * @description The error is fired when a start date occurs before an end date.
+ */
 export declare class InvalidDateOrderError extends Error {
     constructor();
 }
+/**
+ * @description Used when an incompatible date unit is encountered.
+ */
 export declare class InvalidDateUnitError extends Error {
     constructor();
 }
+/**
+ * @description Used when a date to be ISO-formatted is not valid.
+ */
 export declare class InvalidIsoDateConversionError extends Error {
     constructor();
 }
+/**
+ * @description Used when something is missing time.
+ */
 export declare class MissingTimeError extends Error {
     constructor();
 }

lib/errors.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MissingTimeError = exports.InvalidIsoDateConversionError = exports.InvalidDateUnitError = exports.InvalidDateOrderError = void 0;
+/**
+ * @description The error is fired when a start date occurs before an end date.
+ */
 class InvalidDateOrderError extends Error {
@@ -16,2 +19,5 @@ constructor() {
 exports.InvalidDateOrderError = InvalidDateOrderError;
+/**
+ * @description Used when an incompatible date unit is encountered.
+ */
 class InvalidDateUnitError extends Error {
@@ -29,2 +35,5 @@ constructor() {
 exports.InvalidDateUnitError = InvalidDateUnitError;
+/**
+ * @description Used when a date to be ISO-formatted is not valid.
+ */
 class InvalidIsoDateConversionError extends Error {
@@ -36,2 +45,3 @@ constructor() {
         this.message = message;
+        //@ts-ignore
         this.cause = {
@@ -43,2 +53,5 @@ statusCode: 400
 exports.InvalidIsoDateConversionError = InvalidIsoDateConversionError;
+/**
+ * @description Used when something is missing time.
+ */
 class MissingTimeError extends Error {
@@ -50,2 +63,3 @@ constructor() {
         this.message = message;
+        //@ts-ignore
         this.cause = {
@@ -52,0 +66,0 @@ statusCode: 500

lib/getCurrentDate.d.ts

@@ -0,1 +1,12 @@
+/**
+ * @description Returns the current date in `YYYY-MM-DD` format.
+ *
+ * The `noDashes` option will strip any dashes between days, months, etc.
+ *
+ * @example getCurrentDate();
+ * @example getCurrentDate(true);
+ *
+ * @returns `2022-11-20`
+ * @returns `20221120`
+ */
 export declare function getCurrentDate(noDashes?: boolean): string;

lib/getCurrentDate.js

@@ -5,2 +5,13 @@ "use strict";
 const makeTwoDigitDate_1 = require("./makeTwoDigitDate");
+/**
+ * @description Returns the current date in `YYYY-MM-DD` format.
+ *
+ * The `noDashes` option will strip any dashes between days, months, etc.
+ *
+ * @example getCurrentDate();
+ * @example getCurrentDate(true);
+ *
+ * @returns `2022-11-20`
+ * @returns `20221120`
+ */
 function getCurrentDate(noDashes = false) {
@@ -7,0 +18,0 @@ const date = new Date();

lib/getDateFromTimestamp.d.ts

@@ -0,1 +1,8 @@
+/**
+ * @description Takes a timestamp and returns the current date in `YYYYMMDD` format.
+ *
+ * @example getDateFromTimestamp("1664928000");
+ *
+ * @returns `20221005`
+ */
 export declare function getDateFromTimestamp(timestamp: string): string;

lib/getDateFromTimestamp.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDateFromTimestamp = void 0;
+/**
+ * @description Takes a timestamp and returns the current date in `YYYYMMDD` format.
+ *
+ * @example getDateFromTimestamp("1664928000");
+ *
+ * @returns `20221005`
+ */
 function getDateFromTimestamp(timestamp) {
@@ -5,0 +12,0 @@ if (timestamp.length === 10)

lib/getDateYesterday.d.ts

@@ -0,1 +1,12 @@
+/**
+ * @description Return the date of the day before today in `YYYY-MM-DD` format.
+ *
+ * The `noDashes` option will strip any dashes between days, months, etc.
+ *
+ * @example getDateYesterday();
+ * @example getDateYesterday(true);
+ *
+ * @returns `2022-11-20`
+ * @returns `20221120`
+ */
 export declare function getDateYesterday(noDashes?: boolean): string;

lib/getDateYesterday.js

@@ -5,2 +5,13 @@ "use strict";
 const getCurrentDate_1 = require("./getCurrentDate");
+/**
+ * @description Return the date of the day before today in `YYYY-MM-DD` format.
+ *
+ * The `noDashes` option will strip any dashes between days, months, etc.
+ *
+ * @example getDateYesterday();
+ * @example getDateYesterday(true);
+ *
+ * @returns `2022-11-20`
+ * @returns `20221120`
+ */
 function getDateYesterday(noDashes = false) {
@@ -7,0 +18,0 @@ const today = new Date((0, getCurrentDate_1.getCurrentDate)());

lib/getDiffInSeconds.d.ts

@@ -0,1 +1,8 @@
+/**
+ * @description Get the difference in seconds between two moments in time (i.e. Unix timestamps).
+ *
+ * @example getDiffInSeconds('1670873500000', '1670873600000');
+ *
+ * @returns `100`
+ */
 export declare const getDiffInSeconds: (earlierTime: string, laterTime: string) => number;

lib/getDiffInSeconds.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDiffInSeconds = void 0;
+/**
+ * @description Get the difference in seconds between two moments in time (i.e. Unix timestamps).
+ *
+ * @example getDiffInSeconds('1670873500000', '1670873600000');
+ *
+ * @returns `100`
+ */
 const getDiffInSeconds = (earlierTime, laterTime) => Math.floor((parseInt(laterTime) - parseInt(earlierTime)) / 1000);
 exports.getDiffInSeconds = getDiffInSeconds;
 //# sourceMappingURL=getDiffInSeconds.js.map

lib/getFirstDateInCurrentMonth.d.ts

@@ -0,1 +1,8 @@
+/**
+ * @description Returns the first date in the current month in `YYYY-MM-DD` format.
+ *
+ * @example getFirstDateInCurrentMonth();
+ *
+ * @returns `2022-12-01`
+ */
 export declare function getFirstDateInCurrentMonth(): string;

lib/getFirstDateInCurrentMonth.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFirstDateInCurrentMonth = void 0;
+/**
+ * @description Returns the first date in the current month in `YYYY-MM-DD` format.
+ *
+ * @example getFirstDateInCurrentMonth();
+ *
+ * @returns `2022-12-01`
+ */
 function getFirstDateInCurrentMonth() {
@@ -5,0 +12,0 @@ const date = new Date();

lib/getLastDateInCurrentMonth.d.ts

@@ -0,1 +1,8 @@
+/**
+ * @description Return the last date in the current month in `YYYY-MM-DD` format.
+ *
+ * @example getLastDateInCurrentMonth();
+ *
+ * @returns `2022-12-31`
+ */
 export declare function getLastDateInCurrentMonth(): string;

lib/getLastDateInCurrentMonth.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getLastDateInCurrentMonth = void 0;
+/**
+ * @description Return the last date in the current month in `YYYY-MM-DD` format.
+ *
+ * @example getLastDateInCurrentMonth();
+ *
+ * @returns `2022-12-31`
+ */
 function getLastDateInCurrentMonth() {
@@ -5,0 +12,0 @@ const date = new Date();

lib/getMaxTimestampFromDate.d.ts

@@ -0,1 +1,10 @@
+/**
+ * @description Get maximum historical/past timestamp at midnight X number of days ago.
+ *
+ * @example getMaxTimestampFromDate(10, 0);
+ * @example getMaxTimestampFromDate(6, 6);
+ * @example getMaxTimestampFromDate(4, -2);
+ *
+ * @returns `1672790400`
+ */
 export declare function getMaxTimestampFromDate(maxDateRange: number, offset: number): string;

lib/getMaxTimestampFromDate.js

@@ -6,2 +6,11 @@ "use strict";
 const getTimestampForInputDate_1 = require("./getTimestampForInputDate");
+/**
+ * @description Get maximum historical/past timestamp at midnight X number of days ago.
+ *
+ * @example getMaxTimestampFromDate(10, 0);
+ * @example getMaxTimestampFromDate(6, 6);
+ * @example getMaxTimestampFromDate(4, -2);
+ *
+ * @returns `1672790400`
+ */
 function getMaxTimestampFromDate(maxDateRange, offset) {
@@ -8,0 +17,0 @@ const date = new Date((0, getCurrentDate_1.getCurrentDate)());

lib/getMillisecondsForDays.d.ts

@@ -0,1 +1,8 @@
+/**
+ * @description Returns the number of milliseconds for a count of days.
+ *
+ * @example getMillisecondsForDays(3);
+ *
+ * @returns `259200000`
+ */
 export declare const getMillisecondsForDays: (days: number) => number;

lib/getMillisecondsForDays.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getMillisecondsForDays = void 0;
-const getMillisecondsForDays = (days) => 24 * 60 * 60 * 1000 * days;
+/**
+ * @description Returns the number of milliseconds for a count of days.
+ *
+ * @example getMillisecondsForDays(3);
+ *
+ * @returns `259200000`
+ */
+const getMillisecondsForDays = (days) => 24 * 60 * 60 * 1000 * days; // hours x minutes x seconds
 exports.getMillisecondsForDays = getMillisecondsForDays;
 //# sourceMappingURL=getMillisecondsForDays.js.map

lib/getTimestampForInputDate.d.ts

@@ -0,1 +1,13 @@
+/**
+ * @description Gets a corresponding Unix timestamp for a `YYYYMMDD` date.
+ *
+ * @param date Date in YYYYMMDD format
+ * @param offsetInHours Optional timezone offset in hours, using the format `0` (UTC; default), `-4` (behind UTC), or `7` (before UTC)
+ *
+ * @example getTimestampForInputDate('20230101');
+ * @example getTimestampForInputDate('20230101', 4);
+ * @example getTimestampForInputDate('20230101', -11);
+ *
+ * @returns `1672531200`
+ */
 export declare function getTimestampForInputDate(date: string, offsetInHours?: number, lastPossibleTime?: boolean): string;

lib/getTimestampForInputDate.js

@@ -5,2 +5,14 @@ "use strict";
 const errors_1 = require("./errors");
+/**
+ * @description Gets a corresponding Unix timestamp for a `YYYYMMDD` date.
+ *
+ * @param date Date in YYYYMMDD format
+ * @param offsetInHours Optional timezone offset in hours, using the format `0` (UTC; default), `-4` (behind UTC), or `7` (before UTC)
+ *
+ * @example getTimestampForInputDate('20230101');
+ * @example getTimestampForInputDate('20230101', 4);
+ * @example getTimestampForInputDate('20230101', -11);
+ *
+ * @returns `1672531200`
+ */
 function getTimestampForInputDate(date, offsetInHours = 0, lastPossibleTime = false) {
@@ -12,2 +24,7 @@ const formatted = convertToIsoDate(date);
 exports.getTimestampForInputDate = getTimestampForInputDate;
+/**
+ * @description Converts a `YYYYMMDD` date string to ISO format.
+ *
+ * @returns `20230101`
+ */
 function convertToIsoDate(input) {
@@ -21,2 +38,10 @@ if (!input || input.length !== 8)
 }
+/**
+ * @description Retrieve timestamp for an ISO date such as `2023-01-01`.
+ *
+ * @param formattedDate Date in the ISO format of `2023-01-01`
+ * @param offsetInHours Optional timezone offset in hours, using the format `0` (UTC; default), `-4` (behind UTC), or `7` (before UTC)
+ *
+ * @returns `1672531200`
+ */
 function getTimestampForISODate(formattedDate, offsetInHours = 0, lastPossibleTime = false) {
@@ -26,3 +51,16 @@ const date = new Date(createTimezoneConvertedDateString(formattedDate, offsetInHours, lastPossibleTime));
 }
+/**
+ * @description Returns a long timezone-converted date string from a formatted date such as `2023-01-01`.
+ *
+ * @returns `2023-01-01T00:00:00.000+05:00`
+ */
 function createTimezoneConvertedDateString(formattedDate, offsetInHours, lastPossibleTime = false) {
+    /**
+     * Note that this is "flipped" and works contrary to how we normally
+     * think about timezones. We typically think of e.g. New York as
+     * several hours "behind" (minus, -) London/GMT/UTC/Zulu time.
+     *
+     * However, for some unknown reason when adding the offset we get
+     * precisely the reverse results: That's why we do the flip of +/- here.
+     */
     const offsetMarker = offsetInHours.toString().includes('-') ? '+' : '-';
@@ -29,0 +67,0 @@ const numericOffset = offsetInHours.toString().replace('-', '');

lib/getTimestampsForPeriod.d.ts

@@ -0,1 +1,12 @@
+/**
+ * @description Calculates `from` and `to` timestamps for a provided period in days.
+ *
+ * Using `lastNumDays` means getting specified range excluding current day.
+ *
+ * @example getTimestampsForPeriod(1);
+ * @example getTimestampsForPeriod(5, -3);
+ * @example getTimestampsForPeriod(14, 7);
+ *
+ * @returns `{ "from": "1673568000", "to": "1673654399" }`
+ */
 export declare function getTimestampsForPeriod(lastNumDays: number, offsetInHours?: number): {
@@ -2,0 +13,0 @@ from: string;

lib/getTimestampsForPeriod.js

@@ -7,2 +7,13 @@ "use strict";
 const getTimestampForInputDate_1 = require("./getTimestampForInputDate");
+/**
+ * @description Calculates `from` and `to` timestamps for a provided period in days.
+ *
+ * Using `lastNumDays` means getting specified range excluding current day.
+ *
+ * @example getTimestampsForPeriod(1);
+ * @example getTimestampsForPeriod(5, -3);
+ * @example getTimestampsForPeriod(14, 7);
+ *
+ * @returns `{ "from": "1673568000", "to": "1673654399" }`
+ */
 function getTimestampsForPeriod(lastNumDays, offsetInHours = 0) {
@@ -9,0 +20,0 @@ const toTime = (0, getTimestampForInputDate_1.getTimestampForInputDate)((0, getDateYesterday_1.getDateYesterday)(true), offsetInHours, true);

lib/makeTwoDigitDate.d.ts

@@ -0,1 +1,11 @@
+/**
+ * @description Add leading zero if date (day, month) is under 10.
+ *
+ * @example makeTwoDigitDate(1, 'day');
+ * @example makeTwoDigitDate(11, 'month');
+ * @example makeTwoDigitDate(new Date('2022-12-05'), 'day');
+ * @example makeTwoDigitDate(new Date('2022-07-05'), 'month');
+ *
+ * @returns `01`
+ */
 export declare function makeTwoDigitDate(date: Date | number, unit: 'day' | 'month'): string;

lib/makeTwoDigitDate.js

@@ -5,2 +5,12 @@ "use strict";
 const errors_1 = require("./errors");
+/**
+ * @description Add leading zero if date (day, month) is under 10.
+ *
+ * @example makeTwoDigitDate(1, 'day');
+ * @example makeTwoDigitDate(11, 'month');
+ * @example makeTwoDigitDate(new Date('2022-12-05'), 'day');
+ * @example makeTwoDigitDate(new Date('2022-07-05'), 'month');
+ *
+ * @returns `01`
+ */
 function makeTwoDigitDate(date, unit) {
@@ -7,0 +17,0 @@ const value = (() => {

lib/prettifyTime.d.ts

@@ -0,1 +1,10 @@
+/**
+ * @description Returns a prettified time format (`DD:HH:MM:SS`) from a count of seconds.
+ * All fields will be double-digit, but it is possible that double-digit `DD` will in fact
+ * be three-digit `DDD` if the day count is huge (i.e. over 99).
+ *
+ * @example prettifyTime(60);
+ *
+ * @returns `00:00:01:00`
+ */
 export declare function prettifyTime(timeInSeconds: number): string;

lib/prettifyTime.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.prettifyTime = void 0;
+/**
+ * @description Returns a prettified time format (`DD:HH:MM:SS`) from a count of seconds.
+ * All fields will be double-digit, but it is possible that double-digit `DD` will in fact
+ * be three-digit `DDD` if the day count is huge (i.e. over 99).
+ *
+ * @example prettifyTime(60);
+ *
+ * @returns `00:00:01:00`
+ */
 function prettifyTime(timeInSeconds) {
@@ -5,0 +14,0 @@ let days = Math.floor(timeInSeconds / 86400).toString();

lib/prettyTimeToSeconds.d.ts

@@ -0,1 +1,9 @@
+/**
+ * @description Converts a prettified time to a numberic count of seconds
+ * to represent the same value.
+ *
+ * @example prettyTimeToSeconds('00:09:28:24');
+ *
+ * @returns `34104`
+ */
 export declare function prettyTimeToSeconds(time: string): number;

lib/prettyTimeToSeconds.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.prettyTimeToSeconds = void 0;
+/**
+ * @description Converts a prettified time to a numberic count of seconds
+ * to represent the same value.
+ *
+ * @example prettyTimeToSeconds('00:09:28:24');
+ *
+ * @returns `34104`
+ */
 function prettyTimeToSeconds(time) {
@@ -5,0 +13,0 @@ if (!time || time === '00:00:00:00')

lib/zuluToUnix.d.ts

@@ -0,1 +1,8 @@
+/**
+ * @description Converts Zulu time (UTC/GMT +0) to Unix timestamp.
+ *
+ * @example zuluToUnix('2022-11-21T10:41:57Z');
+ *
+ * @returns `1669027317000`
+ */
 export declare function zuluToUnix(zuluTime: string): number;

lib/zuluToUnix.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.zuluToUnix = void 0;
+/**
+ * @description Converts Zulu time (UTC/GMT +0) to Unix timestamp.
+ *
+ * @example zuluToUnix('2022-11-21T10:41:57Z');
+ *
+ * @returns `1669027317000`
+ */
 function zuluToUnix(zuluTime) {
@@ -5,0 +12,0 @@ return new Date(zuluTime).getTime();

package.json

 {
   "name": "chrono-utils",
   "description": "Collects a number of helpful date and time utilities for TypeScript/Javascript.",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "author": "Mikael Vesavuori",
@@ -6,0 +6,0 @@ "license": "MIT",

No alert changes

Improved metrics

Total package byte prevSize

34343

increased by38.91%

Lines of code

667

increased by103.35%

No dependency changes