@duplojs/utils 1.4.57 → 1.4.59

package/dist/date/is.mjs

@@ -1,16 +1,11 @@
-import { theDateRegex } from './constants.mjs';
-import { isSafeTimestamp } from './isSafeTimestamp.mjs';
+import { TheDate } from './theDate.mjs';
 
 /**
  * {@include date/is/index.md}
  */
 function is(input) {
-    const theDateMatch = input.match(theDateRegex);
-    if (theDateMatch) {
-        const { value, sign } = theDateMatch.groups;
-        return isSafeTimestamp(Number(sign === "-"
-            ? `-${value}`
-            : value));
+    if (input instanceof TheDate) {
+        return true;
     }
     return false;
 }

package/dist/date/isSafeTimeValue.d.ts

@@ -1,23 +1,19 @@
 /**
- * Checks whether a time value is safe.
+ * Checks whether a time value is a safe integer inside supported time bounds.
  * 
- * Signature: `isSafeTimeValue(input)` → returns a value
- * 
- * The input value is not mutated.
+ * Signature: `isSafeTimeValue(timeValue)` → `boolean`
  * 
  * ```ts
- * const result = D.isSafeTimeValue(1_500);
- * // result: true
+ * const ok = D.isSafeTimeValue(1_500);
+ * // ok: true
  * 
- * const result2 = D.isSafeTimeValue(Number.NaN);
- * // result2: false
+ * const nan = D.isSafeTimeValue(Number.NaN);
+ * // nan: false
  * 
- * const result3 = D.isSafeTimeValue(9_007_199_254_740_992);
- * // result3: false
- * ```
+ * const tooLarge = D.isSafeTimeValue(9_007_199_254_740_992);
+ * // tooLarge: false
  * 
- * @remarks
- * - Checks for safe integers within the supported time range.
+ * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/date/isSafeTimeValue
  * 

package/dist/date/isSafeTimestamp.d.ts

@@ -1,29 +1,20 @@
 /**
- * Checks whether a timestamp is safe.
+ * Checks whether a timestamp is a safe integer inside supported date bounds.
  * 
- * Signature: `isSafeTimestamp(input)` → returns a value
- * 
- * The input value is not mutated.
+ * Signature: `isSafeTimestamp(timestamp)` → `boolean`
  * 
  * ```ts
- * const input = 1_700_000_000_000;
- * const result = D.isSafeTimestamp(input);
- * // result: true
+ * const ok = D.isSafeTimestamp(1_700_000_000_000);
+ * // ok: true
  * 
- * const input2 = 9_000_000_000_000_000;
- * const result2 = D.isSafeTimestamp(input2);
- * // result2: false
+ * const tooLarge = D.isSafeTimestamp(9_000_000_000_000_000);
+ * // tooLarge: false
  * 
  * pipe(
- * 	input,
+ * 	1_700_000_000_000,
  * 	D.isSafeTimestamp,
- * ); // result: true
- * 
  * ```
  * 
- * @remarks
- * - Checks against the engine min/max timestamp limits.
- * 
  * @see https://utils.duplojs.dev/en/v1/api/date/isSafeTimestamp
  * 
  * @namespace D

package/dist/date/isSerializedTheDate.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var constants = require('./constants.cjs');
+var isSafeTimestamp = require('./isSafeTimestamp.cjs');
+
+/**
+ * {@include date/isSerializedTheDate/index.md}
+ */
+function isSerializedTheDate(input) {
+    const serializeTheDateMatch = input.match(constants.serializeTheDateRegex);
+    if (serializeTheDateMatch) {
+        const { value, sign } = serializeTheDateMatch.groups;
+        return isSafeTimestamp.isSafeTimestamp(Number(sign === "-"
+            ? `-${value}`
+            : value));
+    }
+    return false;
+}
+
+exports.isSerializedTheDate = isSerializedTheDate;

package/dist/date/isSerializedTheDate.d.ts

@@ -0,0 +1,31 @@
+import type { SerializedTheDate } from "./types";
+/**
+ * Checks whether a string is a valid `SerializedTheDate`.
+ * 
+ * Signature: `isSerializedTheDate(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = "date1718841600000+";
+ * 
+ * if (D.isSerializedTheDate(input)) {
+ * 	// input: SerializedTheDate
+ * }
+ * 
+ * const result = D.isSerializedTheDate("date42-");
+ * // result: true
+ * 
+ * const result2 = D.isSerializedTheDate("2024-06-20");
+ * // result2: false
+ * ```
+ * 
+ * @remarks
+ * - A valid serialized date follows the pattern `date${number}${"+" | "-"}` and must contain a safe timestamp value.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/isSerializedTheDate
+ * 
+ * @namespace D
+ * 
+ */
+export declare function isSerializedTheDate(input: string): input is SerializedTheDate;

package/dist/date/isSerializedTheDate.mjs

@@ -0,0 +1,18 @@
+import { serializeTheDateRegex } from './constants.mjs';
+import { isSafeTimestamp } from './isSafeTimestamp.mjs';
+
+/**
+ * {@include date/isSerializedTheDate/index.md}
+ */
+function isSerializedTheDate(input) {
+    const serializeTheDateMatch = input.match(serializeTheDateRegex);
+    if (serializeTheDateMatch) {
+        const { value, sign } = serializeTheDateMatch.groups;
+        return isSafeTimestamp(Number(sign === "-"
+            ? `-${value}`
+            : value));
+    }
+    return false;
+}
+
+export { isSerializedTheDate };

package/dist/date/isSerializedTheTime.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var constants = require('./constants.cjs');
+var isSafeTimeValue = require('./isSafeTimeValue.cjs');
+
+/**
+ * {@include date/isSerializedTheTime/index.md}
+ */
+function isSerializedTheTime(input) {
+    const serializeTheTimeMatch = input.match(constants.serializeTheTimeRegex);
+    if (serializeTheTimeMatch) {
+        const { value, sign } = serializeTheTimeMatch.groups;
+        return isSafeTimeValue.isSafeTimeValue(Number(sign === "-"
+            ? `-${value}`
+            : value));
+    }
+    return false;
+}
+
+exports.isSerializedTheTime = isSerializedTheTime;

package/dist/date/isSerializedTheTime.d.ts

@@ -0,0 +1,31 @@
+import type { SerializedTheTime } from "./types";
+/**
+ * Checks whether a string is a valid `SerializedTheTime`.
+ * 
+ * Signature: `isSerializedTheTime(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = "time5400000+";
+ * 
+ * if (D.isSerializedTheTime(input)) {
+ * 	// input: SerializedTheTime
+ * }
+ * 
+ * const result = D.isSerializedTheTime("time1-");
+ * // result: true
+ * 
+ * const result2 = D.isSerializedTheTime("01:30:00");
+ * // result2: false
+ * ```
+ * 
+ * @remarks
+ * - A valid serialized time follows the pattern `time${number}${"+" | "-"}` and must contain a safe time value.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/isSerializedTheTime
+ * 
+ * @namespace D
+ * 
+ */
+export declare function isSerializedTheTime(input: string): input is SerializedTheTime;

package/dist/date/isSerializedTheTime.mjs

@@ -0,0 +1,18 @@
+import { serializeTheTimeRegex } from './constants.mjs';
+import { isSafeTimeValue } from './isSafeTimeValue.mjs';
+
+/**
+ * {@include date/isSerializedTheTime/index.md}
+ */
+function isSerializedTheTime(input) {
+    const serializeTheTimeMatch = input.match(serializeTheTimeRegex);
+    if (serializeTheTimeMatch) {
+        const { value, sign } = serializeTheTimeMatch.groups;
+        return isSafeTimeValue(Number(sign === "-"
+            ? `-${value}`
+            : value));
+    }
+    return false;
+}
+
+export { isSerializedTheTime };

package/dist/date/isTime.cjs

@@ -1,18 +1,13 @@
 'use strict';
 
-var constants = require('./constants.cjs');
-var isSafeTimestamp = require('./isSafeTimestamp.cjs');
+var theTime = require('./theTime.cjs');
 
 /**
  * {@include date/isTime/index.md}
  */
 function isTime(input) {
-    const theTimeMatch = input.match(constants.theTimeRegex);
-    if (theTimeMatch) {
-        const { value, sign } = theTimeMatch.groups;
-        return isSafeTimestamp.isSafeTimestamp(Number(sign === "-"
-            ? `-${value}`
-            : value));
+    if (input instanceof theTime.TheTime) {
+        return true;
     }
     return false;
 }

package/dist/date/isTime.d.ts

@@ -1,31 +1,24 @@
-import { type TheTime } from "./types";
+import { TheTime } from "./theTime";
 /**
- * Checks whether a string is a TheTime.
+ * Checks whether a value is an instance of `TheTime`.
  * 
- * Signature: `isTime(input)` → returns a value
- * 
- * The input value is not mutated.
+ * Signature: `isTime(input)` → `input is TheTime`
  * 
  * ```ts
- * const input = "time3600000+";
+ * const input = D.createTime(1, "hour") as unknown;
  * 
  * if (D.isTime(input)) {
  * 	// input: TheTime
  * }
  * 
- * const result = D.isTime("time3600000-");
- * // result: true
+ * const result = D.isTime(D.create("2024-06-20"));
+ * // result: false
  * 
- * const result2 = D.isTime("time99999999999999999+");
- * // result2: false
  * ```
  * 
- * @remarks
- * - Validates the string format and the safe time range.
- * 
  * @see https://utils.duplojs.dev/en/v1/api/date/isTime
  * 
  * @namespace D
  * 
  */
-export declare function isTime(input: string): input is TheTime;
+export declare function isTime(input: unknown): input is TheTime;

package/dist/date/isTime.mjs

@@ -1,16 +1,11 @@
-import { theTimeRegex } from './constants.mjs';
-import { isSafeTimestamp } from './isSafeTimestamp.mjs';
+import { TheTime } from './theTime.mjs';
 
 /**
  * {@include date/isTime/index.md}
  */
 function isTime(input) {
-    const theTimeMatch = input.match(theTimeRegex);
-    if (theTimeMatch) {
-        const { value, sign } = theTimeMatch.groups;
-        return isSafeTimestamp(Number(sign === "-"
-            ? `-${value}`
-            : value));
+    if (input instanceof TheTime) {
+        return true;
     }
     return false;
 }

package/dist/date/kind.cjs

@@ -0,0 +1,9 @@
+'use strict';
+
+var kind = require('../common/kind.cjs');
+
+const createDateKind = kind.createKindNamespace(
+// @ts-expect-error - reserved kind namespace
+"DuplojsUtilsDate");
+
+exports.createDateKind = createDateKind;

package/dist/date/kind.d.ts

@@ -0,0 +1 @@
+export declare const createDateKind: <GenericName extends string, GenericKindValue extends unknown = unknown>(name: GenericName & import("../string").ForbiddenString<GenericName, "@" | "/">) => import("../common").KindHandler<import("../common").KindDefinition<`@DuplojsUtilsDate/${GenericName}`, GenericKindValue>>;

package/dist/date/kind.mjs

@@ -0,0 +1,7 @@
+import { createKindNamespace } from '../common/kind.mjs';
+
+const createDateKind = createKindNamespace(
+// @ts-expect-error - reserved kind namespace
+"DuplojsUtilsDate");
+
+export { createDateKind };

package/dist/date/makeSafeTimeValue.d.ts

@@ -1,23 +1,24 @@
 /**
- * Clamps a time value to the supported safe range.
+ * Normalizes a time value into the supported safe range.
  * 
- * Signature: `makeSafeTimeValue(input)` → returns a value
- * 
- * The input value is not mutated.
+ * Signature: `makeSafeTimeValue(timeValue)` → `number`
  * 
  * ```ts
- * const result = D.makeSafeTimeValue(1.2);
- * // result: 1
+ * const rounded = D.makeSafeTimeValue(1.2);
+ * // rounded: 1
+ * 
+ * const fromNaN = D.makeSafeTimeValue(Number.NaN);
+ * // fromNaN: 0
  * 
- * const result2 = D.makeSafeTimeValue(Number.NaN);
- * // result2: 0
+ * const clamped = D.makeSafeTimeValue(Infinity);
+ * // clamped: 9007199254740991
  * 
- * const result3 = D.makeSafeTimeValue(Infinity);
- * // result3: 9007199254740991
  * ```
  * 
  * @remarks
- * - Rounds non-integers, replaces NaN with 0, and clamps to min/max bounds.
+ * - `NaN` becomes `0`.
+ * - Floating values are rounded.
+ * - Values outside bounds are clamped.
  * 
  * @see https://utils.duplojs.dev/en/v1/api/date/makeSafeTimeValue
  * 

package/dist/date/makeSafeTimestamp.d.ts

@@ -1,23 +1,24 @@
 /**
- * Clamps a timestamp to the supported safe range.
+ * Normalizes a timestamp into the supported safe range.
  * 
- * Signature: `makeSafeTimestamp(input)` → returns a value
- * 
- * The input value is not mutated.
+ * Signature: `makeSafeTimestamp(timestamp)` → `number`
  * 
  * ```ts
- * const result = D.makeSafeTimestamp(1_700_000_000_000.4);
- * // result: 1700000000000
+ * const rounded = D.makeSafeTimestamp(1_700_000_000_000.4);
+ * // rounded: 1700000000000
+ * 
+ * const fromNaN = D.makeSafeTimestamp(Number.NaN);
+ * // fromNaN: 0
  * 
- * const result2 = D.makeSafeTimestamp(Number.NaN);
- * // result2: 0
+ * const clamped = D.makeSafeTimestamp(8_640_000_000_000_500);
+ * // clamped: 8640000000000000
  * 
- * const result3 = D.makeSafeTimestamp(8_640_000_000_000_500);
- * // result3: 8640000000000000
  * ```
  * 
  * @remarks
- * - Rounds non-integers, replaces NaN with 0, and clamps to min/max bounds.
+ * - `NaN` becomes `0`.
+ * - Floating values are rounded.
+ * - Values outside bounds are clamped.
  * 
  * @see https://utils.duplojs.dev/en/v1/api/date/makeSafeTimestamp
  * 

package/dist/date/max.cjs

@@ -1,13 +1,13 @@
 'use strict';
 
-var createOrThrow = require('./createOrThrow.cjs');
+var theDate = require('./theDate.cjs');
 var toTimestamp = require('./toTimestamp.cjs');
 
 /**
  * {@include date/max/index.md}
  */
 function max(input) {
-    return createOrThrow.createOrThrow(Math.max(...input.map(toTimestamp.toTimestamp)));
+    return theDate.TheDate.new(Math.max(...input.map(toTimestamp.toTimestamp)));
 }
 
 exports.max = max;

package/dist/date/max.d.ts

@@ -1,22 +1,22 @@
-import { type AnyTuple } from "../common";
-import { type TheDate } from "./types";
+import type { AnyTuple } from "../common/types/anyTuple";
+import { TheDate } from "./theDate";
+import type { SerializedTheDate } from "./types";
 /**
- * Returns the latest date from an iterable.
+ * Returns the greatest date from a tuple of date values.
  * 
- * Signature: `max(input)` → returns a value
- * 
- * The input value is not mutated.
+ * Signature: `max(input)` → `TheDate`
  * 
  * ```ts
- * const input = [D.yesterday(), D.today(), D.tomorrow()] as const;
+ * const input = [
+ * 	D.create("2024-06-20"),
+ * 	"date1718668800000+",
+ * 	D.create("2024-06-25"),
+ * ] as const;
  * 
- * const result = D.max(input);
+ * const value = D.max(input);
+ * // value: TheDate
  * 
  * pipe(
- * 	input,
- * 	D.max,
- * );
- * 
  * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/date/max
@@ -24,4 +24,4 @@ import { type TheDate } from "./types";
  * @namespace D
  * 
  */
-export declare function max<GenericInput extends AnyTuple<TheDate>>(input: GenericInput): `date${number}-` | `date${number}+`;
+export declare function max<GenericInput extends AnyTuple<TheDate | SerializedTheDate>>(input: GenericInput): TheDate;

package/dist/date/max.mjs

@@ -1,11 +1,11 @@
-import { createOrThrow } from './createOrThrow.mjs';
+import { TheDate } from './theDate.mjs';
 import { toTimestamp } from './toTimestamp.mjs';
 
 /**
  * {@include date/max/index.md}
  */
 function max(input) {
-    return createOrThrow(Math.max(...input.map(toTimestamp)));
+    return TheDate.new(Math.max(...input.map(toTimestamp)));
 }
 
 export { max };

package/dist/date/maxTime.cjs

@@ -1,13 +1,13 @@
 'use strict';
 
-var createTheTime = require('./createTheTime.cjs');
+var theTime = require('./theTime.cjs');
 var toTimeValue = require('./toTimeValue.cjs');
 
 /**
  * {@include date/maxTime/index.md}
  */
 function maxTime(input) {
-    return createTheTime.createTheTime(Math.max(...input.map(toTimeValue.toTimeValue)));
+    return theTime.TheTime.new(Math.max(...input.map(toTimeValue.toTimeValue)));
 }
 
 exports.maxTime = maxTime;

package/dist/date/maxTime.d.ts

@@ -1,31 +1,23 @@
-import { type AnyTuple } from "../common";
-import { type TheTime } from "./types";
+import type { AnyTuple } from "../common/types/anyTuple";
+import { TheTime } from "./theTime";
+import type { SerializedTheTime } from "./types";
 /**
- * Returns the largest time from an iterable.
+ * Returns the greatest duration from a tuple of time values.
  * 
- * Signature: `maxTime(input)` → returns a value
- * 
- * The input value is not mutated.
+ * Signature: `maxTime(input)` → `TheTime`
  * 
  * ```ts
- * const result = D.maxTime([
- * 	D.createTheTime(3_000),
- * 	D.createTheTime(1_000),
- * 	D.createTheTime(2_000),
- * ]);
- * // result: "time3000+"
+ * const value = D.maxTime([
+ * 	D.createTime(3_000, "millisecond"),
+ * 	D.createTime(1_000, "millisecond"),
+ * 	"time2000+",
+ * ] as const);
+ * // value: TheTime
  * 
- * const result2 = D.maxTime([
+ * const value2 = D.maxTime([
  * 	"time3000-",
  * 	"time1000-",
  * ] as const);
- * // result2: "time1000-"
- * 
- * const result3 = D.maxTime([
- * 	"time500+",
- * 	"time100+",
- * ] as const);
- * // result3: "time500+"
  * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/date/maxTime
@@ -33,4 +25,4 @@ import { type TheTime } from "./types";
  * @namespace D
  * 
  */
-export declare function maxTime<GenericInput extends AnyTuple<TheTime>>(input: GenericInput): `time${number}-` | `time${number}+`;
+export declare function maxTime<GenericInput extends AnyTuple<TheTime | SerializedTheTime>>(input: GenericInput): TheTime;

package/dist/date/maxTime.mjs

@@ -1,11 +1,11 @@
-import { createTheTime } from './createTheTime.mjs';
+import { TheTime } from './theTime.mjs';
 import { toTimeValue } from './toTimeValue.mjs';
 
 /**
  * {@include date/maxTime/index.md}
  */
 function maxTime(input) {
-    return createTheTime(Math.max(...input.map(toTimeValue)));
+    return TheTime.new(Math.max(...input.map(toTimeValue)));
 }
 
 export { maxTime };

package/dist/date/min.cjs

@@ -1,13 +1,13 @@
 'use strict';
 
-var createOrThrow = require('./createOrThrow.cjs');
 var toTimestamp = require('./toTimestamp.cjs');
+var theDate = require('./theDate.cjs');
 
 /**
  * {@include date/min/index.md}
  */
 function min(input) {
-    return createOrThrow.createOrThrow(Math.min(...input.map(toTimestamp.toTimestamp)));
+    return theDate.TheDate.new(Math.min(...input.map(toTimestamp.toTimestamp)));
 }
 
 exports.min = min;

package/dist/date/min.d.ts

@@ -1,22 +1,22 @@
-import { type AnyTuple } from "../common";
-import { type TheDate } from "./types";
+import type { AnyTuple } from "../common/types/anyTuple";
+import { TheDate } from "./theDate";
+import type { SerializedTheDate } from "./types";
 /**
- * Returns the earliest date from an iterable.
+ * Returns the smallest date from a tuple of date values.
  * 
- * Signature: `min(input)` → returns a value
- * 
- * The input value is not mutated.
+ * Signature: `min(input)` → `TheDate`
  * 
  * ```ts
- * const input = [D.yesterday(), D.today(), D.tomorrow()] as const;
+ * const input = [
+ * 	D.create("2024-06-20"),
+ * 	"date1718668800000+",
+ * 	D.create("2024-06-25"),
+ * ] as const;
  * 
- * const result = D.min(input);
+ * const value = D.min(input);
+ * // value: TheDate
  * 
  * pipe(
- * 	input,
- * 	D.min,
- * );
- * 
  * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/date/min
@@ -24,4 +24,4 @@ import { type TheDate } from "./types";
  * @namespace D
  * 
  */
-export declare function min<GenericInput extends AnyTuple<TheDate>>(input: GenericInput): `date${number}-` | `date${number}+`;
+export declare function min<GenericInput extends AnyTuple<TheDate | SerializedTheDate>>(input: GenericInput): TheDate;

package/dist/date/min.mjs

@@ -1,11 +1,11 @@
-import { createOrThrow } from './createOrThrow.mjs';
 import { toTimestamp } from './toTimestamp.mjs';
+import { TheDate } from './theDate.mjs';
 
 /**
  * {@include date/min/index.md}
  */
 function min(input) {
-    return createOrThrow(Math.min(...input.map(toTimestamp)));
+    return TheDate.new(Math.min(...input.map(toTimestamp)));
 }
 
 export { min };

package/dist/date/minTime.cjs

@@ -1,13 +1,13 @@
 'use strict';
 
-var createTheTime = require('./createTheTime.cjs');
+var theTime = require('./theTime.cjs');
 var toTimeValue = require('./toTimeValue.cjs');
 
 /**
  * {@include date/minTime/index.md}
  */
 function minTime(input) {
-    return createTheTime.createTheTime(Math.min(...input.map(toTimeValue.toTimeValue)));
+    return theTime.TheTime.new(Math.min(...input.map(toTimeValue.toTimeValue)));
 }
 
 exports.minTime = minTime;