@duplojs/utils 1.3.32 → 1.4.33

package/dist/date/isSafeTimeValue.mjs

@@ -1,5 +1,8 @@
 import { minTimeValue, maxTimeValue } from './constants.mjs';
 
+/**
+ * {@include date/isSafeTimeValue/index.md}
+ */
 function isSafeTimeValue(timeValue) {
     if (!Number.isSafeInteger(timeValue)) {
         return false;

package/dist/date/isSafeTimestamp.cjs

@@ -2,6 +2,9 @@
 
 var constants = require('./constants.cjs');
 
+/**
+ * {@include date/isSafeTimestamp/index.md}
+ */
 function isSafeTimestamp(timestamp) {
     if (!Number.isSafeInteger(timestamp)) {
         return false;

package/dist/date/isSafeTimestamp.d.ts

@@ -1 +1,32 @@
+/**
+ * Checks whether a timestamp is safe.
+ * 
+ * Signature: `isSafeTimestamp(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = 1_700_000_000_000;
+ * const result = D.isSafeTimestamp(input);
+ * // result: true
+ * 
+ * const input2 = 9_000_000_000_000_000;
+ * const result2 = D.isSafeTimestamp(input2);
+ * // result2: false
+ * 
+ * pipe(
+ * 	input,
+ * 	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
+ * 
+ */
 export declare function isSafeTimestamp(timestamp: number): boolean;

package/dist/date/isSafeTimestamp.mjs

@@ -1,5 +1,8 @@
 import { minTimestamp, maxTimestamp } from './constants.mjs';
 
+/**
+ * {@include date/isSafeTimestamp/index.md}
+ */
 function isSafeTimestamp(timestamp) {
     if (!Number.isSafeInteger(timestamp)) {
         return false;

package/dist/date/isTime.cjs

@@ -3,6 +3,9 @@
 var constants = require('./constants.cjs');
 var isSafeTimestamp = require('./isSafeTimestamp.cjs');
 
+/**
+ * {@include date/isTime/index.md}
+ */
 function isTime(input) {
     const theTimeMatch = input.match(constants.theTimeRegex);
     if (theTimeMatch) {

package/dist/date/isTime.d.ts

@@ -1,2 +1,31 @@
 import { type TheTime } from "./types";
+/**
+ * Checks whether a string is a TheTime.
+ * 
+ * Signature: `isTime(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = "time3600000+";
+ * 
+ * if (D.isTime(input)) {
+ * 	// input: TheTime
+ * }
+ * 
+ * const result = D.isTime("time3600000-");
+ * // result: true
+ * 
+ * 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;

package/dist/date/isTime.mjs

@@ -1,6 +1,9 @@
 import { theTimeRegex } from './constants.mjs';
 import { isSafeTimestamp } from './isSafeTimestamp.mjs';
 
+/**
+ * {@include date/isTime/index.md}
+ */
 function isTime(input) {
     const theTimeMatch = input.match(theTimeRegex);
     if (theTimeMatch) {

package/dist/date/makeSafeTimeValue.cjs

@@ -2,6 +2,9 @@
 
 var constants = require('./constants.cjs');
 
+/**
+ * {@include date/makeSafeTimeValue/index.md}
+ */
 function makeSafeTimeValue(timeValue) {
     if (Number.isNaN(timeValue)) {
         return 0;

package/dist/date/makeSafeTimeValue.d.ts

@@ -1 +1,27 @@
+/**
+ * Clamps a time value to the supported safe range.
+ * 
+ * Signature: `makeSafeTimeValue(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const result = D.makeSafeTimeValue(1.2);
+ * // result: 1
+ * 
+ * const result2 = D.makeSafeTimeValue(Number.NaN);
+ * // result2: 0
+ * 
+ * const result3 = D.makeSafeTimeValue(Infinity);
+ * // result3: 9007199254740991
+ * ```
+ * 
+ * @remarks
+ * - Rounds non-integers, replaces NaN with 0, and clamps to min/max bounds.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/makeSafeTimeValue
+ * 
+ * @namespace D
+ * 
+ */
 export declare function makeSafeTimeValue(timeValue: number): number;

package/dist/date/makeSafeTimeValue.mjs

@@ -1,5 +1,8 @@
 import { maxTimeValue, minTimeValue } from './constants.mjs';
 
+/**
+ * {@include date/makeSafeTimeValue/index.md}
+ */
 function makeSafeTimeValue(timeValue) {
     if (Number.isNaN(timeValue)) {
         return 0;

package/dist/date/makeSafeTimestamp.cjs

@@ -2,6 +2,9 @@
 
 var constants = require('./constants.cjs');
 
+/**
+ * {@include date/makeSafeTimestamp/index.md}
+ */
 function makeSafeTimestamp(timestamp) {
     if (Number.isNaN(timestamp)) {
         return 0;

package/dist/date/makeSafeTimestamp.d.ts

@@ -1 +1,27 @@
+/**
+ * Clamps a timestamp to the supported safe range.
+ * 
+ * Signature: `makeSafeTimestamp(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const result = D.makeSafeTimestamp(1_700_000_000_000.4);
+ * // result: 1700000000000
+ * 
+ * const result2 = D.makeSafeTimestamp(Number.NaN);
+ * // result2: 0
+ * 
+ * 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.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/makeSafeTimestamp
+ * 
+ * @namespace D
+ * 
+ */
 export declare function makeSafeTimestamp(timestamp: number): number;

package/dist/date/makeSafeTimestamp.mjs

@@ -1,5 +1,8 @@
 import { maxTimestamp, minTimestamp } from './constants.mjs';
 
+/**
+ * {@include date/makeSafeTimestamp/index.md}
+ */
 function makeSafeTimestamp(timestamp) {
     if (Number.isNaN(timestamp)) {
         return 0;

package/dist/date/max.cjs

@@ -3,6 +3,9 @@
 var createOrThrow = require('./createOrThrow.cjs');
 var toTimestamp = require('./toTimestamp.cjs');
 
+/**
+ * {@include date/max/index.md}
+ */
 function max(input) {
     return createOrThrow.createOrThrow(Math.max(...input.map(toTimestamp.toTimestamp)));
 }

package/dist/date/max.d.ts

@@ -1,3 +1,27 @@
 import { type AnyTuple } from "../common";
 import { type TheDate } from "./types";
+/**
+ * Returns the latest date from an iterable.
+ * 
+ * Signature: `max(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = [D.yesterday(), D.today(), D.tomorrow()] as const;
+ * 
+ * const result = D.max(input);
+ * 
+ * pipe(
+ * 	input,
+ * 	D.max,
+ * );
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/max
+ * 
+ * @namespace D
+ * 
+ */
 export declare function max<GenericInput extends AnyTuple<TheDate>>(input: GenericInput): `date${number}-` | `date${number}+`;

package/dist/date/max.mjs

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

package/dist/date/maxTime.cjs

@@ -3,6 +3,9 @@
 var createTheTime = require('./createTheTime.cjs');
 var toTimeValue = require('./toTimeValue.cjs');
 
+/**
+ * {@include date/maxTime/index.md}
+ */
 function maxTime(input) {
     return createTheTime.createTheTime(Math.max(...input.map(toTimeValue.toTimeValue)));
 }

package/dist/date/maxTime.d.ts

@@ -1,3 +1,36 @@
 import { type AnyTuple } from "../common";
 import { type TheTime } from "./types";
+/**
+ * Returns the largest time from an iterable.
+ * 
+ * Signature: `maxTime(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const result = D.maxTime([
+ * 	D.createTheTime(3_000),
+ * 	D.createTheTime(1_000),
+ * 	D.createTheTime(2_000),
+ * ]);
+ * // result: "time3000+"
+ * 
+ * const result2 = 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
+ * 
+ * @namespace D
+ * 
+ */
 export declare function maxTime<GenericInput extends AnyTuple<TheTime>>(input: GenericInput): `time${number}-` | `time${number}+`;

package/dist/date/maxTime.mjs

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

package/dist/date/min.cjs

@@ -3,6 +3,9 @@
 var createOrThrow = require('./createOrThrow.cjs');
 var toTimestamp = require('./toTimestamp.cjs');
 
+/**
+ * {@include date/min/index.md}
+ */
 function min(input) {
     return createOrThrow.createOrThrow(Math.min(...input.map(toTimestamp.toTimestamp)));
 }

package/dist/date/min.d.ts

@@ -1,3 +1,27 @@
 import { type AnyTuple } from "../common";
 import { type TheDate } from "./types";
+/**
+ * Returns the earliest date from an iterable.
+ * 
+ * Signature: `min(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = [D.yesterday(), D.today(), D.tomorrow()] as const;
+ * 
+ * const result = D.min(input);
+ * 
+ * pipe(
+ * 	input,
+ * 	D.min,
+ * );
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/min
+ * 
+ * @namespace D
+ * 
+ */
 export declare function min<GenericInput extends AnyTuple<TheDate>>(input: GenericInput): `date${number}-` | `date${number}+`;

package/dist/date/min.mjs

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

package/dist/date/minTime.cjs

@@ -3,6 +3,9 @@
 var createTheTime = require('./createTheTime.cjs');
 var toTimeValue = require('./toTimeValue.cjs');
 
+/**
+ * {@include date/minTime/index.md}
+ */
 function minTime(input) {
     return createTheTime.createTheTime(Math.min(...input.map(toTimeValue.toTimeValue)));
 }

package/dist/date/minTime.d.ts

@@ -1,3 +1,36 @@
 import { type AnyTuple } from "../common";
 import { type TheTime } from "./types";
+/**
+ * Returns the smallest time from an iterable.
+ * 
+ * Signature: `minTime(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const result = D.minTime([
+ * 	D.createTheTime(3_000),
+ * 	D.createTheTime(1_000),
+ * 	D.createTheTime(2_000),
+ * ]);
+ * // result: "time1000+"
+ * 
+ * const result2 = D.minTime([
+ * 	"time3000-",
+ * 	"time1000-",
+ * ] as const);
+ * // result2: "time3000-"
+ * 
+ * const result3 = D.minTime([
+ * 	"time500+",
+ * 	"time100+",
+ * ] as const);
+ * // result3: "time100+"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/minTime
+ * 
+ * @namespace D
+ * 
+ */
 export declare function minTime<GenericInput extends AnyTuple<TheTime>>(input: GenericInput): `time${number}-` | `time${number}+`;

package/dist/date/minTime.mjs

@@ -1,6 +1,9 @@
 import { createTheTime } from './createTheTime.mjs';
 import { toTimeValue } from './toTimeValue.mjs';
 
+/**
+ * {@include date/minTime/index.md}
+ */
 function minTime(input) {
     return createTheTime(Math.min(...input.map(toTimeValue)));
 }

package/dist/date/now.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include date/now/index.md}
+ */
 function now() {
     const timestamp = Date.now();
     return `date${timestamp}+`;

package/dist/date/now.d.ts

@@ -1 +1,19 @@
+/**
+ * Returns the current date as TheDate.
+ * 
+ * Signature: `now()` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const result = D.now();
+ * // result: "date" + timestamp
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/now
+ * 
+ * @namespace D
+ * 
+ */
 export declare function now(): `date${number}+`;

package/dist/date/now.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include date/now/index.md}
+ */
 function now() {
     const timestamp = Date.now();
     return `date${timestamp}+`;

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

@@ -1,3 +1,29 @@
 import type { TheDate } from "../types";
+/**
+ * Adds days to a date.
+ * 
+ * **Supported call styles:**
+ * - Classic: `addDays(input, day)` → returns a value
+ * - Curried: `addDays(day)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-15");
+ * const result = D.addDays(input, 5);
+ * // result: "date1718928000000+"
+ * 
+ * pipe(
+ * 	input,
+ * 	D.addDays(5),
+ * ); // result: "date1718928000000+"
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/addDays
+ * 
+ * @namespace D
+ * 
+ */
 export declare function addDays<GenericInput extends TheDate, GenericDay extends number>(day: GenericDay): (input: GenericInput) => TheDate;
 export declare function addDays<GenericInput extends TheDate, GenericDay extends number>(input: GenericInput, day: GenericDay): TheDate;

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

@@ -1,3 +1,29 @@
 import type { TheDate } from "../types";
+/**
+ * Adds hours to a date.
+ * 
+ * **Supported call styles:**
+ * - Classic: `addHours(input, hour)` → returns a value
+ * - Curried: `addHours(hour)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-20");
+ * const result = D.addHours(input, 2);
+ * // result: "date1718848800000+"
+ * 
+ * pipe(
+ * 	input,
+ * 	D.addHours(2),
+ * ); // result: "date1718848800000+"
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/addHours
+ * 
+ * @namespace D
+ * 
+ */
 export declare function addHours<GenericInput extends TheDate, GenericHour extends number>(hour: GenericHour): (input: GenericInput) => TheDate;
 export declare function addHours<GenericInput extends TheDate, GenericHour extends number>(input: GenericInput, hour: GenericHour): TheDate;

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

@@ -1,3 +1,29 @@
 import type { TheDate } from "../types";
+/**
+ * Adds milliseconds to a date.
+ * 
+ * **Supported call styles:**
+ * - Classic: `addMilliseconds(input, millisecond)` → returns a value
+ * - Curried: `addMilliseconds(millisecond)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-20");
+ * const result = D.addMilliseconds(input, 10);
+ * // result: "date1718841600010+"
+ * 
+ * pipe(
+ * 	input,
+ * 	D.addMilliseconds(10),
+ * ); // result: "date1718841600010+"
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/addMilliseconds
+ * 
+ * @namespace D
+ * 
+ */
 export declare function addMilliseconds<GenericInput extends TheDate, GenericMillisecond extends number>(millisecond: GenericMillisecond): (input: GenericInput) => TheDate;
 export declare function addMilliseconds<GenericInput extends TheDate, GenericMillisecond extends number>(input: GenericInput, millisecond: GenericMillisecond): TheDate;

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

@@ -1,3 +1,29 @@
 import type { TheDate } from "../types";
+/**
+ * Adds minutes to a date.
+ * 
+ * **Supported call styles:**
+ * - Classic: `addMinutes(input, minute)` → returns a value
+ * - Curried: `addMinutes(minute)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-20");
+ * const result = D.addMinutes(input, 45);
+ * // result: "date1718844300000+"
+ * 
+ * pipe(
+ * 	input,
+ * 	D.addMinutes(45),
+ * ); // result: "date1718844300000+"
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/addMinutes
+ * 
+ * @namespace D
+ * 
+ */
 export declare function addMinutes<GenericInput extends TheDate, GenericMinute extends number>(minute: GenericMinute): (input: GenericInput) => TheDate;
 export declare function addMinutes<GenericInput extends TheDate, GenericMinute extends number>(input: GenericInput, minute: GenericMinute): TheDate;

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

@@ -1,3 +1,33 @@
 import type { TheDate } from "../types";
+/**
+ * Adds months to a date.
+ * 
+ * **Supported call styles:**
+ * - Classic: `addMonths(input, month)` → returns a value
+ * - Curried: `addMonths(month)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-01-31");
+ * const result = D.addMonths(input, 1);
+ * // result: "date1709251200000+" (29 february 2024)
+ * 
+ * const addQuarter = D.addMonths(3);
+ * const result2 = addQuarter(input);
+ * // result2: "date1719782400000+" (30 april 2024)
+ * 
+ * pipe(
+ * 	input,
+ * 	D.addMonths(1),
+ * ); // result: "date1709251200000+" (29 february 2024)
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/addMonths
+ * 
+ * @namespace D
+ * 
+ */
 export declare function addMonths<GenericInput extends TheDate, GenericMonth extends number>(month: GenericMonth): (input: GenericInput) => TheDate;
 export declare function addMonths<GenericInput extends TheDate, GenericMonth extends number>(input: GenericInput, month: GenericMonth): TheDate;

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

@@ -1,3 +1,29 @@
 import type { TheDate } from "../types";
+/**
+ * Adds seconds to a date.
+ * 
+ * **Supported call styles:**
+ * - Classic: `addSeconds(input, second)` → returns a value
+ * - Curried: `addSeconds(second)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-20");
+ * const result = D.addSeconds(input, 5);
+ * // result: "date1718841605000+"
+ * 
+ * pipe(
+ * 	input,
+ * 	D.addSeconds(5),
+ * ); // result: "date1718841605000+"
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/addSeconds
+ * 
+ * @namespace D
+ * 
+ */
 export declare function addSeconds<GenericInput extends TheDate, GenericSecond extends number>(second: GenericSecond): (input: GenericInput) => TheDate;
 export declare function addSeconds<GenericInput extends TheDate, GenericSecond extends number>(input: GenericInput, second: GenericSecond): TheDate;