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

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

@@ -1,11 +1,195 @@
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
 import * as Scope from "effect/Scope";
+/** Finalizer execution order accepted by the published Fx scope helpers.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Fx operators sometimes require deterministic teardown and sometimes permit independent
+ * finalizers to run concurrently. This narrower type exposes only the strategies these helpers
+ * intentionally forward to Effect Scope.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is compile-time metadata and acquires no runtime resources.
+ *
+ * @since 1.0.0
+ * @category type-level
+ * @stability internal-but-published
+ */
 export type ExecutionStrategy = "sequential" | "parallel";
+/** Forks a closeable child from the current Scope and passes it to an Effect builder.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Operators need a lifetime they can close independently while still guaranteeing that the parent
+ * Scope eventually closes it if the operator is interrupted.
+ *
+ * ## Ownership and lifetime
+ *
+ * The caller's required Scope owns the forked child. This helper does not close the child when `f`
+ * returns; parent closure does. Use `withExtendedScope` when the child must close at the returned
+ * Effect's exit. `f` retains its exact value, typed error, and service channels.
+ *
+ * @example
+ * ```ts
+ * import { withCloseableScope } from "@typed/fx/Fx/internal/scope"
+ * import * as Effect from "effect/Effect"
+ *
+ * const child = withCloseableScope((scope) => Effect.succeed(scope), "sequential")
+ * const scope = Effect.runSync(Effect.scoped(child))
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ * @stability internal-but-published
+ */
 export declare const withCloseableScope: <A, E, R>(f: (scope: Scope.Closeable) => Effect.Effect<A, E, R>, executionStrategy?: ExecutionStrategy) => Effect.Effect<A, E, R | Scope.Scope>;
+/** Runs an Effect in a child Scope and closes that child when the Effect exits.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Flattening and timing operators often need resources acquired by one inner Effect to survive its
+ * local construction but not the enclosing operator run.
+ *
+ * ## Ownership and lifetime
+ *
+ * A sequentially closing child Scope is forked from the required parent Scope, installed as the
+ * Effect's `Scope.Scope` service, and closed with the same `Exit` on success, typed failure, defect,
+ * or interruption. Non-Scope services and the `A`/`E` channels are unchanged.
+ *
+ * @example
+ * ```ts
+ * import { extendScope } from "@typed/fx/Fx/internal/scope"
+ * import * as Effect from "effect/Effect"
+ *
+ * const value = Effect.scoped(extendScope(Effect.succeed("ready")))
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ * @stability internal-but-published
+ */
 export declare const extendScope: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | Scope.Scope>;
+/** Builds and runs an Effect inside a child Scope that closes at the Effect's exit.
+ *
+ * @remarks
+ * ## Why
+ *
+ * This combines access to the closeable child with guaranteed local teardown, allowing an operator
+ * to register resources and also close the lifetime explicitly before the parent ends.
+ *
+ * ## Ownership and lifetime
+ *
+ * The required parent Scope owns the child as a fallback. The child is provided to `f` as the
+ * current Scope and is also closed with `f`'s exact `Exit`. `executionStrategy` controls ordering of
+ * its finalizers. The helper preserves typed errors and remaining service requirements.
+ *
+ * @example
+ * ```ts
+ * import { withExtendedScope } from "@typed/fx/Fx/internal/scope"
+ * import * as Effect from "effect/Effect"
+ * import * as Scope from "effect/Scope"
+ *
+ * const program = withExtendedScope((scope) =>
+ *   Scope.addFinalizer(scope, Effect.log("child closed"))
+ * )
+ * Effect.runSync(Effect.scoped(program))
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ * @stability internal-but-published
+ */
 export declare const withExtendedScope: <A, E, R>(f: (scope: Scope.Closeable) => Effect.Effect<A, E, R>, executionStrategy?: ExecutionStrategy) => Effect.Effect<A, E, R | Scope.Scope>;
