@duplojs/utils 1.3.32 → 1.4.33

package/dist/dataParser/parsers/string/index.d.ts

@@ -26,6 +26,36 @@ export interface DataParserString<GenericDefinition extends DataParserDefinition
      */
     construct<const GenericDefinition extends DataParserDefinitionString>(definition: GenericDefinition): DataParserString<MergeDefinition<DataParserDefinitionString, GenericDefinition>>;
 }
+/**
+ * Creates a data parser for strings.
+ * 
+ * **Supported call styles:**
+ * - Classic: `DP.string(definition?)` -> returns a string parser
+ * - Curried: not available
+ * 
+ * Validates that the input is a string, optionally applies coerce, and runs the configured checkers.
+ * 
+ * ```ts
+ * const parser = DP.string();
+ * const result = parser.parse("DuploJS");
+ * if (E.isRight(result)) {
+ * 	const value = unwrap(result);
+ * 	// value: string
+ * }
+ * 
+ * const withCheckers = DP.string({
+ * 	checkers: [DP.checkerStringMin(3), DP.checkerStringMax(10)],
+ * });
+ * 
+ * const coerceParser = DP.coerce.string();
+ * const coerceResult = coerceParser.parse(123);
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/dataParser/string
+ * 
+ * @namespace DP
+ * 
+ */
 export declare function string<const GenericDefinition extends Partial<DataParserDefinitionString> = never>(definition?: GenericDefinition): DataParserString<MergeDefinition<DataParserDefinitionString, NeverCoalescing<GenericDefinition, {}>>>;
 export declare namespace string {
     var overrideHandler: import("../../../common").OverrideHandler<DataParserString<DataParserDefinitionString>>;

package/dist/dataParser/parsers/string/index.mjs

@@ -4,6 +4,9 @@ import { createDataParserKind } from '../../kind.mjs';
 import { createOverride } from '../../../common/override.mjs';
 
 const stringKind = createDataParserKind("string");
+/**
+ * {@include dataParser/classic/string/index.md}
+ */
 function string(definition) {
     const self = dataParserInit(stringKind, {
         errorMessage: definition?.errorMessage,

package/dist/dataParser/parsers/templateLiteral/index.cjs

@@ -8,6 +8,9 @@ var pipe = require('../../../common/pipe.cjs');
 var override = require('../../../common/override.cjs');
 
 const templateLiteralKind = kind.createDataParserKind("template-literal");
+/**
+ * {@include dataParser/classic/templateLiteral/index.md}
+ */
 function templateLiteral(template, definition) {
     const pattern = pipe.pipe(createTemplateLiteralPattern.createTemplateLiteralPattern(template), (result) => new RegExp(`^${result}$`));
     const self = base.dataParserInit(templateLiteralKind, {

package/dist/dataParser/parsers/templateLiteral/index.d.ts

@@ -65,6 +65,36 @@ export interface DataParserTemplateLiteral<GenericDefinition extends DataParserD
      */
     construct<const GenericDefinition extends DataParserDefinitionTemplateLiteral>(definition: GenericDefinition): DataParserTemplateLiteral<MergeDefinition<DataParserDefinitionTemplateLiteral, GenericDefinition>>;
 }
+/**
+ * Creates a data parser for deterministic template literal strings.
+ * 
+ * **Supported call styles:**
+ * - Classic: `DP.templateLiteral(template, definition?)` -> returns a template literal parser
+ * - Curried: not available
+ * 
+ * Validates that the input matches the provided template literal shape and pattern.
+ * 
+ * ```ts
+ * const parser = DP.templateLiteral(["user-", DP.number()]);
+ * const result = parser.parse("user-42");
+ * if (E.isRight(result)) {
+ * 	const value = unwrap(result);
+ * 	// value: string
+ * }
+ * 
+ * const orderParser = DP.templateLiteral(["order-", DP.literal("vip"), "-", DP.number()]);
+ * const orderResult = orderParser.parse("order-vip-12");
+ * 
+ * const withCheckers = DP.templateLiteral(["id-", DP.number()], {
+ * 	checkers: [DP.checkerRefine((value) => value.endsWith("0"))],
+ * });
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/dataParser/templateLiteral
+ * 
+ * @namespace DP
+ * 
+ */
 export declare function templateLiteral<const GenericTemplate extends TemplateLiteralShape, const GenericDefinition extends Partial<Omit<DataParserDefinitionTemplateLiteral, "template" | "pattern">> = never>(template: GenericTemplate, definition?: GenericDefinition): DataParserTemplateLiteral<MergeDefinition<DataParserDefinitionTemplateLiteral, NeverCoalescing<GenericDefinition, {}> & {
     template: GenericTemplate;
 }>>;

package/dist/dataParser/parsers/templateLiteral/index.mjs

@@ -6,6 +6,9 @@ import { pipe } from '../../../common/pipe.mjs';
 import { createOverride } from '../../../common/override.mjs';
 
 const templateLiteralKind = createDataParserKind("template-literal");
+/**
+ * {@include dataParser/classic/templateLiteral/index.md}
+ */
 function templateLiteral(template, definition) {
     const pattern = pipe(createTemplateLiteralPattern(template), (result) => new RegExp(`^${result}$`));
     const self = dataParserInit(templateLiteralKind, {

package/dist/dataParser/parsers/time/index.cjs

@@ -13,6 +13,9 @@ var isTime = require('../../../date/isTime.cjs');
 var override = require('../../../common/override.cjs');
 
 const timeKind = kind.createDataParserKind("time");
+/**
+ * {@include dataParser/classic/time/index.md}
+ */
 function time(definition) {
     const self = base.dataParserInit(timeKind, {
         errorMessage: definition?.errorMessage,

package/dist/dataParser/parsers/time/index.d.ts

@@ -27,6 +27,36 @@ export interface DataParserTime<GenericDefinition extends DataParserDefinitionTi
      */
     construct<const GenericDefinition extends DataParserDefinitionTime>(definition: GenericDefinition): DataParserTime<MergeDefinition<DataParserDefinitionTime, GenericDefinition>>;
 }
+/**
+ * Creates a data parser for TheTime values.
+ * 
+ * **Supported call styles:**
+ * - Classic: `DP.time(definition?)` -> returns a time parser
+ * - Curried: not available
+ * 
+ * Validates that the input is a TheTime, optionally applies coerce, and runs the configured checkers.
+ * 
+ * ```ts
+ * const parser = DP.time();
+ * const result = parser.parse("time0+");
+ * if (E.isRight(result)) {
+ * 	const value = unwrap(result);
+ * 	// value: TheTime
+ * }
+ * 
+ * const withCheckers = DP.time({
+ * 	checkers: [DP.checkerRefine((value) => value !== "time0+")],
+ * });
+ * 
+ * const coerceParser = DP.coerce.time();
+ * const coerceResult = coerceParser.parse("10:20:00");
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/dataParser/time
+ * 
+ * @namespace DP
+ * 
+ */
 export declare function time<const GenericDefinition extends Partial<DataParserDefinitionTime> = never>(definition?: GenericDefinition): DataParserTime<MergeDefinition<DataParserDefinitionTime, NeverCoalescing<GenericDefinition, {}>>>;
 export declare namespace time {
     var overrideHandler: import("../../../common").OverrideHandler<DataParserTime<DataParserDefinitionTime>>;

package/dist/dataParser/parsers/time/index.mjs

@@ -11,6 +11,9 @@ import { isTime } from '../../../date/isTime.mjs';
 import { createOverride } from '../../../common/override.mjs';
 
 const timeKind = createDataParserKind("time");
+/**
+ * {@include dataParser/classic/time/index.md}
+ */
 function time(definition) {
     const self = dataParserInit(timeKind, {
         errorMessage: definition?.errorMessage,

package/dist/dataParser/parsers/transform.cjs

@@ -6,6 +6,9 @@ var kind = require('../kind.cjs');
 var override = require('../../common/override.cjs');
 
 const transformKind = kind.createDataParserKind("transform");
+/**
+ * {@include dataParser/classic/transform/index.md}
+ */
 function transform(inner, theFunction, definition) {
     const self = base.dataParserInit(transformKind, {
         errorMessage: definition?.errorMessage,

package/dist/dataParser/parsers/transform.d.ts

@@ -26,6 +26,35 @@ export interface DataParserTransform<GenericDefinition extends DataParserDefinit
      */
     construct<const GenericDefinition extends DataParserDefinitionTransform>(definition: GenericDefinition): DataParserTransform<MergeDefinition<DataParserDefinitionTransform, GenericDefinition>>;
 }
+/**
+ * Creates a data parser that transforms the output of another parser.
+ * 
+ * **Supported call styles:**
+ * - Classic: `DP.transform(inner, theFunction, definition?)` -> returns a transform parser
+ * - Curried: not available
+ * 
+ * Runs the inner parser and applies a transformation function to its output.
+ * 
+ * ```ts
+ * const parser = DP.transform(DP.string(), (value) => value.length);
+ * const result = parser.parse("Duplo");
+ * if (E.isRight(result)) {
+ * 	const value = unwrap(result);
+ * 	// value: number
+ * }
+ * 
+ * const toUpper = DP.transform(
+ * 	DP.string(),
+ * 	S.toUpperCase,
+ * );
+ * const upperResult = toUpper.parse("duplo");
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/dataParser/transform
+ * 
+ * @namespace DP
+ * 
+ */
 export declare function transform<GenericDataParser extends DataParser, GenericOutput extends unknown, const GenericDefinition extends Partial<Omit<DataParserDefinitionTransform, "inner" | "theFunction">> = never>(inner: GenericDataParser, theFunction: (input: Output<GenericDataParser>, error: DataParserError) => GenericOutput, definition?: GenericDefinition): DataParserTransform<MergeDefinition<DataParserDefinitionTransform, NeverCoalescing<GenericDefinition, {}> & {
     inner: GenericDataParser;
     theFunction(input: Output<GenericDataParser>): GenericOutput;

package/dist/dataParser/parsers/transform.mjs

@@ -4,6 +4,9 @@ import { createDataParserKind } from '../kind.mjs';
 import { createOverride } from '../../common/override.mjs';
 
 const transformKind = createDataParserKind("transform");
+/**
+ * {@include dataParser/classic/transform/index.md}
+ */
 function transform(inner, theFunction, definition) {
     const self = dataParserInit(transformKind, {
         errorMessage: definition?.errorMessage,

package/dist/dataParser/parsers/tuple.cjs

@@ -6,6 +6,9 @@ var kind = require('../kind.cjs');
 var override = require('../../common/override.cjs');
 
 const tupleKind = kind.createDataParserKind("tuple");
+/**
+ * {@include dataParser/classic/tuple/index.md}
+ */
 function tuple(shape, definition) {
     const self = base.dataParserInit(tupleKind, {
         errorMessage: definition?.errorMessage,

package/dist/dataParser/parsers/tuple.d.ts

@@ -41,6 +41,32 @@ export interface DataParserTuple<GenericDefinition extends DataParserDefinitionT
      */
     construct<const GenericDefinition extends DataParserDefinitionTuple>(definition: GenericDefinition): DataParserTuple<MergeDefinition<DataParserDefinitionTuple, GenericDefinition>>;
 }
+/**
+ * Creates a data parser for tuples with a fixed shape.
+ * 
+ * **Supported call styles:**
+ * - Classic: `DP.tuple(shape, definition?)` -> returns a tuple parser
+ * - Curried: not available
+ * 
+ * Validates array inputs against the provided tuple shape, with an optional rest parser.
+ * 
+ * ```ts
+ * const parser = DP.tuple([DP.string(), DP.number()]);
+ * const result = parser.parse(["id", 42]);
+ * if (E.isRight(result)) {
+ * 	const value = unwrap(result);
+ * 	// value: [string, number]
+ * }
+ * 
+ * const withRest = DP.tuple([DP.string()], { rest: DP.number() });
+ * const restResult = withRest.parse(["a", 1, 2, 3]);
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/dataParser/tuple
+ * 
+ * @namespace DP
+ * 
+ */
 export declare function tuple<GenericShape extends TupleShape, const GenericDefinition extends Partial<Omit<DataParserDefinitionTuple, "shape">> = never>(shape: GenericShape, definition?: GenericDefinition): DataParserTuple<MergeDefinition<DataParserDefinitionTuple, NeverCoalescing<GenericDefinition, {}> & {
     shape: GenericShape;
 }>>;

package/dist/dataParser/parsers/tuple.mjs

@@ -4,6 +4,9 @@ import { createDataParserKind } from '../kind.mjs';
 import { createOverride } from '../../common/override.mjs';
 
 const tupleKind = createDataParserKind("tuple");
+/**
+ * {@include dataParser/classic/tuple/index.md}
+ */
 function tuple(shape, definition) {
     const self = dataParserInit(tupleKind, {
         errorMessage: definition?.errorMessage,

package/dist/dataParser/parsers/union.cjs

@@ -6,6 +6,9 @@ var kind = require('../kind.cjs');
 var override = require('../../common/override.cjs');
 
 const unionKind = kind.createDataParserKind("union");
+/**
+ * {@include dataParser/classic/union/index.md}
+ */
 function union(options, definition) {
     const self = base.dataParserInit(unionKind, {
         errorMessage: definition?.errorMessage,

package/dist/dataParser/parsers/union.d.ts

@@ -25,6 +25,37 @@ export interface DataParserUnion<GenericDefinition extends DataParserDefinitionU
      */
     construct<const GenericDefinition extends DataParserDefinitionUnion>(definition: GenericDefinition): DataParserUnion<MergeDefinition<DataParserDefinitionUnion, GenericDefinition>>;
 }
+/**
+ * Creates a data parser that accepts one of multiple parsers.
+ * 
+ * **Supported call styles:**
+ * - Classic: `DP.union(options, definition?)` -> returns a union parser
+ * - Curried: not available
+ * 
+ * Tries each option in order until one succeeds, then returns its output.
+ * 
+ * ```ts
+ * const parser = DP.union([DP.string(), DP.number()]);
+ * const result = parser.parse("hello");
+ * if (E.isRight(result)) {
+ * 	const value = unwrap(result);
+ * 	// value: string | number
+ * }
+ * 
+ * const literals = DP.union([DP.literal("on"), DP.literal("off")]);
+ * const literalResult = literals.parse("off");
+ * 
+ * const withCheckers = DP.union(
+ * 	[DP.string(), DP.coerce.number()],
+ * 	{ checkers: [DP.checkerRefine((value) => value !== "forbidden")] },
+ * );
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/dataParser/union
+ * 
+ * @namespace DP
+ * 
+ */
 export declare function union<GenericOptions extends UnionOptions, const GenericDefinition extends Partial<Omit<DataParserDefinitionUnion, "options">> = never>(options: GenericOptions, definition?: GenericDefinition): DataParserUnion<MergeDefinition<DataParserDefinitionUnion, NeverCoalescing<GenericDefinition, {}> & {
     options: GenericOptions;
 }>>;

package/dist/dataParser/parsers/union.mjs

@@ -4,6 +4,9 @@ import { createDataParserKind } from '../kind.mjs';
 import { createOverride } from '../../common/override.mjs';
 
 const unionKind = createDataParserKind("union");
+/**
+ * {@include dataParser/classic/union/index.md}
+ */
 function union(options, definition) {
     const self = dataParserInit(unionKind, {
         errorMessage: definition?.errorMessage,

package/dist/dataParser/parsers/unknown.cjs

@@ -5,6 +5,9 @@ var kind = require('../kind.cjs');
 var override = require('../../common/override.cjs');
 
 const unknownKind = kind.createDataParserKind("unknown");
+/**
+ * {@include dataParser/classic/unknown/index.md}
+ */
 function unknown(definition) {
     const self = base.dataParserInit(unknownKind, {
         errorMessage: definition?.errorMessage,

package/dist/dataParser/parsers/unknown.d.ts

@@ -23,6 +23,36 @@ export interface DataParserUnknown<GenericDefinition extends DataParserDefinitio
      */
     construct<const GenericDefinition extends DataParserDefinitionUnknown>(definition: GenericDefinition): DataParserUnknown<MergeDefinition<DataParserDefinitionUnknown, GenericDefinition>>;
 }
+/**
+ * Creates a data parser that accepts any value.
+ * 
+ * **Supported call styles:**
+ * - Classic: `DP.unknown(definition?)` -> returns an unknown parser
+ * - Curried: not available
+ * 
+ * Always succeeds, unless additional checkers reject the value.
+ * 
+ * ```ts
+ * const parser = DP.unknown();
+ * const result = parser.parse({ any: "value" });
+ * if (E.isRight(result)) {
+ * 	const value = unwrap(result);
+ * 	// value: unknown
+ * }
+ * 
+ * const nonEmptyString = DP.unknown({
+ * 	checkers: [DP.checkerRefine((value) => typeof value === "string" && value.length > 0)],
+ * });
+ * 
+ * const numbersOnly = DP.unknown()
+ * 	.addChecker(DP.checkerRefine((value) => typeof value === "number"));
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/dataParser/unknown
+ * 
+ * @namespace DP
+ * 
+ */
 export declare function unknown<const GenericDefinition extends Partial<DataParserDefinitionUnknown> = never>(definition?: GenericDefinition): DataParserUnknown<MergeDefinition<DataParserDefinitionUnknown, NeverCoalescing<GenericDefinition, {}>>>;
 export declare namespace unknown {
     var overrideHandler: import("../../common").OverrideHandler<DataParserUnknown<DataParserDefinitionUnknown>>;

package/dist/dataParser/parsers/unknown.mjs

@@ -3,6 +3,9 @@ import { createDataParserKind } from '../kind.mjs';
 import { createOverride } from '../../common/override.mjs';
 
 const unknownKind = createDataParserKind("unknown");
+/**
+ * {@include dataParser/classic/unknown/index.md}
+ */
 function unknown(definition) {
     const self = dataParserInit(unknownKind, {
         errorMessage: definition?.errorMessage,

package/dist/date/applyTimezone.d.ts

@@ -1,4 +1,33 @@
 import { type Timezone } from "./timezone";
 import { type TheDate } from "./types";
+/**
+ * Applies a timezone to a date.
+ * 
+ * **Supported call styles:**
+ * - Classic: `applyTimezone(timeZone)` → returns a value
+ * - Curried: `applyTimezone(theDate, timeZone)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const theDate = D.createOrThrow(1704067200000);
+ * const shiftedDate = D.applyTimezone(theDate, "America/New_York");
+ * // shiftedDate: "date1704085200000+"
+ * 
+ * pipe(
+ * 	theDate,
+ * 	D.applyTimezone("America/New_York"),
+ * ); // shiftedDate: "date1704085200000+"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Applies the timezone offset to shift the date.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/applyTimezone
+ * 
+ * @namespace D
+ * 
+ */
 export declare function applyTimezone(timeZone: Timezone): (theDate: TheDate) => TheDate;
 export declare function applyTimezone(theDate: TheDate, timeZone: Timezone): TheDate;

package/dist/date/closestTo.d.ts

@@ -2,6 +2,41 @@ import type { TheDate } from "./types";
 interface ClosestToParams {
     tieBreaker?: "favorPast" | "favorFuture";
 }
+/**
+ * Finds the closest date to a target.
+ * 
+ * **Supported call styles:**
+ * - Classic: `closestTo(input, target, params?)` → returns a value
+ * - Curried: `closestTo(target, params?)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const inputs = [
+ * 	D.create("2024-06-01"),
+ * 	D.create("2024-06-10"),
+ * 	D.create("2024-06-20"),
+ * ] as const;
+ * 
+ * const target = D.create("2024-06-15");
+ * const result = D.closestTo(inputs, target);
+ * // result: "date1717996800000+" (10 June 2024)
+ * 
+ * pipe(
+ * 	inputs,
+ * 	D.closestTo(target),
+ * ); // result: "date1717996800000+" (10 June 2024)
+ * 
+ * ```
+ * 
+ * @remarks
+ * - `tieBreaker` can be "favorPast" or "favorFuture" to resolve equidistant dates.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/closestTo
+ * 
+ * @namespace D
+ * 
+ */
 export declare function closestTo<GenericIterable extends Iterable<TheDate>>(target: TheDate, params?: ClosestToParams): (input: GenericIterable) => TheDate | undefined;
 export declare function closestTo<GenericIterable extends Iterable<TheDate>>(input: GenericIterable, target: TheDate, params?: ClosestToParams): TheDate | undefined;
 export {};

package/dist/date/create.d.ts

@@ -21,6 +21,58 @@ interface SafeDateParams {
     second?: Second;
     millisecond?: Millisecond;
 }
+/**
+ * Creates a TheDate from various inputs.
+ * 
+ * Signature: `create(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * // Either<"date-created", TheDate>
+ * const mayBeDateFromNativeDate = D.create(
+ * 	new Date("2024-06-20T12:00:00Z"),
+ * );
+ * 
+ * // Either<"date-created", TheDate>
+ * const mayBeDateFromTimestamp = D.create(
+ * 	1_700_000_000_000,
+ * );
+ * 
+ * // "date1709183400000+"
+ * const dateFromSafeFormat = D.create(
+ * 	"2024-02-29",
+ * 	{
+ * 		hour: "10",
+ * 		minute: "30",
+ * 	},
+ * );
+ * 
+ * const dateWrongLeapYear = D.create(
+ * 	// @ts-expect-error Safe with leap year.
+ * 	"2023-02-29",
+ * );
+ * 
+ * const dateWrongRangeYear = D.create(
+ * 	// @ts-expect-error Safe against dates that fall outside the supported date range.
+ * 	"-596126-12-30",
+ * );
+ * 
+ * pipe(
+ * 	"2024-02-29",
+ * 	D.create,
+ * ); // "date1709183400000+"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Returns an Either tagged "date-created" or "date-created-error" for invalid inputs.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/create
+ * 
+ * @namespace D
+ * 
+ */
 export declare function create<GenericInput extends TheDate | Date | number>(input: GenericInput): MayBe;
 export declare function create<GenericInput extends SpoolingDate>(input: GenericInput): MayBe;
 export declare function create<GenericInput extends SafeDate>(input: GenericInput & ForbiddenDate<GenericInput>, params?: SafeDateParams): TheDate;

package/dist/date/createOrThrow.d.ts

@@ -6,6 +6,41 @@ export declare class CreateTheDateError extends CreateTheDateError_base {
     input: string | Date | number | SpoolingDate;
     constructor(input: string | Date | number | SpoolingDate);
 }
+/**
+ * Creates a TheDate or throws on invalid input.
+ * 
+ * Signature: `createOrThrow(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = 1_700_000_000_000;
+ * const result = D.createOrThrow(input);
+ * // result: "date1700000000000+"
+ * 
+ * const input2 = result;
+ * const result2 = D.createOrThrow(input2);
+ * // result2: "date1700000000000+"
+ * 
+ * const input3 = new Date("2024-06-20T12:00:00Z");
+ * const result3 = D.createOrThrow(input3);
+ * // result3: "date1718884800000+"
+ * 
+ * pipe(
+ * 	input,
+ * 	(value) => D.createOrThrow(value),
+ * ); // result: "date1700000000000+"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Throws when the input cannot be converted to TheDate.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/createOrThrow
+ * 
+ * @namespace D
+ * 
+ */
 export declare function createOrThrow<GenericInput extends TheDate | Date | number>(input: GenericInput): TheDate;
 export declare function createOrThrow<GenericInput extends SpoolingDate>(input: GenericInput): TheDate;
 export {};

package/dist/date/createTheDate.cjs

@@ -2,6 +2,9 @@
 
 var makeSafeTimestamp = require('./makeSafeTimestamp.cjs');
 
+/**
+ * {@include date/createTheDate/index.md}
+ */
 function createTheDate(timestamp) {
     const safeTimestamp = makeSafeTimestamp.makeSafeTimestamp(timestamp);
     return `date${Math.abs(safeTimestamp)}${safeTimestamp < 0 ? "-" : "+"}`;

package/dist/date/createTheDate.d.ts

@@ -1,2 +1,28 @@
 import { type TheDate } from "./types";
+/**
+ * Creates a TheDate from a timestamp in milliseconds.
+ * 
+ * Signature: `createTheDate(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const result = D.createTheDate(1_700_000_000_000);
+ * // result: "date1700000000000+"
+ * 
+ * const result2 = D.createTheDate(-1_700_000_000_000);
+ * // result2: "date1700000000000-"
+ * 
+ * const result3 = D.createTheDate(8_640_000_000_000_500);
+ * // result3: "date8640000000000000+"
+ * ```
+ * 
+ * @remarks
+ * - The input is rounded and clamped to the supported timestamp range.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/date/createTheDate
+ * 
+ * @namespace D
+ * 
+ */
 export declare function createTheDate(timestamp: number): TheDate;

package/dist/date/createTheDate.mjs

@@ -1,5 +1,8 @@
 import { makeSafeTimestamp } from './makeSafeTimestamp.mjs';
 
+/**
+ * {@include date/createTheDate/index.md}
+ */
 function createTheDate(timestamp) {
     const safeTimestamp = makeSafeTimestamp(timestamp);
     return `date${Math.abs(safeTimestamp)}${safeTimestamp < 0 ? "-" : "+"}`;

package/dist/date/createTheTime.cjs

@@ -2,6 +2,9 @@
 
 var makeSafeTimeValue = require('./makeSafeTimeValue.cjs');
 
+/**
+ * {@include date/createTheTime/index.md}
+ */
 function createTheTime(timestamp) {
     const safeTimestamp = makeSafeTimeValue.makeSafeTimeValue(timestamp);
     return `time${Math.abs(safeTimestamp)}${safeTimestamp < 0 ? "-" : "+"}`;