feat(64): domain flow

docs/.vitepress/config.ts

@@ -180,6 +180,10 @@ export default defineConfig({
 								text: "Either",
 								link: "/fr/v1/api/either/",
 							},
+							{
+								text: "Flow",
+								link: "/fr/v1/api/flow/",
+							},
 							{
 								text: "Generator",
 								link: "/fr/v1/api/generator/",
@@ -302,6 +306,10 @@ export default defineConfig({
 								text: "Either",
 								link: "/en/v1/api/either/",
 							},
+							{
+								text: "Flow",
+								link: "/en/v1/api/flow/",
+							},
 							{
 								text: "Generator",
 								link: "/en/v1/api/generator/",

docs/.vitepress/theme/components/monacoTSEditor/useComponent.ts

@@ -56,6 +56,8 @@ function initMonaco() {
 			"@duplojs/utils/dataParser": ["node_modules/@duplojs/utils/dataParser/index.d.ts"],
 			"@duplojs/utils/dataParserCoerce": ["node_modules/@duplojs/utils/dataParser/parsers/coerce/index.d.ts"],
 			"@duplojs/utils/dataParserExtended": ["node_modules/@duplojs/utils/dataParser/extended/index.d.ts"],
+			"@duplojs/utils/flow": ["node_modules/@duplojs/utils/flow/index.d.ts"],
+			"@duplojs/utils/flow/initializer": ["node_modules/@duplojs/utils/flow/initializer.d.ts"],
 			"@duplojs/utils/generator": ["node_modules/@duplojs/utils/generator/index.d.ts"],
 			"@duplojs/utils/number": ["node_modules/@duplojs/utils/number/index.d.ts"],
 			"@duplojs/utils/object": ["node_modules/@duplojs/utils/object/index.d.ts"],

docs/en/v1/api/either/index.md

@@ -5,8 +5,8 @@ prev:
   text: 'Date'
   link: '/en/v1/api/date/'
 next:
-  text: 'Generator'
-  link: '/en/v1/api/generator/'
+  text: 'Flow'
+  link: '/en/v1/api/flow/'
 ---
 
 # Either

docs/en/v1/api/flow/breakIf.md

@@ -0,0 +1,47 @@
+---
+outline: [2, 3]
+description: "Stops the current flow branch when a predicate matches."
+prev:
+  text: "exec"
+  link: "/en/v1/api/flow/exec"
+next:
+  text: "exitIf"
+  link: "/en/v1/api/flow/exitIf"
+---
+
+# breakIf
+
+The **`breakIf()`** function tests a value with a predicate and breaks the current flow branch when the predicate returns `true`. If the predicate fails, the value is returned and the flow continues.
+
+## Interactive example
+
+<MonacoTSEditor
+  src="/examples/v1/api/flow/breakIf/tryout.doc.ts"
+  majorVersion="v1"
+  height="229px"
+/>
+
+## Syntax
+
+```typescript
+function breakIf<
+	GenericValue extends unknown
+>(
+	value: GenericValue,
+	thePredicate: (value: GenericValue) => boolean
+): Generator<Break<GenericValue>, GenericValue>
+```
+
+## Parameters
+
+- `value`: The value to test.
+- `thePredicate`: Predicate used to decide whether the current branch must stop.
+
+## Return value
+
+A generator that yields a break effect when the predicate returns `true`, otherwise returns the original value.
+
+## See also
+
+- [`exitIf`](/en/v1/api/flow/exitIf) - Exits the whole running flow instead of only breaking locally
+- [`run`](/en/v1/api/flow/run) - Executes a flow and handles break effects

docs/en/v1/api/flow/create.md

@@ -0,0 +1,45 @@
+---
+outline: [2, 3]
+description: "Creates a reusable flow object from a flow function."
+prev:
+  text: "Flow"
+  link: "/en/v1/api/flow/"
+next:
+  text: "run"
+  link: "/en/v1/api/flow/run"
+---
+
+# create
+
+The **`create()`** function wraps a generator-based flow function into a reusable flow object that can later be executed with `F.run()` or composed with `F.exec()`.
+
+## Interactive example
+
+<MonacoTSEditor
+  src="/examples/v1/api/flow/create/tryout.doc.ts"
+  majorVersion="v1"
+  height="250px"
+/>
+
+## Syntax
+
+```typescript
+function create<
+	GenericTheFlowFunction extends TheFlowFunction
+>(
+	theFunction: GenericTheFlowFunction
+): TheFlow<GenericTheFlowFunction>
+```
+
+## Parameters
+
+- `theFunction`: The generator or async generator function that defines the flow.
+
+## Return value
+
+A flow object that stores the provided function and can be executed many times with `F.run()` or `F.exec()`.
+
+## See also
+
+- [`run`](/en/v1/api/flow/run) - Executes a created flow
+- [`exec`](/en/v1/api/flow/exec) - Executes a created flow inside another flow

docs/en/v1/api/flow/createDependence.md

@@ -0,0 +1,45 @@
+---
+outline: [2, 3]
+description: "Creates a typed dependency handler for the flow system."
+prev:
+  text: "finalizer"
+  link: "/en/v1/api/flow/finalizer"
+next:
+  text: "inject"
+  link: "/en/v1/api/flow/inject"
+---
+
+# createDependence
+
+The **`createDependence()`** function creates a typed dependency handler identified by a string name. This handler is then used with `F.inject()` and matched against the `dependencies` object passed to `F.run()` or `F.exec()`.
+
+## Interactive example
+
+<MonacoTSEditor
+  src="/examples/v1/api/flow/createDependence/tryout.doc.ts"
+  majorVersion="v1"
+  height="292px"
+/>
+
+## Syntax
+
+```typescript
+function createDependence<
+	GenericName extends string
+>(
+	name: GenericName
+): DependenceHandlerDefinition<GenericName>
+```
+
+## Parameters
+
+- `name`: Dependency key used to match a value inside the runner dependency bag.
+
+## Return value
+
+A typed dependence handler definition. Once specialized with a type, it can be used with `F.inject()` to retrieve the matching dependency inside a flow.
+
+## See also
+
+- [`inject`](/en/v1/api/flow/inject) - Requests a dependency from the runner
+- [`run`](/en/v1/api/flow/run) - Provides dependencies to the flow

docs/en/v1/api/flow/createInitializer.md

@@ -0,0 +1,52 @@
+---
+outline: [2, 3]
+description: "Creates an initializer that returns a value and automatically registers flow cleanup effects."
+prev:
+  text: "step"
+  link: "/en/v1/api/flow/step"
+next:
+  text: "Flow"
+  link: "/en/v1/api/flow/"
+---
+
+# createInitializer
+
+The **`createInitializer()`** function wraps an initializer and turns it into a flow-compatible generator that can automatically register a `defer` callback, a `finalizer` callback, or both.
+
+## Interactive example
+
+<MonacoTSEditor
+  src="/examples/v1/api/flow/createInitializer/tryout.doc.ts"
+  majorVersion="v1"
+  height="334px"
+/>
+
+## Syntax
+
+```typescript
+function createInitializer<
+	GenericArgs extends unknown[],
+	GenericOutput extends unknown
+>(
+	initializer: (...args: GenericArgs) => GenericOutput,
+	params: {
+		defer?: (output: Awaited<GenericOutput>) => unknown;
+		finalizer?: (output: Awaited<GenericOutput>) => unknown;
+	}
+): (...args: GenericArgs) => Generator | AsyncGenerator
+```
+
+## Parameters
+
+- `initializer`: Function producing the value to expose inside the flow.
+- `params.defer`: Optional cleanup callback created from the produced value.
+- `params.finalizer`: Optional final callback created from the produced value.
+
+## Return value
+
+A function returning a generator compatible with `F.run()`. The generator returns the initializer result and registers the configured cleanup effects.
+
+## See also
+
+- [`defer`](/en/v1/api/flow/defer) - Registers a cleanup callback
+- [`finalizer`](/en/v1/api/flow/finalizer) - Registers a final callback

docs/en/v1/api/flow/defer.md

@@ -0,0 +1,45 @@
+---
+outline: [2, 3]
+description: "Registers a cleanup callback executed when the flow finishes."
+prev:
+  text: "exitIf"
+  link: "/en/v1/api/flow/exitIf"
+next:
+  text: "finalizer"
+  link: "/en/v1/api/flow/finalizer"
+---
+
+# defer
+
+The **`defer()`** function registers a cleanup callback that the flow runtime executes after the flow ends. It is useful to release resources or run side effects after a return or a break.
+
+## Interactive example
+
+<MonacoTSEditor
+  src="/examples/v1/api/flow/defer/tryout.doc.ts"
+  majorVersion="v1"
+  height="292px"
+/>
+
+## Syntax
+
+```typescript
+function defer<
+	GenericOutput extends unknown
+>(
+	theFunction: () => GenericOutput
+): Generator<Defer<GenericOutput>, undefined>
+```
+
+## Parameters
+
+- `theFunction`: Cleanup callback to run when the flow finishes.
+
+## Return value
+
+A generator yielding a defer effect. The callback result itself is not returned by the flow.
+
+## See also
+
+- [`finalizer`](/en/v1/api/flow/finalizer) - Registers another end-of-flow callback
+- [`run`](/en/v1/api/flow/run) - Executes deferred callbacks when the flow completes

docs/en/v1/api/flow/exec.md

@@ -0,0 +1,52 @@
+---
+outline: [2, 3]
+description: "Executes a nested flow inside the current flow."
+prev:
+  text: "run"
+  link: "/en/v1/api/flow/run"
+next:
+  text: "breakIf"
+  link: "/en/v1/api/flow/breakIf"
+---
+
+# exec
+
+The **`exec()`** function runs a nested flow from inside the current flow. It lets you compose flows while forwarding steps, exits, finalizers, and dependency injection to the outer runner.
+
+## Interactive example
+
+<MonacoTSEditor
+  src="/examples/v1/api/flow/exec/tryout.doc.ts"
+  majorVersion="v1"
+  height="334px"
+/>
+
+## Syntax
+
+```typescript
+function exec<
+	GenericFlow extends TheFlowFunction | TheFlow | TheFlowGenerator
+>(
+	theFlow: GenericFlow,
+	params?: {
+		input?: unknown;
+		dependencies?: Record<string, unknown>;
+	}
+): Generator | AsyncGenerator
+```
+
+## Parameters
+
+- `theFlow`: A flow function, a created flow, or an existing generator to execute.
+- `params.input`: Optional input passed to the nested flow.
+- `params.dependencies`: Optional dependency overrides for the nested execution.
+
+## Return value
+
+A generator compatible with the current flow. When the nested flow breaks, `exec()` returns the break value locally. Other supported effects continue to propagate outward.
+
+## See also
+
+- [`run`](/en/v1/api/flow/run) - Executes the root flow
+- [`create`](/en/v1/api/flow/create) - Creates a reusable flow
+- [`exitIf`](/en/v1/api/flow/exitIf) - Exits a flow from any nested depth

docs/en/v1/api/flow/exitIf.md

@@ -0,0 +1,47 @@
+---
+outline: [2, 3]
+description: "Exits the running flow when a predicate matches, even from nested flows."
+prev:
+  text: "breakIf"
+  link: "/en/v1/api/flow/breakIf"
+next:
+  text: "defer"
+  link: "/en/v1/api/flow/defer"
+---
+
+# exitIf
+
+The **`exitIf()`** function tests a value with a predicate and exits the running flow when the predicate returns `true`. Because exit effects are forwarded through `F.exec()`, it can stop a flow from deep nested levels.
+
+## Interactive example
+
+<MonacoTSEditor
+  src="/examples/v1/api/flow/exitIf/tryout.doc.ts"
+  majorVersion="v1"
+  height="355px"
+/>
+
+## Syntax
+
+```typescript
+function exitIf<
+	GenericValue extends unknown
+>(
+	value: GenericValue,
+	thePredicate: (value: GenericValue) => boolean
+): Generator<Exit<GenericValue>, GenericValue>
+```
+
+## Parameters
+
+- `value`: The value to test.
+- `thePredicate`: Predicate used to decide whether the running flow must exit.
+
+## Return value
+
+A generator that yields an exit effect when the predicate returns `true`, otherwise returns the original value.
+
+## See also
+
+- [`breakIf`](/en/v1/api/flow/breakIf) - Stops only the current local branch
+- [`exec`](/en/v1/api/flow/exec) - Forwards exit effects across nested flows