@duplojs/utils 1.5.15 → 1.6.0

package/dist/clean/primitive/operations/equal.d.ts

@@ -1,4 +1,4 @@
-import { type ToLargeEnsemble, type Unwrap } from "../../../common";
+import { type Unwrap } from "../../../common";
 import { type Primitive, type Primitives } from "../base";
 /**
  * Compares two wrapped primitives (or a primitive and a raw value) with a type guard.
@@ -34,5 +34,5 @@ import { type Primitive, type Primitives } from "../base";
  * @namespace C
  * 
  */
-export declare function equal<GenericInput extends Primitives, GenericValue extends (Primitive<ToLargeEnsemble<Unwrap<GenericInput>>> | ToLargeEnsemble<Unwrap<GenericInput>>)>(value: GenericValue): (input: GenericInput) => input is GenericInput & Primitive<Unwrap<GenericValue>>;
-export declare function equal<GenericInput extends Primitives, GenericValue extends (Primitive<ToLargeEnsemble<Unwrap<GenericInput>>> | ToLargeEnsemble<Unwrap<GenericInput>>)>(input: GenericInput, value: GenericValue): input is GenericInput & Primitive<Unwrap<GenericValue>>;
+export declare function equal<GenericInput extends Primitives, GenericValue extends (Primitive<Unwrap<GenericInput>> | Unwrap<GenericInput>)>(value: GenericValue): (input: GenericInput) => input is GenericInput & Primitive<Unwrap<GenericValue>>;
+export declare function equal<GenericInput extends Primitives, GenericValue extends (Primitive<Unwrap<GenericInput>> | Unwrap<GenericInput>)>(input: GenericInput, value: GenericValue): input is GenericInput & Primitive<Unwrap<GenericValue>>;

package/dist/common/kind.cjs

