@duplojs/utils 1.4.57 → 1.4.58

package/dist/date/operators/subtractYears.d.ts

@@ -1,29 +1,35 @@
-import type { TheDate } from "../types";
+import { TheDate } from "../theDate";
+import type { SerializedTheDate } from "../types";
 /**
- * Subtracts years from a date.
+ * Subtracts a number of calendar years from a date.
  * 
  * **Supported call styles:**
- * - Classic: `subtractYears(input, year)` → returns a value
- * - Curried: `subtractYears(year)` → returns a function waiting for the input
+ * - Classic: `subtractYears(input, year)` → `TheDate`
+ * - Curried: `subtractYears(year)` → `(input) => TheDate`
  * 
- * The input value is not mutated.
+ * `input` accepts `TheDate` or `SerializedTheDate`.
  * 
  * ```ts
  * const input = D.create("2024-06-20");
  * const result = D.subtractYears(input, 1);
- * // result: "date1687219200000+"
+ * // result: TheDate
+ * 
+ * const serialized = D.serialize(result);
+ * // serialized: SerializedTheDate
  * 
  * pipe(
- * 	input,
+ * 	serialized,
  * 	D.subtractYears(1),
- * ); // result: "date1687219200000+"
- * 
+ * ); // TheDate
  * ```
  * 
+ * @remarks
+ * - Uses UTC year arithmetic (`Date#setUTCFullYear` behavior).
+ * 
  * @see https://utils.duplojs.dev/en/v1/api/date/subtractYears
  * 
  * @namespace D
  * 
  */
-export declare function subtractYears<GenericInput extends TheDate, GenericYear extends number>(year: GenericYear): (input: GenericInput) => TheDate;
-export declare function subtractYears<GenericInput extends TheDate, GenericYear extends number>(input: GenericInput, year: GenericYear): TheDate;
+export declare function subtractYears<GenericInput extends TheDate | SerializedTheDate, GenericYear extends number>(year: GenericYear): (input: GenericInput) => TheDate;
+export declare function subtractYears<GenericInput extends TheDate | SerializedTheDate, GenericYear extends number>(input: GenericInput, year: GenericYear): TheDate;

package/dist/date/operators/subtractYears.mjs

