@duplojs/utils 1.4.32 → 1.4.33

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)));
 }

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

@@ -8,6 +8,75 @@ export declare const eitherBoolTruthyKind: import("../../common").KindHandler<im
 type _EitherBoolTruthy<GenericValue extends unknown = unknown> = (EitherRight<"bool", GenericValue> & Kind<typeof eitherBoolKind.definition> & Kind<typeof eitherBoolTruthyKind.definition>);
 export interface EitherBoolTruthy<GenericValue extends unknown = unknown> extends _EitherBoolTruthy<GenericValue> {
 }
+/**
+ * Forces the creation of an EitherRight<"bool"> by explicitly marking a truthy value.
+ * 
+ * Signature: `boolTruthy(value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = "hello@duplo.dev" as string;
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	when(
+ * 		S.includes("@"),
+ * 		E.boolTruthy,
+ * 	),
+ * );
+ * 
+ * // type: string | E.EitherBoolTruthy<`${string}@${string}`>
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/boolTruthy
+ * 
+ * @namespace E
+ * 
+ */
+/**
+ * Type guard that checks whether an Either from the boolean helpers is truthy.
+ * 
+ * Signature: `isBoolTruthy(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.isBoolTruthy(maybeInput)) {
+ * 	// type: E.EitherBoolTruthy<true>
+ * }
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/isBoolTruthy
+ * 
+ * @namespace E
+ * 
+ */
+/**
+ * Callback executed only for EitherBoolTruthy values. Otherwise, the initial value is returned.
+ * 
+ * **Supported call styles:**
+ * - Classic: `whenIsBoolTruthy(input, theFunction)` → returns a value
+ * - Curried: `whenIsBoolTruthy(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.whenIsBoolTruthy(S.toUpperCase),
+ * );
+ * 
+ * // type: E.EitherBoolFalsy<null> | "VALUE"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/whenIsBoolTruthy
+ * 
+ * @namespace E
+ * 
+ */
 export declare function boolTruthy<const GenericValue extends unknown>(value: GenericValue): EitherBoolTruthy<GenericValue>;
 type Either = EitherRight | EitherLeft;
 export declare function isBoolTruthy<GenericInput extends unknown>(input: GenericInput): input is Extract<GenericInput, EitherBoolTruthy>;

package/dist/either/bool/truthy.mjs

@@ -7,6 +7,15 @@ import { isLeft } from '../left/is.mjs';
 import { unwrap } from '../../common/unwrap.mjs';
 
 const eitherBoolTruthyKind = createEitherKind("bool-truthy");
+/**
+ * {@include either/boolTruthy/index.md}
+ */
+/**
+ * {@include either/isBoolTruthy/index.md}
+ */
+/**
+ * {@include either/whenIsBoolTruthy/index.md}
+ */
 function boolTruthy(value) {
     return eitherBoolKind.setTo(eitherBoolTruthyKind.setTo(right("bool", value)));
 }

package/dist/either/future/create.cjs

@@ -41,6 +41,9 @@ class Future extends Promise {
         return new Future(Promise.all(values.map((value) => new Future(value))));
     }
 }
+/**
+ * {@include either/future/index.md}
+ */
 function future(value) {
     return new Future(value);
 }

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

@@ -20,5 +20,28 @@ export declare class Future<const GenericValue extends unknown = unknown> extend
     static instanceof<GenericValue extends unknown>(value: GenericValue): value is Extract<GenericValue, Future<any>>;
     static rightAll<const GenericArray extends readonly unknown[]>(values: GenericArray): FutureEitherAllResult<GenericArray>;
 }
+/**
+ * Future<T> class: an enhanced promise capable of carrying Either values and exposing helpers like Future.all.
+ * 
+ * Signature: `future(value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const maybePromise = E.future(
+ * 	Promise.resolve(1),
+ * );
+ * 
+ * await maybePromise.then((value) => {
+ * 	// type: E.EitherFutureSuccess<number> | E.EitherFutureError
+ * 	return value;
+ * });
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/future
+ * 
+ * @namespace E
+ * 
+ */
 export declare function future<GenericEither extends AnyValue>(value: GenericEither): Future<GenericEither>;
 export {};

package/dist/either/future/create.mjs

@@ -39,6 +39,9 @@ class Future extends Promise {
         return new Future(Promise.all(values.map((value) => new Future(value))));
     }
 }
+/**
+ * {@include either/future/index.md}
+ */
 function future(value) {
     return new Future(value);
 }

package/dist/either/future/error.cjs

@@ -5,6 +5,9 @@ var kind = require('../kind.cjs');
 var create = require('../left/create.cjs');
 
 const eitherFutureErrorKind = kind.createEitherKind("future-error");
+/**
+ * {@include either/futureError/index.md}
+ */
 function futureError(value) {
     return base.eitherFutureKind.setTo(eitherFutureErrorKind.setTo(create.left("future", value)));
 }

