@duplojs/utils 1.4.57 → 1.4.59

package/dist/date/sort.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var createOrThrow = require('./createOrThrow.cjs');
 var toTimestamp = require('./toTimestamp.cjs');
+var theDate = require('./theDate.cjs');
 
 function sort(...args) {
     if (args.length === 1) {
@@ -14,7 +14,7 @@ function sort(...args) {
         .sort(type === "DSC"
         ? (first, second) => second - first
         : (first, second) => first - second)
-        .map(createOrThrow.createOrThrow);
+        .map(theDate.TheDate.new);
 }
 
 exports.sort = sort;

package/dist/date/sort.d.ts

@@ -1,33 +1,34 @@
-import { type SortType } from "../common";
-import { type TheDate } from "./types";
+import type { SortType } from "../common/types/sortType";
+import { TheDate } from "./theDate";
+import type { SerializedTheDate } from "./types";
 /**
- * Sorts dates in ascending or descending order.
+ * Sorts date values and returns normalized `TheDate[]`.
  * 
  * **Supported call styles:**
- * - Classic: `sort(array, type)` → returns a value
- * - Curried: `sort(type)` → returns a function waiting for the input
- * 
- * The input value is not mutated.
+ * - Classic: `sort(array, type)` → `TheDate[]`
+ * - Curried: `sort(type)` → `(array) => TheDate[]`
  * 
  * ```ts
- * const input = [D.tomorrow(), D.yesterday(), D.today()] as const;
+ * const input = [
+ * 	D.create("2024-06-03"),
+ * 	"date1717286400000+",
+ * 	D.create("2024-06-01"),
+ * ] as const;
  * 
- * const result = D.sort(input, "ASC");
+ * const asc = D.sort(input, "ASC");
+ * // asc: TheDate[]
  * 
  * pipe(
  * 	input,
- * 	D.sort("ASC"),
- * );
- * 
  * ```
  * 
  * @remarks
- * - Sort order uses "ASC" or "DSC".
+ * - `type` is `"ASC"` or `"DSC"`.
  * 
  * @see https://utils.duplojs.dev/en/v1/api/date/sort
  * 
  * @namespace D
  * 
  */
-export declare function sort<GenericArray extends readonly TheDate[]>(type: SortType): (array: GenericArray) => TheDate[];
-export declare function sort<GenericArray extends readonly TheDate[]>(array: GenericArray, type: SortType): TheDate[];
+export declare function sort<GenericArray extends readonly (TheDate | SerializedTheDate)[]>(type: SortType): (array: GenericArray) => TheDate[];
+export declare function sort<GenericArray extends readonly (TheDate | SerializedTheDate)[]>(array: GenericArray, type: SortType): TheDate[];

package/dist/date/sort.mjs

@@ -1,5 +1,5 @@
-import { createOrThrow } from './createOrThrow.mjs';
 import { toTimestamp } from './toTimestamp.mjs';
+import { TheDate } from './theDate.mjs';
 
 function sort(...args) {
     if (args.length === 1) {
@@ -12,7 +12,7 @@ function sort(...args) {
         .sort(type === "DSC"
         ? (first, second) => second - first
         : (first, second) => first - second)
-        .map(createOrThrow);
+        .map(TheDate.new);
 }
 
 export { sort };

package/dist/date/sortTimes.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var createTheTime = require('./createTheTime.cjs');
 var toTimeValue = require('./toTimeValue.cjs');
+var theTime = require('./theTime.cjs');
 
 function sortTimes(...args) {
     if (args.length === 1) {
@@ -14,7 +14,7 @@ function sortTimes(...args) {
         .sort(type === "DSC"
         ? (first, second) => second - first
         : (first, second) => first - second)
-        .map(createTheTime.createTheTime);
+        .map(theTime.TheTime.new);
 }
 
 exports.sortTimes = sortTimes;

package/dist/date/sortTimes.d.ts

@@ -1,40 +1,34 @@
-import { type SortType } from "../common";
-import { type TheTime } from "./types";
+import type { SortType } from "../common/types/sortType";
+import { TheTime } from "./theTime";
+import type { SerializedTheTime } from "./types/serializedTheTime";
 /**
- * Sorts time values in ascending or descending order.
+ * Sorts duration values and returns normalized `TheTime[]`.
  * 
  * **Supported call styles:**
- * - Classic: `sortTimes(array, type)` → returns a value
- * - Curried: `sortTimes(type)` → returns a function waiting for the input
- * 
- * The input value is not mutated.
+ * - Classic: `sortTimes(array, type)` → `TheTime[]`
+ * - Curried: `sortTimes(type)` → `(array) => TheTime[]`
  * 
  * ```ts
  * const input = [
- * 	D.createTheTime(3_000),
- * 	D.createTheTime(1_000),
- * 	D.createTheTime(2_000),
- * ];
- * 
- * const result = D.sortTimes(input, "ASC");
- * // result: ["time1000+", "time2000+", "time3000+"]
+ * 	D.createTime(3_000, "millisecond"),
+ * 	"time1000+",
+ * 	D.createTime(2_000, "millisecond"),
+ * ] as const;
  * 
- * const result2 = D.sortTimes(input, "DSC");
- * // result2: ["time3000+", "time2000+", "time1000+"]
+ * const asc = D.sortTimes(input, "ASC");
+ * // asc: TheTime[]
  * 
  * pipe(
  * 	input,
- * 	D.sortTimes("ASC"),
- * ); // result: ["time1000+", "time2000+", "time3000+"]
  * ```
  * 
  * @remarks
- * - Sort order uses "ASC" or "DSC".
+ * - `type` is `"ASC"` or `"DSC"`.
  * 
  * @see https://utils.duplojs.dev/en/v1/api/date/sortTimes
  * 
  * @namespace D
  * 
  */
-export declare function sortTimes<GenericArray extends readonly TheTime[]>(type: SortType): (array: GenericArray) => TheTime[];
-export declare function sortTimes<GenericArray extends readonly TheTime[]>(array: GenericArray, type: SortType): TheTime[];
+export declare function sortTimes<GenericArray extends readonly (TheTime | SerializedTheTime)[]>(type: SortType): (array: GenericArray) => TheTime[];
+export declare function sortTimes<GenericArray extends readonly (TheTime | SerializedTheTime)[]>(array: GenericArray, type: SortType): TheTime[];

package/dist/date/sortTimes.mjs

@@ -1,5 +1,5 @@
-import { createTheTime } from './createTheTime.mjs';
 import { toTimeValue } from './toTimeValue.mjs';
+import { TheTime } from './theTime.mjs';
 
 function sortTimes(...args) {
     if (args.length === 1) {
@@ -12,7 +12,7 @@ function sortTimes(...args) {
         .sort(type === "DSC"
         ? (first, second) => second - first
         : (first, second) => first - second)
-        .map(createTheTime);
+        .map(TheTime.new);
 }
 
 export { sortTimes };

package/dist/date/theDate.cjs

@@ -0,0 +1,124 @@
+'use strict';
+
+var kind = require('../common/kind.cjs');
+var kind$1 = require('./kind.cjs');
+var makeSafeTimestamp = require('./makeSafeTimestamp.cjs');
+var serialize = require('./serialize.cjs');
+
+const defaultKindValue = {};
+/**
+ * {@include date/theDate/index.md}
+ */
+class TheDate extends kind.kindHeritage("the-date", kind$1.createDateKind("the-date"), Date) {
+    constructor(timestamp) {
+        super(defaultKindValue, [timestamp]);
+    }
+    toNative() {
+        return new Date(this.getTime());
+    }
+    toString() {
+        return serialize.serialize(this);
+    }
+    toJSON() {
+        return serialize.serialize(this);
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setDate(_date) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setFullYear(_year, _month, _date) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setHours(_hours, _min, _sec, _ms) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setMilliseconds(_ms) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setMinutes(_min, _sec, _ms) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setMonth(_month, _date) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setSeconds(_sec, _ms) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setTime(_time) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCDate(_date) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCFullYear(_year, _month, _date) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCHours(_hours, _min, _sec, _ms) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCMilliseconds(_ms) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCMinutes(_min, _sec, _ms) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCMonth(_month, _date) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCSeconds(_sec, _ms) {
+        return this.getTime();
+    }
+    /**
+     * @internal
+     * @deprecated use DDate.create | DDate.createOrThrow function
+     */
+    static "new"(timestamp) {
+        return new TheDate(makeSafeTimestamp.makeSafeTimestamp(timestamp));
+    }
+}
+
+exports.TheDate = TheDate;

package/dist/date/theDate.d.ts

@@ -0,0 +1,114 @@
+import type { SerializedTheDate } from "./types/serializedTheDate";
+declare const TheDate_base: new (params: {
+    "@DuplojsUtilsDate/the-date"?: unknown;
+}, parentParams: readonly [value: string | number | Date]) => Date & import("../common/kind").Kind<import("../common/kind").KindDefinition<"the-date", unknown>, unknown> & import("../common/kind").Kind<import("../common/kind").KindDefinition<"@DuplojsUtilsDate/the-date", unknown>, unknown>;
+/**
+ * Represents an immutable date-time object (`TheDate`) based on UTC.
+ * 
+ * Signature: `TheDate` → immutable class extending `Date`
+ * 
+ * `TheDate` solves two recurring problems: accidental mutation of native `Date`, and ambiguity between object dates and transport formats. You manipulate a stable object in code, and serialize it explicitly when you need to cross process boundaries.
+ * 
+ * ```ts
+ * const theDate = D.create("2025-10-20");
+ * // theDate: TheDate
+ * 
+ * const timestamp = theDate.getTime();
+ * // timestamp: number
+ * 
+ * const nativeDate = theDate.toNative();
+ * // nativeDate: Date
+ * 
+ * const serialized = D.serialize(theDate);
+ * // serialized: SerializedTheDate
+ * 
+ * const yearInParis = D.getYear(theDate, "Europe/Paris");
+ * // yearInParis: number
+ * 
+ * const datePlusOneDay = D.addDays(theDate, 1);
+ * // datePlusOneDay: TheDate
+ * 
+ * const iso = D.toISOString(theDate);
+ * // iso: string
+ * 
+ * ```
+ * 
+ * @remarks
+ * - `TheDate` is immutable: mutation methods from `Date` are intentionally disabled.
+ * - Use `D.serialize(theDate)` to convert to `SerializedTheDate`.
+ * - Use `D.create(...)` / `D.createOrThrow(...)` to construct instances.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/theDate
+ * @see https://utils.duplojs.dev/en/v1/api/date/serialize
+ * @see https://utils.duplojs.dev/en/v1/api/date/create
+ * 
+ * @namespace D
+ * 
+ */
+export declare class TheDate extends TheDate_base {
+    private constructor();
+    toNative(): Date;
+    toString(): SerializedTheDate;
+    toJSON(): SerializedTheDate;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setDate(_date: number): number;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setFullYear(_year: number, _month?: number, _date?: number): number;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setHours(_hours: number, _min?: number, _sec?: number, _ms?: number): number;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setMilliseconds(_ms: number): number;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setMinutes(_min: number, _sec?: number, _ms?: number): number;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setMonth(_month: number, _date?: number): number;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setSeconds(_sec: number, _ms?: number): number;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setTime(_time: number): number;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCDate(_date: number): number;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCFullYear(_year: number, _month?: number, _date?: number): number;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCHours(_hours: number, _min?: number, _sec?: number, _ms?: number): number;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCMilliseconds(_ms: number): number;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCMinutes(_min: number, _sec?: number, _ms?: number): number;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCMonth(_month: number, _date?: number): number;
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCSeconds(_sec: number, _ms?: number): number;
+}
+export {};

package/dist/date/theDate.mjs

@@ -0,0 +1,122 @@
+import { kindHeritage } from '../common/kind.mjs';
+import { createDateKind } from './kind.mjs';
+import { makeSafeTimestamp } from './makeSafeTimestamp.mjs';
+import { serialize } from './serialize.mjs';
+
+const defaultKindValue = {};
+/**
+ * {@include date/theDate/index.md}
+ */
+class TheDate extends kindHeritage("the-date", createDateKind("the-date"), Date) {
+    constructor(timestamp) {
+        super(defaultKindValue, [timestamp]);
+    }
+    toNative() {
+        return new Date(this.getTime());
+    }
+    toString() {
+        return serialize(this);
+    }
+    toJSON() {
+        return serialize(this);
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setDate(_date) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setFullYear(_year, _month, _date) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setHours(_hours, _min, _sec, _ms) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setMilliseconds(_ms) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setMinutes(_min, _sec, _ms) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setMonth(_month, _date) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setSeconds(_sec, _ms) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setTime(_time) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCDate(_date) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCFullYear(_year, _month, _date) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCHours(_hours, _min, _sec, _ms) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCMilliseconds(_ms) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCMinutes(_min, _sec, _ms) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCMonth(_month, _date) {
+        return this.getTime();
+    }
+    /**
+     * @deprecated this method does not work on ImmutableDate
+     */
+    setUTCSeconds(_sec, _ms) {
+        return this.getTime();
+    }
+    /**
+     * @internal
+     * @deprecated use DDate.create | DDate.createOrThrow function
+     */
+    static "new"(timestamp) {
+        return new TheDate(makeSafeTimestamp(timestamp));
+    }
+}
+
+export { TheDate };

package/dist/date/theTime.cjs

@@ -0,0 +1,36 @@
+'use strict';
+
+var kind = require('../common/kind.cjs');
+var kind$1 = require('./kind.cjs');
+var makeSafeTimeValue = require('./makeSafeTimeValue.cjs');
+var serialize = require('./serialize.cjs');
+
+const defaultKindValue = {};
+/**
+ * {@include date/theTime/index.md}
+ */
+class TheTime extends kind.kindHeritage("the-time", kind$1.createDateKind("the-time")) {
+    timeValue;
+    constructor(timeValue) {
+        super(defaultKindValue);
+        this.timeValue = timeValue;
+    }
+    toNative() {
+        return this.timeValue;
+    }
+    toString() {
+        return serialize.serialize(this);
+    }
+    toJSON() {
+        return serialize.serialize(this);
+    }
+    /**
+     * @internal
+     * @deprecated use DDate.createTime | DDate.createTimeOrThrow function
+     */
+    static "new"(time) {
+        return new TheTime(makeSafeTimeValue.makeSafeTimeValue(time));
+    }
+}
+
+exports.TheTime = TheTime;

package/dist/date/theTime.d.ts

@@ -0,0 +1,53 @@
+import { type SerializedTheTime } from "./types";
+declare const TheTime_base: new (params?: {
+    "@DuplojsUtilsDate/the-time"?: unknown;
+} | undefined) => import("../common/kind").Kind<import("../common/kind").KindDefinition<"the-time", unknown>, unknown> & import("../common/kind").Kind<import("../common/kind").KindDefinition<"@DuplojsUtilsDate/the-time", unknown>, unknown>;
+/**
+ * Represents an immutable time value object (`TheTime`) stored in milliseconds.
+ * 
+ * Signature: `TheTime` → immutable class-like value object
+ * 
+ * `TheTime` solves unit-fragmentation issues (`hours`, `minutes`, `seconds`) by using a single safe millisecond representation while keeping strong typing and explicit serialization.
+ * 
+ * ```ts
+ * const theTime = D.createTime(2, "hour");
+ * // theTime: TheTime
+ * 
+ * const timeValue = theTime.toNative();
+ * // timeValue: number
+ * 
+ * const serialized = D.serialize(theTime);
+ * // serialized: SerializedTheTime
+ * 
+ * const date = D.create("2025-10-20");
+ * const dateWithDuration = D.addTime(date, theTime);
+ * // dateWithDuration: TheDate
+ * 
+ * const threeHours = D.createTime(3, "hour");
+ * // threeHours: TheTime
+ * 
+ * const asMilliseconds = D.toTimeValue(theTime);
+ * // asMilliseconds: number
+ * ```
+ * 
+ * @remarks
+ * - `TheTime` is not a `number`, but it behaves as an immutable numeric time value.
+ * - Date unit operators (`addMinutes`, `subtractDays`, etc.) target `TheDate`; `TheTime` is used as a normalized duration value.
+ * - Use `D.serialize(theTime)` to convert to `SerializedTheTime`.
+ * - Use `D.createTime(...)` / `D.createTimeOrThrow(...)` to construct instances.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/theTime
+ * @see https://utils.duplojs.dev/en/v1/api/date/serialize
+ * @see https://utils.duplojs.dev/en/v1/api/date/createTime
+ * 
+ * @namespace D
+ * 
+ */
+export declare class TheTime extends TheTime_base {
+    private timeValue;
+    private constructor();
+    toNative(): number;
+    toString(): SerializedTheTime;
+    toJSON(): SerializedTheTime;
+}
+export {};

package/dist/date/theTime.mjs

@@ -0,0 +1,34 @@
+import { kindHeritage } from '../common/kind.mjs';
+import { createDateKind } from './kind.mjs';
+import { makeSafeTimeValue } from './makeSafeTimeValue.mjs';
+import { serialize } from './serialize.mjs';
+
+const defaultKindValue = {};
+/**
+ * {@include date/theTime/index.md}
+ */
+class TheTime extends kindHeritage("the-time", createDateKind("the-time")) {
+    timeValue;
+    constructor(timeValue) {
+        super(defaultKindValue);
+        this.timeValue = timeValue;
+    }
+    toNative() {
+        return this.timeValue;
+    }
+    toString() {
+        return serialize(this);
+    }
+    toJSON() {
+        return serialize(this);
+    }
+    /**
+     * @internal
+     * @deprecated use DDate.createTime | DDate.createTimeOrThrow function
+     */
+    static "new"(time) {
+        return new TheTime(makeSafeTimeValue(time));
+    }
+}
+
+export { TheTime };

package/dist/date/timezone.cjs

@@ -2,6 +2,9 @@
 
 var _enum = require('../common/enum.cjs');
 
+/**
+ * {@include date/timezone/index.md}
+ */
 const timezone = _enum.createEnum([
     "Africa/Abidjan",
     "Africa/Accra",