@duplojs/utils 1.3.32 → 1.4.33

package/dist/either/optional/filled.d.ts

@@ -9,6 +9,67 @@ type _EitherOptionalFilled<GenericValue extends unknown = unknown> = (EitherRigh
 export interface EitherOptionalFilled<GenericValue extends unknown = unknown> extends _EitherOptionalFilled<GenericValue> {
 }
 type Either = EitherRight | EitherLeft;
+/**
+ * Type guard that checks that an optional contains a value.
+ * 
+ * Signature: `isOptionalFilled(input)` → returns a value
+ * 
+ * Acts as a type guard and narrows the input type when true.
+ * 
+ * ```ts
+ * const maybeValue = E.optional(true ? "value" : undefined);
+ * 
+ * if (E.isOptionalFilled(maybeValue)) {
+ * 	// type: E.EitherOptionalFilled<"value">
+ * }
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/isOptionalFilled
+ * 
+ * @namespace E
+ * 
+ */
+/**
+ * Builds an EitherRight<"optional"> when the value is defined.
+ * 
+ * Signature: `optionalFilled(value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const result = E.optionalFilled("value");
+ * 
+ * // type: E.EitherOptionalFilled<"value">
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/optionalFilled
+ * 
+ * @namespace E
+ * 
+ */
+/**
+ * Applies a callback only when the optional Either contains a value (OptionalFilled).
+ * 
+ * **Supported call styles:**
+ * - Classic: `whenIsOptionalFilled(input, theFunction)` → returns a value
+ * - Curried: `whenIsOptionalFilled(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.optional(true ? "value" : undefined),
+ * 	E.whenIsOptionalFilled(S.capitalize),
+ * );
+ * 
+ * // type: E.EitherOptionalEmpty | "Value"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/whenIsOptionalFilled
+ * 
+ * @namespace E
+ * 
+ */
 export declare function optionalFilled<const GenericValue extends unknown>(value: GenericValue): EitherOptionalFilled<GenericValue>;
 export declare function isOptionalFilled<GenericInput extends unknown>(input: GenericInput): input is Extract<GenericInput, EitherOptionalFilled>;
 type ToOptionalEither<GenericValue extends unknown> = GenericValue extends Either ? GenericValue : ReturnType<typeof optional<GenericValue>>;

package/dist/either/optional/filled.mjs

@@ -7,6 +7,15 @@ import { isLeft } from '../left/is.mjs';
 import { unwrap } from '../../common/unwrap.mjs';
 
 const eitherOptionalFilledKind = createEitherKind("optional-filled");
+/**
+ * {@include either/isOptionalFilled/index.md}
+ */
+/**
+ * {@include either/optionalFilled/index.md}
+ */
+/**
+ * {@include either/whenIsOptionalFilled/index.md}
+ */
 function optionalFilled(value) {
     return eitherOptionalKind.setTo(eitherOptionalFilledKind.setTo(right("optional", value)));
 }

package/dist/either/right/asyncGroup.cjs

@@ -11,6 +11,9 @@ var when = require('../../common/when.cjs');
 var isType = require('../../common/isType.cjs');
 var when$1 = require('./when.cjs');
 
+/**
+ * {@include either/asyncGroup/index.md}
+ */
 function asyncGroup(group) {
     return asyncPipe.asyncPipe(group, entries.entries, asyncReduce.asyncReduce(reduce.reduceFrom({}), ({ element: [key, value], lastValue, nextWithObject, exit }) => asyncPipe.asyncPipe(value, when.when(isType.isType("function"), (getter) => getter()), when.when(is.isLeft, exit), when$1.whenIsRight((data) => nextWithObject(lastValue, { [key]: data })))), whenNot.whenNot(is.isLeft, success.success));
 }

package/dist/either/right/asyncGroup.d.ts

@@ -8,5 +8,34 @@ type ComputeResult<GenericGroup extends Record<string, MayBeGetter<Either>>> = P
 }>> | {
     [Prop in keyof GenericGroup]: GenericGroup[Prop] extends AnyFunction ? Extract<Awaited<ReturnType<GenericGroup[Prop]>>, EitherLeft> : Extract<Awaited<GenericGroup[Prop]>, EitherLeft>;
 }[keyof GenericGroup]>;
