feat(46): add jsDoc namespace pattern

Author: ZeRiix

docs/public/libs/v1/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);
 }

docs/public/libs/v1/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>;

docs/public/libs/v1/pattern/exhaustive.mjs

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

docs/public/libs/v1/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;

docs/public/libs/v1/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";

docs/public/libs/v1/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}
+ */

docs/public/libs/v1/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>>>;

docs/public/libs/v1/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>>;

docs/public/libs/v1/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>);

docs/public/libs/v1/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) => {