package/dist/either/future/error.d.ts

@@ -5,5 +5,23 @@ export declare const eitherFutureErrorKind: import("../../common/kind").KindHand
 type _EitherFutureError = (EitherLeft<"future", unknown> & Kind<typeof eitherFutureKind.definition> & Kind<typeof eitherFutureErrorKind.definition>);
 export interface EitherFutureError extends _EitherFutureError {
 }
+/**
+ * Creates a Future resolved with an EitherLeft<"future">, ideal for propagating a standardized rejection.
+ * 
+ * Signature: `futureError(value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const future = E.futureError("error");
+ * 
+ * // type: E.EitherFutureError
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/futureError
+ * 
+ * @namespace E
+ * 
+ */
 export declare function futureError(value: unknown): EitherFutureError;
 export {};

package/dist/either/future/error.mjs

@@ -3,6 +3,9 @@ import { createEitherKind } from '../kind.mjs';
 import { left } from '../left/create.mjs';
 
 const eitherFutureErrorKind = createEitherKind("future-error");
+/**
+ * {@include either/futureError/index.md}
+ */
 function futureError(value) {
     return eitherFutureKind.setTo(eitherFutureErrorKind.setTo(left("future", value)));
 }

package/dist/either/future/success.cjs

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

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

@@ -5,5 +5,23 @@ export declare const eitherFutureSuccessKind: import("../../common/kind").KindHa
 type _EitherFutureSuccess<GenericValue extends unknown = unknown> = (EitherRight<"future", GenericValue> & Kind<typeof eitherFutureKind.definition> & Kind<typeof eitherFutureSuccessKind.definition>);
 export interface EitherFutureSuccess<GenericValue extends unknown = unknown> extends _EitherFutureSuccess<GenericValue> {
 }
+/**
+ * Creates a Future resolved with an EitherRight<"future">.
+ * 
+ * Signature: `futureSuccess(value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const future = E.futureSuccess("value");
+ * 
+ * // type: E.EitherFutureSuccess<"value">
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/futureSuccess
+ * 
+ * @namespace E
+ * 
+ */
 export declare function futureSuccess<const GenericValue extends unknown>(value: GenericValue): EitherFutureSuccess<GenericValue>;
 export {};

package/dist/either/future/success.mjs

@@ -3,6 +3,9 @@ import { eitherFutureKind } from './base.mjs';
 import { right } from '../right/create.mjs';
 
 const eitherFutureSuccessKind = createEitherKind("future-success");
+/**
+ * {@include either/futureSuccess/index.md}
+ */
 function futureSuccess(value) {
     return eitherFutureKind.setTo(eitherFutureSuccessKind.setTo(right("future", value)));
 }

package/dist/either/hasInformation.d.ts

@@ -3,6 +3,36 @@ import { type EitherLeft } from "./left";
 import { type EitherRight } from "./right";
 import { eitherInformationKind } from "./kind";
 type Either = EitherRight | EitherLeft;
+/**
+ * Type guard based on the literal information stored in the Either. Lets you precisely target a business case without extra introspection.
+ * 
+ * **Supported call styles:**
+ * - Classic predicate: `hasInformation(input, information)` → narrows the input type
+ * - Curried predicate: `hasInformation(information)` → narrows the input type
+ * 
+ * Acts as a type guard and returns "true" when the match succeeds.
+ * 
+ * ```ts
+ * const result = true
+ * 	? false
+ * 		? E.right("right-1", 1)
+ * 		: E.left("left-2", 2)
+ * 	: E.left("left-3", 3);
+ * 
+ * if (E.isLeft(result)) {
+ * 	// type: E.EitherLeft<"left-2", 2> | E.EitherLeft<"left-3", 3>
+ * 
+ * 	if (E.hasInformation(result, "left-2")) {
+ * 		// type: E.EitherLeft<"left-2", 2>
+ * 	}
+ * }
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/hasInformation
+ * 
+ * @namespace E
+ * 
+ */
 export declare function hasInformation<const GenericInput extends unknown, GenericInformation extends (GenericInput extends Either ? ReturnType<typeof eitherInformationKind.getValue<GenericInput>> : never)>(information: GenericInformation): (input: GenericInput) => input is Extract<GenericInput, Kind<typeof eitherInformationKind.definition, GenericInformation>>;
 export declare function hasInformation<const GenericInput extends unknown, GenericInformation extends (GenericInput extends Either ? ReturnType<typeof eitherInformationKind.getValue<GenericInput>> : never)>(input: GenericInput, information: GenericInformation): input is Extract<GenericInput, Kind<typeof eitherInformationKind.definition, GenericInformation>>;
 export {};

package/dist/either/index.cjs

@@ -39,7 +39,9 @@ var when$1 = require('./right/when.cjs');
 var group = require('./right/group.cjs');
 var asyncGroup = require('./right/asyncGroup.cjs');
 