+/**
+ * The asyncGroup() function runs synchronous or asynchronous Either values in parallel (promises, Future) and returns the first Left encountered. If all are Right, it aggregates their values into a typed object.
+ * 
+ * Signature: `asyncGroup(group)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const asyncLoad = E.future(Promise.resolve(E.right("user.loaded", { id: 1 })));
+ * const callbackRights = () => E.right("rights.loaded", ["read"]);
+ * const promiseProfile = Promise.resolve(E.right("profile.loaded", { name: "Ada" }));
+ * 
+ * const result = await E.asyncGroup({
+ * 	user: asyncLoad,
+ * 	rights: callbackRights,
+ * 	profile: promiseProfile,
+ * });
+ * 
+ * // type: E.EitherFutureError
+ * ```
+ * 
+ * @remarks
+ * - Stops at the first Left and forwards it as-is.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/asyncGroup
+ * 
+ * @namespace E
+ * 
+ */
 export declare function asyncGroup<GenericGroup extends Record<string, MayBeGetter<Either>>>(group: GenericGroup): Extract<ComputeResult<GenericGroup>, any>;
 export {};

package/dist/either/right/asyncGroup.mjs

@@ -9,6 +9,9 @@ import { when } from '../../common/when.mjs';
 import { isType } from '../../common/isType.mjs';
 import { whenIsRight } from './when.mjs';
 
+/**
+ * {@include either/asyncGroup/index.md}
+ */
 function asyncGroup(group) {
     return asyncPipe(group, entries, asyncReduce(reduceFrom({}), ({ element: [key, value], lastValue, nextWithObject, exit }) => asyncPipe(value, when(isType("function"), (getter) => getter()), when(isLeft, exit), whenIsRight((data) => nextWithObject(lastValue, { [key]: data })))), whenNot(isLeft, success));
 }

package/dist/either/right/asyncPipe.d.ts

@@ -7,6 +7,43 @@ import { type AnyValue, type Unwrap } from "../../common";
 type Either = EitherRight | EitherLeft;
 export type EitherRightAsyncPipeFunction<GenericInput extends AnyValue = AnyValue, GenericOutput extends MaybeFutureEither<AnyValue> = MaybeFutureEither<AnyValue>> = (input: Awaited<GenericInput> extends infer InferredInput ? InferredInput extends Either ? Unwrap<Exclude<InferredInput, EitherLeft>> : InferredInput : never) => GenericOutput;
 export type EitherRightAsyncPipeResult<GenericPipeOutputs extends AnyValue, GenericLastPipeOutput extends AnyValue> = Extract<Awaited<GenericPipeOutputs>, EitherLeft> | (Awaited<GenericLastPipeOutput> extends infer InferredLastResult ? Exclude<InferredLastResult extends Either ? InferredLastResult : EitherSuccess<InferredLastResult>, EitherLeft> : never);
+/**
+ * Asynchronous version of rightPipe. Automatically handles promises, Future, and Either, and short-circuits on the first Left.
+ * 
+ * Signature: `rightAsyncPipe(input, pipe1, pipe2)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = E.future(
+ * 	Promise.resolve(
+ * 		true
+ * 			? false
+ * 				? true
+ * 					? E.right("right-1", 1)
+ * 					: E.left("left-1", null)
+ * 				: E.right("right-2", 2)
+ * 			: E.left("left-2", 2),
+ * 	),
+ * );
+ * 
+ * const result = E.rightAsyncPipe(
+ * 	input,
+ * 	(value) => {
+ * 		// type: 1 | 2
+ * 		return value;
+ * 	},
+ * );
+ * ```
+ * 
+ * @remarks
+ * - Stops at the first Left and forwards it as-is.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/rightAsyncPipe
+ * 
+ * @namespace E
+ * 
+ */
 export declare function rightAsyncPipe<GenericInput extends MaybeFutureEither<AnyValue>, GenericOutputPipe1 extends MaybeFutureEither<AnyValue>>(input: GenericInput, pipe1: EitherRightAsyncPipeFunction<GenericInput, GenericOutputPipe1>): Future<Extract<EitherRightAsyncPipeResult<GenericInput | GenericOutputPipe1, GenericOutputPipe1>, any>>;
 export declare function rightAsyncPipe<GenericInput extends MaybeFutureEither<AnyValue>, GenericOutputPipe1 extends MaybeFutureEither<AnyValue>, GenericOutputPipe2 extends MaybeFutureEither<AnyValue>>(input: GenericInput, pipe1: EitherRightAsyncPipeFunction<GenericInput, GenericOutputPipe1>, pipe2: EitherRightAsyncPipeFunction<GenericOutputPipe1, GenericOutputPipe2>): Future<Extract<EitherRightAsyncPipeResult<GenericInput | GenericOutputPipe1 | GenericOutputPipe2, GenericOutputPipe2>, any>>;
 export declare function rightAsyncPipe<GenericInput extends MaybeFutureEither<AnyValue>, GenericOutputPipe1 extends MaybeFutureEither<AnyValue>, GenericOutputPipe2 extends MaybeFutureEither<AnyValue>, GenericOutputPipe3 extends MaybeFutureEither<AnyValue>>(input: GenericInput, pipe1: EitherRightAsyncPipeFunction<GenericInput, GenericOutputPipe1>, pipe2: EitherRightAsyncPipeFunction<GenericOutputPipe1, GenericOutputPipe2>, pipe3: EitherRightAsyncPipeFunction<GenericOutputPipe2, GenericOutputPipe3>): Future<Extract<EitherRightAsyncPipeResult<GenericInput | GenericOutputPipe1 | GenericOutputPipe2 | GenericOutputPipe3, GenericOutputPipe3>, any>>;