@@ -24,7 +24,8 @@ function createKind(name) {
         },
         has(input) {
             return input
-                && typeof input === "object"
+                && (typeof input === "object"
+                    || typeof input === "function")
                 && runTimeKey in input;
         },
         getValue(input) {

package/dist/common/kind.d.ts

@@ -94,6 +94,7 @@ export interface ReservedKindNamespace {
     DuplojsUtilsError: true;
     DuplojsUtilsClean: true;
     DuplojsUtilsDate: true;
+    DuplojsUtilsFlow: true;
 }
 type ForbiddenKindNamespace<GenericValue extends string> = (ForbiddenKindCharacters<GenericValue> & ForbiddenString<GenericValue, GetPropsWithValue<ReservedKindNamespace, true>>);
 /**

package/dist/common/kind.mjs

@@ -22,7 +22,8 @@ function createKind(name) {
         },
         has(input) {
             return input
-                && typeof input === "object"
+                && (typeof input === "object"
+                    || typeof input === "function")
                 && runTimeKey in input;
         },
         getValue(input) {

package/dist/flow/breakIf.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+var _break = require('./theFlow/break.cjs');
+
+function* breakIf(value, thePredicate) {
+    if (thePredicate(value) === true) {
+        yield _break.createBreak(value);
+    }
+    else {
+        return value;
+    }
+}
+
+exports.breakIf = breakIf;

package/dist/flow/breakIf.d.ts

@@ -0,0 +1,50 @@
+import { type NeverCoalescing } from "../common";
+import { type Break } from "./theFlow";
+/**
+ * Breaks a flow when a predicate matches a value.
+ * 
+ * **Supported call styles:**
+ * - Classic boolean predicate: `breakIf(value, thePredicate)` -> yields a break effect or returns the value
+ * - Classic predicate overload: `breakIf(value, thePredicate)` -> narrows the matched value type before breaking
+ * 
+ * `breakIf` is designed to be used inside `F.run(...)` or a nested flow executed by `F.exec(...)`.
+ * When the predicate returns `true`, the current flow stops with the provided value as a break result.
+ * When the predicate returns `false`, the original value is returned and the flow continues normally.
+ * 
+ * ```ts
+ * F.run(
+ * 	function *() {
+ * 		yield *F.breakIf(2, (value) => value === 2);
+ * 
+ * 		return "test";
+ * 	},
+ * ); // 2
+ * 
+ * F.run(
+ * 	function *() {
+ * 		const value = yield *F.breakIf("keep", (value) => value === "stop");
+ * 		return value;
+ * 	},
+ * ); // "keep"
+ * 
+ * F.run(
+ * 	function *() {
+ * 		yield *F.step("before break");
+ * 		yield *F.breakIf(2, (value) => value === 2);
+ * 		return "done";
+ * 	},
+ * 	{ includeDetails: true },
+ * ); // { result: 2, steps: ["before break"] }
+ * ```
+ * 
+ * @remarks
+ * - Use `breakIf` to stop the current flow without exiting outer flows
+ * 
+ * @see [`F.exitIf`](https://utils.duplojs.dev/en/v1/api/flow/exitIf) To exit a flow instead of breaking it
+ * @see https://utils.duplojs.dev/en/v1/api/flow/breakIf
+ * 
+ * @namespace F
+ * 
+ */
+export declare function breakIf<GenericValue extends unknown, GenericPredicate extends GenericValue>(value: GenericValue, thePredicate: (value: GenericValue) => value is GenericPredicate): Generator<Break<NeverCoalescing<Extract<GenericValue, GenericPredicate>, GenericPredicate>>, Exclude<GenericValue, GenericPredicate>>;
+export declare function breakIf<GenericValue extends unknown>(value: GenericValue, thePredicate: (value: GenericValue) => boolean): Generator<Break<GenericValue>, GenericValue>;

package/dist/flow/breakIf.mjs

@@ -0,0 +1,12 @@
+import { createBreak } from './theFlow/break.mjs';
+
+function* breakIf(value, thePredicate) {
+    if (thePredicate(value) === true) {
+        yield createBreak(value);
+    }
+    else {
+        return value;
+    }
+}
+
+export { breakIf };

package/dist/flow/defer.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+var defer$1 = require('./theFlow/defer.cjs');
+
+/**
+ * {@include flow/defer/index.md}
+ */
+function* defer(theFunction) {
+    yield defer$1.createDefer(theFunction);
+}
+
+exports.defer = defer;

package/dist/flow/defer.d.ts

@@ -0,0 +1,47 @@
+import { type Defer } from "./theFlow";
+/**
+ * Registers a cleanup callback that runs when the flow finishes.
+ * 
+ * **Supported call styles:**
+ * - Classic: `defer(theFunction)` -> yields a defer effect
+ * 
+ * `defer` stores a callback that is executed after the flow has completed.
+ * It is useful for releasing resources, closing handles, or running cleanup logic after a `break` or a normal return.
+ * Use it inside `F.run(...)` or inside subflows executed by `F.exec(...)`.
+ * 
+ * ```ts
+ * F.run(
+ * 	function *() {
+ * 		yield *F.defer(() => void console.log("close connection"));
+ * 		return "done";
+ * 	},
+ * ); // "done"
+ * 
+ * F.run(
+ * 	function *() {
+ * 		yield *F.defer(() => void console.log("clear cache"));
+ * 		yield *F.breakIf(2, (value) => value === 2);
+ * 		return "done";
+ * 	},
+ * ); // 2
+ * 
+ * await F.run(
+ * 	async function *() {
+ * 		yield *F.defer(async() => {
+ * 			await Promise.resolve();
+ * 		});
+ * 		return Promise.resolve("done");
+ * 	},
+ * ); // Promise<"done">
+ * ```
+ * 
+ * @remarks
+ * - Deferred callbacks run after the flow result has been computed
+ * 
+ * @see [`F.finalizer`](https://utils.duplojs.dev/en/v1/api/flow/finalizer) To register final logic in the same flow system
+ * @see https://utils.duplojs.dev/en/v1/api/flow/defer
+ * 
+ * @namespace F
+ * 
+ */
+export declare function defer<GenericOutput extends unknown>(theFunction: () => GenericOutput): (Generator<Defer<GenericOutput>, undefined> | (GenericOutput extends Promise<unknown> ? AsyncGenerator<Defer<GenericOutput>, undefined> : never));

package/dist/flow/defer.mjs

@@ -0,0 +1,10 @@
+import { createDefer } from './theFlow/defer.mjs';
+
+/**
+ * {@include flow/defer/index.md}
+ */
+function* defer(theFunction) {
+    yield createDefer(theFunction);
+}
+
+export { defer };

package/dist/flow/exec.cjs

@@ -0,0 +1,125 @@
+'use strict';
+
+var index = require('./theFlow/index.cjs');
+var defer = require('./theFlow/defer.cjs');
+var finalizer = require('./theFlow/finalizer.cjs');
+var justExec = require('../common/justExec.cjs');
+var _break = require('./theFlow/break.cjs');
+var exit = require('./theFlow/exit.cjs');
+var step = require('./theFlow/step.cjs');
+var injection = require('./theFlow/injection.cjs');
+var dependence = require('./theFlow/dependence.cjs');
+var forward = require('../common/forward.cjs');
+
+/**
+ * {@include flow/exec/index.md}
+ */
+function exec(theFlow, ...[params]) {
+    let result = undefined;
+    let deferFunctions = undefined;
+    const generator = justExec.justExec(() => {
+        if (Symbol.asyncIterator in theFlow || Symbol.iterator in theFlow) {
+            return forward.forward(theFlow);
+        }
+        else if (typeof theFlow === "function") {
+            return theFlow(params?.input);
+        }
+        else {
+            return index.theFlowKind.getValue(theFlow).run(params?.input);
+        }
+    });
+    if (Symbol.asyncIterator in generator) {
+        return (async function* () {
+            try {
+                do {
+                    result = await generator.next();
+                    if (result.done === true) {
+                        break;
+                    }
+                    else if (_break.breakKind.has(result.value)) {
+                        result = await generator.return(_break.breakKind.getValue(result.value).value);
+                        break;
+                    }
+                    else if (exit.exitKind.has(result.value)) {
+                        yield result.value;
+                    }
+                    else if (defer.deferKind.has(result.value)) {
+                        deferFunctions ??= [];
+                        deferFunctions.push(defer.deferKind.getValue(result.value));
+                    }
+                    else if (finalizer.finalizerKind.has(result.value)) {
+                        yield result.value;
+                    }
+                    else if (step.stepKind.has(result.value)) {
+                        yield result.value;
+                    }
+                    else if (injection.injectionKind.has(result.value)) {
+                        const injectionProperties = injection.injectionKind.getValue(result.value);
+                        const dependenceName = dependence.dependenceHandlerKind.getValue(injectionProperties.dependenceHandler);
+                        if (!params?.dependencies
+                            || !(dependenceName in params.dependencies)) {
+                            yield result.value;
+                        }
+                        else {
+                            injectionProperties.inject(params.dependencies[dependenceName]);
+                        }
+                    }
+                } while (true);
+                return result.value;
+            }
+            finally {
+                await generator.return(undefined);
+                if (deferFunctions) {
+                    await Promise.all(deferFunctions.map(justExec.justExec));
+                }
+            }
+        })();
+    }
+    return (function* () {
+        try {
+            do {
+                result = generator.next();
+                if (result.done === true) {
+                    break;
+                }
+                else if (_break.breakKind.has(result.value)) {
+                    result = generator.return(_break.breakKind.getValue(result.value).value);
+                    break;
+                }
+                else if (exit.exitKind.has(result.value)) {
+                    yield result.value;
+                }
+                else if (defer.deferKind.has(result.value)) {
+                    deferFunctions ??= [];
+                    deferFunctions.push(defer.deferKind.getValue(result.value));
+                }
+                else if (finalizer.finalizerKind.has(result.value)) {
+                    yield result.value;
+                }
+                else if (step.stepKind.has(result.value)) {
+                    yield result.value;
+                }
+                else if (injection.injectionKind.has(result.value)) {
+                    const injectionProperties = injection.injectionKind.getValue(result.value);
+                    const dependenceName = dependence.dependenceHandlerKind.getValue(injectionProperties.dependenceHandler);
+                    if (!params?.dependencies
+                        || !(dependenceName in params.dependencies)) {
+                        yield result.value;
+                    }
+                    else {
+                        injectionProperties.inject(params.dependencies[dependenceName]);
+                    }
+                }
+            } while (true);
+            return result.value;
+        }
+        finally {
+            generator.return(undefined);
+            if (deferFunctions) {
+                deferFunctions.map(justExec.justExec);
+            }
+        }
+    })();
+}
+
+exports.exec = exec;

package/dist/flow/exec.d.ts

@@ -0,0 +1,83 @@
+import { type SimplifyTopLevel, type IsEqual, type IsExtends, type Or } from "../common";
+import { type TheFlowGenerator, type TheFlow, type TheFlowFunction, type FlowInput, type WrapFlow, type Exit, type Break, type Injection, type Step, type FlowDependencies } from "./theFlow";
+import { type Finalizer } from "./theFlow/finalizer";
+type ComputeExecParams<GenericInput extends unknown, GenericDependencies extends Record<string, unknown>> = SimplifyTopLevel<(Or<[
+    IsEqual<GenericInput, unknown>,
+    IsEqual<GenericInput, never>,
+    IsExtends<GenericInput, undefined>
+]> extends true ? {
+    input?: GenericInput;
+} : {
+    input: GenericInput;
+}) & {
+    dependencies?: GenericDependencies;
+}>;
+export type ExecResult<GenericFlow extends TheFlow> = GenericFlow extends TheFlow<infer InferredFunction> ? InferredFunction extends TheFlowFunction<any, infer InferredGenerator> ? InferredGenerator extends TheFlowGenerator<infer InferredOutput, infer InferredEffect> ? [
+    ((InferredEffect extends Break<infer InferredValue> ? InferredValue : never) | InferredOutput),
+    Extract<InferredEffect, Exit | Injection | Finalizer | Step>
+] extends [
+    infer InferredOutput,
+    infer InferredEffect
+] ? InferredGenerator extends AsyncGenerator ? AsyncGenerator<InferredEffect, InferredOutput> : Generator<InferredEffect, InferredOutput> : never : never : never : never;
+/**
+ * Executes a nested flow inside the current flow.
+ * 
+ * **Supported call styles:**
+ * - Classic with a flow function: `exec(theFlow, params?)` -> runs the provided flow function
+ * - Classic with a flow instance: `exec(theFlow, params?)` -> runs a flow created with `F.create(...)`
+ * - Classic with a generator: `exec(theGenerator, params?)` -> runs an existing generator directly
+ * 
+ * `exec` lets a parent flow call another flow while staying in the same execution model.
+ * Break values are converted into the local return value of `exec`, while exit, step, injection, and finalizer effects are forwarded to the outer flow.
+ * It can be used in synchronous and asynchronous flows.
+ * 
+ * ```ts
+ * 
+ * const upperCaseFlow = F.create(
+ * 	function *(input: string) {
+ * 		return input.toUpperCase();
+ * 	},
+ * );
+ * 
+ * const userFlow = F.create(
+ * 	function *(id: number) {
+ * 		return `user-${id}`;
+ * 	},
+ * );
+ * 
+ * const breakableFlow = F.create(
+ * 	function *(value: number) {
+ * 		yield *F.breakIf(value, (current) => current === 2);
+ * 		return "done";
+ * 	},
+ * );
+ * 
+ * F.run(
+ * 	function *() {
+ * 		return yield *F.exec(upperCaseFlow, { input: "hello" });
+ * 	},
+ * ); // "HELLO"
+ * 
+ * F.run(
+ * 	function *() {
+ * 		return yield *F.exec(userFlow, { input: 42 });
+ * 	},
+ * ); // "user-42"
+ * 
+ * F.run(
+ * 	function *() {
+ * 		return yield *F.exec(breakableFlow, { input: 2 });
+ * 	},
+ * ```
+ * 
+ * @remarks
+ * - `exec` is useful for composing small flows into larger ones
+ * 
+ * @see [`F.run`](https://utils.duplojs.dev/en/v1/api/flow/run) To execute the root flow
+ * @see https://utils.duplojs.dev/en/v1/api/flow/exec
+ * 
+ * @namespace F
+ * 
+ */
+export declare function exec<GenericFlow extends (TheFlowFunction | TheFlow | TheFlowGenerator), GenericWrapFlow extends WrapFlow<GenericFlow>, const GenericParams extends ComputeExecParams<FlowInput<GenericWrapFlow>, FlowDependencies<GenericWrapFlow>>>(theFlow: GenericFlow, ...[params]: ({} extends GenericParams ? [params?: GenericParams] : [params: GenericParams])): ExecResult<WrapFlow<GenericFlow>>;
+export {};

package/dist/flow/exec.mjs

@@ -0,0 +1,123 @@
+import { theFlowKind } from './theFlow/index.mjs';
+import { deferKind } from './theFlow/defer.mjs';
+import { finalizerKind } from './theFlow/finalizer.mjs';
+import { justExec } from '../common/justExec.mjs';
+import { breakKind } from './theFlow/break.mjs';
+import { exitKind } from './theFlow/exit.mjs';
+import { stepKind } from './theFlow/step.mjs';
+import { injectionKind } from './theFlow/injection.mjs';
+import { dependenceHandlerKind } from './theFlow/dependence.mjs';
+import { forward } from '../common/forward.mjs';
+
+/**
+ * {@include flow/exec/index.md}
+ */
+function exec(theFlow, ...[params]) {
+    let result = undefined;
+    let deferFunctions = undefined;
+    const generator = justExec(() => {
+        if (Symbol.asyncIterator in theFlow || Symbol.iterator in theFlow) {
+            return forward(theFlow);
+        }
+        else if (typeof theFlow === "function") {
+            return theFlow(params?.input);
+        }
+        else {
+            return theFlowKind.getValue(theFlow).run(params?.input);
+        }
+    });
+    if (Symbol.asyncIterator in generator) {
+        return (async function* () {
+            try {
+                do {
+                    result = await generator.next();
+                    if (result.done === true) {
+                        break;
+                    }
+                    else if (breakKind.has(result.value)) {
+                        result = await generator.return(breakKind.getValue(result.value).value);
+                        break;
+                    }
+                    else if (exitKind.has(result.value)) {
+                        yield result.value;
+                    }
+                    else if (deferKind.has(result.value)) {
+                        deferFunctions ??= [];
+                        deferFunctions.push(deferKind.getValue(result.value));
+                    }
+                    else if (finalizerKind.has(result.value)) {
+                        yield result.value;
+                    }
+                    else if (stepKind.has(result.value)) {
+                        yield result.value;
+                    }
+                    else if (injectionKind.has(result.value)) {
+                        const injectionProperties = injectionKind.getValue(result.value);
+                        const dependenceName = dependenceHandlerKind.getValue(injectionProperties.dependenceHandler);
+                        if (!params?.dependencies
+                            || !(dependenceName in params.dependencies)) {
+                            yield result.value;
+                        }
+                        else {
+                            injectionProperties.inject(params.dependencies[dependenceName]);
+                        }
+                    }
+                } while (true);
+                return result.value;
+            }
+            finally {
+                await generator.return(undefined);
+                if (deferFunctions) {
+                    await Promise.all(deferFunctions.map(justExec));
+                }
+            }
+        })();
+    }
+    return (function* () {
+        try {
+            do {
+                result = generator.next();
+                if (result.done === true) {
+                    break;
+                }
+                else if (breakKind.has(result.value)) {
+                    result = generator.return(breakKind.getValue(result.value).value);
+                    break;
+                }
+                else if (exitKind.has(result.value)) {
+                    yield result.value;
+                }
+                else if (deferKind.has(result.value)) {
+                    deferFunctions ??= [];
+                    deferFunctions.push(deferKind.getValue(result.value));
+                }
+                else if (finalizerKind.has(result.value)) {
+                    yield result.value;
+                }
+                else if (stepKind.has(result.value)) {
+                    yield result.value;
+                }
+                else if (injectionKind.has(result.value)) {
+                    const injectionProperties = injectionKind.getValue(result.value);
+                    const dependenceName = dependenceHandlerKind.getValue(injectionProperties.dependenceHandler);
+                    if (!params?.dependencies
+                        || !(dependenceName in params.dependencies)) {
+                        yield result.value;
+                    }
+                    else {
+                        injectionProperties.inject(params.dependencies[dependenceName]);
+                    }
+                }
+            } while (true);
+            return result.value;
+        }
+        finally {
+            generator.return(undefined);
+            if (deferFunctions) {
+                deferFunctions.map(justExec);
+            }
+        }
+    })();
+}
+
+export { exec };

package/dist/flow/exitIf.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+var exit = require('./theFlow/exit.cjs');
+
+function* exitIf(value, thePredicate) {
+    if (thePredicate(value) === true) {
+        yield exit.createExit(value);
+    }
+    else {
+        return value;
+    }
+}
+
+exports.exitIf = exitIf;

package/dist/flow/exitIf.d.ts

@@ -0,0 +1,67 @@
+import { type NeverCoalescing } from "../common";
+import { type Exit } from "./theFlow";
+/**
+ * Exits a flow when a predicate matches a value.
+ * 
+ * **Supported call styles:**
+ * - Classic boolean predicate: `exitIf(value, thePredicate)` -> yields an exit effect or returns the value
+ * - Classic predicate overload: `exitIf(value, thePredicate)` -> narrows the matched value type before exiting
+ * 
+ * `exitIf` is designed to be used inside `F.run(...)` or a nested flow executed by `F.exec(...)`.
+ * When the predicate returns `true`, the current flow exits with the provided value.
+ * When the predicate returns `false`, the original value is returned and the flow continues normally.
+ * Because the exit effect is forwarded through nested `exec(...)` calls, it can stop a deeply nested flow from any depth.
+ * 
+ * ```ts
+ * const thirdLevelFlow = F.create(
+ * 	function *() {
+ * 		yield *F.exitIf("stop", (value) => value === "stop");
+ * 		return "done";
+ * 	},
+ * );
+ * 
+ * const secondLevelFlow = F.create(
+ * 	function *() {
+ * 		return yield *F.exec(thirdLevelFlow);
+ * 	},
+ * );
+ * 
+ * const firstLevelFlow = F.create(
+ * 	function *() {
+ * 		return yield *F.exec(secondLevelFlow);
+ * 	},
+ * );
+ * 
+ * F.run(
+ * 	function *() {
+ * 		return yield *F.exitIf(2, (value) => value === 2);
+ * 	},
+ * ); // 2
+ * 
+ * F.run(
+ * 	function *() {
+ * 		const value = yield *F.exitIf("keep", (value) => value === "stop");
+ * 		return value;
+ * 	},
+ * ); // "keep"
+ * 
+ * F.run(
+ * 	function *() {
+ * 		yield *F.step("before deep exit");
+ * 		return yield *F.exec(firstLevelFlow);
+ * 	},
+ * 	{ includeDetails: true },
+ * ); // { result: "stop", steps: ["before deep exit"] }
+ * ```
+ * 
+ * @remarks
+ * - Use `exitIf` when the whole running flow should stop with a value
+ * 
+ * @see [`F.breakIf`](https://utils.duplojs.dev/en/v1/api/flow/breakIf) To stop only the current local flow branch
+ * @see https://utils.duplojs.dev/en/v1/api/flow/exitIf
+ * 
+ * @namespace F
+ * 
+ */
+export declare function exitIf<GenericValue extends unknown, GenericPredicate extends GenericValue>(value: GenericValue, thePredicate: (value: GenericValue) => value is GenericPredicate): Generator<Exit<NeverCoalescing<Extract<GenericValue, GenericPredicate>, GenericPredicate>>, Exclude<GenericValue, GenericPredicate>>;
+export declare function exitIf<GenericValue extends unknown>(value: GenericValue, thePredicate: (value: GenericValue) => boolean): Generator<Exit<GenericValue>, GenericValue>;

package/dist/flow/exitIf.mjs

@@ -0,0 +1,12 @@
+import { createExit } from './theFlow/exit.mjs';
+
+function* exitIf(value, thePredicate) {
+    if (thePredicate(value) === true) {
+        yield createExit(value);
+    }
+    else {
+        return value;
+    }
+}
+
+export { exitIf };

package/dist/flow/finalizer.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+var finalizer$1 = require('./theFlow/finalizer.cjs');
+
+/**
+ * {@include flow/finalizer/index.md}
+ */
+function* finalizer(theFunction) {
+    yield finalizer$1.createFinalizer(theFunction);
+}
+
+exports.finalizer = finalizer;