+/** Starts Effects as interruptible fibers owned by an operator's child Scope.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Passing a constrained fork function prevents nested work from escaping the exact lifetime an Fx
+ * operator established for it.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each returned Fiber is closed by that child Scope. The forked Effect keeps its own typed error and
+ * service channels; fiber creation itself cannot fail in the typed channel.
+ *
+ * @since 1.0.0
+ * @category type-level
+ * @stability internal-but-published
+ */
 export type Fork = <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<Fiber.Fiber<A, E>, never, R>;
+/** Provides a child Scope and a function for forking interruptible work into it.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Concurrent Fx operators need all child fibers to terminate together when their operator run ends,
+ * including failure and interruption paths.
+ *
+ * ## Ownership and lifetime
+ *
+ * The helper uses `withExtendedScope`, so the child closes on every exit and remains attached to the
+ * required parent Scope. Forks use `Effect.forkIn` with `uninterruptible: false` and
+ * `startImmediately: false`; their services come from the Effect supplied to `fork`. Finalizer order
+ * follows `executionStrategy`.
+ *
+ * @example
+ * ```ts
+ * import { withScopedFork } from "@typed/fx/Fx/internal/scope"
+ * import * as Effect from "effect/Effect"
+ * import * as Fiber from "effect/Fiber"
+ *
+ * const program = withScopedFork((fork) =>
+ *   Effect.flatMap(fork(Effect.succeed(1)), Fiber.join)
+ * )
+ * Effect.runSync(Effect.scoped(program))
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ * @stability internal-but-published
+ */
 export declare const withScopedFork: <A, E, R>(f: (fork: Fork, scope: Scope.Closeable) => Effect.Effect<A, E, R>, executionStrategy?: ExecutionStrategy) => Effect.Effect<A, E, R | Scope.Scope>;
+/** Suspends until a Scope starts running its finalizers.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Subjects remain subscribed for the lifetime of their observing Scope even when there is no other
+ * Effect work to await. Registering a finalizer turns that lifetime boundary into a completion
+ * signal without polling.
+ *
+ * ## Ownership and lifetime
+ *
+ * Execution registers one finalizer on `scope` from a small helper fiber using the current
+ * scheduler. The Effect resumes when that finalizer runs. Cancelling the callback interrupts the
+ * registration fiber; once registration has completed, the finalizer belongs to `scope`. No typed
+ * errors or services are introduced.
+ *
+ * @example
+ * ```ts
+ * import { awaitScopeClose } from "@typed/fx/Fx/internal/scope"
+ * import * as Effect from "effect/Effect"
+ * import * as Exit from "effect/Exit"
+ * import * as Fiber from "effect/Fiber"
+ * import * as Scope from "effect/Scope"
+ *
+ * const program = Effect.gen(function* () {
+ *   const scope = yield* Scope.make()
+ *   const waiter = yield* Effect.forkDetach(awaitScopeClose(scope))
+ *   yield* Scope.close(scope, Exit.void)
+ *   yield* Fiber.join(waiter)
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ * @stability internal-but-published
+ */
 export declare function awaitScopeClose(scope: Scope.Scope): Effect.Effect<unknown, never, never>;
 //# sourceMappingURL=scope.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/Fx/internal/scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,UAAU,CAAC;AAE1D,eAAO,MAAM,kBAAkB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACxC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACrD,oBAAoB,iBAAiB,KACpC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CACiD,CAAC;AAExF,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACjC,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAInC,CAAC;AAEJ,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACvC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACrD,oBAAoB,iBAAiB,KACpC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAKnC,CAAC;AAEJ,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACzB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;AAEhD,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACpC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjE,oBAAoB,iBAAiB,KACpC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAQnC,CAAC;AAEJ,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,wCASjD"}
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/Fx/internal/scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,UAAU,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,KACrC,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,sBACjC,iBAAiB,KACpC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CACiD,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,UACzB,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAInC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,KACpC,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,sBACjC,iBAAiB,KACpC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAKnC,CAAC;AAEJ;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACzB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,KACjC,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,sBAC7C,iBAAiB,KACpC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAQnC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,wCASjD"}