package/dist/either/right/create.cjs

@@ -4,6 +4,9 @@ var wrapValue = require('../../common/wrapValue.cjs');
 var kind = require('../kind.cjs');
 
 const eitherRightKind = kind.createEitherKind("right");
+/**
+ * {@include either/right/index.md}
+ */
 function right(information, value = undefined) {
     return eitherRightKind.setTo(kind.eitherInformationKind.setTo(wrapValue.wrapValue(value), information));
 }

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

@@ -5,5 +5,41 @@ export declare const eitherRightKind: import("../../common/kind").KindHandler<im
 type _EitherRight<GenericInformation extends string = string, GenericValue extends unknown = unknown> = (Kind<typeof eitherRightKind.definition> & Kind<typeof eitherInformationKind.definition, GenericInformation> & WrappedValue<GenericValue>);
 export interface EitherRight<GenericInformation extends string = string, GenericValue extends unknown = unknown> extends _EitherRight<GenericInformation, GenericValue> {
 }
+/**
+ * Builds an EitherRight by associating mandatory business information (literal string) and an optional payload. This is the basic brick to signal a contextualized success.
+ * 
+ * Signature: `right(information, value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = "SAVE-15" as string;
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	P.when(
+ * 		S.startsWith("SAVE"),
+ * 		(code) => E.right(
+ * 			"coupon.applied",
+ * 			{
+ * 				code,
+ * 				percent: 15,
+ * 			},
+ * 		),
+ * 	),
+ * 	P.otherwise(
+ * 		(value) => E.left("coupon.invalid", value),
+ * 	),
+ * );
+ * 
+ * // type: E.EitherRight< "coupon.applied", { readonly code: `SAVE${string}`; readonly percent: 15; } >
+ * // | E.EitherLeft< "coupon.invalid", string >
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/right
+ * 
+ * @namespace E
+ * 
+ */
 export declare function right<GenericInformation extends string, const GenericValue extends unknown = undefined>(information: GenericInformation, value?: GenericValue): EitherRight<GenericInformation, GenericValue>;
 export {};

package/dist/either/right/create.mjs

@@ -2,6 +2,9 @@ import { wrapValue } from '../../common/wrapValue.mjs';
 import { createEitherKind, eitherInformationKind } from '../kind.mjs';
 
 const eitherRightKind = createEitherKind("right");
+/**
+ * {@include either/right/index.md}
+ */
 function right(information, value = undefined) {
     return eitherRightKind.setTo(eitherInformationKind.setTo(wrapValue(value), information));
 }

package/dist/either/right/group.cjs

@@ -10,6 +10,9 @@ var entries = require('../../object/entries.cjs');
 var success = require('./success.cjs');
 var is = require('../left/is.cjs');
 
