@duplojs/utils 1.4.32 → 1.4.34

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;

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

@@ -1,4 +1,35 @@
 import type { TheDate, TheTime } from "../types";
+/**
+ * Adds a TheTime to a TheDate or TheTime.
+ * 
+ * **Supported call styles:**
+ * - Classic: `addTime(input, time)` → returns a value
+ * - Curried: `addTime(time)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const date = D.createTheDate(0);
+ * const time = D.createTheTime(3_600_000);
+ * 
+ * const result = D.addTime(date, time);
+ * // result: "date3600000+"
+ * 
+ * const result2 = D.addTime("time3000+", "time2000+");
+ * // result2: "time5000+"
+ * 
+ * const result3 = pipe(
+ * 	date,
+ * 	D.addTime("time1000+"),
+ * );
+ * // result3: "date3601000+"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/addTime
+ * 
+ * @namespace D
+ * 
+ */
 export declare function addTime<GenericInput extends TheDate>(time: TheTime): (input: GenericInput) => TheDate;
 export declare function addTime<GenericInput extends TheTime>(time: TheTime): (input: GenericInput) => TheTime;
 export declare function addTime<GenericInput extends TheDate>(input: GenericInput, time: TheTime): TheDate;

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

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

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

@@ -1,3 +1,33 @@
 import type { TheDate } from "../types";
+/**
+ * Adds years to a date.
+ * 
+ * **Supported call styles:**
+ * - Classic: `addYears(input, year)` → returns a value
+ * - Curried: `addYears(year)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2020-02-29");
+ * const result = D.addYears(input, 4);
+ * // result: "date1766707200000+" (29 february 2024)
+ * 
+ * const addOneYear = D.addYears(1);
+ * const result2 = addOneYear(input);
+ * // result2: "date1646006400000+" (28 february 2023)
+ * 
+ * pipe(
+ * 	input,
+ * 	D.addYears(4),
+ * ); // result: "date1766707200000+" (29 february 2024)
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/addYears
+ * 
+ * @namespace D
+ * 
+ */
 export declare function addYears<GenericInput extends TheDate, GenericYear extends number>(year: GenericYear): (input: GenericInput) => TheDate;
 export declare function addYears<GenericInput extends TheDate, GenericYear extends number>(input: GenericInput, year: GenericYear): TheDate;

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

@@ -1,3 +1,35 @@
 import type { TheDate } from "../types";
+/**
+ * Checks whether a date is between two dates (inclusive).
+ * 
+ * **Supported call styles:**
+ * - Classic: `between(input, greater, less)` → returns a value
+ * - Curried: `between(greater, less)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const start = D.create("2024-06-01");
+ * const end = D.create("2024-06-30");
+ * const input = D.create("2024-06-15");
+ * 
+ * const result = D.between(input, start, end);
+ * // result: true
+ * 
+ * pipe(
+ * 	input,
+ * 	D.between(start, end),
+ * ); // result: true
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Bounds are inclusive.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/between
+ * 
+ * @namespace D
+ * 
+ */
 export declare function between<GenericValue extends TheDate>(greater: TheDate, less: TheDate): (input: GenericValue) => boolean;
 export declare function between<GenericValue extends TheDate>(input: GenericValue, greater: TheDate, less: TheDate): boolean;