@typed/fx 2.0.0-beta.1 → 2.0.0-beta.10

package/dist/Fx/combinators/keyed.d.ts

@@ -1,24 +1,98 @@
+import * as Cause from "effect/Cause";
 import * as Duration from "effect/Duration";
 import * as Scope from "effect/Scope";
 import * as RefSubject from "../../RefSubject/RefSubject.js";
 import type { Fx } from "../Fx.js";
 /**
  * Configuration options for the `keyed` combinator.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The options put identity, per-identity work, and output coalescing beside one
+ * another so callers can choose collection behavior without exposing the keyed
+ * implementation's maps, child Scopes, or diff patches.
+ *
+ * ## Ownership and lifetime
+ *
+ * The options object acquires nothing. {@link keyed} invokes `onValue` once per
+ * admitted key. Its run fiber belongs to the outer parent Scope; the per-key
+ * child Scope is supplied to that Fx for resources it explicitly registers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * interface Row { readonly id: string; readonly value: number }
+ *
+ * const options: Fx.KeyedOptions<Row, string, number, never, never> = {
+ *   getKey: (row) => row.id,
+ *   onValue: (row) => Fx.map(row, ({ value }) => value)
+ * }
+ * ```
+ *
  * @since 1.0.0
- * @category models
+ * @category Operator options
  */
 export interface KeyedOptions<A, B, C, E2, R2> {
     /**
-     * Function to extract a unique key from an element.
+     * Extracts the stable identity of an element.
+     *
+     * @remarks
+     * ## Why
+     *
+     * A key lets value updates and moves reuse one existing child rather than
+     * interpreting array position as identity.
+     *
+     * ## Ownership and lifetime
+     *
+     * The function is called synchronously while processing a source array. It
+     * acquires no resource; keys are retained only while their entries are live.
+     *
+     * @since 1.0.0
+     * @category models
      */
     readonly getKey: (a: A) => B;
     /**
-     * Function to transform a value into an Fx, receiving a RefSubject of the value.
-     * This allows the transformation to react to updates of the same item (same key).
+     * Creates the Fx for one key from its live value RefSubject and stable key.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Passing a `RefSubject` separates identity from the current value: later
+     * values with the same key update the existing child instead of recreating it.
+     *
+     * ## Ownership and lifetime
+     *
+     * `keyed` calls this once when a key is added and forks its run fiber in the
+     * outer parent Scope. It provides a per-key child `Scope` to the run, so
+     * resources registered through that service close when the key is removed.
+     * Closing the child Scope does not by itself interrupt an arbitrary returned
+     * Fx run fiber; resourceful work must honor the supplied Scope. Failures and
+     * services remain on the returned `keyed` Fx.
+     *
+     * @since 1.0.0
+     * @category models
      */
     readonly onValue: (ref: RefSubject.RefSubject<A>, key: B) => Fx<C, E2, R2 | Scope.Scope>;
     /**
-     * Optional debounce duration for emission.
+     * Delays and coalesces array emissions after keyed state changes.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Several child updates can describe one logical collection change. Debounce
+     * replaces the pending array emission so consumers receive the latest coherent
+     * ready prefix rather than every intermediate scheduling step.
+     *
+     * ## Ownership and lifetime
+     *
+     * The delay fiber belongs to the outer keyed `Scope`. A later change interrupts
+     * and replaces it; outer completion waits for the final scheduled emission and
+     * interruption discards it. Omission uses a one-millisecond delay.
+     *
+     * @since 1.0.0
+     * @category models
      */
     readonly debounce?: Duration.Input;
 }
