@duplojs/utils 1.4.57 → 1.4.59

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

package/dist/date/tomorrow.cjs

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

package/dist/date/tomorrow.d.ts

@@ -1,19 +1,24 @@
+import { TheDate } from "./theDate";
 /**
- * Returns tomorrow's date as TheDate.
+ * Returns an instant approximately one day after now as `TheDate`.
  * 
- * Signature: `tomorrow()` → returns a value
- * 
- * The input value is not mutated.
+ * Signature: `tomorrow()` → `TheDate`
  * 
  * ```ts
- * const result = D.tomorrow();
- * // result: "date" + timestamp
+ * const value = D.tomorrow();
+ * // value: TheDate
+ * 
+ * const iso = D.toISOString(value);
+ * // iso: string
  * 
  * ```
  * 
+ * @remarks
+ * - Computed from current timestamp plus one day in milliseconds.
+ * 
  * @see https://utils.duplojs.dev/en/v1/api/date/tomorrow
  * 
  * @namespace D
  * 
  */
-export declare function tomorrow(): `date${number}+`;
+export declare function tomorrow(): TheDate;

package/dist/date/tomorrow.mjs

@@ -1,11 +1,12 @@
 import { millisecondsInOneDay } from './constants.mjs';
+import { TheDate } from './theDate.mjs';
 
 /**
  * {@include date/tomorrow/index.md}
  */
 function tomorrow() {
     const timestamp = Date.now() + millisecondsInOneDay;
-    return `date${timestamp}+`;
+    return TheDate.new(timestamp);
 }
 
 export { tomorrow };

package/dist/date/types/index.d.ts

@@ -1,9 +1,9 @@
-export * from "./theDate";
+export * from "./serializedTheDate";
 export * from "./isLeapYear";
 export * from "./unit";
 export * from "./month";
 export * from "./time";
 export * from "./isSafeYear";
 export * from "./spoolingDate";
-export * from "./theTime";
+export * from "./serializedTheTime";
 export * from "./spoolingTime";

package/dist/date/types/serializedTheDate.d.ts

@@ -0,0 +1 @@
+export type SerializedTheDate = `date${number}${"-" | "+"}`;

package/dist/date/types/serializedTheTime.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 type SerializedTheTime = `time${number}${"+" | "-"}`;

package/dist/date/types/spoolingDate.d.ts

@@ -1,6 +1,7 @@
+import type { TheDate } from "../theDate";
 import { type Timezone } from "../timezone";
 export interface SpoolingDate {
-    value: string | Date | number;
+    value: TheDate | string | Date | number;
     timezone?: Timezone;
     year?: number;
     month?: number;

package/dist/date/yesterday.cjs

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

package/dist/date/yesterday.d.ts

@@ -1,19 +1,24 @@
+import { TheDate } from "./theDate";
 /**
- * Returns yesterday's date as TheDate.
+ * Returns an instant approximately one day before now as `TheDate`.
  * 
- * Signature: `yesterday()` → returns a value
- * 
- * The input value is not mutated.
+ * Signature: `yesterday()` → `TheDate`
  * 
  * ```ts
- * const result = D.yesterday();
- * // result: "date" + timestamp
+ * const value = D.yesterday();
+ * // value: TheDate
+ * 
+ * const iso = D.toISOString(value);
+ * // iso: string
  * 
  * ```
  * 
+ * @remarks
+ * - Computed from current timestamp minus one day in milliseconds.
+ * 
  * @see https://utils.duplojs.dev/en/v1/api/date/yesterday
  * 
  * @namespace D
  * 
  */
-export declare function yesterday(): `date${number}+`;
+export declare function yesterday(): TheDate;

package/dist/date/yesterday.mjs

@@ -1,11 +1,12 @@
 import { millisecondsInOneDay } from './constants.mjs';
+import { TheDate } from './theDate.mjs';
 
 /**
  * {@include date/yesterday/index.md}
  */
 function yesterday() {
     const timestamp = Date.now() - millisecondsInOneDay;
-    return `date${timestamp}+`;
+    return TheDate.new(timestamp);
 }
 
 export { yesterday };

package/dist/generator/asyncGroup.cjs

@@ -0,0 +1,31 @@
+'use strict';
+
+var group = require('./group.cjs');
+
+function asyncGroup(...args) {
+    if (args.length === 1) {
+        const [theFunction] = args;
+        return (asyncIterator) => asyncGroup(asyncIterator, theFunction);
+    }
+    const [asyncIterator, theFunction] = args;
+    const result = {};
+    let index = 0;
+    return (async () => {
+        for await (const element of asyncIterator) {
+            const { group: group$1, value } = await theFunction(element, {
+                index,
+                output: group.groupOutput,
+            });
+            if (result[group$1]) {
+                result[group$1].push(value);
+            }
+            else {
+                result[group$1] = [value];
+            }
+            index++;
+        }
+        return result;
+    })();
+}
+
+exports.asyncGroup = asyncGroup;