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

package/dist/Fx/internal/DeferredRef.js

@@ -3,30 +3,171 @@ import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as MutableRef from "effect/MutableRef";
 import * as Option from "effect/Option";
+import { EffectableWithOverride } from "./effectableWithOverride.js";
 /**
- * This is the core piece of state for {@link RefSubject}. It presents an Yieldable/Effect interface
- * which supports retrieving the latest Exit<A, E> or waiting for an initial Exit<A, E> to be set otherwise.
+ * A mutable, Effect-compatible cell that waits for its first `Exit` and samples the latest one
+ * thereafter.
  *
- * It utilizes a Equivalence to determine if the latest Exit<A, E> is the same as the current Exit<A, E> through the
- * done method.
+ * @remarks
+ * ## Why
  *
- * @internal
+ * RefSubject needs one object that can be yielded as an Effect before initialization and read
+ * synchronously from retained state after initialization. `DeferredRef` combines those two phases
+ * without starting a polling fiber or allocating a new Deferred for every update.
+ *
+ * ## Ownership and lifetime
+ *
+ * An instance owns its current Deferred and mutates the supplied `MutableRef`. It acquires no
+ * Scope. Callers must ensure that mutation is serialized when updates can race. `reset` interrupts
+ * waiters on the previous Deferred and replaces it; dropping the instance releases the retained
+ * `Exit` for garbage collection.
+ *
+ * ## Errors and interruption
+ *
+ * Executing the instance waits while `current` is `None`, then succeeds or fails exactly as the
+ * stored `Exit`. `reset` completes the old Deferred with interruption attributed to `fiberId`.
+ * The equality function controls version changes and the boolean returned by `done`; it does not
+ * erase or transform typed failures.
+ *
+ * This import path is published for advanced state implementations, but its shape follows
+ * RefSubject and Effect runtime details and may change between prereleases.
+ *
+ * @example
+ * ```ts
+ * import { DeferredRef } from "@typed/fx/Fx/internal/DeferredRef"
+ * import { getExitEquivalence } from "@typed/fx/Fx/internal/equivalence"
+ * import * as Effect from "effect/Effect"
+ * import * as Equivalence from "effect/Equivalence"
+ * import * as Exit from "effect/Exit"
+ * import * as MutableRef from "effect/MutableRef"
+ * import * as Option from "effect/Option"
+ *
+ * const current = MutableRef.make<Option.Option<Exit.Exit<number, never>>>(Option.none())
+ * const ref = new DeferredRef(undefined, getExitEquivalence(Equivalence.Number), current)
+ * ref.done(Exit.succeed(1))
+ * const value = Effect.runSync(ref) // 1
+ * ```
+ *
+ * @since 1.0.0
+ * @category advanced
+ * @stability internal-but-published
  */
