Date type and predicate improvements

package.json

@@ -87,7 +87,7 @@
   "devDependencies": {
     "@commitlint/config-conventional": "^19.8.1",
     "@commitlint/types": "^19.8.1",
-    "@types/node": "^22.17.0",
+    "@types/node": "^22.17.2",
     "@vitest/coverage-v8": "^3.2.4",
     "@webdeveric/eslint-config-ts": "^0.11.0",
     "@webdeveric/prettier-config": "^0.3.0",
@@ -101,7 +101,7 @@
     "eslint-plugin-import": "^2.32.0",
     "husky": "^9.1.7",
     "jsdom": "^26.1.0",
-    "lint-staged": "^16.1.2",
+    "lint-staged": "^16.1.5",
     "prettier": "^3.6.2",
     "rimraf": "^6.0.1",
     "semantic-release": "^24.2.7",

src/predicate/index.ts

@@ -10,6 +10,7 @@ export * from './isBigIntArray.js';
 export * from './isBinaryNumberString.js';
 export * from './isBoolean.js';
 export * from './isBooleanArray.js';
+export * from './isDateInputString.js';
 export * from './isDateString.js';
 export * from './isDigitsString.js';
 export * from './isFiniteNumber.js';

src/predicate/isDateInputString.ts

@@ -0,0 +1,8 @@
+import type { DateInputString } from '../types/date-time.js';
+import type { TypePredicateFn } from '../types/functions.js';
+
+/**
+ * Determine if `input` is a valid date string.
+ */
+export const isDateInputString: TypePredicateFn<DateInputString> = (input: unknown): input is DateInputString =>
+  typeof input === 'string' && !Number.isNaN(Date.parse(input));

src/predicate/isDateString.ts

@@ -1,7 +1,10 @@
+import { isDateInputString } from './isDateInputString.js';
+
 import type { TypePredicateFn } from '../types/functions.js';
 
 /**
  * Determine if `input` is a valid date string.
+ *
+ * @deprecated Use `isDateInputString` instead.
  */
-export const isDateString: TypePredicateFn<string> = (input: unknown): input is string =>
-  typeof input === 'string' && !Number.isNaN(Date.parse(input));
+export const isDateString: TypePredicateFn<string> = isDateInputString;

src/predicate/isISODateString.ts

@@ -3,7 +3,7 @@ import { matching } from './factory/matching.js';
 import type { ISODateString } from '../types/date-time.js';
 
 export const ISO_DATE_PATTERN =
-  /^(?<year>\d{4,})-(?<month>[01]\d)-(?<day>0[1-9]|[12]\d|3[01])T(?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})\.(?<timezone>\d{3}Z)$/;
+  /^(?<year>\d{4,})-(?<month>[01]\d)-(?<day>0[1-9]|[12]\d|3[01])T(?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})\.(?<timezone>\d+Z)$/;
 
 /**
  * This checks to see if the input matches the format that `toISOString()`

src/types/date-time.ts

@@ -3,6 +3,11 @@ import type { NumericString } from './common.js';
 
 export type DateInput = ConstructorParameters<typeof Date>[0];
 
+/**
+ * This is used to represent a string can be used as input for a `Date` constructor.
+ */
+export type DateInputString = Branded<string, 'DateInputString'>;
+
 export type YearString = Branded<NumericString<number>, 'YearString'>;
 
 export type MonthString = Branded<NumericString<number>, 'MonthString'>;

test/predicate/isDateString.test.ts → test/predicate/isDateInputString.test.ts

@@ -1,19 +1,19 @@
 import { describe, it, expect } from 'vitest';
 
-import { isDateString } from '../../src/predicate/isDateString.js';
+import { isDateInputString } from '../../src/predicate/isDateInputString.js';
 
-describe('isDateString()', () => {
+describe('isDateInputString()', () => {
   it.each([
     new Date().toISOString(),
     new Date().toLocaleDateString('en-US'),
     new Date().toLocaleString(),
     new Date().toUTCString(),
     new Date().toString(),
   ])('Returns true for valid input: %j', (input) => {
-    expect(isDateString(input)).toBeTruthy();
+    expect(isDateInputString(input)).toBeTruthy();
   });
 
   it.each([Date.now(), 'bad input', true, null, {}, undefined])('Returns false for invalid input: %j', (input) => {
-    expect(isDateString(input)).toBeFalsy();
+    expect(isDateInputString(input)).toBeFalsy();
   });
 });

test/predicate/isISODateString.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest';
+
+import { isISODateString } from '../../src/predicate/isISODateString.js';
+
+describe('isISODateString()', () => {
+  it.each([new Date(0).toISOString(), new Date('+9999-12-31').toISOString(), '2025-08-01T01:23:34.123456789Z'])(
+    'Returns true for valid input: "%s"',
+    (input) => {
+      expect(isISODateString(input)).toBeTruthy();
+    },
+  );
+
+  it.each(['9999-12-31T06:00:00', null, false, ''])('Returns false for invalid input: "%s"', (input) => {
+    expect(isISODateString(input)).toBeFalsy();
+  });
+});

test/type-predicate.test.ts

@@ -11,7 +11,6 @@ import {
   isFunction,
   isInteger,
   isIntString,
-  isISODateString,
   isIterable,
   isLengthAware,
   isNull,
@@ -323,19 +322,6 @@ describe('isIntString()', () => {
   });
 });
 
-describe('isISODateString()', () => {
-  it.each([new Date(0).toISOString(), new Date('+9999-12-31').toISOString()])(
-    'Returns true for valid input: "%s"',
-    (input) => {
-      expect(isISODateString(input)).toBeTruthy();
-    },
-  );
-
-  it.each(['9999-12-31T06:00:00', null, false, ''])('Returns false for invalid input: "%s"', (input) => {
-    expect(isISODateString(input)).toBeFalsy();
-  });
-});
-
 describe('isDigitsString()', () => {
   it('Returns true for valid input', () => {
     expect(isDigitsString('12345')).toBeTruthy();