@duplojs/utils 1.4.32 → 1.4.34

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

package/dist/either/bool/create.d.ts

@@ -1,5 +1,27 @@
 import { type FalsyValue, type IsEqual } from "../../common";
 import { type EitherBoolFalsy } from "./falsy";
 import { type EitherBoolTruthy } from "./truthy";
+/**
+ * Converts any value into a boolean monad (EitherBoolTruthy or EitherBoolFalsy). Handy to keep track of the test while benefiting from the whenIsBoolTruthy/whenIsBoolFalsy helpers.
+ * 
+ * Signature: `bool(value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const result = pipe(
+ * 	["duplo"],
+ * 	A.find(equal("nest")),
+ * 	E.bool,
+ * );
+ * 
+ * // type: E.EitherBoolFalsy<undefined> | E.EitherBoolTruthy<"nest">
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/bool
+ * 
+ * @namespace E
+ * 
+ */
 export declare function bool<const GenericValue extends unknown = undefined>(value: GenericValue): GenericValue extends FalsyValue ? EitherBoolFalsy<GenericValue> : IsEqual<GenericValue, number> extends true ? EitherBoolTruthy<GenericValue> | EitherBoolFalsy<0> : IsEqual<GenericValue, bigint> extends true ? EitherBoolTruthy<GenericValue> | EitherBoolFalsy<0n> : IsEqual<GenericValue, string> extends true ? EitherBoolTruthy<GenericValue> | EitherBoolFalsy<""> : EitherBoolTruthy<GenericValue>;
 export type Bool<GenericValue extends unknown> = EitherBoolTruthy<GenericValue> | EitherBoolFalsy;

package/dist/either/bool/falsy.cjs

@@ -9,6 +9,15 @@ var is$1 = require('../right/is.cjs');
 var unwrap = require('../../common/unwrap.cjs');
 
 const eitherBoolFalsyKind = kind.createEitherKind("bool-falsy");
+/**
+ * {@include either/boolFalsy/index.md}
+ */
+/**
+ * {@include either/isBoolFalsy/index.md}
+ */
+/**
+ * {@include either/whenIsBoolFalsy/index.md}
+ */
 function boolFalsy(value = undefined) {
     return base.eitherBoolKind.setTo(eitherBoolFalsyKind.setTo(create.left("bool", value)));
 }

package/dist/either/bool/falsy.d.ts

@@ -8,6 +8,75 @@ export declare const eitherBoolFalsyKind: import("../../common").KindHandler<imp
 type _EitherBoolFalsy<GenericValue extends FalsyValue = FalsyValue> = (EitherLeft<"bool", GenericValue> & Kind<typeof eitherBoolKind.definition> & Kind<typeof eitherBoolFalsyKind.definition>);
 export interface EitherBoolFalsy<GenericValue extends FalsyValue = FalsyValue> extends _EitherBoolFalsy<GenericValue> {
 }
+/**
+ * Builds an EitherLeft<"bool"> for an explicitly falsy value (0, "", null, undefined, false).
+ * 
+ * Signature: `boolFalsy(value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = "word" as string;
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	when(
+ * 		equal(""),
+ * 		E.boolFalsy,
+ * 	),
+ * );
+ * 
+ * // type: string | E.EitherBoolFalsy<"">
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/boolFalsy
+ * 
+ * @namespace E
+ * 
+ */
+/**
+ * Type guard that detects an EitherBoolFalsy.
+ * 
+ * Signature: `isBoolFalsy(input)` → returns a value
+ * 
+ * Acts as a type guard and narrows the input type when true.
+ * 
+ * ```ts
+ * const maybeInput = E.bool(true ? true : null);
+ * 
+ * if (E.isBoolFalsy(maybeInput)) {
+ * 	// type: E.EitherBoolFalsy<null>
+ * }
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/isBoolFalsy
+ * 
+ * @namespace E
+ * 
+ */
+/**
+ * Applies a callback only when the boolean value is falsy.
+ * 
+ * **Supported call styles:**
+ * - Classic: `whenIsBoolFalsy(input, theFunction)` → returns a value
+ * - Curried: `whenIsBoolFalsy(theFunction)` → returns a function waiting for the input
+ * 
+ * If the condition matches, the callback runs; otherwise the original value is returned.
+ * 
+ * ```ts
+ * const result = pipe(
+ * 	E.bool(true ? "value" : null),
+ * 	E.whenIsBoolFalsy(() => "falsy"),
+ * );
+ * 
+ * // type: E.EitherBoolTruthy<"value"> | "falsy"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/whenIsBoolFalsy
+ * 
+ * @namespace E
+ * 
+ */
 export declare function boolFalsy<const GenericValue extends FalsyValue = undefined>(value?: GenericValue): EitherBoolFalsy<GenericValue>;
 type Either = EitherRight | EitherLeft;
 export declare function isBoolFalsy<GenericInput extends unknown>(input: GenericInput): input is Extract<GenericInput, EitherBoolFalsy>;

package/dist/either/bool/falsy.mjs

@@ -7,6 +7,15 @@ import { isRight } from '../right/is.mjs';
 import { unwrap } from '../../common/unwrap.mjs';
 
 const eitherBoolFalsyKind = createEitherKind("bool-falsy");
+/**
+ * {@include either/boolFalsy/index.md}
+ */
+/**
+ * {@include either/isBoolFalsy/index.md}
+ */
+/**
+ * {@include either/whenIsBoolFalsy/index.md}
+ */
 function boolFalsy(value = undefined) {
     return eitherBoolKind.setTo(eitherBoolFalsyKind.setTo(left("bool", value)));
 }

package/dist/either/bool/truthy.cjs

@@ -9,6 +9,15 @@ var is$1 = require('../left/is.cjs');
 var unwrap = require('../../common/unwrap.cjs');
 
 const eitherBoolTruthyKind = kind.createEitherKind("bool-truthy");
+/**
+ * {@include either/boolTruthy/index.md}
+ */
+/**
+ * {@include either/isBoolTruthy/index.md}
+ */
+/**
+ * {@include either/whenIsBoolTruthy/index.md}
+ */
 function boolTruthy(value) {
     return base.eitherBoolKind.setTo(eitherBoolTruthyKind.setTo(create.right("bool", value)));
 }