@duplojs/utils 1.4.57 → 1.4.58

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",

package/dist/date/timezone.d.ts

@@ -1,4 +1,31 @@
 import { type GetEnumValue } from "../common/enum";
+/**
+ * Provides the list of supported IANA timezone identifiers.
+ * 
+ * Signature: `timezone` → enum-like constant, `Timezone` → associated union type
+ * 
+ * Use these values with timezone-aware date functions (`getYear`, `format`, `applyTimezone`, etc.).
+ * 
+ * ```ts
+ * const input = D.create("2024-06-20", {
+ * 	hour: "12",
+ * });
+ * 
+ * const ParisTimezone = D.timezone["Europe/Paris"];
+ * // Timezone: "Europe/Paris"
+ * 
+ * const offset = D.getTimezoneOffset(input, "America/New_York");
+ * // offset: number
+ * ```
+ * 
+ * @remarks
+ * - Values follow the IANA timezone database naming.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/getTimezoneOffset
+ * 
+ * @namespace D
+ * 
+ */
 export declare const timezone: {
     "Africa/Abidjan": "Africa/Abidjan";
     "Africa/Accra": "Africa/Accra";

package/dist/date/timezone.mjs

@@ -1,5 +1,8 @@
 import { createEnum } from '../common/enum.mjs';
 
+/**
+ * {@include date/timezone/index.md}
+ */
 const timezone = createEnum([
     "Africa/Abidjan",
     "Africa/Accra",

package/dist/date/toISOString.cjs

@@ -1,13 +1,16 @@
 'use strict';
 
+var theDate = require('./theDate.cjs');
 var toNative = require('./toNative.cjs');
 
 /**
  * {@include date/toISOString/index.md}
  */
 function toISOString(input) {
-    const date = toNative.toNative(input);
-    return date.toISOString();
+    if (input instanceof theDate.TheDate) {
+        return input.toISOString();
+    }
+    return toNative.toNative(input).toISOString();
 }
 
 exports.toISOString = toISOString;

package/dist/date/toISOString.d.ts

@@ -1,21 +1,23 @@
-import type { TheDate } from "./types";
+import { TheDate } from "./theDate";
+import type { SerializedTheDate } from "./types";
 /**
- * Converts a date to an ISO string.
+ * Converts a date value to ISO-8601 string.
  * 
- * Signature: `toISOString(input)` → returns a value
+ * Signature: `toISOString(input)` → `string`
  * 
- * The input value is not mutated.
+ * `input` accepts `TheDate` or `SerializedTheDate`.
  * 
  * ```ts
- * const input = D.create("2023-11-14");
- * const result = D.toISOString(input);
- * // result: "2023-11-14T00:00:00.000Z"
+ * const input = D.create("2024-06-20");
+ * const iso = D.toISOString(input);
+ * // iso: string
+ * 
+ * const iso2 = D.toISOString("date1718841600000+");
+ * // iso2: string
  * 
  * pipe(
  * 	input,
  * 	D.toISOString,
- * ); // result: "2023-11-14T00:00:00.000Z"
- * 
  * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/date/toISOString
@@ -23,4 +25,4 @@ import type { TheDate } from "./types";
  * @namespace D
  * 
  */
-export declare function toISOString<GenericInput extends TheDate>(input: GenericInput): string;
+export declare function toISOString<GenericInput extends TheDate | SerializedTheDate>(input: GenericInput): string;

package/dist/date/toISOString.mjs

@@ -1,11 +1,14 @@
+import { TheDate } from './theDate.mjs';
 import { toNative } from './toNative.mjs';
 
 /**
  * {@include date/toISOString/index.md}
  */
 function toISOString(input) {
-    const date = toNative(input);
-    return date.toISOString();
+    if (input instanceof TheDate) {
+        return input.toISOString();
+    }
+    return toNative(input).toISOString();
 }
 
 export { toISOString };

package/dist/date/toNative.cjs

@@ -1,11 +1,15 @@
 'use strict';
 
+var theDate = require('./theDate.cjs');
 var toTimestamp = require('./toTimestamp.cjs');
 
 /**
  * {@include date/toNative/index.md}
  */
 function toNative(input) {
+    if (input instanceof theDate.TheDate) {
+        return input.toNative();
+    }
     const timestamp = toTimestamp.toTimestamp(input);
     return new Date(timestamp);
 }

package/dist/date/toNative.d.ts

@@ -1,21 +1,23 @@
-import type { TheDate } from "./types";
+import { TheDate } from "./theDate";
+import type { SerializedTheDate } from "./types";
 /**
- * Converts a TheDate to a native Date.
+ * Converts a date value to native JavaScript `Date`.
  * 
- * Signature: `toNative(input)` → returns a value
+ * Signature: `toNative(input)` → `Date`
  * 
- * The input value is not mutated.
+ * `input` accepts `TheDate` or `SerializedTheDate`.
  * 
  * ```ts
- * const input = D.create("2023-11-14");
- * const result = D.toNative(input);
- * // result: Date { time: 1699920000000 }
+ * const input = D.create("2024-06-20");
+ * const nativeDate = D.toNative(input);
+ * // nativeDate: Date
+ * 
+ * const nativeDate2 = D.toNative("date1718841600000+");
+ * // nativeDate2: Date
  * 
  * pipe(
  * 	input,
  * 	D.toNative,
- * ); // result: Date { time: 1699920000000 }
- * 
  * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/date/toNative
@@ -23,4 +25,4 @@ import type { TheDate } from "./types";
  * @namespace D
  * 
  */
-export declare function toNative<GenericInput extends TheDate>(input: GenericInput): Date;
+export declare function toNative<GenericInput extends TheDate | SerializedTheDate>(input: GenericInput): Date;

package/dist/date/toNative.mjs

@@ -1,9 +1,13 @@
+import { TheDate } from './theDate.mjs';
 import { toTimestamp } from './toTimestamp.mjs';
 
 /**
  * {@include date/toNative/index.md}
  */
 function toNative(input) {
+    if (input instanceof TheDate) {
+        return input.toNative();
+    }
     const timestamp = toTimestamp(input);
     return new Date(timestamp);
 }

package/dist/date/toTimeValue.cjs

@@ -1,13 +1,17 @@
 'use strict';
 
-var constants = require('./constants.cjs');
 var makeSafeTimeValue = require('./makeSafeTimeValue.cjs');
+var theTime = require('./theTime.cjs');
+var constants = require('./constants.cjs');
 
 /**
  * {@include date/toTimeValue/index.md}
  */
 function toTimeValue(input) {
-    const match = input.match(constants.theTimeRegex);
+    if (input instanceof theTime.TheTime) {
+        return input.toNative();
+    }
+    const match = input.match(constants.serializeTheTimeRegex);
     const { value, sign } = match.groups;
     return makeSafeTimeValue.makeSafeTimeValue(Number(sign === "-"
         ? `-${value}`

package/dist/date/toTimeValue.d.ts

@@ -1,21 +1,23 @@
-import { type TheTime } from "./types";
+import { TheTime } from "./theTime";
+import type { SerializedTheTime } from "./types";
 /**
- * Converts a TheTime to a millisecond value.
+ * Converts a duration value to a numeric millisecond time value.
  * 
- * Signature: `toTimeValue(input)` → returns a value
+ * Signature: `toTimeValue(input)` → `number`
  * 
- * The input value is not mutated.
+ * `input` accepts `TheTime` or `SerializedTheTime`.
  * 
  * ```ts
- * const input = D.createTheTime(90_000);
- * const result = D.toTimeValue(input);
- * // result: 90000
+ * const input = D.createTime(90_000, "millisecond");
+ * const value = D.toTimeValue(input);
+ * // value: number
  * 
- * const result2 = D.toTimeValue("time3600000-");
- * // result2: -3600000
+ * const value2 = D.toTimeValue("time3600000-");
+ * // value2: number
  * 
- * const result3 = D.toTimeValue("time90000+");
- * // result3: 90000
+ * pipe(
+ * 	input,
+ * 	D.toTimeValue,
  * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/date/toTimeValue
@@ -23,4 +25,4 @@ import { type TheTime } from "./types";
  * @namespace D
  * 
  */
-export declare function toTimeValue<GenericInput extends TheTime>(input: GenericInput): number;
+export declare function toTimeValue<GenericInput extends TheTime | SerializedTheTime>(input: GenericInput): number;

package/dist/date/toTimeValue.mjs

@@ -1,11 +1,15 @@
-import { theTimeRegex } from './constants.mjs';
 import { makeSafeTimeValue } from './makeSafeTimeValue.mjs';
+import { TheTime } from './theTime.mjs';
+import { serializeTheTimeRegex } from './constants.mjs';
 
 /**
  * {@include date/toTimeValue/index.md}
  */
 function toTimeValue(input) {
-    const match = input.match(theTimeRegex);
+    if (input instanceof TheTime) {
+        return input.toNative();
+    }
+    const match = input.match(serializeTheTimeRegex);
     const { value, sign } = match.groups;
     return makeSafeTimeValue(Number(sign === "-"
         ? `-${value}`

package/dist/date/toTimestamp.cjs

@@ -2,14 +2,16 @@
 
 var constants = require('./constants.cjs');
 var makeSafeTimestamp = require('./makeSafeTimestamp.cjs');
+var theDate = require('./theDate.cjs');
 
 /**
  * {@include date/toTimestamp/index.md}
  */
 function toTimestamp(input) {
-    const match = input.startsWith("date")
-        ? input.match(constants.theDateRegex)
-        : input.match(constants.theTimeRegex);
+    if (input instanceof theDate.TheDate) {
+        return input.getTime();
+    }
+    const match = input.match(constants.serializeTheDateRegex);
     const { value, sign } = match.groups;
     return makeSafeTimestamp.makeSafeTimestamp(Number(sign === "-"
         ? `-${value}`

package/dist/date/toTimestamp.d.ts

@@ -1,21 +1,23 @@
-import type { TheDate } from "./types";
+import { TheDate } from "./theDate";
+import type { SerializedTheDate } from "./types";
 /**
- * Converts a TheDate to a UTC timestamp.
+ * Converts a date value to UTC timestamp (milliseconds).
  * 
- * Signature: `toTimestamp(input)` → returns a value
+ * Signature: `toTimestamp(input)` → `number`
  * 
- * The input value is not mutated.
+ * `input` accepts `TheDate` or `SerializedTheDate`.
  * 
  * ```ts
  * const input = D.create("2024-06-20");
- * const result = D.toTimestamp(input);
- * // result: 1718841600000
+ * const timestamp = D.toTimestamp(input);
+ * // timestamp: number
+ * 
+ * const timestamp2 = D.toTimestamp("date1718841600000+");
+ * // timestamp2: number
  * 
  * pipe(
  * 	input,
  * 	D.toTimestamp,
- * ); // result: 1718841600000
- * 
  * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/date/toTimestamp
@@ -23,4 +25,4 @@ import type { TheDate } from "./types";
  * @namespace D
  * 
  */
-export declare function toTimestamp<GenericInput extends TheDate>(input: GenericInput): number;
+export declare function toTimestamp<GenericInput extends TheDate | SerializedTheDate>(input: GenericInput): number;

package/dist/date/toTimestamp.mjs

@@ -1,13 +1,15 @@
-import { theDateRegex, theTimeRegex } from './constants.mjs';
+import { serializeTheDateRegex } from './constants.mjs';
 import { makeSafeTimestamp } from './makeSafeTimestamp.mjs';
+import { TheDate } from './theDate.mjs';
 
 /**
  * {@include date/toTimestamp/index.md}
  */
 function toTimestamp(input) {
-    const match = input.startsWith("date")
-        ? input.match(theDateRegex)
-        : input.match(theTimeRegex);
+    if (input instanceof TheDate) {
+        return input.getTime();
+    }
+    const match = input.match(serializeTheDateRegex);
     const { value, sign } = match.groups;
     return makeSafeTimestamp(Number(sign === "-"
         ? `-${value}`

package/dist/date/today.cjs

@@ -1,11 +1,13 @@
 'use strict';
 
+var theDate = require('./theDate.cjs');
+
 /**
  * {@include date/today/index.md}
  */
 function today() {
     const timestamp = new Date().setUTCHours(0, 0, 0, 0);
-    return `date${timestamp}+`;
+    return theDate.TheDate.new(timestamp);
 }
 
 exports.today = today;

package/dist/date/today.d.ts

@@ -1,19 +1,26 @@
+import { TheDate } from "./theDate";
 /**
- * Returns today's date as TheDate.
+ * Returns current day at UTC midnight as `TheDate`.
  * 
- * Signature: `today()` → returns a value
- * 
- * The input value is not mutated.
+ * Signature: `today()` → `TheDate`
  * 
  * ```ts
- * const result = D.today();
- * // result: "date" + timestamp
+ * const value = D.today();
+ * // value: TheDate
+ * 
+ * const hour = D.getHour(value);
+ * // hour: 0
  * 
+ * const serialized = D.serialize(value);
+ * // serialized: SerializedTheDate
  * ```
  * 
+ * @remarks
+ * - Time part is normalized to `00:00:00.000` UTC.
+ * 
  * @see https://utils.duplojs.dev/en/v1/api/date/today
  * 
  * @namespace D
  * 
  */
-export declare function today(): `date${number}+`;
+export declare function today(): TheDate;

package/dist/date/today.mjs

@@ -1,9 +1,11 @@
+import { TheDate } from './theDate.mjs';
+
 /**
  * {@include date/today/index.md}
  */
 function today() {
     const timestamp = new Date().setUTCHours(0, 0, 0, 0);
-    return `date${timestamp}+`;
+    return TheDate.new(timestamp);
 }
 
 export { today };