@@ -29,16 +103,56 @@ export interface KeyedOptions<A, B, C, E2, R2> {
  * When the input list changes:
  * - New keys cause `onValue` to be called.
  * - Existing keys have their `RefSubject` updated with the new value.
- * - Removed keys have their corresponding Fx and scope cleaned up.
+ * - Removed keys close the supplied child Scope and clean resources registered
+ *   through it; the `onValue` run fiber remains owned by the outer parent Scope.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A stable key separates identity from position. Consumers can move or update
+ * the exact result already associated with a value instead of recreating every
+ * result when a collection changes. This is the state-preserving substrate used
+ * by keyed template rendering, but the combinator itself is renderer-agnostic.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each key receives its own `RefSubject` and child `Scope`. Reusing a key updates
+ * that subject in place. Removing a key closes the child Scope and therefore the
+ * resources registered through its supplied Scope service. The `onValue` run
+ * fiber itself is forked in the outer parent Scope, so child-Scope closure does
+ * not guarantee interruption of an arbitrary Fx that ignores Scope. Interrupting
+ * the outer run closes the parent and remaining children. Source and `onValue`
+ * failures, services, and Scope requirements remain visible in the return type.
+ *
+ * ## Ordering and failures
+ *
+ * Each source array produces a unique-key diff. Added keys start one child Fx;
+ * reused keys update their existing RefSubject, including moves; removed keys
+ * have their child Scope closed. A child may emit repeatedly, replacing only
+ * that key's latest output. Arrays follow current source order and contain the
+ * contiguous ready prefix: a later key is withheld until every earlier key has
+ * emitted at least once. Debounce coalesces scheduled arrays, not child Fx
+ * values. Duplicate keys fail with `Cause.IllegalArgumentError` rather than
+ * sharing a child lifetime.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const rows = Fx.keyed(Fx.succeed([{ id: "a", value: 1 }]), {
+ *   getKey: (row) => row.id,
+ *   onValue: (row) => Fx.map(row, ({ value }) => value)
+ * })
+ * ```
  *
  * @param fx - An `Fx` emitting an array of values.
  * @param options - Configuration options.
  * @returns An `Fx` emitting an array of results.
  * @since 1.0.0
- * @category combinators
+ * @category Keyed work
  */
 export declare const keyed: {
-    <A, B extends PropertyKey, C, E2, R2>(options: KeyedOptions<A, B, C, E2, R2>): <E, R>(fx: Fx<ReadonlyArray<A>, E, R>) => Fx<ReadonlyArray<C>, E | E2, R | R2 | Scope.Scope>;
-    <A, E, R, B extends PropertyKey, C, E2, R2>(fx: Fx<ReadonlyArray<A>, E, R>, options: KeyedOptions<A, B, C, E2, R2>): Fx<ReadonlyArray<C>, E | E2, R | R2 | Scope.Scope>;
+    <A, B extends PropertyKey, C, E2, R2>(options: KeyedOptions<A, B, C, E2, R2>): <E, R>(fx: Fx<ReadonlyArray<A>, E, R>) => Fx<ReadonlyArray<C>, E | E2 | Cause.IllegalArgumentError, R | R2 | Scope.Scope>;
+    <A, E, R, B extends PropertyKey, C, E2, R2>(fx: Fx<ReadonlyArray<A>, E, R>, options: KeyedOptions<A, B, C, E2, R2>): Fx<ReadonlyArray<C>, E | E2 | Cause.IllegalArgumentError, R | R2 | Scope.Scope>;
 };
 //# sourceMappingURL=keyed.d.ts.map

package/dist/Fx/combinators/keyed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keyed.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/keyed.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAQ5C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAItC,OAAO,KAAK,UAAU,MAAM,gCAAgC,CAAC;AAE7D,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAMnC;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE;IAC3C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IACzF;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC;CACpC;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK,EAAE;IAClB,CAAC,CAAC,EAAE,CAAC,SAAS,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAClC,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACrC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IAChG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACxC,EAAE,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC9B,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACrC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;CAetD,CAAC"}
+{"version":3,"file":"keyed.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/keyed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAO5C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAItC,OAAO,KAAK,UAAU,MAAM,gCAAgC,CAAC;AAE7D,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAMnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE;IAC3C;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IAC7B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IACzF;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,KAAK,EAAE;IAClB,CAAC,CAAC,EAAE,CAAC,SAAS,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAClC,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACrC,CAAC,CAAC,EAAE,CAAC,EACN,EAAE,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC3B,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,oBAAoB,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IACrF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACxC,EAAE,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC9B,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACrC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,oBAAoB,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;CAenF,CAAC"}

package/dist/Fx/combinators/keyed.js

@@ -1,3 +1,4 @@
+import * as Cause from "effect/Cause";
 import * as Clock from "effect/Clock";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
@@ -6,13 +7,12 @@ import * as Fiber from "effect/Fiber";
 import { dual, identity } from "effect/Function";
 import * as Option from "effect/Option";
 import { pipeArguments } from "effect/Pipeable";
-import { MaxOpsBeforeYield } from "effect/Scheduler";
 import * as Scope from "effect/Scope";
-import * as ServiceMap from "effect/ServiceMap";
+import * as Context from "effect/Context";
 import * as SynchronizedRef from "effect/SynchronizedRef";
 import * as RefSubject from "../../RefSubject/RefSubject.js";
 import * as Sink from "../../Sink/Sink.js";
-import { diff, getKeyMap } from "../internal/diff.js";
+import { diff } from "../internal/diff.js";
 import { withScopedFork } from "../internal/scope.js";
 import { FxTypeId } from "../TypeId.js";
 /**
@@ -22,18 +22,58 @@ import { FxTypeId } from "../TypeId.js";
  * When the input list changes:
  * - New keys cause `onValue` to be called.
  * - Existing keys have their `RefSubject` updated with the new value.
- * - Removed keys have their corresponding Fx and scope cleaned up.
+ * - Removed keys close the supplied child Scope and clean resources registered
+ *   through it; the `onValue` run fiber remains owned by the outer parent Scope.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A stable key separates identity from position. Consumers can move or update
+ * the exact result already associated with a value instead of recreating every
+ * result when a collection changes. This is the state-preserving substrate used
+ * by keyed template rendering, but the combinator itself is renderer-agnostic.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each key receives its own `RefSubject` and child `Scope`. Reusing a key updates
+ * that subject in place. Removing a key closes the child Scope and therefore the
+ * resources registered through its supplied Scope service. The `onValue` run
+ * fiber itself is forked in the outer parent Scope, so child-Scope closure does
+ * not guarantee interruption of an arbitrary Fx that ignores Scope. Interrupting
+ * the outer run closes the parent and remaining children. Source and `onValue`
+ * failures, services, and Scope requirements remain visible in the return type.
+ *
+ * ## Ordering and failures
+ *
+ * Each source array produces a unique-key diff. Added keys start one child Fx;
+ * reused keys update their existing RefSubject, including moves; removed keys
+ * have their child Scope closed. A child may emit repeatedly, replacing only
+ * that key's latest output. Arrays follow current source order and contain the
+ * contiguous ready prefix: a later key is withheld until every earlier key has
+ * emitted at least once. Debounce coalesces scheduled arrays, not child Fx
+ * values. Duplicate keys fail with `Cause.IllegalArgumentError` rather than
+ * sharing a child lifetime.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const rows = Fx.keyed(Fx.succeed([{ id: "a", value: 1 }]), {
+ *   getKey: (row) => row.id,
+ *   onValue: (row) => Fx.map(row, ({ value }) => value)
+ * })
+ * ```
  *
  * @param fx - An `Fx` emitting an array of values.
  * @param options - Configuration options.
  * @returns An `Fx` emitting an array of results.
  * @since 1.0.0
- * @category combinators
+ * @category Keyed work
  */
 export const keyed = dual(2, function keyed(fx, options) {
     return new Keyed(fx, options);
 });
-const StateContext = ServiceMap.Service("@services/StateContext");
+const StateContext = Context.Service("@services/StateContext");
 const VARIANCE = {
     _A: identity,
     _E: identity,
@@ -48,7 +88,7 @@ class Keyed {
         this.options = options;
     }
     run(sink) {
-        return Effect.withFiber((fiber) => runKeyed(this.fx, this.options, sink, fiber.id)).pipe(Effect.provideService(MaxOpsBeforeYield, Infinity));
+        return Effect.withFiber((fiber) => runKeyed(this.fx, this.options, sink, fiber.id));
     }
     pipe() {
         return pipeArguments(this, arguments);
@@ -70,7 +110,10 @@ function runKeyed(fx, options, sink, id) {
         let previousKeyMap = new Map();
         return fx.run(Sink.make(sink.onFailure, Effect.fn(function* (values) {
             const previous = state.previousValues;
-            const keyMap = getKeyMap(values, options.getKey);
+            const keyMap = getUniqueKeyMap(values, options.getKey);
+            if (Cause.isIllegalArgumentError(keyMap)) {
+                return yield* sink.onFailure(Cause.fail(keyMap));
+            }
             let changed = first;
             first = false;
             for (const patch of diff(previous, values, {
@@ -96,10 +139,11 @@ function runKeyed(fx, options, sink, id) {
                     });
                 }
                 else {
+                    changed = true;
                     yield* updateValue(state, values, patch);
                 }
             }
-            state.previousValues = values;
+            state.previousValues = Array.from(values);
             previousKeyMap = keyMap;
             if (changed) {
                 yield* scheduleNextEmit;
@@ -110,6 +154,20 @@ function runKeyed(fx, options, sink, id) {
         })));
     }, options.debounce || 1);
 }
+function getUniqueKeyMap(values, getKey) {
+    const keyMap = new Map();
+    for (let i = 0; i < values.length; ++i) {
+        const key = getKey(values[i]);
+        if (keyMap.has(key)) {
+            return new Cause.IllegalArgumentError(`Duplicate keyed() key ${formatKeyedKey(key)}`);
+        }
+        keyMap.set(key, i);
+    }
+    return keyMap;
+}
+function formatKeyedKey(key) {
+    return typeof key === "symbol" ? key.toString() : JSON.stringify(key);
+}
 class KeyedEntry {
     value;
     index;
@@ -188,8 +246,8 @@ function withDebounceFork(f, duration) {
     })))), "sequential");
 }
 function* adjustTime() {
-    const services = yield* Effect.services();
-    const clock = ServiceMap.get(services, Clock.Clock);
+    const services = yield* Effect.context();
+    const clock = Context.get(services, Clock.Clock);
     if ("adjust" in clock) {
         yield* clock.adjust(Duration.millis(1));
     }

package/dist/Fx/combinators/loop.d.ts

@@ -3,11 +3,27 @@ import type { Fx } from "../Fx.js";
  * Loops over an Fx with an accumulator, producing a new value for each element
  * and updating the accumulator.
  *
+ * @remarks
+ * ## Why
+ * `loop` is the primitive for a synchronous state machine over pushed values. Every input emits
+ * exactly one output and installs exactly one next state, preserving source order.
+ *
+ * ## Ownership and lifetime
+ * A fresh accumulator starts from `seed` for each run and is discarded when that run ends. The
+ * pure callback adds no failures, services, fibers, or resources.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const indexed = Fx.fromIterable(["a", "b"]).pipe(Fx.loop(0, (index, value) => [[index, value] as const, index + 1]))
+ * ```
+ *
  * @param seed - The initial value of the accumulator.
  * @param f - A function that takes the accumulator and an element, returning a tuple of the emitted value and the new accumulator.
  * @returns An `Fx` that emits the transformed values.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export declare const loop: {
     <B, A, C>(seed: B, f: (acc: B, a: A) => readonly [C, B]): <E, R>(self: Fx<A, E, R>) => Fx<C, E, R>;

package/dist/Fx/combinators/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/loop.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;GASG;AACH,eAAO,MAAM,IAAI,EAAE;IACjB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACN,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GACnC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5C,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAKhG,CAAC"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/loop.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,IAAI,EAAE;IACjB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACN,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GACnC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5C,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAKhG,CAAC"}

package/dist/Fx/combinators/loop.js

@@ -5,10 +5,26 @@ import { make } from "../constructors/make.js";
  * Loops over an Fx with an accumulator, producing a new value for each element
  * and updating the accumulator.
  *
+ * @remarks
+ * ## Why
+ * `loop` is the primitive for a synchronous state machine over pushed values. Every input emits
+ * exactly one output and installs exactly one next state, preserving source order.
+ *
+ * ## Ownership and lifetime
+ * A fresh accumulator starts from `seed` for each run and is discarded when that run ends. The
+ * pure callback adds no failures, services, fibers, or resources.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const indexed = Fx.fromIterable(["a", "b"]).pipe(Fx.loop(0, (index, value) => [[index, value] as const, index + 1]))
+ * ```
+ *
  * @param seed - The initial value of the accumulator.
  * @param f - A function that takes the accumulator and an element, returning a tuple of the emitted value and the new accumulator.
  * @returns An `Fx` that emits the transformed values.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export const loop = dual(3, (self, seed, f) => make((sink) => self.run(sinkCore.loop(sink, seed, f))));

package/dist/Fx/combinators/loopCause.d.ts

@@ -3,11 +3,28 @@ import type { Fx } from "../Fx.js";
 /**
  * Loops over the failure causes of an Fx with an accumulator.
  *
+ * @remarks
+ * ## Why
+ * `loopCause` is the stateful counterpart of error mapping over full Effect causes. Successful
+ * values pass unchanged; each cause is synchronously transformed and advances the error state.
+ *
+ * ## Ownership and lifetime
+ * A fresh state begins for each run and is discarded afterward. The callback owns no resources and
+ * sees typed failures, defects, and interruption represented by `Cause`.
+ *
+ * @example
+ * ```ts
+ * import { Cause } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const numbered = Fx.fail("offline").pipe(Fx.loopCause(0, (n, cause) => [Cause.map(cause, (e) => `${n}:${e}`), n + 1]))
+ * ```
+ *
  * @param seed - The initial state.
  * @param f - The loop function for causes.
  * @returns An `Fx` with transformed errors.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export declare const loopCause: {
     <B, A, C>(seed: B, f: (acc: B, a: Cause.Cause<A>) => readonly [Cause.Cause<C>, B]): <E, R>(self: Fx<A, E, R>) => Fx<A, C, R>;

package/dist/Fx/combinators/loopCause.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loopCause.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/loopCause.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAI3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,EAAE;IACtB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACN,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7D,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5C,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EACZ,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7D,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAQhB,CAAC"}
+{"version":3,"file":"loopCause.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/loopCause.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAI3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,SAAS,EAAE;IACtB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACN,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7D,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5C,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EACZ,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7D,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAQhB,CAAC"}

package/dist/Fx/combinators/loopCause.js

@@ -4,10 +4,27 @@ import { make } from "../constructors/make.js";
 /**
  * Loops over the failure causes of an Fx with an accumulator.
  *
+ * @remarks
+ * ## Why
+ * `loopCause` is the stateful counterpart of error mapping over full Effect causes. Successful
+ * values pass unchanged; each cause is synchronously transformed and advances the error state.
+ *
+ * ## Ownership and lifetime
+ * A fresh state begins for each run and is discarded afterward. The callback owns no resources and
+ * sees typed failures, defects, and interruption represented by `Cause`.
+ *
+ * @example
+ * ```ts
+ * import { Cause } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const numbered = Fx.fail("offline").pipe(Fx.loopCause(0, (n, cause) => [Cause.map(cause, (e) => `${n}:${e}`), n + 1]))
+ * ```
+ *
  * @param seed - The initial state.
  * @param f - The loop function for causes.
  * @returns An `Fx` with transformed errors.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export const loopCause = dual(3, (self, seed, f) => make((sink) => self.run(sinkCore.loopCause(sink, seed, f))));

package/dist/Fx/combinators/loopCauseEffect.d.ts

@@ -4,11 +4,29 @@ import type { Fx } from "../Fx.js";
 /**
  * Effectfully loops over the failure causes of an Fx with an accumulator.
  *
+ * @remarks
+ * ## Why
+ * `loopCauseEffect` allows cause transformation to consult services or perform Effects while
+ * retaining state between failures. It does not serialize concurrent failure deliveries, so
+ * overlapping callbacks can read the same seed and commit in completion order.
+ *
+ * ## Ownership and lifetime
+ * One mutable seed belongs to each run. Required services remain in the result; callback failure is
+ * delivered to the Sink, and interruption follows each producer delivery without adding a lock.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const observed = Fx.fail("offline").pipe(Fx.loopCauseEffect(0, (n, cause) => Effect.succeed([cause, n + 1])))
+ * ```
+ *
  * @param seed - The initial state.
  * @param f - The effectful loop function for causes.
  * @returns An `Fx` with transformed errors.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export declare const loopCauseEffect: {
     <B, A, E, R2, C>(seed: B, f: (acc: B, a: Cause.Cause<A>) => Effect.Effect<readonly [Cause.Cause<C>, B], R2>): <R>(self: Fx<A, E, R>) => Fx<A, C | E, R | R2>;

package/dist/Fx/combinators/loopCauseEffect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loopCauseEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/loopCauseEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAI7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE;IAC5B,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EACb,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAChF,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAElD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAChB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GACnF,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CASrB,CAAC"}
+{"version":3,"file":"loopCauseEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/loopCauseEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAI7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,eAAe,EAAE;IAC5B,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EACb,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAChF,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAElD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAChB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GACnF,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CASrB,CAAC"}

package/dist/Fx/combinators/loopCauseEffect.js

@@ -4,10 +4,28 @@ import { make } from "../constructors/make.js";
 /**
  * Effectfully loops over the failure causes of an Fx with an accumulator.
  *
+ * @remarks
+ * ## Why
+ * `loopCauseEffect` allows cause transformation to consult services or perform Effects while
+ * retaining state between failures. It does not serialize concurrent failure deliveries, so
+ * overlapping callbacks can read the same seed and commit in completion order.
+ *
+ * ## Ownership and lifetime
+ * One mutable seed belongs to each run. Required services remain in the result; callback failure is
+ * delivered to the Sink, and interruption follows each producer delivery without adding a lock.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const observed = Fx.fail("offline").pipe(Fx.loopCauseEffect(0, (n, cause) => Effect.succeed([cause, n + 1])))
+ * ```
+ *
  * @param seed - The initial state.
  * @param f - The effectful loop function for causes.
  * @returns An `Fx` with transformed errors.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export const loopCauseEffect = dual(3, (self, seed, f) => make((sink) => self.run(sinkCore.loopCauseEffect(sink, seed, f))));

package/dist/Fx/combinators/loopEffect.d.ts

@@ -3,11 +3,34 @@ import type { Fx } from "../Fx.js";
 /**
  * Effectfully loops over an Fx with an accumulator, producing a new value for each element.
  *
+ * @remarks
+ * ## Why
+ * `loopEffect` models an Effectful state transition without nested Fx values. It does not serialize
+ * producer callbacks: overlapping deliveries can read the same seed, complete out of order, and
+ * overwrite one another's next state. Use a serialized producer when atomic accumulation matters.
+ *
+ * ## Ownership and lifetime
+ * One mutable seed is retained per run. Each callback Effect follows its invoking delivery; failure
+ * is sent to the Sink, services remain required, and interruption does not provide a global lock.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const concurrent = Fx.make<number>((sink) =>
+ *   Effect.all([sink.onSuccess(1), sink.onSuccess(2)], { concurrency: "unbounded", discard: true })
+ * )
+ * const program = Fx.collectAll(
+ *   concurrent.pipe(Fx.loopEffect(0, (sum, n) => Effect.succeed([sum + n, sum + n])))
+ * ) // both overlapping transitions may observe sum === 0
+ * ```
+ *
  * @param seed - The initial state.
  * @param f - The effectful loop function.
  * @returns An `Fx` emitting the transformed values.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export declare const loopEffect: {
     <B, A, E2, R2, C>(seed: B, f: (acc: B, a: A) => Effect.Effect<readonly [C, B], E2, R2>): <E, R>(self: Fx<A, E | E2, R>) => Fx<C, E | E2, R | R2>;

package/dist/Fx/combinators/loopEffect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loopEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/loopEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAI7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,EAAE;IACvB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EACd,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAC1D,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAE3D,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EACZ,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACxD,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAQhB,CAAC"}
+{"version":3,"file":"loopEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/loopEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAI7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,UAAU,EAAE;IACvB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EACd,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAC1D,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAE3D,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EACZ,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACxD,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAQhB,CAAC"}

package/dist/Fx/combinators/loopEffect.js

@@ -4,10 +4,33 @@ import { make } from "../constructors/make.js";
 /**
  * Effectfully loops over an Fx with an accumulator, producing a new value for each element.
  *
+ * @remarks
+ * ## Why
+ * `loopEffect` models an Effectful state transition without nested Fx values. It does not serialize
+ * producer callbacks: overlapping deliveries can read the same seed, complete out of order, and
+ * overwrite one another's next state. Use a serialized producer when atomic accumulation matters.
+ *
+ * ## Ownership and lifetime
+ * One mutable seed is retained per run. Each callback Effect follows its invoking delivery; failure
+ * is sent to the Sink, services remain required, and interruption does not provide a global lock.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const concurrent = Fx.make<number>((sink) =>
+ *   Effect.all([sink.onSuccess(1), sink.onSuccess(2)], { concurrency: "unbounded", discard: true })
+ * )
+ * const program = Fx.collectAll(
+ *   concurrent.pipe(Fx.loopEffect(0, (sum, n) => Effect.succeed([sum + n, sum + n])))
+ * ) // both overlapping transitions may observe sum === 0
+ * ```
+ *
  * @param seed - The initial state.
  * @param f - The effectful loop function.
  * @returns An `Fx` emitting the transformed values.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export const loopEffect = dual(3, (self, seed, f) => make((sink) => self.run(sinkCore.loopEffect(seed, f)(sink))));