@duplojs/utils 1.3.32 → 1.4.33

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

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

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

@@ -1,3 +1,29 @@
 import type { TheDate } from "../types";
+/**
+ * Subtracts seconds from a date.
+ * 
+ * **Supported call styles:**
+ * - Classic: `subtractSeconds(input, second)` → returns a value
+ * - Curried: `subtractSeconds(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.subtractSeconds(input, 30);
+ * // result: "date1718841570000+"
+ * 
+ * pipe(
+ * 	input,
+ * 	D.subtractSeconds(30),
+ * ); // result: "date1718841570000+"
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/subtractSeconds
+ * 
+ * @namespace D
+ * 
+ */
 export declare function subtractSeconds<GenericInput extends TheDate, GenericSecond extends number>(second: GenericSecond): (input: GenericInput) => TheDate;
 export declare function subtractSeconds<GenericInput extends TheDate, GenericSecond extends number>(input: GenericInput, second: GenericSecond): TheDate;

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

@@ -1,4 +1,35 @@
 import type { TheDate, TheTime } from "../types";
+/**
+ * Subtracts a TheTime from a TheDate or TheTime.
+ * 
+ * **Supported call styles:**
+ * - Classic: `subtractTime(input, time)` → returns a value
+ * - Curried: `subtractTime(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.subtractTime(date, time);
+ * // result: "date3600000-"
+ * 
+ * const result2 = D.subtractTime("time5000+", "time2000+");
+ * // result2: "time3000+"
+ * 
+ * const result3 = pipe(
+ * 	date,
+ * 	D.subtractTime("time1000+"),
+ * );
+ * // result3: "date3599000-"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/subtractTime
+ * 
+ * @namespace D
+ * 
+ */
 export declare function subtractTime<GenericInput extends TheDate>(time: TheTime): (input: GenericInput) => TheDate;
 export declare function subtractTime<GenericInput extends TheTime>(time: TheTime): (input: GenericInput) => TheTime;
 export declare function subtractTime<GenericInput extends TheDate>(input: GenericInput, time: TheTime): TheDate;

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

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

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

@@ -1,3 +1,29 @@
 import type { TheDate } from "../types";
+/**
+ * Subtracts years from a date.
+ * 
+ * **Supported call styles:**
+ * - Classic: `subtractYears(input, year)` → returns a value
+ * - Curried: `subtractYears(year)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-20");
+ * const result = D.subtractYears(input, 1);
+ * // result: "date1687219200000+"
+ * 
+ * pipe(
+ * 	input,
+ * 	D.subtractYears(1),
+ * ); // result: "date1687219200000+"
+ * 
+ * ```
+ * 
+ * @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;

package/dist/date/round.cjs

@@ -13,6 +13,9 @@ const stepMapper = {
         return date.setUTCHours(0, 0, 0, 0);
     },
 };
+/**
+ * {@include date/round/index.md}
+ */
 function round(input, unit = "day") {
     const date = toNative.toNative(input);
     const timestamp = stepMapper[unit](date);

package/dist/date/round.d.ts

@@ -1,3 +1,38 @@
 import type { TheDate, Unit } from "./types";
 export type RoundUnit = Exclude<Unit, "millisecond">;
+/**
+ * Rounds a date to a unit.
+ * 
+ * Signature: `round(input, unit)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2024-06-20", {
+ * 	hour: "12",
+ * 	minute: "34",
+ * 	second: "56",
+ * 	millisecond: "789",
+ * });
+ * const result = D.round(input);
+ * // result: "date1718841600000+"
+ * 
+ * const result2 = D.round(input, "month");
+ * // result2: "date1717200000000+"
+ * 
+ * pipe(
+ * 	input,
+ * 	D.round,
+ * ); // result: "date1718841600000+"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Rounds using the provided unit.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/round
+ * 
+ * @namespace D
+ * 
+ */
 export declare function round(input: TheDate, unit?: RoundUnit): `date${number}-` | `date${number}+`;

package/dist/date/round.mjs

@@ -11,6 +11,9 @@ const stepMapper = {
         return date.setUTCHours(0, 0, 0, 0);
     },
 };
