@duplojs/utils 1.3.32 → 1.4.33

package/dist/object/to.d.ts

@@ -5,6 +5,49 @@ type ShapeObject<GenericInput extends unknown = unknown> = {
 type ComputesResult<GenericShapeObject extends ShapeObject<any>> = SimplifyTopLevel<{
     [Prop in keyof GenericShapeObject]: (ReturnType<Adaptor<GenericShapeObject[Prop], AnyFunction>> | (undefined extends GenericShapeObject[Prop] ? undefined : never));
 }>;
+/**
+ * Builds an object from an input using a shape of functions.
+ * 
+ * **Supported call styles:**
+ * - Classic: `to(input, shapeObject)` → returns a new object
+ * - Curried: `to(shapeObject)` → returns a function waiting for the input
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * O.to(
+ * 	{
+ * 		name: "Ada",
+ * 		age: 36,
+ * 	},
+ * 	{
+ * 		label: (input) => `${input.name}:${input.age}`,
+ * 	},
+ * ); // { label: "Ada:36" }
+ * 
+ * pipe(
+ * 	{
+ * 		name: "Ada",
+ * 	},
+ * 	O.to({
+ * 		upper: (input) => input.name.toUpperCase(),
+ * 	}),
+ * ); // { upper: "ADA" }
+ * 
+ * O.to(
+ * 	"alpha",
+ * 	{
+ * 		len: (input) => input.length,
+ * 	},
+ * ); // { len: 5 }
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/object/to
+ * 
+ * @namespace O
+ * 
+ */
 export declare function to<GenericInput extends unknown, GenericShapeObject extends ShapeObject<NoInfer<GenericInput>>>(shapeObject: ShapeObject<NoInfer<GenericInput>> & GenericShapeObject): (input: GenericInput) => ComputesResult<NoInfer<GenericShapeObject>>;
 export declare function to<GenericInput extends unknown, GenericShapeObject extends ShapeObject<GenericInput>>(input: GenericInput, shapeObject: FixDeepFunctionInfer<ShapeObject<GenericInput>, GenericShapeObject>): ComputesResult<GenericShapeObject>;
 export {};

package/dist/object/transformProperties.d.ts

@@ -5,6 +5,52 @@ type TransformObject<GenericObjectInput extends object = object> = {
 type ComputesResult<GenericObjectInput extends object, GenericTransformObject extends TransformObject<GenericObjectInput>> = SimplifyTopLevel<Omit<GenericObjectInput, keyof GenericTransformObject> & {
     [Prop in keyof GenericTransformObject]: (ReturnType<Adaptor<GenericTransformObject[Prop], AnyFunction>> | (undefined extends GenericTransformObject[Prop] ? GenericObjectInput[Adaptor<Prop, keyof GenericObjectInput>] : never));
 }>;
+/**
+ * Transforms multiple object properties.
+ * 
+ * **Supported call styles:**
+ * - Classic: `transformProperties(obj, transformObject)` → returns a new object
+ * - Curried: `transformProperties(transformObject)` → returns a function waiting for the object
+ * 
+ * The input object is not mutated.
+ * 
+ * ```ts
+ * O.transformProperties(
+ * 	{
+ * 		count: 2,
+ * 		label: "item",
+ * 	},
+ * 	{
+ * 		count: (value) => value + 1,
+ * 		label: (value) => value.toUpperCase(),
+ * 	},
+ * ); // { count: 3, label: "ITEM" }
+ * 
+ * pipe(
+ * 	{
+ * 		name: "Ada",
+ * 		age: 36,
+ * 	},
+ * 	O.transformProperties({
+ * 		age: (value) => value + 1,
+ * 	}),
+ * ); // { name: "Ada", age: 37 }
+ * 
+ * O.transformProperties(
+ * 	{
+ * 		active: true,
+ * 	},
+ * 	{},
+ * ); // { active: true }
+ * 
+ * ```
+ * 
+ * @see [`O.transformProperty`](https://utils.duplojs.dev/en/v1/api/object/transformProperty) For a single key
+ * @see https://utils.duplojs.dev/en/v1/api/object/transformProperties
+ * 
+ * @namespace O
+ * 
+ */
 export declare function transformProperties<GenericObjectInput extends object, GenericTransformObject extends TransformObject<NoInfer<GenericObjectInput>>>(transformObject: TransformObject<NoInfer<GenericObjectInput>> & GenericTransformObject): (obj: GenericObjectInput) => ComputesResult<NoInfer<GenericObjectInput>, NoInfer<GenericTransformObject>>;
 export declare function transformProperties<GenericObjectInput extends object, GenericTransformObject extends TransformObject<GenericObjectInput>>(obj: GenericObjectInput, transformObject: FixDeepFunctionInfer<TransformObject<GenericObjectInput>, GenericTransformObject>): ComputesResult<GenericObjectInput, GenericTransformObject>;
 export {};

package/dist/object/transformProperty.d.ts

@@ -1,4 +1,45 @@
 import { type SimplifyTopLevel } from "../common";
+/**
+ * Transforms a single object property.
+ * 
+ * **Supported call styles:**
+ * - Classic: `transformProperty(obj, key, transform)` → returns a new object
+ * - Curried: `transformProperty(key, transform)` → returns a function waiting for the object
+ * 
+ * The input object is not mutated.
+ * 
+ * ```ts
+ * O.transformProperty(
+ * 	{
+ * 		count: 2,
+ * 	},
+ * 	"count",
+ * 	(value) => value + 1,
+ * ); // { count: 3 }
+ * 
+ * pipe(
+ * 	{
+ * 		name: "Ada",
+ * 	},
+ * 	O.transformProperty("name", (value) => value.toUpperCase()),
+ * ); // { name: "ADA" }
+ * 
+ * O.transformProperty(
+ * 	{
+ * 		active: true,
+ * 	},
+ * 	"active",
+ * 	(value) => !value,
+ * ); // { active: false }
+ * 
+ * ```
+ * 
+ * @see [`O.transformProperties`](https://utils.duplojs.dev/en/v1/api/object/transformProperties) For multiple keys
+ * @see https://utils.duplojs.dev/en/v1/api/object/transformProperty
+ * 
+ * @namespace O
+ * 
+ */
 export declare function transformProperty<GenericObject extends object, GenericKey extends keyof GenericObject, GenericNewValue extends unknown>(key: GenericKey, transform: (value: GenericObject[GenericKey]) => GenericNewValue): (obj: GenericObject) => SimplifyTopLevel<{
     [Prop in GenericKey]: GenericNewValue;
 } & Omit<GenericObject, GenericKey>>;

package/dist/object/values.cjs

@@ -3,6 +3,9 @@
 var wrapValue = require('../common/wrapValue.cjs');
 var kind = require('../common/kind.cjs');
 
+/**
+ * {@include object/values/index.md}
+ */
 function values(object) {
     return Object.entries(object)
         .filter(([key]) => !wrapValue.isRuntimeWrappedValueKey(key) && !kind.isRuntimeKind(key))

package/dist/object/values.d.ts

@@ -1,2 +1,35 @@
 import { type AnyValue } from "../common/types/anyValue";
+/**
+ * Returns object values.
+ * 
+ * Signature: `values(object)` → returns values
+ * 
+ * The input object is not mutated.
+ * 
+ * ```ts
+ * O.values(
+ * 	{
+ * 		name: "Ada",
+ * 		age: 36,
+ * 	},
+ * ); // ["Ada", 36]
+ * 
+ * pipe(
+ * 	{
+ * 		name: "William",
+ * 		role: "client",
+ * 	},
+ * 	O.values,
+ * ); // ["William", "client"]
+ * ```
+ * 
+ * @remarks
+ * - Filters runtime keys used by the library
+ * - Uses the same semantics as [`Object.values`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/values)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/object/values
+ * 
+ * @namespace O
+ * 
+ */
 export declare function values<GenericValue extends AnyValue>(object: Record<string, GenericValue>): GenericValue[];

package/dist/object/values.mjs

@@ -1,6 +1,9 @@
 import { isRuntimeWrappedValueKey } from '../common/wrapValue.mjs';
 import { isRuntimeKind } from '../common/kind.mjs';
 
+/**
+ * {@include object/values/index.md}
+ */
 function values(object) {
     return Object.entries(object)
         .filter(([key]) => !isRuntimeWrappedValueKey(key) && !isRuntimeKind(key))

package/dist/pattern/exhaustive.cjs

@@ -2,6 +2,9 @@
 
 var unwrap = require('../common/unwrap.cjs');
 
+/**
+ * {@include pattern/exhaustive/index.md}
+ */
 function exhaustive(result) {
     return unwrap.unwrap(result);
 }

package/dist/pattern/exhaustive.d.ts

@@ -1,3 +1,54 @@
 import { type Unwrap } from "../common";
 import { type PatternResult } from "./result";
+/**
+ * Unwraps a pattern result when all cases are handled.
+ * 
+ * Signature: `exhaustive(result)` → returns the unwrapped value
+ * 
+ * Use this to signal that all patterns have been handled.
+ * 
+ * ```ts
+ * const input = <{
+ * 	kind: "circle";
+ * 	radius: number;
+ * } | {
+ * 	kind: "square";
+ * 	size: number;
+ * }>{
+ * 	kind: "circle",
+ * 	radius: 2,
+ * };
+ * 
+ * P.match(input)
+ * 	.with(
+ * 		{ kind: "circle" },
+ * 		(shape) => shape.radius * 2,
+ * 	)
+ * 	.with(
+ * 		{ kind: "square" },
+ * 		(shape) => shape.size * 2,
+ * 
+ * 	)
+ * 	.exhaustive(); // 4
+ * 
+ * pipe(
+ * 	input,
+ * 	P.match(
+ * 		{ kind: "circle" },
+ * 		(shape) => shape.radius * 2,
+ * 	),
+ * 	P.match(
+ * 		{ kind: "square" },
+ * 		(shape) => shape.size * 2,
+ * 	),
+ * 	P.exhaustive,
+ * ); // 4
+ * ```
+ * 
+ * @see [`P.match`](https://utils.duplojs.dev/en/v1/api/pattern/match) For building match chains
+ * @see https://utils.duplojs.dev/en/v1/api/pattern/exhaustive
+ * 
+ * @namespace P
+ * 
+ */
 export declare function exhaustive<const GenericValue extends unknown, GenericResult extends PatternResult<GenericValue>>(result: GenericResult): Unwrap<GenericResult>;

package/dist/pattern/exhaustive.mjs

@@ -1,5 +1,8 @@
 import { unwrap } from '../common/unwrap.mjs';
 
+/**
+ * {@include pattern/exhaustive/index.md}
+ */
 function exhaustive(result) {
     return unwrap(result);
 }

package/dist/pattern/index.cjs

@@ -10,7 +10,9 @@ var when = require('./when.cjs');
 var builder = require('./match/builder.cjs');
 var pattern = require('./types/pattern.cjs');
 
-
+/**
+ * {@include pattern/index.md}
+ */
 
 exports.isResult = result.isResult;
 exports.result = result.result;

package/dist/pattern/index.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Pattern matching utilities for building typed match pipelines. Functions preserve
+ * inputs and return new values.
+ * 
+ * **How to import:**
+ * - From the main entry (namespace style)
+ * - Via direct import for tree-shaking
+ * 
+ * ```ts
+ * import { DPattern, P } from "@duplojs/utils";
+ * import * as DPattern from "@duplojs/utils/pattern";
+ * import * as P from "@duplojs/utils/pattern";
+ * ```
+ * 
+ * What you will find in this namespace:
+ * - matching flow (`P.match`, `P.when`, `P.otherwise`, `P.exhaustive`)
+ * - predicates and patterns (`P.isMatch`, `P.union`)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/pattern
+ * @see https://utils.duplojs.dev/fr/v1/api/pattern
+ * 
+ * @namespace P
+ * 
+ */
 export * from "./result";
 export * from "./exhaustive";
 export * from "./otherwise";

package/dist/pattern/index.mjs

@@ -7,3 +7,7 @@ export { union } from './union.mjs';
 export { when } from './when.mjs';
 export { InvalidExhaustivePatternError, matchBuilder } from './match/builder.mjs';
 export { SymbolToolPatternFunctionLabel } from './types/pattern.mjs';
+
+/**
+ * {@include pattern/index.md}
+ */

package/dist/pattern/isMatch.d.ts

@@ -1,5 +1,41 @@
 import { type ForcePredicate, type AnyValue, type FixDeepFunctionInfer } from "../common";
 import { type Pattern, type PatternValue } from "./types/pattern";
 import { type ComplexMatchedValue } from "./types";
+/**
+ * Checks whether a value matches a pattern.
+ * 
+ * **Supported call styles:**
+ * - Classic: `isMatch(input, pattern)` → returns a boolean
+ * - Curried: `isMatch(pattern)` → returns a function waiting for the input
+ * - Classic predicate: `isMatch(input, pattern)` → narrows the input type
+ * - Curried predicate: `isMatch(pattern)` → narrows the input type
+ * 
+ * The input is not mutated.
+ * 
+ * ```ts
+ * const input = <{
+ * 	kind: "text";
+ * 	content: string;
+ * } | {
+ * 	kind: "image";
+ * 	url: string;
+ * }>{
+ * 	kind: "text",
+ * 	content: "hello",
+ * };
+ * 
+ * if (P.isMatch(input, { kind: "text" })) {
+ * 	// { kind: "text", content: "hello" }
+ * }
+ * ```
+ * 
+ * @remarks
+ * - Predicate overloads (type guards) narrow the output type
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/pattern/isMatch
+ * 
+ * @namespace P
+ * 
+ */
 export declare function isMatch<GenericInput extends AnyValue, const GenericPattern extends Pattern<GenericInput>>(pattern: FixDeepFunctionInfer<Pattern<GenericInput>, GenericPattern>): (input: GenericInput) => input is ForcePredicate<GenericInput, ComplexMatchedValue<GenericInput, PatternValue<GenericPattern>>>;
 export declare function isMatch<GenericInput extends AnyValue, const GenericPattern extends Pattern<GenericInput>>(input: GenericInput, pattern: FixDeepFunctionInfer<Pattern<GenericInput>, GenericPattern>): input is ForcePredicate<GenericInput, ComplexMatchedValue<GenericInput, PatternValue<GenericPattern>>>;

package/dist/pattern/match/index.d.ts

@@ -4,6 +4,64 @@ import { type PatternResult } from "../result";
 import { type ComplexMatchedValue, type ComplexUnMatchedValue } from "../types";
 import { type MatchBuilder } from "./builder";
 export * from "./builder";
+/**
+ * Creates a match builder or applies a single pattern.
+ * 
+ * **Supported call styles:**
+ * - Classic: `match(input)` → returns a match builder
+ * - Classic: `match(input, pattern, handler)` → returns a result or the input
+ * - Curried: `match(pattern, handler)` → returns a function waiting for the input
+ * 
+ * If the input matches the pattern, the handler runs and the result is wrapped for chaining.
+ * The input is not mutated.
+ * 
+ * ```ts
+ * const input = <{
+ * 	type: "text";
+ * 	value: string;
+ * } | {
+ * 	type: "count";
+ * 	value: number;
+ * }>{
+ * 	type: "text",
+ * 	value: "hello",
+ * };
+ * 
+ * P.match(input)
+ * 	.with(
+ * 		{ type: "text" },
+ * 		(item) => item.value.toUpperCase(),
+ * 	)
+ * 	.with(
+ * 		{ type: "count" },
+ * 		(item) => `${item.value}:${item.type}`,
+ * 	)
+ * 	.otherwise(() => "unknown"); // "HELLO"
+ * 
+ * pipe(
+ * 	input,
+ * 	P.match(
+ * 		{ type: "count" },
+ * 		(item) => item.value * 2,
+ * 	),
+ * 	P.otherwise(() => 0),
+ * ); // 4
+ * 
+ * P.match(input)
+ * 	.when(
+ * 		(item) => typeof item === "number",
+ * 		() => "ok",
+ * 	)
+ * 	.otherwise(() => "no"); // "ok"
+ * ```
+ * 
+ * @see [`P.when`](https://utils.duplojs.dev/en/v1/api/pattern/when) For predicate branches
+ * @see [`P.otherwise`](https://utils.duplojs.dev/en/v1/api/pattern/otherwise) For fallbacks
+ * @see https://utils.duplojs.dev/en/v1/api/pattern/match
+ * 
+ * @namespace P
+ * 
+ */
 export declare function match<GenericInput extends unknown>(input: GenericInput): MatchBuilder<IsEqual<GenericInput, unknown> extends true ? AnyValue : GenericInput>;
 export declare function match<GenericInput extends unknown, GenericInputValue extends Exclude<IsEqual<GenericInput, unknown> extends true ? AnyValue : GenericInput, PatternResult>, GenericInputPatternResult extends Extract<GenericInput, PatternResult>, const GenericPattern extends Pattern<GenericInputValue>, GenericPatternValue extends PatternValue<GenericPattern>, GenericOutput extends AnyValue | EscapeVoid, GenericMatchedValue extends Extract<ComplexMatchedValue<GenericInputValue, GenericPatternValue>, any>>(pattern: FixDeepFunctionInfer<Pattern<GenericInputValue>, GenericPattern>, theFunction: (value: Extract<ComplexMatchedValue<GenericInputValue, PatternValue<GenericPattern>>, any>) => GenericOutput): (input: GenericInput | GenericInputValue | GenericInputPatternResult) => BreakGenericLink<((IsEqual<GenericMatchedValue, never> extends true ? never : PatternResult<GenericOutput>) | GenericInputPatternResult | Extract<ComplexUnMatchedValue<GenericInputValue, GenericPatternValue>, any>)>;
 export declare function match<GenericInput extends unknown, GenericInputValue extends Exclude<IsEqual<GenericInput, unknown> extends true ? AnyValue : GenericInput, PatternResult>, GenericInputPatternResult extends Extract<GenericInput, PatternResult>, const GenericPattern extends Pattern<GenericInputValue>, GenericPatternValue extends PatternValue<GenericPattern>, GenericOutput extends AnyValue | EscapeVoid, GenericMatchedValue extends Extract<ComplexMatchedValue<GenericInputValue, GenericPatternValue>, any>>(input: GenericInput | GenericInputValue | GenericInputPatternResult, pattern: FixDeepFunctionInfer<Pattern<GenericInputValue>, GenericPattern>, theFunction: (value: Extract<ComplexMatchedValue<GenericInputValue, PatternValue<GenericPattern>>, any>) => GenericOutput): BreakGenericLink<(IsEqual<GenericMatchedValue, never> extends true ? never : PatternResult<GenericOutput>) | GenericInputPatternResult | Extract<ComplexUnMatchedValue<GenericInputValue, GenericPatternValue>, any>>;

package/dist/pattern/otherwise.d.ts

@@ -1,4 +1,60 @@
 import { type AnyValue, type Unwrap } from "../common";
 import { type PatternResult } from "./result";
+/**
+ * Applies a fallback handler when no prior pattern matched.
+ * 
+ * **Supported call styles:**
+ * - Classic: `otherwise(input, handler)` → returns the unwrapped result or fallback
+ * - Curried: `otherwise(handler)` → returns a function waiting for the input
+ * 
+ * If the input is already a pattern result, it is unwrapped and returned.
+ * The input is not mutated.
+ * 
+ * ```ts
+ * const input = <{
+ * 	type: "text";
+ * 	value: string;
+ * } | {
+ * 	type: "count";
+ * 	value: number;
+ * }>{
+ * 	type: "text",
+ * 	value: "hello",
+ * };
+ * 
+ * P.match(input)
+ * 	.with(
+ * 		{ type: "text" },
+ * 		(item) => item.value.toUpperCase(),
+ * 	)
+ * 	.with(
+ * 		{ type: "count" },
+ * 		(item) => `${item.value}:${item.type}`,
+ * 	)
+ * 	.otherwise(() => "unknown"); // "HELLO"
+ * 
+ * pipe(
+ * 	input,
+ * 	P.match(
+ * 		{ type: "count" },
+ * 		(item) => item.value * 2,
+ * 	),
+ * 	P.otherwise(() => 0),
+ * ); // 4
+ * 
+ * P.match(input)
+ * 	.when(
+ * 		(item) => typeof item === "number",
+ * 		() => "ok",
+ * 	)
+ * 	.otherwise(() => "no"); // "ok"
+ * ```
+ * 
+ * @see [`P.match`](https://utils.duplojs.dev/en/v1/api/pattern/match) For building match chains
+ * @see https://utils.duplojs.dev/en/v1/api/pattern/otherwise
+ * 
+ * @namespace P
+ * 
+ */
 export declare function otherwise<GenericInput extends AnyValue, GenericInputValue extends Exclude<GenericInput, PatternResult>, GenericInputPatternResult extends Extract<GenericInput, PatternResult>, GenericOutput extends AnyValue>(theFunction: (rest: GenericInputValue) => GenericOutput): (input: GenericInput | GenericInputPatternResult | GenericInputValue) => (GenericOutput | Unwrap<GenericInputPatternResult>);
 export declare function otherwise<GenericInput extends AnyValue, GenericInputValue extends Exclude<GenericInput, PatternResult>, GenericInputPatternResult extends Extract<GenericInput, PatternResult>, GenericOutput extends AnyValue>(input: GenericInput | GenericInputPatternResult | GenericInputValue, theFunction: (rest: GenericInputValue) => GenericOutput): (GenericOutput | Unwrap<GenericInputPatternResult>);

package/dist/pattern/union.cjs

@@ -4,6 +4,9 @@ var isMatch = require('./isMatch.cjs');
 var pattern = require('./types/pattern.cjs');
 
 const SymbolToolPatternFunction = Symbol.for(pattern.SymbolToolPatternFunctionLabel);
+/**
+ * {@include pattern/union/index.md}
+ */
 function union(...patterns) {
     return {
         [SymbolToolPatternFunction]: (input) => {

package/dist/pattern/union.d.ts

@@ -1,5 +1,42 @@
 import { type FixDeepFunctionInfer } from "../common";
 import { type Pattern, type ToolPattern } from "./types/pattern";
+/**
+ * Creates a pattern that matches any of the provided patterns.
+ * 
+ * Signature: `union(...patterns)` → returns a pattern tool
+ * 
+ * The returned tool can be used with `match` or `isMatch`.
+ * 
+ * ```ts
+ * const input = <{
+ * 	kind: "text";
+ * 	content: string;
+ * } | {
+ * 	kind: "error";
+ * 	message: string;
+ * } | {
+ * 	kind: "image";
+ * 	url: string;
+ * }>{
+ * 	kind: "text",
+ * 	content: "hello",
+ * };
+ * 
+ * P.match(
+ * 	input,
+ * 	forward({ kind: P.union("text", "image") }),
+ * 	() => {
+ * 		// { kind: "text"; content: string; } | { kind: "error"; message: string;}
+ * 	},
+ * );
+ * ```
+ * 
+ * @see [`P.isMatch`](https://utils.duplojs.dev/en/v1/api/pattern/isMatch) For checking values
+ * @see https://utils.duplojs.dev/en/v1/api/pattern/union
+ * 
+ * @namespace P
+ * 
+ */
 export declare function union<GenericInput extends unknown, const GenericPatterns extends readonly [
     Pattern<GenericInput extends infer InferredInput ? InferredInput : never>,
     ...Pattern<GenericInput extends infer InferredInput ? InferredInput : never>[]

package/dist/pattern/union.mjs

@@ -2,6 +2,9 @@ import { isMatch } from './isMatch.mjs';
 import { SymbolToolPatternFunctionLabel } from './types/pattern.mjs';
 
 const SymbolToolPatternFunction = Symbol.for(SymbolToolPatternFunctionLabel);
+/**
+ * {@include pattern/union/index.md}
+ */
 function union(...patterns) {
     return {
         [SymbolToolPatternFunction]: (input) => {

package/dist/pattern/when.d.ts

@@ -1,5 +1,48 @@
 import { type AnyValue, type BreakGenericLink, type IsEqual, type EscapeVoid } from "../common";
 import { type PatternResult } from "./result";
+/**
+ * Applies a handler when a predicate matches.
+ * 
+ * **Supported call styles:**
+ * - Classic: `when(input, predicate, handler)` → returns a result or the input
+ * - Curried: `when(predicate, handler)` → returns a function waiting for the input
+ * - Classic predicate: `when(input, isType, handler)` → narrows input types
+ * - Curried predicate: `when(isType, handler)` → narrows input types
+ * 
+ * If the predicate matches, the handler runs and the result is wrapped for chaining.
+ * The input is not mutated.
+ * 
+ * ```ts
+ * pipe(
+ * 	5,
+ * 	P.when(
+ * 		(value) => value > 3,
+ * 		(value) => value * 2,
+ * 	),
+ * 	P.otherwise((value) => value),
+ * ); // 10
+ * 
+ * A.map(
+ * 	<const>["alpha", 2],
+ * 	innerPipe(
+ * 		P.when(
+ * 			isType("string"),
+ * 			(value) => value.toUpperCase(),
+ * 		),
+ * 		P.otherwise((value) => value),
+ * 	),
+ * ); // ["ALPHA", 2]
+ * ```
+ * 
+ * @remarks
+ * - Predicate overloads (type guards) narrow the output type
+ * 
+ * @see [`P.otherwise`](https://utils.duplojs.dev/en/v1/api/pattern/otherwise) For fallbacks
+ * @see https://utils.duplojs.dev/en/v1/api/pattern/when
+ * 
+ * @namespace P
+ * 
+ */
 export declare function when<GenericInput extends unknown, GenericInputValue extends Exclude<IsEqual<GenericInput, unknown> extends true ? AnyValue : GenericInput, PatternResult>, GenericInputPatternResult extends Extract<GenericInput, PatternResult>, GenericPredicatedInput extends GenericInputValue, GenericOutput extends AnyValue | EscapeVoid>(predicate: (input: GenericInputValue) => input is GenericPredicatedInput, theFunction: (predicatedInput: GenericPredicatedInput) => GenericOutput): (input: (GenericInput | GenericInputPatternResult | GenericInputValue)) => (GenericInputPatternResult | Exclude<BreakGenericLink<GenericInput>, GenericPredicatedInput | PatternResult> | PatternResult<GenericOutput>);
 export declare function when<GenericInput extends unknown, GenericInputValue extends Exclude<IsEqual<GenericInput, unknown> extends true ? AnyValue : GenericInput, PatternResult>, GenericInputPatternResult extends Extract<GenericInput, PatternResult>, GenericOutput extends AnyValue | EscapeVoid>(predicate: (input: GenericInputValue) => boolean, theFunction: (predicatedInput: GenericInputValue) => GenericOutput): (input: (GenericInput | GenericInputPatternResult | GenericInputValue)) => (GenericInputPatternResult | GenericInputValue | PatternResult<GenericOutput>);
 export declare function when<GenericInput extends unknown, GenericInputValue extends Exclude<IsEqual<GenericInput, unknown> extends true ? AnyValue : GenericInput, PatternResult>, GenericInputPatternResult extends Extract<GenericInput, PatternResult>, GenericPredicatedInput extends GenericInputValue, GenericOutput extends AnyValue | EscapeVoid>(input: (GenericInput | GenericInputPatternResult | GenericInputValue), predicate: (input: GenericInputValue) => input is GenericPredicatedInput, theFunction: (predicatedInput: GenericPredicatedInput) => GenericOutput): (GenericInputPatternResult | Exclude<BreakGenericLink<GenericInput>, GenericPredicatedInput | PatternResult> | PatternResult<GenericOutput>);

package/dist/string/at/default.d.ts

@@ -1,2 +1,32 @@
+/**
+ * Returns the character at a given index.
+ * 
+ * **Supported call styles:**
+ * - Classic: `at(input, index)` → returns a character or `undefined`
+ * - Curried: `at(index)` → returns a function waiting for the input
+ * 
+ * Negative indexes count from the end.
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.at("DuploJS", -1); // "S"
+ * 
+ * pipe(
+ * 	"TypeScript",
+ * 	S.at(-1),
+ * ); // "t"
+ * 
+ * S.at("Alpha", 12); // undefined
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`String.prototype.at`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/at)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/at
+ * 
+ * @namespace S
+ * 
+ */
 export declare function at<GenericString extends string, GenericIndex extends number>(index: GenericIndex): (input: GenericString) => string | undefined;
 export declare function at<GenericString extends string, GenericIndex extends number>(input: GenericString, index: GenericIndex): string | undefined;

package/dist/string/capitalize.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include string/capitalize/index.md}
+ */
 function capitalize(input) {
     return `${input.charAt(0).toUpperCase()}${input.slice(1)}`;
 }