package/dist/Fx/internal/scope.js

@@ -1,10 +1,160 @@
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
 import * as Scope from "effect/Scope";
+/** Forks a closeable child from the current Scope and passes it to an Effect builder.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Operators need a lifetime they can close independently while still guaranteeing that the parent
+ * Scope eventually closes it if the operator is interrupted.
+ *
+ * ## Ownership and lifetime
+ *
+ * The caller's required Scope owns the forked child. This helper does not close the child when `f`
+ * returns; parent closure does. Use `withExtendedScope` when the child must close at the returned
+ * Effect's exit. `f` retains its exact value, typed error, and service channels.
+ *
+ * @example
+ * ```ts
+ * import { withCloseableScope } from "@typed/fx/Fx/internal/scope"
+ * import * as Effect from "effect/Effect"
+ *
+ * const child = withCloseableScope((scope) => Effect.succeed(scope), "sequential")
+ * const scope = Effect.runSync(Effect.scoped(child))
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ * @stability internal-but-published
+ */
 export const withCloseableScope = (f, executionStrategy) => Effect.scopedWith((scope) => Effect.flatMap(Scope.fork(scope, executionStrategy), f));
+/** Runs an Effect in a child Scope and closes that child when the Effect exits.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Flattening and timing operators often need resources acquired by one inner Effect to survive its
+ * local construction but not the enclosing operator run.
+ *
+ * ## Ownership and lifetime
+ *
+ * A sequentially closing child Scope is forked from the required parent Scope, installed as the
+ * Effect's `Scope.Scope` service, and closed with the same `Exit` on success, typed failure, defect,
+ * or interruption. Non-Scope services and the `A`/`E` channels are unchanged.
+ *
+ * @example
+ * ```ts
+ * import { extendScope } from "@typed/fx/Fx/internal/scope"
+ * import * as Effect from "effect/Effect"
+ *
+ * const value = Effect.scoped(extendScope(Effect.succeed("ready")))
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ * @stability internal-but-published
+ */
 export const extendScope = (effect) => withCloseableScope((scope) => Scope.provide(effect.pipe(Effect.onExit((exit) => Scope.close(scope, exit))), scope), "sequential");
+/** Builds and runs an Effect inside a child Scope that closes at the Effect's exit.
+ *
+ * @remarks
+ * ## Why
+ *
+ * This combines access to the closeable child with guaranteed local teardown, allowing an operator
+ * to register resources and also close the lifetime explicitly before the parent ends.
+ *
+ * ## Ownership and lifetime
+ *
+ * The required parent Scope owns the child as a fallback. The child is provided to `f` as the
+ * current Scope and is also closed with `f`'s exact `Exit`. `executionStrategy` controls ordering of
+ * its finalizers. The helper preserves typed errors and remaining service requirements.
+ *
+ * @example
+ * ```ts
+ * import { withExtendedScope } from "@typed/fx/Fx/internal/scope"
+ * import * as Effect from "effect/Effect"
+ * import * as Scope from "effect/Scope"
+ *
+ * const program = withExtendedScope((scope) =>
+ *   Scope.addFinalizer(scope, Effect.log("child closed"))
+ * )
+ * Effect.runSync(Effect.scoped(program))
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ * @stability internal-but-published
+ */
 export const withExtendedScope = (f, executionStrategy) => withCloseableScope((scope) => Scope.provide(f(scope).pipe(Effect.onExit((exit) => Scope.close(scope, exit))), scope), executionStrategy);