@@ -1,4 +1,4 @@
-import { createTheDate } from '../createTheDate.mjs';
+import { TheDate } from '../theDate.mjs';
 import { toNative } from '../toNative.mjs';
 
 function subtractYears(...args) {
@@ -9,7 +9,7 @@ function subtractYears(...args) {
     const [input, year] = args;
     const date = toNative(input);
     date.setUTCFullYear(date.getUTCFullYear() - year);
-    return createTheDate(date.getTime());
+    return TheDate.new(date.getTime());
 }
 
 export { subtractYears };

package/dist/date/round.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var theDate = require('./theDate.cjs');
 var toNative = require('./toNative.cjs');
 
 const stepMapper = {
@@ -19,8 +20,7 @@ const stepMapper = {
 function round(input, unit = "day") {
     const date = toNative.toNative(input);
     const timestamp = stepMapper[unit](date);
-    const isNegative = timestamp < 0;
-    return `date${Math.abs(timestamp)}${isNegative ? "-" : "+"}`;
+    return theDate.TheDate.new(timestamp);
 }
 
 exports.round = round;

package/dist/date/round.d.ts

@@ -1,11 +1,12 @@
-import type { TheDate, Unit } from "./types";
+import { TheDate } from "./theDate";
+import type { SerializedTheDate, Unit } from "./types";
 export type RoundUnit = Exclude<Unit, "millisecond">;
 /**
- * Rounds a date to a unit.
+ * Rounds down a date to a UTC unit boundary.
  * 
- * Signature: `round(input, unit)` → returns a value
+ * Signature: `round(input, unit?)` → `TheDate`
  * 
- * The input value is not mutated.
+ * `input` accepts `TheDate` or `SerializedTheDate`. Default `unit` is `"day"`.
  * 
  * ```ts
  * const input = D.create("2024-06-20", {
@@ -14,25 +15,21 @@ export type RoundUnit = Exclude<Unit, "millisecond">;
  * 	second: "56",
  * 	millisecond: "789",
  * });
- * const result = D.round(input);
- * // result: "date1718841600000+"
  * 
- * const result2 = D.round(input, "month");
- * // result2: "date1717200000000+"
+ * const byDay = D.round(input);
+ * // byDay: TheDate
  * 
- * pipe(
- * 	input,
- * 	D.round,
- * ); // result: "date1718841600000+"
+ * const byMonth = D.round(input, "month");
+ * // byMonth: TheDate
  * 
  * ```
  * 
  * @remarks
- * - Rounds using the provided unit.
+ * - Supported units: `second`, `minute`, `hour`, `day`, `month`, `year`.
  * 
  * @see https://utils.duplojs.dev/en/v1/api/date/round
  * 
  * @namespace D
  * 
  */
-export declare function round(input: TheDate, unit?: RoundUnit): `date${number}-` | `date${number}+`;
+export declare function round(input: (TheDate | SerializedTheDate), unit?: RoundUnit): TheDate;

package/dist/date/round.mjs

@@ -1,3 +1,4 @@
+import { TheDate } from './theDate.mjs';
 import { toNative } from './toNative.mjs';
 
 const stepMapper = {
@@ -17,8 +18,7 @@ const stepMapper = {
 function round(input, unit = "day") {
     const date = toNative(input);
     const timestamp = stepMapper[unit](date);
-    const isNegative = timestamp < 0;
-    return `date${Math.abs(timestamp)}${isNegative ? "-" : "+"}`;
+    return TheDate.new(timestamp);
 }
 
 export { round };

package/dist/date/serialize.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+var theDate = require('./theDate.cjs');
+
+function serialize(input) {
+    if (input instanceof theDate.TheDate) {
+        const timestamp = input.getTime();
+        return `date${Math.abs(timestamp)}${timestamp > 0 ? "+" : "-"}`;
+    }
+    const number = input.toNative();
+    return `time${Math.abs(number)}${number > 0 ? "+" : "-"}`;
+}
+
+exports.serialize = serialize;

package/dist/date/serialize.d.ts

@@ -0,0 +1,41 @@
+import { TheDate } from "./theDate";
+import type { TheTime } from "./theTime";
+import type { SerializedTheTime } from "./types";
+import { type SerializedTheDate } from "./types/serializedTheDate";
+/**
+ * Serializes immutable date values into their string literal formats.
+ * 
+ * Supported call styles:
+ * - Classic: `serialize(input)` where `input` is `TheDate` or `TheTime`
+ * - Curried: not supported
+ * 
+ * `TheDate` values are serialized to `SerializedTheDate` (`date${number}${"+" | "-"}`), and `TheTime` values are serialized to `SerializedTheTime` (`time${number}${"+" | "-"}`).
+ * 
+ * ```ts
+ * const inputDate = D.create("2024-06-20");
+ * const resultDate = D.serialize(inputDate);
+ * // resultDate: SerializedTheDate
+ * 
+ * const inputTime = D.createTime(4, "day");
+ * const resultTime = D.serialize(inputTime);
+ * // resultTime: SerializedTheTime
+ * 
+ * const resultDate2 = D.serialize(
+ * 	D.create("2025-10-20"),
+ * );
+ * // resultDate2: SerializedTheDate
+ * 
+ * ```
+ * 
+ * @remarks
+ * - This function is the string bridge between immutable classes (`TheDate`, `TheTime`) and serialized literal types (`SerializedTheDate`, `SerializedTheTime`).
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/serialize
+ * @see https://utils.duplojs.dev/en/v1/api/date/theDate
+ * @see https://utils.duplojs.dev/en/v1/api/date/theTime
+ * 
+ * @namespace D
+ * 
+ */
+export declare function serialize(input: TheDate): SerializedTheDate;
+export declare function serialize(input: TheTime): SerializedTheTime;

package/dist/date/serialize.mjs

@@ -0,0 +1,12 @@
+import { TheDate } from './theDate.mjs';
+
+function serialize(input) {
+    if (input instanceof TheDate) {
+        const timestamp = input.getTime();
+        return `date${Math.abs(timestamp)}${timestamp > 0 ? "+" : "-"}`;
+    }
+    const number = input.toNative();
+    return `time${Math.abs(number)}${number > 0 ? "+" : "-"}`;
+}
+
+export { serialize };

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 {};