@typed/fx 2.0.0-beta.4 → 2.0.0-beta.6

package/dist/Fx/internal/multicast.js

@@ -1,14 +1,93 @@
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
-export class MulticastEffect extends Effect.YieldableClass {
+import { EffectableWithOverride } from "./effectableWithOverride.js";
+/** An Effect-compatible wrapper that joins the currently recorded detached execution.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Some sampled state computations are expensive but may be requested concurrently. The wrapper
+ * lets later callers join the same in-flight fiber, preserving one result, typed failure, and Cause
+ * for that run. After completion the recorded fiber is cleared and a later call starts fresh work.
+ *
+ * ## Ownership and lifetime
+ *
+ * The first caller starts `effect` in a detached fiber using that caller's services. Interrupting a
+ * joining caller stops only its wait; the detached computation continues until completion or an
+ * explicit `interrupt`. A directly constructed instance has no automatic finalizer. Prefer
+ * `makeMulticastEffect` when a Scope should interrupt remaining work.
+ *
+ * ## Concurrency and interruption
+ *
+ * Calls made after `_fiber` is recorded join that fiber. Recording uses mutable instance state
+ * rather than a semaphore, so this is a low-level primitive whose callers must not assume a stronger
+ * atomic-start guarantee than the implementation provides. Completion or explicit interruption
+ * clears the matching record; all joiners observe the fiber's exact success, typed error, defect,
+ * or interruption.
+ *
+ * This path is published for advanced state implementations and may change between prereleases.
+ *
+ * @example
+ * ```ts
+ * import { MulticastEffect } from "@typed/fx/Fx/internal/multicast"
+ * import * as Effect from "effect/Effect"
+ *
+ * const sharedWhileRunning = new MulticastEffect(Effect.succeed("ready"))
+ * const value = Effect.runSync(sharedWhileRunning)
+ * ```
+ *
+ * @since 1.0.0
+ * @category advanced
+ * @stability internal-but-published
+ */
+export class MulticastEffect extends EffectableWithOverride {
     _fiber = null;
+    /** Underlying computation started when no recorded fiber is running.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Keeping the source Effect visible lets advanced implementations inspect or compose the exact
+     * work whose in-flight execution is shared.
+     *
+     * ## Ownership and lifetime
+     *
+     * The wrapper retains this immutable Effect description; resources begin only when it is run.
+     *
+     * @since 1.0.0
+     * @category effects
+     */
     effect;
+    /** Creates a wrapper without attaching its future detached fiber to a Scope.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Direct construction supports owners such as Versioned that already expose an explicit
+     * interruption boundary and do not need acquisition itself to require Scope.
+     *
+     * ## Ownership and lifetime
+     *
+     * Construction retains only the Effect description and starts no work. The first evaluation may
+     * start a detached fiber, which remains this instance's responsibility until it completes or
+     * `interrupt` is run. Use `makeMulticastEffect` when Scope closure should provide that cleanup.
+     *
+     * @example
+     * ```ts
+     * import { MulticastEffect } from "@typed/fx/Fx/internal/multicast"
+     * import * as Effect from "effect/Effect"
+     *
+     * const shared = new MulticastEffect(Effect.succeed("ready"))
+     * const result = Effect.runSync(shared)
+     * ```
+     *
+     * @since 1.0.0
+     * @category constructors
+     */
     constructor(effect) {
         super();
         this.effect = effect;
-    }
-    asEffect() {
-        return Effect.suspend(() => {
+        this.override = Effect.suspend(() => {
             if (this._fiber) {
                 return Fiber.join(this._fiber);
             }
@@ -17,6 +96,38 @@ export class MulticastEffect extends Effect.YieldableClass {
             }
         });
     }
+    /** Effect view that joins the recorded fiber or starts and records a detached one.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Effect evaluation is the common entry point through which concurrent callers share work.
+     *
+     * ## Ownership and lifetime
+     *
+     * A newly started fiber is detached from the joining caller and remains recorded until completion
+     * or explicit interruption.
+     *
+     * @since 1.0.0
+     * @category effects
+     */
+    override;
+    /** Interrupts the currently recorded fiber as the calling fiber and clears the record.
+     *
+     * @remarks
+     * ## Why
+     *
+     * If no fiber is recorded, the Effect succeeds immediately. Interruption of the child is awaited,
+     * and cleanup clears the field even when interruption observation itself is interrupted.
+     *
+     * ## Ownership and lifetime
+     *
+     * The Effect owns only this interruption action; it does not prevent a later execution from
+     * starting a fresh fiber.
+     *
+     * @since 1.0.0
+     * @category lifecycle
+     */
     interrupt() {
         return Effect.withFiber((fiber) => {
             if (this._fiber) {
@@ -29,4 +140,35 @@ export class MulticastEffect extends Effect.YieldableClass {
         });
     }
 }
+/** Acquires a scoped `MulticastEffect` whose finalizer interrupts recorded work.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The scoped constructor makes the detached-fiber lifetime explicit and prevents a computation
+ * from surviving the application lifetime that requested sharing.
+ *
+ * ## Ownership and lifetime
+ *
+ * Acquisition allocates the wrapper but does not start `effect`. The first execution starts work;
+ * closing the required Scope calls `interrupt` and waits for the recorded fiber to terminate. The
+ * original effect's `E` and `R` channels are preserved when the wrapper is executed.
+ *
+ * @example
+ * ```ts
+ * import { makeMulticastEffect } from "@typed/fx/Fx/internal/multicast"
+ * import * as Effect from "effect/Effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   const shared = yield* makeMulticastEffect(Effect.succeed("ready"))
+ *   return yield* shared
+ * })
+ *
+ * Effect.runSync(Effect.scoped(program))
+ * ```
+ *
+ * @since 1.0.0
+ * @category constructors
+ * @stability internal-but-published
+ */
 export const makeMulticastEffect = (effect) => Effect.acquireRelease(Effect.sync(() => new MulticastEffect(effect)), (multicastEffect) => multicastEffect.interrupt());

package/dist/Fx/internal/ring-buffer.d.ts

@@ -1,14 +1,163 @@
 import { type Effect } from "effect/Effect";
+/** A fixed-capacity FIFO buffer that overwrites its oldest value when full.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Replay subjects need bounded history with O(1) append cost and deterministic oldest-to-newest
+ * replay, without shifting an array on every publication.
+ *
+ * ## Ownership and lifetime
+ *
+ * The instance exclusively owns an array of `capacity` slots and retains at most that many values.
+ * It acquires no Scope. `clear` replaces the backing array so retained values can be collected;
+ * callers decide when that cleanup occurs.
+ *
+ * ## Errors and complexity
+ *
+ * Construction throws `Cause.IllegalArgumentError` synchronously unless capacity is an integer from
+ * 1 through 4,294,967,295. `push`, `size`, and indexed access are O(1). `forEach` builds and executes
+ * an O(size) sequential Effect chain. This published implementation utility may change between
+ * prereleases.
+ *
+ * @example
+ * ```ts
+ * import { RingBuffer } from "@typed/fx/Fx/internal/ring-buffer"
+ * import * as Effect from "effect/Effect"
+ *
+ * const buffer = new RingBuffer<number>(2)
+ * buffer.push(1)
+ * buffer.push(2)
+ * buffer.push(3)
+ * Effect.runSync(buffer.forEach((value) => Effect.sync(() => console.log(value)))) // 2, 3
+ * ```
+ *
+ * @since 1.0.0
+ * @category advanced
+ * @stability internal-but-published
+ */
 export declare class RingBuffer<A> {
+    /** Maximum number of values retained by this buffer.
+     *
+     * @remarks
+     * ## Why
+     *
+     * A fixed bound makes replay retention and overwrite behavior predictable.
+     *
+     * ## Ownership and lifetime
+     *
+     * Immutable scalar metadata retained for the instance lifetime.
+     *
+     * @since 1.0.0
+     * @category state
+     */
     readonly capacity: number;
+    /** Allocates an empty backing array for a validated capacity.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Validating at the allocation boundary prevents modulo-by-zero behavior, impossible array
+     * lengths, and an unbounded replay contract before any value can be retained.
+     *
+     * ## Ownership and lifetime
+     *
+     * Construction allocates and exclusively owns one sparse array of `capacity` slots. No Scope or
+     * Effect is acquired. Invalid capacity is thrown synchronously as `Cause.IllegalArgumentError`,
+     * not returned through an Effect error channel.
+     *
+     * @example
+     * ```ts
+     * import { RingBuffer } from "@typed/fx/Fx/internal/ring-buffer"
+     * import * as Cause from "effect/Cause"
+     *
+     * const buffer = new RingBuffer<string>(2)
+     * buffer.capacity // 2
+     *
+     * try {
+     *   new RingBuffer(0)
+     * } catch (error) {
+     *   Cause.isIllegalArgumentError(error) // true
+     * }
+     * ```
+     *
+     * @since 1.0.0
+     * @category constructors
+     */
     constructor(capacity: number);
     private _buffer;
     private _size;
     private _head;
+    /** Current number of retained values, from zero through `capacity`.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Callers can inspect occupancy without exposing backing-array indices.
+     *
+     * ## Ownership and lifetime
+     *
+     * Reading the counter is O(1) and acquires no resources.
+     *
+     * @since 1.0.0
+     * @category state
+     */
     get size(): number;
+    /** Appends one value, overwriting the oldest value when the buffer is full.
+     *
+     * @remarks
+     * ## Why
+     *
+     * The operation mutates this buffer in O(1) time and performs no Effect or cleanup action.
+     *
+     * ## Ownership and lifetime
+     *
+     * The buffer retains `a` until overwrite, `clear`, or collection; an overwritten value is released.
+     *
+     * @since 1.0.0
+     * @category mutations
+     */
     push(a: A): void;
     private at;
+    /** Runs an Effect for each retained value in oldest-to-newest order.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Effects are sequenced with `flatMap`; failure, defect, or interruption stops later values. The
+     * callback receives a zero-based replay index rather than the backing-array index. The method
+     * preserves callback errors and services and does not clear the buffer.
+     *
+     * `_size` and the first callback invocation are captured eagerly when `forEach` is called. For
+     * sizes greater than one, later slots are read and their callbacks are invoked lazily as the
+     * returned Effect executes. This is deliberately not a snapshot: mutating or clearing the buffer
+     * between construction and execution can combine the earlier first Effect with later values from
+     * the mutated buffer. Callers that require one coherent replay must not mutate the buffer until
+     * the Effect completes.
+     *
+     * ## Ownership and lifetime
+     *
+     * The returned Effect borrows the current retained values while executing and owns no additional
+     * lifetime after completion.
+     *
+     * @since 1.0.0
+     * @category effects
+     */
     forEach<B, E2, R2>(f: (a: A, i: number) => Effect<B, E2, R2>): Effect<unknown, E2, R2>;
+    /** Drops all retained values and resets insertion to the start of a fresh backing array.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Capacity is unchanged. The operation acquires no Scope and runs synchronously.
+     *
+     * ## Ownership and lifetime
+     *
+     * Replacing the array releases every retained value from this instance at once.
+     *
+     * @since 1.0.0
+     * @category mutations
+     */
     clear(): void;
 }
 //# sourceMappingURL=ring-buffer.d.ts.map

package/dist/Fx/internal/ring-buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ring-buffer.d.ts","sourceRoot":"","sources":["../../../src/Fx/internal/ring-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAA0B,MAAM,eAAe,CAAC;AAEpE,qBAAa,UAAU,CAAC,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;IAK5B,OAAO,CAAC,OAAO,CAAW;IAC1B,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,KAAK,CAAK;IAElB,IAAI,IAAI,WAEP;IAED,IAAI,CAAC,CAAC,EAAE,CAAC;IAQT,OAAO,CAAC,EAAE;IAOV,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC;IAqB5D,KAAK;CAKN"}
+{"version":3,"file":"ring-buffer.d.ts","sourceRoot":"","sources":["../../../src/Fx/internal/ring-buffer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAA0B,MAAM,eAAe,CAAC;AAMpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,UAAU,CAAC,CAAC;IACvB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,YAAY,QAAQ,EAAE,MAAM,EAM3B;IAED,OAAO,CAAC,OAAO,CAAW;IAC1B,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,KAAK,CAAK;IAElB;;;;;;;;;;;;;OAaG;IACH,IAAI,IAAI,WAEP;IAED;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,CAAC,EAAE,CAAC,QAMR;IAED,OAAO,CAAC,EAAE;IAOV;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,2BAmB3D;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,SAIJ;CACF"}

package/dist/Fx/internal/ring-buffer.js

@@ -1,16 +1,133 @@
+import * as Cause from "effect/Cause";
 import { flatMap, void as void_ } from "effect/Effect";
+const MAX_ARRAY_LENGTH = 4294967295;
+const INVALID_CAPACITY_MESSAGE = "Ring buffer capacity must be an integer from 1 through 4294967295";
+/** A fixed-capacity FIFO buffer that overwrites its oldest value when full.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Replay subjects need bounded history with O(1) append cost and deterministic oldest-to-newest
+ * replay, without shifting an array on every publication.
+ *
+ * ## Ownership and lifetime
+ *
+ * The instance exclusively owns an array of `capacity` slots and retains at most that many values.
+ * It acquires no Scope. `clear` replaces the backing array so retained values can be collected;
+ * callers decide when that cleanup occurs.
+ *
+ * ## Errors and complexity
+ *
+ * Construction throws `Cause.IllegalArgumentError` synchronously unless capacity is an integer from
+ * 1 through 4,294,967,295. `push`, `size`, and indexed access are O(1). `forEach` builds and executes
+ * an O(size) sequential Effect chain. This published implementation utility may change between
+ * prereleases.
+ *
+ * @example
+ * ```ts
+ * import { RingBuffer } from "@typed/fx/Fx/internal/ring-buffer"
+ * import * as Effect from "effect/Effect"
+ *
+ * const buffer = new RingBuffer<number>(2)
+ * buffer.push(1)
+ * buffer.push(2)
+ * buffer.push(3)
+ * Effect.runSync(buffer.forEach((value) => Effect.sync(() => console.log(value)))) // 2, 3
+ * ```
+ *
+ * @since 1.0.0
+ * @category advanced
+ * @stability internal-but-published
+ */
 export class RingBuffer {
+    /** Maximum number of values retained by this buffer.
+     *
+     * @remarks
+     * ## Why
+     *
+     * A fixed bound makes replay retention and overwrite behavior predictable.
+     *
+     * ## Ownership and lifetime
+     *
+     * Immutable scalar metadata retained for the instance lifetime.
+     *
+     * @since 1.0.0
+     * @category state
+     */
     capacity;
+    /** Allocates an empty backing array for a validated capacity.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Validating at the allocation boundary prevents modulo-by-zero behavior, impossible array
+     * lengths, and an unbounded replay contract before any value can be retained.
+     *
+     * ## Ownership and lifetime
+     *
+     * Construction allocates and exclusively owns one sparse array of `capacity` slots. No Scope or
+     * Effect is acquired. Invalid capacity is thrown synchronously as `Cause.IllegalArgumentError`,
+     * not returned through an Effect error channel.
+     *
+     * @example
+     * ```ts
+     * import { RingBuffer } from "@typed/fx/Fx/internal/ring-buffer"
+     * import * as Cause from "effect/Cause"
+     *
+     * const buffer = new RingBuffer<string>(2)
+     * buffer.capacity // 2
+     *
+     * try {
+     *   new RingBuffer(0)
+     * } catch (error) {
+     *   Cause.isIllegalArgumentError(error) // true
+     * }
+     * ```
+     *
+     * @since 1.0.0
+     * @category constructors
+     */
     constructor(capacity) {
+        if (!Number.isInteger(capacity) || capacity < 1 || capacity > MAX_ARRAY_LENGTH) {
+            throw new Cause.IllegalArgumentError(INVALID_CAPACITY_MESSAGE);
+        }
         this.capacity = capacity;
         this._buffer = Array(this.capacity);
     }
     _buffer;
     _size = 0;
     _head = 0;
+    /** Current number of retained values, from zero through `capacity`.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Callers can inspect occupancy without exposing backing-array indices.
+     *
+     * ## Ownership and lifetime
+     *
+     * Reading the counter is O(1) and acquires no resources.
+     *
+     * @since 1.0.0
+     * @category state
+     */
     get size() {
         return this._size;
     }
+    /** Appends one value, overwriting the oldest value when the buffer is full.
+     *
+     * @remarks
+     * ## Why
+     *
+     * The operation mutates this buffer in O(1) time and performs no Effect or cleanup action.
+     *
+     * ## Ownership and lifetime
+     *
+     * The buffer retains `a` until overwrite, `clear`, or collection; an overwritten value is released.
+     *
+     * @since 1.0.0
+     * @category mutations
+     */
     push(a) {
         this._buffer[this._head] = a;
         this._head = (this._head + 1) % this.capacity;
@@ -24,6 +141,30 @@ export class RingBuffer {
         }
         return this._buffer[(this._head + index) % this.capacity];
     }
+    /** Runs an Effect for each retained value in oldest-to-newest order.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Effects are sequenced with `flatMap`; failure, defect, or interruption stops later values. The
+     * callback receives a zero-based replay index rather than the backing-array index. The method
+     * preserves callback errors and services and does not clear the buffer.
+     *
+     * `_size` and the first callback invocation are captured eagerly when `forEach` is called. For
+     * sizes greater than one, later slots are read and their callbacks are invoked lazily as the
+     * returned Effect executes. This is deliberately not a snapshot: mutating or clearing the buffer
+     * between construction and execution can combine the earlier first Effect with later values from
+     * the mutated buffer. Callers that require one coherent replay must not mutate the buffer until
+     * the Effect completes.
+     *
+     * ## Ownership and lifetime
+     *
+     * The returned Effect borrows the current retained values while executing and owns no additional
+     * lifetime after completion.
+     *
+     * @since 1.0.0
+     * @category effects
+     */
     forEach(f) {
         switch (this._size) {
             case 0:
@@ -44,6 +185,20 @@ export class RingBuffer {
             }
         }
     }
+    /** Drops all retained values and resets insertion to the start of a fresh backing array.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Capacity is unchanged. The operation acquires no Scope and runs synchronously.
+     *
+     * ## Ownership and lifetime
+     *
+     * Replacing the array releases every retained value from this instance at once.
+     *
+     * @since 1.0.0
+     * @category mutations
+     */
     clear() {
         this._buffer = Array(this.capacity);
         this._size = 0;