+/**
+ * {@include either/group/index.md}
+ */
 function group(group) {
     return pipe.pipe(group, entries.entries, reduce.reduce(reduce.reduceFrom({}), ({ element: [key, value], lastValue, nextWithObject, exit }) => pipe.pipe(value, when.when(isType.isType("function"), (getter) => getter()), when.when(is.isLeft, exit), when$1.whenIsRight((data) => nextWithObject(lastValue, { [key]: data })))), whenNot.whenNot(is.isLeft, success.success));
 }

package/dist/either/right/group.d.ts

@@ -8,5 +8,31 @@ type ComputeResult<GenericGroup extends Record<string, MayBeGetter<Either>>> = (
 }>> | {
     [Prop in keyof GenericGroup]: GenericGroup[Prop] extends AnyFunction ? Extract<ReturnType<GenericGroup[Prop]>, EitherLeft> : Extract<GenericGroup[Prop], EitherLeft>;
 }[keyof GenericGroup]);
+/**
+ * The group() function runs several Either values (or functions returning an Either) and returns the first Left encountered. If all are Right, it aggregates their values into a typed object.
+ * 
+ * Signature: `group(group)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const result = E.group({
+ * 	user: E.right("user.loaded", { id: 1 }),
+ * 	rights: E.right("rights.loaded", ["read", "write"]),
+ * 	profile: E.left("profile.missing", null),
+ * });
+ * 
+ * // type: E.EitherLeft<"profile.missing", null>
+ * // | E.EitherSuccess<{ user: { readonly id: 1; }; rights: readonly ["read", "write"]; profile: never; }>
+ * ```
+ * 
+ * @remarks
+ * - Stops at the first Left and forwards it as-is.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/group
+ * 
+ * @namespace E
+ * 
+ */
 export declare function group<GenericGroup extends Record<string, MayBeGetter<Either>>>(group: GenericGroup): Extract<ComputeResult<GenericGroup>, any>;
 export {};

package/dist/either/right/group.mjs

@@ -8,6 +8,9 @@ import { entries } from '../../object/entries.mjs';
 import { success } from './success.mjs';
 import { isLeft } from '../left/is.mjs';
 
+/**
+ * {@include either/group/index.md}
+ */
 function group(group) {
     return pipe(group, entries, reduce(reduceFrom({}), ({ element: [key, value], lastValue, nextWithObject, exit }) => pipe(value, when(isType("function"), (getter) => getter()), when(isLeft, exit), whenIsRight((data) => nextWithObject(lastValue, { [key]: data })))), whenNot(isLeft, success));
 }

package/dist/either/right/is.cjs

@@ -4,6 +4,9 @@ var kind = require('../kind.cjs');
 var create = require('./create.cjs');
 var wrapValue = require('../../common/wrapValue.cjs');
 