+/**
+ * {@include date/round/index.md}
+ */
 function round(input, unit = "day") {
     const date = toNative(input);
     const timestamp = stepMapper[unit](date);

package/dist/date/sort.d.ts

@@ -1,4 +1,33 @@
 import { type SortType } from "../common";
 import { type TheDate } from "./types";
+/**
+ * Sorts dates in ascending or descending order.
+ * 
+ * **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.
+ * 
+ * ```ts
+ * const input = [D.tomorrow(), D.yesterday(), D.today()] as const;
+ * 
+ * const result = D.sort(input, "ASC");
+ * 
+ * pipe(
+ * 	input,
+ * 	D.sort("ASC"),
+ * );
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Sort order uses "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[];

package/dist/date/sortTimes.d.ts

@@ -1,4 +1,40 @@
 import { type SortType } from "../common";
 import { type TheTime } from "./types";
+/**
+ * Sorts time values in ascending or descending order.
+ * 
+ * **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.
+ * 
+ * ```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+"]
+ * 
+ * const result2 = D.sortTimes(input, "DSC");
+ * // result2: ["time3000+", "time2000+", "time1000+"]
+ * 
+ * pipe(
+ * 	input,
+ * 	D.sortTimes("ASC"),
+ * ); // result: ["time1000+", "time2000+", "time3000+"]
+ * ```
+ * 
+ * @remarks
+ * - Sort order uses "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[];

package/dist/date/toISOString.cjs

@@ -2,6 +2,9 @@
 
 var toNative = require('./toNative.cjs');
 
+/**
+ * {@include date/toISOString/index.md}
+ */
 function toISOString(input) {
     const date = toNative.toNative(input);
     return date.toISOString();

package/dist/date/toISOString.d.ts

@@ -1,2 +1,26 @@
 import type { TheDate } from "./types";
+/**
+ * Converts a date to an ISO string.
+ * 
+ * Signature: `toISOString(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2023-11-14");
+ * const result = D.toISOString(input);
+ * // result: "2023-11-14T00:00:00.000Z"
+ * 
+ * pipe(
+ * 	input,
+ * 	D.toISOString,
+ * ); // result: "2023-11-14T00:00:00.000Z"
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/toISOString
+ * 
+ * @namespace D
+ * 
+ */
 export declare function toISOString<GenericInput extends TheDate>(input: GenericInput): string;

package/dist/date/toISOString.mjs

@@ -1,5 +1,8 @@
 import { toNative } from './toNative.mjs';
 
+/**
+ * {@include date/toISOString/index.md}
+ */
 function toISOString(input) {
     const date = toNative(input);
     return date.toISOString();

package/dist/date/toNative.cjs

@@ -2,6 +2,9 @@
 
 var toTimestamp = require('./toTimestamp.cjs');
 
+/**
+ * {@include date/toNative/index.md}
+ */
 function toNative(input) {
     const timestamp = toTimestamp.toTimestamp(input);
     return new Date(timestamp);

package/dist/date/toNative.d.ts

@@ -1,2 +1,26 @@
 import type { TheDate } from "./types";
+/**
+ * Converts a TheDate to a native Date.
+ * 
+ * Signature: `toNative(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.create("2023-11-14");
+ * const result = D.toNative(input);
+ * // result: Date { time: 1699920000000 }
+ * 
+ * pipe(
+ * 	input,
+ * 	D.toNative,
+ * ); // result: Date { time: 1699920000000 }
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/toNative
+ * 
+ * @namespace D
+ * 
+ */
 export declare function toNative<GenericInput extends TheDate>(input: GenericInput): Date;

package/dist/date/toNative.mjs

@@ -1,5 +1,8 @@
 import { toTimestamp } from './toTimestamp.mjs';
 
+/**
+ * {@include date/toNative/index.md}
+ */
 function toNative(input) {
     const timestamp = toTimestamp(input);
     return new Date(timestamp);

package/dist/date/toTimeValue.cjs

@@ -3,6 +3,9 @@
 var constants = require('./constants.cjs');
 var makeSafeTimeValue = require('./makeSafeTimeValue.cjs');
 
+/**
+ * {@include date/toTimeValue/index.md}
+ */
 function toTimeValue(input) {
     const match = input.match(constants.theTimeRegex);
     const { value, sign } = match.groups;

package/dist/date/toTimeValue.d.ts

@@ -1,2 +1,26 @@
 import { type TheTime } from "./types";
+/**
+ * Converts a TheTime to a millisecond value.
+ * 
+ * Signature: `toTimeValue(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = D.createTheTime(90_000);
+ * const result = D.toTimeValue(input);
+ * // result: 90000
+ * 
+ * const result2 = D.toTimeValue("time3600000-");
+ * // result2: -3600000
+ * 
+ * const result3 = D.toTimeValue("time90000+");
+ * // result3: 90000
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/toTimeValue
+ * 
+ * @namespace D
+ * 
+ */
 export declare function toTimeValue<GenericInput extends TheTime>(input: GenericInput): number;

package/dist/date/toTimeValue.mjs

@@ -1,6 +1,9 @@
 import { theTimeRegex } from './constants.mjs';
 import { makeSafeTimeValue } from './makeSafeTimeValue.mjs';
 
+/**
+ * {@include date/toTimeValue/index.md}
+ */
 function toTimeValue(input) {
     const match = input.match(theTimeRegex);
     const { value, sign } = match.groups;

package/dist/date/toTimestamp.cjs

@@ -3,6 +3,9 @@
 var constants = require('./constants.cjs');
 var makeSafeTimestamp = require('./makeSafeTimestamp.cjs');
 
+/**
+ * {@include date/toTimestamp/index.md}
+ */
 function toTimestamp(input) {
     const match = input.startsWith("date")
         ? input.match(constants.theDateRegex)

package/dist/date/toTimestamp.d.ts

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

package/dist/date/toTimestamp.mjs

@@ -1,6 +1,9 @@
 import { theDateRegex, theTimeRegex } from './constants.mjs';
 import { makeSafeTimestamp } from './makeSafeTimestamp.mjs';
 
+/**
+ * {@include date/toTimestamp/index.md}
+ */
 function toTimestamp(input) {
     const match = input.startsWith("date")
         ? input.match(theDateRegex)

package/dist/date/today.cjs

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

package/dist/date/today.d.ts

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

package/dist/date/today.mjs

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

package/dist/date/tomorrow.cjs

@@ -2,6 +2,9 @@
 
 var constants = require('./constants.cjs');
 
+/**
+ * {@include date/tomorrow/index.md}
+ */
 function tomorrow() {
     const timestamp = Date.now() + constants.millisecondsInOneDay;
     return `date${timestamp}+`;

package/dist/date/tomorrow.d.ts

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

package/dist/date/tomorrow.mjs

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

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

@@ -4,5 +4,13 @@ type OddTen = "1" | "3" | "5" | "7" | "9";
 type MultipleOf4 = `${TenEven}${"0" | "4" | "8"}` | `${OddTen}${"2" | "6"}`;
 type MultipleOf100 = `${Exclude<DString.Digit, "0">}00`;
 type MultipleOf400 = `${Exclude<MultipleOf4, "0">}00`;
+/**
+ * Type-level check for leap years.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/isLeapYear
+ * 
+ * @namespace D
+ * 
+ */
 export type IsLeapYear<GenericYear extends number> = `${GenericYear}` extends infer InferredYear ? InferredYear extends `${number | ""}${MultipleOf4}` ? InferredYear extends `${number | ""}${MultipleOf100}` ? InferredYear extends `${number | ""}${MultipleOf400}` ? true : false : true : false : never;
 export {};

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

@@ -1,5 +1,13 @@
 import { type And } from "../../common";
 import type * as DNumber from "../../number";
+/**
+ * Type-level check for years within the supported safe range.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/isSafeYear
+ * 
+ * @namespace D
+ * 
+ */
 export type IsSafeYear<GenericYears extends number> = And<[
     DNumber.IsGreater<GenericYears, -271820>,
     DNumber.IsLess<GenericYears, 275759>

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

@@ -1 +1,11 @@
+/**
+ * Represents a TheDate string: a UTC timestamp encoded with a sign.
+ * It solves common date issues across languages and HTTP by using a single transportable format, independent of local timezone quirks.
+ * When you need local time (e.g., Brazil), you convert from the UTC timestamp with getters and a timezone, keeping storage robust and consistent.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/theDate
+ * 
+ * @namespace D
+ * 
+ */
 export type TheDate = `date${number}${"-" | "+"}`;

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

@@ -1 +1,10 @@
+/**
+ * Represents a TheTime string: a constrained number stored as milliseconds with a sign.
+ * It gives a single, consistent format for time values so 10 seconds, 3 days, or 1 hour are all just the same unit, making time manipulation predictable.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/theTime
+ * 
+ * @namespace D
+ * 
+ */
 export type TheTime = `time${number}${"+" | "-"}`;

package/dist/date/yesterday.cjs

@@ -2,6 +2,9 @@
 
 var constants = require('./constants.cjs');
 
+/**
+ * {@include date/yesterday/index.md}
+ */
 function yesterday() {
     const timestamp = Date.now() - constants.millisecondsInOneDay;
     return `date${timestamp}+`;

package/dist/date/yesterday.d.ts

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

package/dist/date/yesterday.mjs

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