-export class DeferredRef extends Effect.YieldableClass {
+export class DeferredRef extends EffectableWithOverride {
+    /** The zero-based version of the latest distinct `Exit` since the last reset.
+     *
+     * @remarks
+     * ## Why
+     *
+     * `reset` sets this to `-1`; the first distinct `done` call changes it to `0`, the next to `1`,
+     * and so on. It is an ordinal, not a count.
+     *
+     * ## Ownership and lifetime
+     *
+     * The instance mutates this counter; reading it acquires no resources.
+     *
+     * @since 1.0.0
+     * @category state
+     */
     version;
+    /** The one-shot gate used by Effects waiting for the first value after a reset.
+     *
+     * @remarks
+     * ## Why
+     *
+     * This field is replaced by `reset`. Mutating or completing it externally can violate the
+     * `current`/Deferred invariant.
+     *
+     * ## Ownership and lifetime
+     *
+     * The instance owns the gate until reset or collection; waiters borrow it through `override`.
+     *
+     * @since 1.0.0
+     * @category state
+     */
     deferred;
+    /** Fiber identifier used to attribute interruption when `reset` closes the old gate.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Retaining the creator's identifier makes reset interruption attributable in an Effect Cause.
+     *
+     * ## Ownership and lifetime
+     *
+     * Immutable scalar metadata retained for the instance lifetime.
+     *
+     * @since 1.0.0
+     * @category state
+     */
     fiberId;
+    /** Equivalence used to suppress version changes for repeated Exits.
+     *
+     * @remarks
+     * ## Why
+     *
+     * State implementations can define semantic equality independently from object identity.
+     *
+     * ## Ownership and lifetime
+     *
+     * The instance retains and invokes the pure function; it acquires no services.
+     *
+     * @since 1.0.0
+     * @category state
+     */
     eq;
+    /** Shared mutable storage containing the latest success or failure, if initialized.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Sharing one cell lets RefSubject publication and Effect sampling observe the same latest Exit.
+     *
+     * ## Ownership and lifetime
+     *
+     * The constructor borrows this cell and clears it; external owners must coordinate mutation.
+     *
+     * @since 1.0.0
+     * @category state
+     */
     current;
+    /** Constructs a cell over caller-supplied storage and immediately starts an empty version.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Advanced state implementations can share their existing current-Exit cell with the yieldable
+     * Effect view while choosing the equality and interruption identity used by publication.
+     *
+     * ## Ownership and lifetime
+     *
+     * The constructor borrows and clears `current`, sets `version` to `-1`, and owns the newly created
+     * one-shot Deferred until reset or collection. It does not clone storage, acquire a Scope, or
+     * synchronize external mutation.
+     *
+     * @example
+     * ```ts
+     * import { DeferredRef } from "@typed/fx/Fx/internal/DeferredRef"
+     * import { getExitEquivalence } from "@typed/fx/Fx/internal/equivalence"
+     * import * as Equivalence from "effect/Equivalence"
+     * import type * as Exit from "effect/Exit"
+     * import * as MutableRef from "effect/MutableRef"
+     * import * as Option from "effect/Option"
+     *
+     * const current = MutableRef.make<Option.Option<Exit.Exit<number, never>>>(Option.none())
+     * const ref = new DeferredRef(undefined, getExitEquivalence(Equivalence.Number), current)
+     * ref.version // -1 until the first distinct Exit is published
+     * ```
+     *
+     * @since 1.0.0
+     * @category constructors
+     */
     constructor(fiberId, eq, current) {
         super();
         this.fiberId = fiberId;
         this.eq = eq;
         this.current = current;
         this.reset();
-    }
-    asEffect() {
-        return Effect.suspend(() => {
+        this.override = Effect.suspend(() => {
             const current = MutableRef.get(this.current);
             if (Option.isNone(current)) {
                 return Deferred.await(this.deferred);
@@ -36,6 +177,41 @@ export class DeferredRef extends Effect.YieldableClass {
             }
         });
     }
+    /** Effect view that awaits initialization or evaluates the latest stored `Exit`.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Each execution reads `current`. Once initialized, reads are O(1) and do not wait on the
+     * Deferred.
+     *
+     * ## Ownership and lifetime
+     *
+     * The Effect borrows instance state and retains no per-execution resource after it completes.
+     *
+     * @since 1.0.0
+     * @category effects
+     */
+    override;
+    /** Stores an `Exit` and reports whether it differs from the previously stored value.
+     *
+     * @remarks
+     * ## Why
+     *
+     * The current cell is updated even when `eq` reports equality. The first distinct value after a
+     * reset completes the one-shot Deferred, changes `version` from `-1` to `0`, and releases waiters.
+     * Later distinct values replace `current` and advance the zero-based version, but the already
+     * completed Deferred is not re-completed and existing executions sample `current` directly.
+     * An equivalent value leaves the version unchanged and returns `false`. The operation is O(1)
+     * plus the cost of `eq`.
+     *
+     * ## Ownership and lifetime
+     *
+     * Mutates only this cell's current value, Deferred, and version; it starts no fiber or Scope.
+     *
+     * @since 1.0.0
+     * @category mutations
+     */
     done(exit) {
         const current = MutableRef.get(this.current);
         MutableRef.set(this.current, Option.some(exit));
@@ -46,6 +222,21 @@ export class DeferredRef extends Effect.YieldableClass {
         this.version += 1;
         return true;
     }
+    /** Clears the sampled value and starts a fresh initialization phase.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Existing waiters are interrupted before the replacement Deferred is installed. The method is
+     * synchronous and acquires no Scope.
+     *
+     * ## Ownership and lifetime
+     *
+     * Releases the old current Exit and gate from this instance after interrupting its waiters.
+     *
+     * @since 1.0.0
+     * @category mutations
+     */
     reset() {
         MutableRef.set(this.current, Option.none());
         this.version = -1;
@@ -55,9 +246,69 @@ export class DeferredRef extends Effect.YieldableClass {
         this.deferred = Deferred.makeUnsafe();
     }
 }
+/** Creates a fresh `DeferredRef` and records the creating fiber for reset interruption.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Capturing the current fiber gives interruption of pre-reset waiters an attributable origin while
+ * keeping ordinary construction inside Effect.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned instance owns its Deferred and mutable cell but acquires no Scope. Its state remains
+ * reachable for exactly as long as callers retain the instance.
+ *
+ * @example
+ * ```ts
+ * import { make } from "@typed/fx/Fx/internal/DeferredRef"
+ * import { getExitEquivalence } from "@typed/fx/Fx/internal/equivalence"
+ * import * as Effect from "effect/Effect"
+ * import * as Equivalence from "effect/Equivalence"
+ *
+ * const program = Effect.gen(function* () {
+ *   const ref = yield* make(getExitEquivalence<never, number>(Equivalence.Number))
+ *   return ref
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category constructors
+ * @stability internal-but-published
+ */
 export function make(eq) {
     return Effect.withFiber((fiber) => Effect.succeed(new DeferredRef(fiber.id, eq, MutableRef.make(Option.none()))));
 }
+/** Constructs a `DeferredRef` over existing mutable storage without entering Effect.
+ *
+ * @remarks
+ * ## Why
+ *
+ * State implementations that already own an `Exit` cell can share it with the Effect view instead
+ * of copying or synchronizing two stores.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned instance borrows `current` and immediately resets it to `None`. Callers own all
+ * synchronization and must not assume that the previous cell value survives construction.
+ *
+ * @example
+ * ```ts
+ * import { unsafeMake } from "@typed/fx/Fx/internal/DeferredRef"
+ * import { getExitEquivalence } from "@typed/fx/Fx/internal/equivalence"
+ * import * as Equivalence from "effect/Equivalence"
+ * import * as Exit from "effect/Exit"
+ * import * as MutableRef from "effect/MutableRef"
+ * import * as Option from "effect/Option"
+ *
+ * const current = MutableRef.make<Option.Option<Exit.Exit<number, never>>>(Option.none())
+ * const ref = unsafeMake(undefined, getExitEquivalence(Equivalence.Number), current)
+ * ```
+ *
+ * @since 1.0.0
+ * @category constructors
+ * @stability internal-but-published
+ */
 export function unsafeMake(id, eq, current) {
     return new DeferredRef(id, eq, current);
 }

package/dist/Fx/internal/UnionToTuple.d.ts

@@ -1,6 +1,28 @@
 type Contra<T> = T extends any ? (arg: T) => void : never;
 type InferContra<T> = [T] extends [(arg: infer I) => void] ? I : never;
 type PickOne<T> = InferContra<InferContra<Contra<Contra<T>>>>;
+/** Converts a union to a tuple so recursive type-level folds can visit each member.
+ *
+ * @remarks
+ * ## Why
+ *
+ * TypeScript cannot directly reduce a union while accumulating state. This helper repeatedly
+ * selects one member through contravariant inference, excludes it, and appends it to a tuple. Typed
+ * uses that tuple to merge RefSubject structure kinds.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is a compile-time transformation. It emits no JavaScript, acquires no services, and retains
+ * no runtime resources.
+ *
+ * Union member order is an implementation detail of TypeScript inference and must not be used as a
+ * stable ordering contract. Very large unions may also reach the compiler's instantiation-depth
+ * limit. This published helper follows compiler internals and may change between prereleases.
+ *
+ * @since 1.0.0
+ * @category type-level
+ * @stability internal-but-published
+ */
 export type UnionToTuple<T> = PickOne<T> extends infer U ? Exclude<T, U> extends never ? [T] : [...UnionToTuple<Exclude<T, U>>, U] : never;
 export {};
 //# sourceMappingURL=UnionToTuple.d.ts.map

package/dist/Fx/internal/UnionToTuple.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UnionToTuple.d.ts","sourceRoot":"","sources":["../../../src/Fx/internal/UnionToTuple.ts"],"names":[],"mappings":"AAAA,KAAK,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC;AAE1D,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEvE,KAAK,OAAO,CAAC,CAAC,IAAI,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9D,MAAM,MAAM,YAAY,CAAC,CAAC,IACxB,OAAO,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,GACtB,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,KAAK,GACzB,CAAC,CAAC,CAAC,GACH,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GACrC,KAAK,CAAC"}
+{"version":3,"file":"UnionToTuple.d.ts","sourceRoot":"","sources":["../../../src/Fx/internal/UnionToTuple.ts"],"names":[],"mappings":"AAAA,KAAK,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC;AAE1D,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEvE,KAAK,OAAO,CAAC,CAAC,IAAI,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IACxB,OAAO,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,GACtB,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,KAAK,GACzB,CAAC,CAAC,CAAC,GACH,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GACrC,KAAK,CAAC"}