+/**
+ * {@include either/isRight/index.md}
+ */
 function isRight(input) {
     return create.eitherRightKind.has(input)
         && kind.eitherInformationKind.has(input)

package/dist/either/right/is.d.ts

@@ -1,2 +1,24 @@
 import { type EitherRight } from "./create";
+/**
+ * Type guard that checks whether a value is an EitherRight. Allows accessing the payload without explicit conversion.
+ * 
+ * Signature: `isRight(input)` → returns a value
+ * 
+ * Acts as a type guard and narrows the input type when true.
+ * 
+ * ```ts
+ * const result = true
+ * 	? E.ok()
+ * 	: E.fail();
+ * 
+ * if (E.isRight(result)) {
+ * 	// type: E.EitherOk
+ * }
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/isRight
+ * 
+ * @namespace E
+ * 
+ */
 export declare function isRight<GenericInput extends unknown>(input: GenericInput): input is Extract<GenericInput, EitherRight>;

package/dist/either/right/is.mjs

@@ -2,6 +2,9 @@ import { eitherInformationKind } from '../kind.mjs';
 import { eitherRightKind } from './create.mjs';
 import { isWrappedValue } from '../../common/wrapValue.mjs';
 
+/**
+ * {@include either/isRight/index.md}
+ */
 function isRight(input) {
     return eitherRightKind.has(input)
         && eitherInformationKind.has(input)

package/dist/either/right/ok.cjs

@@ -4,6 +4,9 @@ var kind = require('../kind.cjs');
 var create = require('./create.cjs');
 
 const eitherOkKind = kind.createEitherKind("ok");
+/**
+ * {@include either/ok/index.md}
+ */
 function ok() {
     return eitherOkKind.setTo(create.right("ok", undefined));
 }

package/dist/either/right/ok.d.ts

@@ -4,5 +4,30 @@ export declare const eitherOkKind: import("../../common/kind").KindHandler<impor
 type _EitherOk = (EitherRight<"ok", never> & Kind<typeof eitherOkKind.definition>);
 export interface EitherOk extends _EitherOk {
 }
+/**
+ * Returns an EitherRight<"ok", never>: an empty success that confirms an operation went fine without extra data.
+ * 
+ * Signature: `ok()` → returns a value
+ * 
+ * ```ts
+ * const input = "hello@duplo.dev" as string;
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	whenElse(
+ * 		S.includes("@"),
+ * 		E.ok,
+ * 		E.fail,
+ * 	),
+ * );
+ * 
+ * // type: E.EitherOk | E.EitherFail
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/ok
+ * 
+ * @namespace E
+ * 
+ */
 export declare function ok(): EitherOk;
 export {};

package/dist/either/right/ok.mjs

@@ -2,6 +2,9 @@ import { createEitherKind } from '../kind.mjs';
 import { right } from './create.mjs';
 
 const eitherOkKind = createEitherKind("ok");
+/**
+ * {@include either/ok/index.md}
+ */
 function ok() {
     return eitherOkKind.setTo(right("ok", undefined));
 }

package/dist/either/right/pipe.d.ts

@@ -5,6 +5,39 @@ import { type AnyValue, type Unwrap } from "../../common";
 type Either = EitherRight | EitherLeft;
 export type EitherRightPipeFunction<GenericInput extends AnyValue = AnyValue, GenericOutput extends AnyValue = AnyValue> = (input: GenericInput extends Either ? Unwrap<Exclude<GenericInput, EitherLeft>> : GenericInput) => GenericOutput;
 export type EitherRightPipeResult<GenericPipeOutputs extends AnyValue, GenericLastPipeOutput extends AnyValue> = Extract<GenericPipeOutputs, EitherLeft> | Exclude<GenericLastPipeOutput extends Either ? GenericLastPipeOutput : EitherSuccess<GenericLastPipeOutput>, EitherLeft>;
+/**
+ * Chains synchronous transformations on an Either as long as it remains Right. The pipeline stops as soon as a Left is returned.
+ * 
+ * Signature: `rightPipe(input, pipe1, pipe2)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = true
+ * 	? false
+ * 		? true
+ * 			? E.right("right-1", 1)
+ * 			: E.left("left-1", null)
+ * 		: E.right("right-2", 2)
+ * 	: E.left("left-2", 2);
+ * 
+ * const result = E.rightPipe(
+ * 	input,
+ * 	(value) => {
+ * 		// type: 1 | 2
+ * 		return value;
+ * 	},
+ * );
+ * ```
+ * 
+ * @remarks
+ * - Stops at the first Left and forwards it as-is.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/rightPipe
+ * 
+ * @namespace E
+ * 
+ */
 export declare function rightPipe<GenericInput extends AnyValue, GenericOutputPipe1 extends AnyValue>(input: GenericInput, pipe1: EitherRightPipeFunction<GenericInput, GenericOutputPipe1>): Extract<EitherRightPipeResult<GenericInput | GenericOutputPipe1, GenericOutputPipe1>, any>;
 export declare function rightPipe<GenericInput extends AnyValue, GenericOutputPipe1 extends AnyValue, GenericOutputPipe2 extends AnyValue>(input: GenericInput, pipe1: EitherRightPipeFunction<GenericInput, GenericOutputPipe1>, pipe2: EitherRightPipeFunction<GenericOutputPipe1, GenericOutputPipe2>): Extract<EitherRightPipeResult<GenericInput | GenericOutputPipe1 | GenericOutputPipe2, GenericOutputPipe2>, any>;
 export declare function rightPipe<GenericInput extends AnyValue, GenericOutputPipe1 extends AnyValue, GenericOutputPipe2 extends AnyValue, GenericOutputPipe3 extends AnyValue>(input: GenericInput, pipe1: EitherRightPipeFunction<GenericInput, GenericOutputPipe1>, pipe2: EitherRightPipeFunction<GenericOutputPipe1, GenericOutputPipe2>, pipe3: EitherRightPipeFunction<GenericOutputPipe2, GenericOutputPipe3>): Extract<EitherRightPipeResult<GenericInput | GenericOutputPipe1 | GenericOutputPipe2 | GenericOutputPipe3, GenericOutputPipe3>, any>;

package/dist/either/right/success.cjs

@@ -4,6 +4,9 @@ var kind = require('../kind.cjs');
 var create = require('./create.cjs');
 
 const eitherSuccessKind = kind.createEitherKind("success");
+/**
+ * {@include either/success/index.md}
+ */
 function success(value) {
     return eitherSuccessKind.setTo(create.right("success", value));
 }

package/dist/either/right/success.d.ts

@@ -4,5 +4,33 @@ export declare const eitherSuccessKind: import("../../common/kind").KindHandler<
 type _EitherSuccess<GenericValue extends unknown = unknown> = (EitherRight<"success", GenericValue> & Kind<typeof eitherSuccessKind.definition>);
 export interface EitherSuccess<GenericValue extends unknown = unknown> extends _EitherSuccess<GenericValue> {
 }
+/**
+ * Readable shortcut to create an EitherRight with the literal info "success". Ideal for functions that return only one type of success.
+ * 
+ * Signature: `success(value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = "  duplo  ";
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	S.trim,
+ * 	whenElse(
+ * 		(value) => equal(S.length(value), 0),
+ * 		E.error,
+ * 		E.success,
+ * 	),
+ * );
+ * 
+ * // type: E.EitherError<string> | E.EitherSuccess<string>
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/success
+ * 
+ * @namespace E
+ * 
+ */
 export declare function success<const GenericValue extends unknown>(value: GenericValue): EitherSuccess<GenericValue>;
 export {};

package/dist/either/right/success.mjs

@@ -2,6 +2,9 @@ import { createEitherKind } from '../kind.mjs';
 import { right } from './create.mjs';
 
 const eitherSuccessKind = createEitherKind("success");
+/**
+ * {@include either/success/index.md}
+ */
 function success(value) {
     return eitherSuccessKind.setTo(right("success", value));
 }

package/dist/either/right/when.d.ts

@@ -1,4 +1,30 @@
 import { type EscapeVoid, type AnyValue, type Unwrap, type BreakGenericLink } from "../../common";
 import { type EitherRight } from "./create";
+/**
+ * Applies a function only when the input is an EitherRight. Otherwise, the original value is returned as-is.
+ * 
+ * **Supported call styles:**
+ * - Classic: `whenIsRight(input, theFunction)` → returns a value
+ * - Curried: `whenIsRight(theFunction)` → returns a function waiting for the input
+ * 
+ * If the condition matches, the callback runs; otherwise the original value is returned.
+ * 
+ * ```ts
+ * pipe(
+ * 	true
+ * 		? E.success("true")
+ * 		: E.error("false"),
+ * 
+ * 	E.whenIsRight((value) => {
+ * 		// type: "true"
+ * 	}),
+ * );
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/whenIsRight
+ * 
+ * @namespace E
+ * 
+ */
 export declare function whenIsRight<const GenericInput extends unknown, const GenericOutput extends AnyValue | EscapeVoid>(theFunction: (eitherValue: Unwrap<Extract<BreakGenericLink<GenericInput>, EitherRight>>) => GenericOutput): (input: GenericInput) => Exclude<BreakGenericLink<GenericInput>, EitherRight> | GenericOutput;
 export declare function whenIsRight<const GenericInput extends unknown, const GenericOutput extends AnyValue | EscapeVoid>(input: GenericInput, theFunction: (eitherValue: Unwrap<Extract<BreakGenericLink<GenericInput>, EitherRight>>) => GenericOutput): Exclude<GenericInput, EitherRight> | GenericOutput;

package/dist/either/safeCallback.cjs

@@ -4,6 +4,9 @@ var kind = require('./kind.cjs');
 var create = require('./left/create.cjs');
 
 const eitherCallbackErrorKind = kind.createEitherKind("callback-error");
+/**
+ * {@include either/safeCallback/index.md}
+ */
 function callbackError(value) {
     return eitherCallbackErrorKind.setTo(create.left("callback", value));
 }

package/dist/either/safeCallback.d.ts

@@ -4,6 +4,32 @@ export declare const eitherCallbackErrorKind: import("../common").KindHandler<im
 type _EitherCallbackError = (EitherLeft<"callback", unknown> & Kind<typeof eitherCallbackErrorKind.definition>);
 export interface EitherCallbackError extends _EitherCallbackError {
 }
+/**
+ * Runs a callback in a safe block. If the callback throws, the function returns a "callback" typed EitherLeft instead of propagating the exception.
+ * 
+ * Signature: `safeCallback(theFunction)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const success = E.safeCallback(() => 42);
+ * 
+ * const failure = E.safeCallback(() => {
+ * 	throw new Error("boom");
+ * });
+ * 
+ * const isFailure = E.isLeft(failure);
+ * ```
+ * 
+ * @remarks
+ * - Catches exceptions thrown by the callback and wraps them in an `EitherLeft<"callback">`
+ * - Useful for working in an unsafe environment (3rd party libraries, user code, etc.)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/safeCallback
+ * 
+ * @namespace E
+ * 
+ */
 export declare function callbackError(value: unknown): EitherCallbackError;
 export declare function safeCallback<GenericOutput extends unknown>(theFunction: () => GenericOutput): GenericOutput | EitherCallbackError;
 export {};

package/dist/either/safeCallback.mjs

@@ -2,6 +2,9 @@ import { createEitherKind } from './kind.mjs';
 import { left } from './left/create.mjs';
 
 const eitherCallbackErrorKind = createEitherKind("callback-error");
+/**
+ * {@include either/safeCallback/index.md}
+ */
 function callbackError(value) {
     return eitherCallbackErrorKind.setTo(left("callback", value));
 }

package/dist/either/whenHasInformation.d.ts

@@ -3,6 +3,42 @@ import { type EitherRight } from "./right";
 import { type EitherLeft } from "./left";
 import { eitherInformationKind } from "./kind";
 type Either = EitherRight | EitherLeft;
+/**
+ * Functional pattern matching based on the literal information of an Either. The function is executed only when the information (or one of the informations) matches.
+ * 
+ * **Supported call styles:**
+ * - Classic: `whenHasInformation(input, information, theFunction)` → returns a value
+ * - Curried: `whenHasInformation(information, theFunction)` → returns a function waiting for the input
+ * 
+ * If the condition matches, the callback runs; otherwise the original value is returned.
+ * 
+ * ```ts
+ * const input = true
+ * 	? false
+ * 		? E.right("right-1", 1)
+ * 		: E.left("left-2", 2)
+ * 	: E.left("left-3", 3);
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	E.whenHasInformation("right-1", (value) => {
+ * 		// type: 1
+ * 		return value;
+ * 	}),
+ * 	E.whenHasInformation("left-2", (value) => {
+ * 		// type: 2
+ * 		return value;
+ * 	}),
+ * );
+ * 
+ * // type: 1 | 2 | E.EitherLeft<"left-3", 3>
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/whenHasInformation
+ * 
+ * @namespace E
+ * 
+ */
 export declare function whenHasInformation<const GenericInput extends unknown, GenericInformation extends (GenericInput extends Either ? ReturnType<typeof eitherInformationKind.getValue<GenericInput>> : never), const GenericOutput extends AnyValue>(information: GenericInformation | GenericInformation[], theFunction: (value: Unwrap<Extract<BreakGenericLink<GenericInput>, Kind<typeof eitherInformationKind.definition, GenericInformation> & WrappedValue>>) => GenericOutput): (input: GenericInput) => GenericOutput | Exclude<BreakGenericLink<GenericInput>, Kind<typeof eitherInformationKind.definition, GenericInformation>>;
 export declare function whenHasInformation<const GenericInput extends unknown, GenericInformation extends (GenericInput extends Either ? ReturnType<typeof eitherInformationKind.getValue<GenericInput>> : never), const GenericOutput extends AnyValue>(input: GenericInput, information: GenericInformation | GenericInformation[], theFunction: (value: Unwrap<Extract<BreakGenericLink<GenericInput>, Kind<typeof eitherInformationKind.definition, GenericInformation> & WrappedValue>>) => GenericOutput): GenericOutput | Exclude<GenericInput, Kind<typeof eitherInformationKind.definition, GenericInformation>>;
 export {};