@duplojs/utils 1.4.32 → 1.4.34

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

@@ -7,12 +7,12 @@ import { type AnyValue } from "../../common";
 type Either = EitherRight | EitherLeft;
 type ComputeEitherFutureSuccessResult<GenericValue extends unknown> = IsEqual<never, Exclude<GenericValue, Either>> extends false ? EitherFutureSuccess<Exclude<GenericValue, Either>> : never;
 type ComputeEitherFutureErrorResult<GenericValue extends unknown> = GenericValue extends Future<any> ? GenericValue : GenericValue extends Promise<unknown> ? EitherFutureError : never;
-type ComputeFutureEitherResult<GenericValue extends unknown = unknown> = (Extract<Awaited<GenericValue>, Either> | ComputeEitherFutureSuccessResult<Awaited<GenericValue>> | ComputeEitherFutureErrorResult<GenericValue>);
+type ComputeFutureEitherResult<GenericValue extends unknown = unknown> = Extract<(Extract<Awaited<GenericValue>, Either> | ComputeEitherFutureSuccessResult<Awaited<GenericValue>> | ComputeEitherFutureErrorResult<GenericValue>), any>;
 export type FutureEitherAllResult<GenericArray extends readonly unknown[] | []> = Future<{
     -readonly [Prop in keyof GenericArray]: Awaited<Future<GenericArray[Prop]>>;
 }>;
 declare const kind = "kind-future-either";
-export declare class Future<const GenericValue extends unknown = unknown> extends Promise<ComputeFutureEitherResult<GenericValue>> {
+export declare class Future<const GenericValue extends unknown = unknown> extends Promise<Extract<ComputeFutureEitherResult<GenericValue>, any>> {
     constructor(value: GenericValue);
     [kind]: unknown;
     then<TResult1 = Extract<ComputeFutureEitherResult<GenericValue>, any>, TResult2 = never>(onfulfilled?: ((value: Extract<ComputeFutureEitherResult<GenericValue>, any>) => TResult1 | PromiseLike<TResult1>) | null): Promise<TResult1 | TResult2>;
@@ -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)

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

@@ -1,2 +1,24 @@
 import { type EitherLeft } from "./create";
+/**
+ * Type guard that checks whether a value is an EitherLeft. Ideal to secure an unwrap or trigger an error branch.
+ * 
+ * Signature: `isLeft(input)` → returns a value
+ * 
+ * Acts as a type guard and narrows the input type when true.
+ * 
+ * ```ts
+ * const result = false
+ * 	? E.ok()
+ * 	: E.fail();
+ * 
+ * if (E.isLeft(result)) {
+ * 	// type: E.EitherFail
+ * }
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/isLeft
+ * 
+ * @namespace E
+ * 
+ */
 export declare function isLeft<GenericInput extends unknown>(input: GenericInput): input is Extract<GenericInput, EitherLeft>;

package/dist/either/left/is.mjs

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

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

@@ -1,4 +1,30 @@
 import { type EscapeVoid, type AnyValue, type Unwrap, type BreakGenericLink } from "../../common";
 import { type EitherLeft } from "./create";
+/**
+ * Executes a function only when the input is an EitherLeft. Otherwise, the original value is returned as-is.
+ * 
+ * **Supported call styles:**
+ * - Classic: `whenIsLeft(input, theFunction)` → returns a value
+ * - Curried: `whenIsLeft(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.whenIsLeft((value) => {
+ * 		// type: "false"
+ * 	}),
+ * );
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/whenIsLeft
+ * 
+ * @namespace E
+ * 
+ */
 export declare function whenIsLeft<const GenericInput extends unknown, const GenericOutput extends AnyValue | EscapeVoid>(theFunction: (eitherValue: Unwrap<Extract<BreakGenericLink<GenericInput>, EitherLeft>>) => GenericOutput): (input: GenericInput) => Exclude<BreakGenericLink<GenericInput>, EitherLeft> | GenericOutput;
 export declare function whenIsLeft<const GenericInput extends unknown, const GenericOutput extends AnyValue | EscapeVoid>(input: GenericInput, theFunction: (eitherValue: Unwrap<Extract<BreakGenericLink<GenericInput>, EitherLeft>>) => GenericOutput): Exclude<GenericInput, EitherLeft> | GenericOutput;

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

@@ -1,4 +1,22 @@
 import { type EitherNullableEmpty } from "./empty";
 import { type EitherNullableFilled } from "./filled";
+/**
+ * Wraps a null or non-null value in an Either, while keeping the information on whether it is filled or empty.
+ * 
+ * Signature: `nullable(value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const result = E.nullable(true ? "value" : null);
+ * 
+ * // type: E.EitherNullableEmpty | E.EitherNullableFilled<"value">
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/either/nullable
+ * 
+ * @namespace E
+ * 
+ */
 export declare function nullable<const GenericValue extends unknown = null>(value: GenericValue): GenericValue extends null ? EitherNullableEmpty : EitherNullableFilled<GenericValue>;
 export type Nullable<GenericValue extends unknown> = EitherNullableFilled<GenericValue> | EitherNullableEmpty;

package/dist/either/nullable/empty.cjs

@@ -9,6 +9,15 @@ var is$1 = require('../right/is.cjs');
 var unwrap = require('../../common/unwrap.cjs');
 
 const eitherNullableEmptyKind = kind.createEitherKind("nullable-empty");
+/**
+ * {@include either/isNullableEmpty/index.md}
+ */
+/**
+ * {@include either/nullableEmpty/index.md}
+ */
+/**
+ * {@include either/whenIsNullableEmpty/index.md}
+ */
 function nullableEmpty() {
     return base.eitherNullableKind.setTo(eitherNullableEmptyKind.setTo(create.left("nullable", null)));
 }