-
+/**
+ * {@include either/index.md}
+ */
 
 exports.hasInformation = hasInformation.hasInformation;
 exports.whenHasInformation = whenHasInformation.whenHasInformation;

package/dist/either/index.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Either utilities for explicit success/error flows. Functions preserve values and return
+ * new results without mutation.
+ * 
+ * **How to import:**
+ * - From the main entry (namespace style)
+ * - Via direct import for tree-shaking
+ * 
+ * ```ts
+ * import { DEither, E } from "@duplojs/utils";
+ * import * as DEither from "@duplojs/utils/either";
+ * import * as E from "@duplojs/utils/either";
+ * ```
+ * 
+ * What you will find in this namespace:
+ * - constructors (`E.left`, `E.right`, `E.bool`, `E.nullable`, `E.nullish`, `E.optional`)
+ * - guards and utilities (`E.hasInformation`, `E.whenHasInformation`, `E.kind`)
+ * - async helpers (`E.future`, `E.safeCallback`)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either
+ * 
+ * @namespace E
+ * 
+ */
 export * from "./bool";
 export * from "./future";
 export * from "./left";

package/dist/either/index.mjs

@@ -36,3 +36,7 @@ export { eitherSuccessKind, success } from './right/success.mjs';
 export { whenIsRight } from './right/when.mjs';
 export { group } from './right/group.mjs';
 export { asyncGroup } from './right/asyncGroup.mjs';
+
+/**
+ * {@include either/index.md}
+ */

package/dist/either/left/create.cjs

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

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

@@ -5,5 +5,34 @@ export declare const eitherLeftKind: import("../../common/kind").KindHandler<imp
 type _EitherLeft<GenericInformation extends string = string, GenericValue extends unknown = unknown> = (Kind<typeof eitherLeftKind.definition> & Kind<typeof eitherInformationKind.definition, GenericInformation> & WrappedValue<GenericValue>);
 export interface EitherLeft<GenericInformation extends string = string, GenericValue extends unknown = unknown> extends _EitherLeft<GenericInformation, GenericValue> {
 }
+/**
+ * Builds an EitherLeft by associating mandatory business information (literal string) with a value representing the error. This is the fundamental brick to signal a contextualized failure.
+ * 
+ * Signature: `left(information, value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = 0 as number;
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	P.when(
+ * 		N.greaterThan(0),
+ * 		(value) => E.right("number.positive", value),
+ * 	),
+ * 	P.otherwise(
+ * 		(value) => E.left("number.notPositive", value),
+ * 	),
+ * );
+ * 
+ * // type: E.EitherRight<"number.positive", number> | E.EitherLeft<"number.notPositive", number>
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/left
+ * 
+ * @namespace E
+ * 
+ */
 export declare function left<GenericInformation extends string, const GenericValue extends unknown = undefined>(information: GenericInformation, value?: GenericValue): EitherLeft<GenericInformation, GenericValue>;
 export {};

package/dist/either/left/create.mjs

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

package/dist/either/left/error.cjs

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

package/dist/either/left/error.d.ts

@@ -4,5 +4,33 @@ export declare const eitherErrorKind: import("../../common/kind").KindHandler<im
 type _EitherError<GenericValue extends unknown = unknown> = (EitherLeft<"error", GenericValue> & Kind<typeof eitherErrorKind.definition>);
 export interface EitherError<GenericValue extends unknown = unknown> extends _EitherError<GenericValue> {
 }
+/**
+ * Handy alias to create an EitherLeft with the info fixed to "error". Useful to signal a generic error without manually providing the info.
+ * 
+ * Signature: `error(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/error
+ * 
+ * @namespace E
+ * 
+ */
 export declare function error<const GenericValue extends unknown>(value: GenericValue): EitherError<GenericValue>;
 export {};

package/dist/either/left/error.mjs

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

package/dist/either/left/fail.cjs

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

package/dist/either/left/fail.d.ts

@@ -4,5 +4,34 @@ export declare const eitherFailKind: import("../../common/kind").KindHandler<imp
 type _EitherFail = (EitherLeft<"fail", never> & Kind<typeof eitherFailKind.definition>);
 export interface EitherFail extends _EitherFail {
 }
+/**
+ * Returns an EitherLeft<"fail", never>: perfect to signal a failure without carrying extra data.
+ * 
+ * Signature: `fail()` → returns a value
+ * 
+ * ```ts
+ * const input = 3 as number;
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	whenElse(
+ * 		N.lessThan(3),
+ * 		(value) => pipe(
+ * 			value,
+ * 			N.add(1),
+ * 			E.success,
+ * 		),
+ * 		E.fail,
+ * 	),
+ * );
+ * 
+ * // type: E.EitherSuccess<number> | E.EitherFail
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/fail
+ * 
+ * @namespace E
+ * 
+ */
 export declare function fail(): EitherFail;
 export {};

package/dist/either/left/fail.mjs

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

package/dist/either/left/is.cjs

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