@cityssm/utils-datetime 1.1.0 → 1.1.2

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,12 +1,19 @@
 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
 
 /**
@@ -18,11 +25,11 @@ export function dateIntegerToDate(
   dateInteger: number | undefined | null,
   timeInteger: number | undefined | null = 0
 ): Date | undefined {
-  if (!isValidDateInteger(dateInteger)) {
+  if (!isValidDateInteger(dateInteger) || !isValidTimeInteger(timeInteger)) {
     return undefined
   }
 
-  const dateString = `00000000${(dateInteger as number).toString()}`.slice(-8)
+  const dateString = `00000000${dateInteger.toString()}`.slice(-8)
 
   const timeString = `0000${(timeInteger ?? 0).toString()}`.slice(-4)
 

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,7 +3,11 @@ 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): ''
 
 /**
@@ -18,5 +22,5 @@ export function dateIntegerToString(
     return ''
   }
 
-  return dateToString(dateIntegerToDate(dateInteger as number))
+  return dateToString(dateIntegerToDate(dateInteger))
 }

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.
+ * @param {string} dateString - A string representing a date.
+ * @param {string} timeString - A string representing a time.
  * @returns {Date} - A JavaScript Date object.
  */
 export function dateStringToDate(
-  dateString: DateString,
-  timeString: TimeString = '00:00'
-): Date {
+  dateString: string,
+  timeString: string = '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')
+ * @param {string} dateString - A date formatted as a string (ex. '2024-12-31')
  * @returns {number} - 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,4 +1,7 @@
 export function dateToInteger(dateObject) {
+    if (dateObject === undefined) {
+        return undefined;
+    }
     return (dateObject.getFullYear() * 10000 +
         (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.
  */
-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.
  */
-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.
+ * @param {Date} dateObject - A JavaScript Date object.
  * @returns {number} - 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.)
  */
-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.
  */
-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.d.ts

@@ -1 +1 @@
-export declare function isValidDateInteger(possibleDateInteger: unknown): boolean;
+export declare function isValidDateInteger(possibleDateInteger: unknown): possibleDateInteger is number;

package/isValidDateInteger.ts

@@ -3,7 +3,9 @@
  * @param {unknown} possibleDateInteger - A possible date number
  * @returns {boolean} - True if the possible date integer is valid.
  */
-export function isValidDateInteger(possibleDateInteger: unknown): boolean {
+export function isValidDateInteger(
+  possibleDateInteger: unknown
+): possibleDateInteger is number {
   return (
     typeof possibleDateInteger === 'number' &&
     possibleDateInteger >= 101 &&

package/isValidDateString.d.ts

@@ -1 +1,2 @@
-export declare function isValidDateString(possibleDateString: unknown): boolean;
+import type { DateString } from './dateTimeTypes.js';
+export declare function isValidDateString(possibleDateString: unknown): possibleDateString is DateString;

package/isValidDateString.ts

@@ -1,3 +1,5 @@
+import type { DateString } from './dateTimeTypes.js'
+
 const dateStringRegex = /^\d{4}-[01]\d-[0-3]\d$/
 
 /**
@@ -5,7 +7,9 @@ const dateStringRegex = /^\d{4}-[01]\d-[0-3]\d$/
  * @param {unknown} possibleDateString - A possible date string
  * @returns {boolean} - True when the possible date string is valid
  */
-export function isValidDateString(possibleDateString: unknown): boolean {
+export function isValidDateString(
+  possibleDateString: unknown
+): possibleDateString is DateString {
   return (
     typeof possibleDateString === 'string' &&
     (possibleDateString ?? '').length === 10 &&

package/isValidTimeInteger.d.ts

@@ -1 +1 @@
-export declare function isValidTimeInteger(possibleTimeInteger: unknown): boolean;
+export declare function isValidTimeInteger(possibleTimeInteger: unknown): possibleTimeInteger is number;

package/isValidTimeInteger.ts

@@ -3,7 +3,9 @@
  * @param {unknown} possibleTimeInteger - A possible time number
  * @returns {boolean} - True if the possible time integer is valid.
  */
-export function isValidTimeInteger(possibleTimeInteger: unknown): boolean {
+export function isValidTimeInteger(
+  possibleTimeInteger: unknown
+): possibleTimeInteger is number {
   return (
     typeof possibleTimeInteger === 'number' &&
     possibleTimeInteger >= 0 &&

package/isValidTimeString.d.ts

@@ -1 +1,2 @@
-export declare function isValidTimeString(possibleTimeString: unknown): boolean;
+import type { TimeString } from './dateTimeTypes.js';
+export declare function isValidTimeString(possibleTimeString: unknown): possibleTimeString is TimeString;

package/isValidTimeString.ts

@@ -1,3 +1,5 @@
+import type { TimeString } from './dateTimeTypes.js'
+
 const timeStringRegex = /^[01]\d:[0-5]\d$/
 
 /**
@@ -5,7 +7,9 @@ const timeStringRegex = /^[01]\d:[0-5]\d$/
  * @param {unknown} possibleTimeString - A possible time string.
  * @returns {boolean} - True when the possible time string is valid.
  */
-export function isValidTimeString(possibleTimeString: unknown): boolean {
+export function isValidTimeString(
+  possibleTimeString: unknown
+): possibleTimeString is TimeString {
   return (
     typeof possibleTimeString === 'string' &&
     (possibleTimeString ?? '').length === 5 &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cityssm/utils-datetime",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Date time utilities for Node.js applications",
   "keywords": [
     "date",

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): TimePeriodString | '';

package/timeIntegerToPeriodString.js

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

package/timeIntegerToPeriodString.ts

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

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.
+ * @param {string} timeString - A string representing a time.
  * @returns {number} - 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)
 }