+/** Provides a child Scope and a function for forking interruptible work into it.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Concurrent Fx operators need all child fibers to terminate together when their operator run ends,
+ * including failure and interruption paths.
+ *
+ * ## Ownership and lifetime
+ *
+ * The helper uses `withExtendedScope`, so the child closes on every exit and remains attached to the
+ * required parent Scope. Forks use `Effect.forkIn` with `uninterruptible: false` and
+ * `startImmediately: false`; their services come from the Effect supplied to `fork`. Finalizer order
+ * follows `executionStrategy`.
+ *
+ * @example
+ * ```ts
+ * import { withScopedFork } from "@typed/fx/Fx/internal/scope"
+ * import * as Effect from "effect/Effect"
+ * import * as Fiber from "effect/Fiber"
+ *
+ * const program = withScopedFork((fork) =>
+ *   Effect.flatMap(fork(Effect.succeed(1)), Fiber.join)
+ * )
+ * Effect.runSync(Effect.scoped(program))
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ * @stability internal-but-published
+ */
 export const withScopedFork = (f, executionStrategy) => withExtendedScope((scope) => f((eff) => Effect.forkIn(eff, scope, { uninterruptible: false, startImmediately: false }), scope), executionStrategy);
+/** Suspends until a Scope starts running its finalizers.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Subjects remain subscribed for the lifetime of their observing Scope even when there is no other
+ * Effect work to await. Registering a finalizer turns that lifetime boundary into a completion
+ * signal without polling.
+ *
+ * ## Ownership and lifetime
+ *
+ * Execution registers one finalizer on `scope` from a small helper fiber using the current
+ * scheduler. The Effect resumes when that finalizer runs. Cancelling the callback interrupts the
+ * registration fiber; once registration has completed, the finalizer belongs to `scope`. No typed
+ * errors or services are introduced.
+ *
+ * @example
+ * ```ts
+ * import { awaitScopeClose } from "@typed/fx/Fx/internal/scope"
+ * import * as Effect from "effect/Effect"
+ * import * as Exit from "effect/Exit"
+ * import * as Fiber from "effect/Fiber"
+ * import * as Scope from "effect/Scope"
+ *
+ * const program = Effect.gen(function* () {
+ *   const scope = yield* Scope.make()
+ *   const waiter = yield* Effect.forkDetach(awaitScopeClose(scope))
+ *   yield* Scope.close(scope, Exit.void)
+ *   yield* Fiber.join(waiter)
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ * @stability internal-but-published
+ */
 export function awaitScopeClose(scope) {
     return Effect.callback(function (cb) {
         return Fiber.interrupt(Effect.runFork(Scope.addFinalizerExit(scope, () => Effect.sync(() => cb(Effect.void))), { scheduler: this }));

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

@@ -2,16 +2,131 @@ import * as Effect from "effect/Effect";
 import type { Sink } from "../../Sink/Sink.js";
 import type * as Fx from "../Fx.js";
 import { FxTypeId } from "../TypeId.js";
-export declare abstract class YieldableFx<A, E, R, B, E2, R2> extends Effect.YieldableClass<B, E2, R2> implements Fx.Fx<A, E, R> {
+import { EffectableWithOverride } from "./effectableWithOverride.js";
+/** Base class for values that are both an Fx push source and an Effect-compatible sample.
+ *
+ * @remarks
+ * ## Why
+ *
+ * RefSubject and Versioned values need one object that composes through Fx operators when observed
+ * and through Effect operators when a current value is requested. This class supplies the shared
+ * brands, pipeability, and Effect evaluator bridge without forcing the two channels to have the
+ * same value, error, or service types.
+ *
+ * ## Ownership and lifetime
+ *
+ * The base class acquires no resources. `run` defines the push subscription lifetime and `toEffect`
+ * defines sampling. The first Effect evaluation memoizes the Effect object returned by `toEffect`,
+ * not its result: each execution still follows that Effect's own acquisition, error, interruption,
+ * and cleanup behavior.
+ *
+ * This is a published advanced extension point coupled to Typed's Fx brand and Effect evaluator
+ * protocol. Its shape may change between prereleases.
+ *
+ * @example
+ * ```ts
+ * import { YieldableFx } from "@typed/fx/Fx/internal/yieldable"
+ * import type { Sink } from "@typed/fx/Sink/Sink"
+ * import * as Effect from "effect/Effect"
+ *
+ * class One extends YieldableFx<number, never, never, number, never, never> {
+ *   run<R>(sink: Sink<number, never, R>): Effect.Effect<unknown, never, R> {
+ *     return sink.onSuccess(1)
+ *   }
+ *   toEffect() {
+ *     return Effect.succeed(1)
+ *   }
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ * @category advanced
+ * @stability internal-but-published
+ */
+export declare abstract class YieldableFx<A, E, R, B, E2, R2> extends EffectableWithOverride<B, E2, R2> implements Fx.Fx<A, E, R> {
+    /** Fx variance marker that makes subclasses valid `Fx<A, E, R>` values.
+     *
+     * @remarks
+     * ## Why
+     *
+     * The marker carries Fx's value, error, and service variance through subclass types.
+     *
+     * ## Ownership and lifetime
+     *
+     * Immutable protocol metadata shared through the instance; it acquires no resources.
+     *
+     * @since 1.0.0
+     * @category symbols
+     */
     readonly [FxTypeId]: {
         _A: <A_1>(a: A_1) => A_1;
         _E: <A_1>(a: A_1) => A_1;
         _R: <A_1>(a: A_1) => A_1;
     };
+    /** Subscribes a Sink to the pushed channel.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Implementations determine cardinality, ordering, and subscription cleanup. The contract exposes
+     * no typed failure because failures are delivered to the Sink; required services combine `R` with
+     * the sink's `RSink`.
+     *
+     * ## Ownership and lifetime
+     *
+     * The implementation owns the subscription and must bind cleanup to the lifetime visible in its
+     * service requirements.
+     *
+     * @since 1.0.0
+     * @category effects
+     */
     abstract run<RSink>(sink: Sink<A, E, RSink>): Effect.Effect<unknown, never, R | RSink>;
+    /** Builds the Effect used when the value is sampled or yielded.
+     *
+     * @remarks
+     * ## Why
+     *
+     * The returned Effect object is memoized by `override`; its result is not automatically cached.
+     *
+     * ## Ownership and lifetime
+     *
+     * Implementations define acquisition and finalization; the base class retains the returned Effect.
+     *
+     * @since 1.0.0
+     * @category effects
+     */
     abstract toEffect(): Effect.Effect<B, E2, R2>;
+    /** Pipes this dual Fx/Effect value through Effect or Typed combinators.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Delegates to Effect's `pipeArguments` and acquires no resources.
+     *
+     * ## Ownership and lifetime
+     *
+     * Returns the combinator result and retains no state beyond whatever that result captures.
+     *
+     * @since 1.0.0
+     * @category combinators
+     */
     pipe(): unknown;
     protected _effect: Effect.Effect<B, E2, R2> | null;
-    asEffect(): Effect.Effect<B, E2, R2>;
+    /** Memoized Effect view used by Effect's evaluator protocol.
+     *
+     * @remarks
+     * ## Why
+     *
+     * The getter calls `toEffect` at most once per instance. It does not run the Effect and therefore
+     * does not memoize successes or failures.
+     *
+     * ## Ownership and lifetime
+     *
+     * The instance retains the Effect description for its lifetime; each execution owns its own work.
+     *
+     * @since 1.0.0
+     * @category effects
+     */
+    get override(): Effect.Effect<B, E2, R2>;
 }
 //# sourceMappingURL=yieldable.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"yieldable.d.ts","sourceRoot":"","sources":["../../../src/Fx/internal/yieldable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,KAAK,KAAK,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAQxC,8BAAsB,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAClD,SAAQ,MAAM,CAAC,cAAc,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CACvC,YAAW,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAEzB,QAAQ,CAAC,CAAC,QAAQ,CAAC;;;;MAAY;IAC/B,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC;IACtF,QAAQ,CAAC,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC;IAE7C,IAAI;IAKJ,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,CAAQ;IAC1D,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC;CAGrC"}
+{"version":3,"file":"yieldable.d.ts","sourceRoot":"","sources":["../../../src/Fx/internal/yieldable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,KAAK,KAAK,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAQrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,8BAAsB,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAClD,SAAQ,sBAAsB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CACxC,YAAW,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAEzB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,CAAC,QAAQ,CAAC;;;;MAAY;IAE/B;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC;IAEvF;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAE9C;;;;;;;;;;;;;OAaG;IACH,IAAI,YAEH;IAGD,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,CAAQ;IAC1D;;;;;;;;;;;;;;OAcG;IACH,IAAI,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAEvC;CACF"}

package/dist/Fx/internal/yieldable.js

@@ -1,20 +1,103 @@
-import * as Effect from "effect/Effect";
 import { identity } from "effect/Function";
 import { pipeArguments } from "effect/Pipeable";
 import { FxTypeId } from "../TypeId.js";
+import { EffectableWithOverride } from "./effectableWithOverride.js";
 const VARIANCE = {
     _A: identity,
     _E: identity,
     _R: identity,
 };
-export class YieldableFx extends Effect.YieldableClass {
+/** Base class for values that are both an Fx push source and an Effect-compatible sample.
+ *
+ * @remarks
+ * ## Why
+ *
+ * RefSubject and Versioned values need one object that composes through Fx operators when observed
+ * and through Effect operators when a current value is requested. This class supplies the shared
+ * brands, pipeability, and Effect evaluator bridge without forcing the two channels to have the
+ * same value, error, or service types.
+ *
+ * ## Ownership and lifetime
+ *
+ * The base class acquires no resources. `run` defines the push subscription lifetime and `toEffect`
+ * defines sampling. The first Effect evaluation memoizes the Effect object returned by `toEffect`,
+ * not its result: each execution still follows that Effect's own acquisition, error, interruption,
+ * and cleanup behavior.
+ *
+ * This is a published advanced extension point coupled to Typed's Fx brand and Effect evaluator
+ * protocol. Its shape may change between prereleases.
+ *
+ * @example
+ * ```ts
+ * import { YieldableFx } from "@typed/fx/Fx/internal/yieldable"
+ * import type { Sink } from "@typed/fx/Sink/Sink"
+ * import * as Effect from "effect/Effect"
+ *
+ * class One extends YieldableFx<number, never, never, number, never, never> {
+ *   run<R>(sink: Sink<number, never, R>): Effect.Effect<unknown, never, R> {
+ *     return sink.onSuccess(1)
+ *   }
+ *   toEffect() {
+ *     return Effect.succeed(1)
+ *   }
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ * @category advanced
+ * @stability internal-but-published
+ */
+export class YieldableFx extends EffectableWithOverride {
+    /** Fx variance marker that makes subclasses valid `Fx<A, E, R>` values.
+     *
+     * @remarks
+     * ## Why
+     *
+     * The marker carries Fx's value, error, and service variance through subclass types.
+     *
+     * ## Ownership and lifetime
+     *
+     * Immutable protocol metadata shared through the instance; it acquires no resources.
+     *
+     * @since 1.0.0
+     * @category symbols
+     */
     [FxTypeId] = VARIANCE;
+    /** Pipes this dual Fx/Effect value through Effect or Typed combinators.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Delegates to Effect's `pipeArguments` and acquires no resources.
+     *
+     * ## Ownership and lifetime
+     *
+     * Returns the combinator result and retains no state beyond whatever that result captures.
+     *
+     * @since 1.0.0
+     * @category combinators
+     */
     pipe() {
         return pipeArguments(this, arguments);
     }
     // Memoize the effect
     _effect = null;
-    asEffect() {
+    /** Memoized Effect view used by Effect's evaluator protocol.
+     *
+     * @remarks
+     * ## Why
+     *
+     * The getter calls `toEffect` at most once per instance. It does not run the Effect and therefore
+     * does not memoize successes or failures.
+     *
+     * ## Ownership and lifetime
+     *
+     * The instance retains the Effect description for its lifetime; each execution owns its own work.
+     *
+     * @since 1.0.0
+     * @category effects
+     */
+    get override() {
         return (this._effect ??= this.toEffect());
     }
 }