@cityssm/utils-datetime 1.1.1 → 1.1.3

package/dateIntegerToDate.d.ts

@@ -1,2 +1,3 @@
-export declare function dateIntegerToDate(dateInteger: number, timeInteger?: number): Date;
-export declare function dateIntegerToDate(dateInteger: null | undefined | 0, timeInteger?: number): undefined;
+export declare function dateIntegerToDate<D extends number | undefined | null, T extends number | undefined | null>(dateInteger: D, timeInteger?: T): Date | undefined;
+export declare function dateIntegerToDate(dateInteger: number, timeInteger?: number): Date | undefined;
+export declare function dateIntegerToDate(dateInteger: undefined | null, timeInteger?: undefined | null): undefined;

package/dateIntegerToDate.js

@@ -1,6 +1,7 @@
 import { isValidDateInteger } from './isValidDateInteger.js';
+import { isValidTimeInteger } from './isValidTimeInteger.js';
 export function dateIntegerToDate(dateInteger, timeInteger = 0) {
-    if (!isValidDateInteger(dateInteger)) {
+    if (!isValidDateInteger(dateInteger) || !isValidTimeInteger(timeInteger)) {
         return undefined;
     }
     const dateString = `00000000${dateInteger.toString()}`.slice(-8);

package/dateIntegerToDate.ts

@@ -1,24 +1,31 @@
 import { isValidDateInteger } from './isValidDateInteger.js'
+import { isValidTimeInteger } from './isValidTimeInteger.js'
+
+export function dateIntegerToDate<
+  D extends number | undefined | null,
+  T extends number | undefined | null
+>(dateInteger: D, timeInteger?: T): Date | undefined
 
 export function dateIntegerToDate(
   dateInteger: number,
   timeInteger?: number
-): Date
+): Date | undefined
+
 export function dateIntegerToDate(
-  dateInteger: null | undefined | 0,
-  timeInteger?: number
+  dateInteger: undefined | null,
+  timeInteger?: undefined | null
 ): undefined
 
 /**
- * @param {number | undefined | null} dateInteger - A number representing a date (ex. 20241231)
- * @param {number} timeInteger - A number representing a time (ex. 2359)
- * @returns {Date | undefined} - A Date object (ex. '2024-12-31 23:59')
+ * @param dateInteger - A number representing a date (ex. 20241231)
+ * @param timeInteger - A number representing a time (ex. 2359)
+ * @returns - A Date object (ex. '2024-12-31 23:59')
  */
 export function dateIntegerToDate(
   dateInteger: number | undefined | null,
   timeInteger: number | undefined | null = 0
 ): Date | undefined {
-  if (!isValidDateInteger(dateInteger)) {
+  if (!isValidDateInteger(dateInteger) || !isValidTimeInteger(timeInteger)) {
     return undefined
   }
 

package/dateIntegerToString.d.ts

@@ -1,3 +1,4 @@
 import type { DateString } from './dateTimeTypes.js';
-export declare function dateIntegerToString(dateInteger: number): DateString;
+export declare function dateIntegerToString<D extends number | undefined | null>(dateInteger: D): DateString | '';
+export declare function dateIntegerToString(dateInteger: number): DateString | '';
 export declare function dateIntegerToString(dateInteger: null | undefined | 0): '';

package/dateIntegerToString.ts

@@ -3,13 +3,17 @@ import type { DateString } from './dateTimeTypes.js'
 import { dateToString } from './dateToString.js'
 import { isValidDateInteger } from './isValidDateInteger.js'
 
-export function dateIntegerToString(dateInteger: number): DateString
+export function dateIntegerToString<D extends number | undefined | null>(
+  dateInteger: D
+): DateString | ''
+
+export function dateIntegerToString(dateInteger: number): DateString | ''
 export function dateIntegerToString(dateInteger: null | undefined | 0): ''
 
 /**
  * Formats a date number as a string.
- * @param {number | undefined | null} dateInteger - A number representing a date.
- * @returns {DateString | ''} - A string representing a date.
+ * @param dateInteger - A number representing a date.
+ * @returns - A string representing a date.
  */
 export function dateIntegerToString(
   dateInteger: number | undefined | null

package/dateStringToDate.d.ts

@@ -1,2 +1 @@
-import type { DateString, TimeString } from './dateTimeTypes.js';
-export declare function dateStringToDate(dateString: DateString, timeString?: TimeString): Date;
+export declare function dateStringToDate(dateString: string, timeString?: string): Date | undefined;

package/dateStringToDate.js

@@ -1,4 +1,9 @@
+import { isValidDateString } from './isValidDateString.js';
+import { isValidTimeString } from './isValidTimeString.js';
 export function dateStringToDate(dateString, timeString = '00:00') {
+    if (!isValidDateString(dateString) || !isValidTimeString(timeString)) {
+        return undefined;
+    }
     const datePieces = dateString.split('-');
     const timePieces = timeString.split(':');
     return new Date(Number.parseInt(datePieces[0], 10), Number.parseInt(datePieces[1], 10) - 1, Number.parseInt(datePieces[2], 10), Number.parseInt(timePieces[0], 10), Number.parseInt(timePieces[1], 10), 0, 0);

package/dateStringToDate.ts

@@ -1,15 +1,20 @@
-import type { DateString, TimeString } from './dateTimeTypes.js'
+import { isValidDateString } from './isValidDateString.js'
+import { isValidTimeString } from './isValidTimeString.js'
 
 /**
  * Formats a string date and time as a JavaScript Date object.
- * @param {DateString} dateString - A string representing a date.
- * @param {TimeString} timeString - A string representing a time.
- * @returns {Date} - A JavaScript Date object.
+ * @param dateString - A string representing a date.
+ * @param timeString - A string representing a time.
+ * @returns - A JavaScript Date object.
  */
 export function dateStringToDate(
-  dateString: DateString,
-  timeString: TimeString = '00:00'
-): Date {
+  dateString: string,
+  timeString = '00:00'
+): Date | undefined {
+  if (!isValidDateString(dateString) || !isValidTimeString(timeString)) {
+    return undefined
+  }
+
   const datePieces = dateString.split('-')
   const timePieces = timeString.split(':')
 

package/dateStringToInteger.d.ts

@@ -1,2 +1 @@
-import type { DateString } from './dateTimeTypes.js';
-export declare function dateStringToInteger(dateString: DateString): number;
+export declare function dateStringToInteger(dateString: string): number | undefined;

package/dateStringToInteger.js

@@ -1,5 +1,9 @@
 import { dateStringToDate } from './dateStringToDate.js';
 import { dateToInteger } from './dateToInteger.js';
+import { isValidDateString } from './isValidDateString.js';
 export function dateStringToInteger(dateString) {
+    if (!isValidDateString(dateString)) {
+        return undefined;
+    }
     return dateToInteger(dateStringToDate(dateString));
 }

package/dateStringToInteger.ts

@@ -1,12 +1,16 @@
 import { dateStringToDate } from './dateStringToDate.js'
-import type { DateString } from './dateTimeTypes.js'
 import { dateToInteger } from './dateToInteger.js'
+import { isValidDateString } from './isValidDateString.js'
 
 /**
  * Formats a date string as a number.
- * @param {DateString} dateString - A date formatted as a string (ex. '2024-12-31')
- * @returns {number} - A number representing a date.
+ * @param dateString - A date formatted as a string (ex. '2024-12-31')
+ * @returns - A number representing a date.
  */
-export function dateStringToInteger(dateString: DateString): number {
+export function dateStringToInteger(dateString: string): number | undefined {
+  if (!isValidDateString(dateString)) {
+    return undefined
+  }
+
   return dateToInteger(dateStringToDate(dateString))
 }

package/dateToInteger.d.ts

@@ -1 +1,3 @@
+export declare function dateToInteger<T extends Date | undefined>(dateObject: T): number | undefined;
 export declare function dateToInteger(dateObject: Date): number;
+export declare function dateToInteger(dateObject: undefined): undefined;

package/dateToInteger.js

@@ -1,5 +1,8 @@
 export function dateToInteger(dateObject) {
-    return (dateObject.getFullYear() * 10000 +
+    if (dateObject === undefined) {
+        return undefined;
+    }
+    return (dateObject.getFullYear() * 10_000 +
         (dateObject.getMonth() + 1) * 100 +
         dateObject.getDate());
 }

package/dateToInteger.ts

@@ -1,9 +1,20 @@
+export function dateToInteger<T extends Date | undefined>(dateObject: T): number | undefined
+
+export function dateToInteger(dateObject: Date): number
+export function dateToInteger(dateObject: undefined): undefined
+
 /**
  * Formats a JavaScript Date object as a number.
- * @param {Date} dateObject - A JavaScript Date object.
- * @returns {number} - A number representing the date.
+ * @param dateObject - A JavaScript Date object.
+ * @returns - A number representing the date.
  */
-export function dateToInteger(dateObject: Date): number {
+export function dateToInteger(
+  dateObject: Date | undefined
+): number | undefined {
+  if (dateObject === undefined) {
+    return undefined
+  }
+
   return (
     dateObject.getFullYear() * 10_000 +
     (dateObject.getMonth() + 1) * 100 +

package/dateToString.d.ts

@@ -1,2 +1,4 @@
 import type { DateString } from './dateTimeTypes.js';
+export declare function dateToString<D extends Date | undefined>(dateObject: D): DateString | '';
 export declare function dateToString(dateObject: Date): DateString;
+export declare function dateToString(dateObject: undefined): '';

package/dateToString.js

@@ -1,4 +1,7 @@
 export function dateToString(dateObject) {
+    if (dateObject === undefined) {
+        return '';
+    }
     return Intl.DateTimeFormat('fr-CA', {
         year: 'numeric',
         month: '2-digit',

package/dateToString.ts

@@ -1,11 +1,22 @@
 import type { DateString } from './dateTimeTypes.js'
 
+export function dateToString<D extends Date | undefined>(
+  dateObject: D
+): DateString | ''
+
+export function dateToString(dateObject: Date): DateString
+export function dateToString(dateObject: undefined): ''
+
 /**
  * Formats a JavaScript Date object as a date string.
- * @param {Date} dateObject - A JavaScript Date object
- * @returns {DateString} A date string.
+ * @param dateObject - A JavaScript Date object
+ * @returns - A date string.
  */
-export function dateToString(dateObject: Date): DateString {
+export function dateToString(dateObject: Date | undefined): DateString | '' {
+  if (dateObject === undefined) {
+    return ''
+  }
+
   return Intl.DateTimeFormat('fr-CA', {
     year: 'numeric',
     month: '2-digit',

package/dateToTimeInteger.d.ts

@@ -1 +1,3 @@
+export declare function dateToTimeInteger<D extends Date | undefined>(dateObject: D): number | undefined;
 export declare function dateToTimeInteger(dateObject: Date): number;
+export declare function dateToTimeInteger(dateObject: undefined): undefined;

package/dateToTimeInteger.js

@@ -1,3 +1,6 @@
 export function dateToTimeInteger(dateObject) {
+    if (dateObject === undefined) {
+        return undefined;
+    }
     return dateObject.getHours() * 100 + dateObject.getMinutes();
 }

package/dateToTimeInteger.ts

@@ -1,8 +1,21 @@
+export function dateToTimeInteger<D extends Date | undefined>(
+  dateObject: D
+): number | undefined
+
+export function dateToTimeInteger(dateObject: Date): number
+export function dateToTimeInteger(dateObject: undefined): undefined
+
 /**
  * Formats the time in a JavaScript Date as a number.
- * @param {Date} dateObject - A JavaString Date object.
- * @returns {number} - A number representing a time.
+ * @param dateObject - A JavaScript Date object.
+ * @returns - A number representing a time.
  */
-export function dateToTimeInteger(dateObject: Date): number {
+export function dateToTimeInteger(
+  dateObject: Date | undefined
+): number | undefined {
+  if (dateObject === undefined) {
+    return undefined
+  }
+
   return dateObject.getHours() * 100 + dateObject.getMinutes()
 }

package/dateToTimePeriodString.d.ts

@@ -1,2 +1,4 @@
 import type { TimePeriodString } from './dateTimeTypes.js';
+export declare function dateToTimePeriodString<D extends Date | undefined>(dateObject: D): TimePeriodString | '';
 export declare function dateToTimePeriodString(dateObject: Date): TimePeriodString;
+export declare function dateToTimePeriodString(dateObject: undefined): '';

package/dateToTimePeriodString.js

@@ -1,4 +1,7 @@
 export function dateToTimePeriodString(dateObject) {
+    if (dateObject === undefined) {
+        return '';
+    }
     return Intl.DateTimeFormat('en-CA', {
         hourCycle: 'h12',
         hour: 'numeric',

package/dateToTimePeriodString.ts

@@ -1,11 +1,24 @@
 import type { TimePeriodString } from './dateTimeTypes.js'
 
+export function dateToTimePeriodString<D extends Date | undefined>(
+  dateObject: D
+): TimePeriodString | ''
+
+export function dateToTimePeriodString(dateObject: Date): TimePeriodString
+export function dateToTimePeriodString(dateObject: undefined): ''
+
 /**
  * Formats a JavaScript Date as a time period string.
- * @param {Date} dateObject - A JavaScript Date object.
- * @returns {TimePeriodString} - A time string formatted with the time period (ex. 1:23 a.m.)
+ * @param dateObject - A JavaScript Date object.
+ * @returns - A time string formatted with the time period (ex. 1:23 a.m.)
  */
-export function dateToTimePeriodString(dateObject: Date): TimePeriodString {
+export function dateToTimePeriodString(
+  dateObject: Date | undefined
+): TimePeriodString | '' {
+  if (dateObject === undefined) {
+    return ''
+  }
+
   return Intl.DateTimeFormat('en-CA', {
     hourCycle: 'h12',
     hour: 'numeric',

package/dateToTimeString.d.ts

@@ -1,2 +1,4 @@
 import type { TimeString } from './dateTimeTypes.js';
+export declare function dateToTimeString<D extends Date | undefined>(dateObject: D): TimeString | '';
 export declare function dateToTimeString(dateObject: Date): TimeString;
+export declare function dateToTimeString(dateObject: undefined): '';

package/dateToTimeString.js

@@ -1,4 +1,7 @@
 export function dateToTimeString(dateObject) {
+    if (dateObject === undefined) {
+        return '';
+    }
     return Intl.DateTimeFormat('en-CA', {
         hourCycle: 'h24',
         hour: '2-digit',

package/dateToTimeString.ts

@@ -1,11 +1,24 @@
 import type { TimeString } from './dateTimeTypes.js'
 
+export function dateToTimeString<D extends Date | undefined>(
+  dateObject: D
+): TimeString | ''
+
+export function dateToTimeString(dateObject: Date): TimeString
+export function dateToTimeString(dateObject: undefined): ''
+
 /**
  * Formats a JavaScript Date object as a time string.
- * @param {Date} dateObject - A JavaScript Date object.
- * @returns {TimeString} - A string representing the time.
+ * @param dateObject - A JavaScript Date object.
+ * @returns - A string representing the time.
  */
-export function dateToTimeString(dateObject: Date): TimeString {
+export function dateToTimeString(
+  dateObject: Date | undefined
+): TimeString | '' {
+  if (dateObject === undefined) {
+    return ''
+  }
+
   return Intl.DateTimeFormat('en-CA', {
     hourCycle: 'h24',
     hour: '2-digit',

package/isValidDateInteger.ts

@@ -1,7 +1,7 @@
 /**
  * Determines if a number is a valid date number.
- * @param {unknown} possibleDateInteger - A possible date number
- * @returns {boolean} - True if the possible date integer is valid.
+ * @param possibleDateInteger - A possible date number
+ * @returns - True if the possible date integer is valid.
  */
 export function isValidDateInteger(
   possibleDateInteger: unknown

package/isValidDateString.ts

@@ -4,8 +4,8 @@ const dateStringRegex = /^\d{4}-[01]\d-[0-3]\d$/
 
 /**
  * Determines if a string is a valid date string.
- * @param {unknown} possibleDateString - A possible date string
- * @returns {boolean} - True when the possible date string is valid
+ * @param possibleDateString - A possible date string
+ * @returns - True when the possible date string is valid
  */
 export function isValidDateString(
   possibleDateString: unknown

package/isValidTimeInteger.ts

@@ -1,7 +1,7 @@
 /**
  * Determines if a number is a valid time number.
- * @param {unknown} possibleTimeInteger - A possible time number
- * @returns {boolean} - True if the possible time integer is valid.
+ * @param possibleTimeInteger - A possible time number
+ * @returns - True if the possible time integer is valid.
  */
 export function isValidTimeInteger(
   possibleTimeInteger: unknown

package/isValidTimeString.ts

@@ -4,8 +4,8 @@ const timeStringRegex = /^[01]\d:[0-5]\d$/
 
 /**
  * Determines if a string is a valid time string.
- * @param {unknown} possibleTimeString - A possible time string.
- * @returns {boolean} - True when the possible time string is valid.
+ * @param possibleTimeString - A possible time string.
+ * @returns - True when the possible time string is valid.
  */
 export function isValidTimeString(
   possibleTimeString: unknown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cityssm/utils-datetime",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Date time utilities for Node.js applications",
   "keywords": [
     "date",
@@ -25,14 +25,14 @@
     "test": "test"
   },
   "scripts": {
-    "test": "mocha",
-    "coverage": "c8 mocha"
+    "test": "node --test",
+    "coverage": "c8 --reporter=lcov --reporter=text --reporter=text-summary node --test"
   },
   "author": "The Corporation of the City of Sault Ste. Marie",
   "license": "MIT",
   "devDependencies": {
-    "@types/mocha": "^10.0.6",
-    "@types/node": "^20.11.19",
-    "eslint-config-cityssm": "^1.4.1"
+    "@types/node": "^20.14.5",
+    "eslint-config-cityssm": "^5.0.0",
+    "prettier-config-cityssm": "^1.0.0"
   }
 }

package/timeIntegerToPeriodString.d.ts

@@ -1,2 +1,2 @@
 import type { TimePeriodString } from './dateTimeTypes.js';
-export declare function timeIntegerToPeriodString(timeInteger: number): TimePeriodString;
+export declare function timeIntegerToPeriodString(timeInteger?: number | undefined | null): TimePeriodString | '';

package/timeIntegerToPeriodString.js

@@ -1,5 +1,5 @@
 import { dateIntegerToDate } from './dateIntegerToDate.js';
 import { dateToTimePeriodString } from './dateToTimePeriodString.js';
-export function timeIntegerToPeriodString(timeInteger) {
-    return dateToTimePeriodString(dateIntegerToDate(19700101, timeInteger));
+export function timeIntegerToPeriodString(timeInteger = 0) {
+    return dateToTimePeriodString(dateIntegerToDate(19700101, timeInteger ?? 0));
 }

package/timeIntegerToPeriodString.ts

@@ -4,12 +4,12 @@ import { dateToTimePeriodString } from './dateToTimePeriodString.js'
 
 /**
  * Formats a time represented as a number as a string.
- * @param {number} timeInteger - A number representing a time.
- * @returns {TimePeriodString} - A string representing a time.
+ * @param timeInteger - A number representing a time.
+ * @returns - A string representing a time.
  */
 export function timeIntegerToPeriodString(
-  timeInteger: number
-): TimePeriodString {
+  timeInteger: number | undefined | null = 0
+): TimePeriodString | '' {
   // eslint-disable-next-line unicorn/numeric-separators-style
-  return dateToTimePeriodString(dateIntegerToDate(19700101, timeInteger))
+  return dateToTimePeriodString(dateIntegerToDate(19700101, timeInteger ?? 0))
 }

package/timeIntegerToString.ts

@@ -2,8 +2,8 @@ import type { TimeString } from './dateTimeTypes.js'
 
 /**
  * Formats a number representing a time as a string.
- * @param {number} timeInteger - A number representing a time.
- * @returns {TimeString} - A string representing a time.
+ * @param timeInteger - A number representing a time.
+ * @returns - A string representing a time.
  */
 export function timeIntegerToString(
   timeInteger: number | undefined | null

package/timeStringToInteger.d.ts

@@ -1,2 +1 @@
-import type { TimeString } from './dateTimeTypes.js';
-export declare function timeStringToInteger(timeString: TimeString): number;
+export declare function timeStringToInteger(timeString: string): number | undefined;

package/timeStringToInteger.js

@@ -1,3 +1,7 @@
+import { isValidTimeString } from './isValidTimeString.js';
 export function timeStringToInteger(timeString) {
+    if (!isValidTimeString(timeString)) {
+        return undefined;
+    }
     return Number.parseInt(`0${timeString}`.replaceAll(':', ''), 10);
 }

package/timeStringToInteger.ts

@@ -1,10 +1,14 @@
-import type { TimeString } from './dateTimeTypes.js'
+import { isValidTimeString } from './isValidTimeString.js'
 
 /**
  * Formats a string representing a time as a number.
- * @param {TimeString} timeString - A string representing a time.
- * @returns {number} - A number representing a time.
+ * @param timeString - A string representing a time.
+ * @returns - A number representing a time.
  */
-export function timeStringToInteger(timeString: TimeString): number {
+export function timeStringToInteger(timeString: string): number | undefined {
+  if (!isValidTimeString(timeString)) {
+    return undefined
+  }
+
   return Number.parseInt(`0${timeString}`.replaceAll(':', ''), 10)
 }