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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present The Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,7 +10,7 @@
 
 ## API overview
 
-- **Fx** — Stream type `Fx.Fx<A, E, R>` with constructors (`succeed`, `fail`, `fromEffect`, `fromIterable`, `make`, `periodic`, etc.), combinators (`map`, `flatMap`, `filter`, `take`, `switchMap`, etc.), and run (`runPromise`, `collect`, `fork`, `observe`).
+- **Fx** — Stream type `Fx.Fx<A, E, R>` with constructors (`succeed`, `fail`, `fromEffect`, `fromIterable`, `make`, `periodic`, etc.), combinators (`map`, `flatMap`, `filter`, `take`, `switchMap`, etc.), and run (`runPromise`, `collectAll`, `fork`, `observe`).
 - **Push** — Push-based stream abstraction.
 - **RefSubject** — Mutable reactive refs; `RefSubject.make(initial)`; typed helpers like `RefSubject.increment` / `RefSubject.decrement` for numbers; `RefArray`, `RefBoolean`, `RefOption`, etc.
 - **Subject** — Multicast subject for Fx streams.
@@ -20,17 +20,18 @@
 ## Example
 
 ```ts
+import { Effect } from "effect";
 import { Fx } from "@typed/fx";
 
 Fx.fromIterable([1, 2, 3]).pipe(
   Fx.filter((n) => n % 2 === 0),
   Fx.map((n) => n * 2),
   Fx.observe((n) => Effect.log(`emitted: ${n}`)),
-  Effect.runPromise
+  Effect.runPromise,
 );
 ```
 
-See the [counter example](https://github.com/typed-smol/typed-smol/tree/main/examples/counter) for a full runnable app.
+See the [counter example](https://github.com/TylorS/typed/tree/development/examples/counter) for a full runnable app.
 
 ## API reference
 
@@ -69,7 +70,6 @@ Reactive stream type with concurrency, error handling, and context, integrated w
 - `never` — Run forever without emitting.
 - `fromEffect(effect)` — One-value Fx from an Effect (emit on success, fail on failure).
 - `fromIterable(iterable)` — Emit each element of the iterable then complete.
-- `fromYieldable(yieldable)` — Fx from any Yieldable (Effect, Promise, etc.).
 - `fromSchedule(schedule)` — Emit `void` each time the schedule fires.
 - `fromFailures(failures)` — Fx that fails with combined failures from an iterable.
 - `make(run)` — Low-level: build Fx from a function that runs a Sink.
@@ -82,56 +82,80 @@ Reactive stream type with concurrency, error handling, and context, integrated w
 
 - `map(f)` — Transform emitted values.
 - `mapEffect(f)` — Transform with an Effect.
+- `mapError(f)` — Transform typed failures.
+- `mapBoth({ onSuccess, onFailure })` — Transform both success values and typed failures.
 - `flatMap(f)` — Map to inner Fx and merge (concurrent; like mergeMap).
-- `flatMapEffect(f)` — FlatMap with an Effect returning Fx.
-- `flatMapConcurrently(f, concurrency?)` — FlatMap with a concurrency limit.
-- `flatMapConcurrentlyEffect(f, concurrency?)` — Same with Effect-based inner Fx.
+- `flatMapEffect(f)` — Map to an Effect and merge its successful values.
+- `flatMapConcurrently(f, concurrency)` — FlatMap with a positive safe-integer concurrency limit; invalid limits fail through the Fx error channel with `IllegalArgumentError`.
+- `flatMapConcurrentlyEffect(f, concurrency)` — Map to Effects with the same validated concurrency contract.
 - `switchMap(f)` — Map to inner Fx and switch to latest (cancels previous).
-- `switchMapEffect(f)` — SwitchMap with Effect returning Fx.
+- `switchMapEffect(f)` — Map to an Effect and switch to the latest execution.
 - `exhaustMap(f)` — Map to inner Fx, ignore new outer values while inner runs.
-- `exhaustMapEffect(f)` — ExhaustMap with Effect returning Fx.
+- `exhaustMapEffect(f)` — Map to an Effect, ignoring new values while it runs.
 - `exhaustLatestMap(f)` — Like exhaustMap but cancel previous inner when new outer arrives.
-- `exhaustLatestMapEffect(f)` — ExhaustLatestMap with Effect returning Fx.
+- `exhaustLatestMapEffect(f)` — Effect-based exhaustLatestMap.
 - `filter(f)` — Keep only values satisfying the predicate.
 - `filterEffect(f)` — Filter with an Effect predicate.
 - `filterMap(f)` — Filter and map to Option; compact.
 - `filterMapEffect(f)` — FilterMap with Effect.
 - `compact` — Filter out `None`, unwrap `Some`.
 - `take(n)` — Take first n elements.
-- `takeUntil(fx)` — Take until another Fx emits.
+- `takeEffect(effect)` — Take first n elements, where n is computed by an Effect.
+- `takeUntil(predicate)` — Take values until the predicate matches; the matching value is excluded.
+- `takeUntilEffect(f)` — Take values until an effectful predicate matches; the matching value is excluded.
+- `takeWhile(f)` — Take while predicate holds.
+- `takeWhileEffect(f)` — Take while effectful predicate holds.
 - `skip(n)` — Skip first n elements.
+- `skipEffect(effect)` — Skip first n elements, where n is computed by an Effect.
+- `skipWhile(f)` / `dropWhile(f)` — Skip while predicate holds.
+- `skipWhileEffect(f)` / `dropWhileEffect(f)` — Skip while effectful predicate holds.
 - `slice(options)` — Skip/take by bounds.
+- `sliceEffect(effect)` — Skip/take by bounds produced by an Effect.
 - `skipRepeats` — Drop consecutive duplicates (Equal).
 - `skipRepeatsWith(equiv)` — Drop consecutive duplicates with custom equivalence.
+- `changesWithEffect(f)` — Effectful consecutive deduplication predicate.
+- `merge(fx)` — Merge with another Fx.
 - `mergeAll(fxs)` — Merge multiple Fx streams.
 - `mergeOrdered(fxs)` — Merge with ordering guarantees.
+- `concat(fx)` — Concatenate with another Fx (run second after first completes).
+- `zip(fx)` / `zipWith(fx, f)` — Zip streams in lockstep.
+- `zipLatest(fx)` / `zipLatestWith(fx, f)` — Zip latest values after both emit once.
 - `catch(f)` — Recover from errors.
+- `catchIf(refinement, f)` — Recover conditionally from typed failures.
+- `catchCauseIf(predicate, f)` — Recover conditionally from failure causes.
+- `catchTags(handlers)` — Recover from multiple tagged failures with handler map.
 - `onError(f)` — Run an effect on failure.
 - `onExit(f)` — Run an effect on exit (success/failure/interrupt).
 - `onInterrupt(f)` — Run an effect on interrupt.
 - `ensuring(effect)` — Run effect when Fx ends (success, failure, or interrupt).
-- `provide(services)` — Provide context to the Fx.
-- `when(condition, fx)` — Run Fx only when condition holds.
+- `provide(layer)` — Provide services to the Fx from a Layer.
+- `provideService(tag, service)` — Provide a single service to the Fx.
+- `provideServiceEffect(tag, effect)` — Provide a service produced by an Effect.
+- `if(condition, { onTrue, onFalse })` — Switch between two Fx streams based on a boolean Fx.
+- `when(condition, { onTrue, onFalse })` — Map a boolean Fx to one of two values.
 - `unwrap` — Unwrap Fx of Fx (flatten one level).
 - `unwrapScoped` — Unwrap with Scope for inner Fx.
 - `gen(f)` — Build Fx from a generator (yield Effects, return Fx).
 - `genScoped(f)` — gen with Scope.
 - `loop(initial, f)` — Loop with state and Option for continue/exit.
 - `loopEffect(initial, f)` — Loop with Effect.
+- `scan(initial, f)` — Emit running accumulation (includes initial value).
+- `scanEffect(initial, f)` — Effectful running accumulation.
 - `loopCause(initial, f)` — Loop with Cause handling.
 - `loopCauseEffect(initial, f)` — Loop with Cause and Effect.
 - `filterMapLoop(initial, f)` — Loop yielding Option.
 - `filterMapLoopEffect(initial, f)` — filterMapLoop with Effect.
 - `filterMapLoopCause(initial, f)` — filterMapLoop with Cause.
 - `filterMapLoopCauseEffect(initial, f)` — filterMapLoop with Cause and Effect.
-- `keyed(keyFn, f)` — Keyed stream (e.g. by id) with inner Fx per key.
-- `tapEffect(f)` — Run effect for each value, pass value through.
+- `keyed({ getKey, onValue, debounce? })` — Track array elements by key and run an inner Fx per key.
+- `tap(f)` — Run a function or Effect for each value, then pass the value through.
 - `exit` — Turn Fx of Exit into Fx that fails/succeeds accordingly.
+- `result` — Materialize successes/failures as `Result`.
 - `causes` — Expose failures as Cause emissions.
 - `continueWith(f)` — When Fx ends, continue with another Fx.
 - `flip` — Swap success and error types.
 - `tuple(...fxs)` — Combine Fx streams into tuple Fx.
-- `withSpan(name?, options?)` — Add tracing span around the Fx.
+- `withSpan(name, options?)` — Add tracing spans around the Fx and sink callbacks.
 
 **Run**
 
@@ -188,6 +212,8 @@ Mutable reactive reference: observable state that can be read (as Effect), updat
 **Constructors**
 
 - `make(initial, options?)` — Create RefSubject from value, Effect, or Fx; options include `eq` (equivalence).
+- `hydrate(schema, initial, options?)` — Create a callable `HydratedRefSubject` that is both reactive state and its DOM hydration ref. A named hydration requires a string-encoded schema.
+- `hydrateAll(first, ...rest)` — Compose hydrated states into one DOM ref invocation.
 - `fromEffect(effect)` — RefSubject driven by an Effect (e.g. initial value from async source).
 - `fromFx(fx)` — RefSubject that follows an Fx stream.
 - `fromStream(stream)` — RefSubject from an Effect Stream.
@@ -206,6 +232,17 @@ Mutable reactive reference: observable state that can be read (as Effect), updat
 - `proxy(ref)` — Create a proxy RefSubject that forwards to the given ref.
 - `isRefSubject(value)` — Type guard for RefSubject.
 
+**Hydration**
+
+```ts
+const count = yield * RefSubject.hydrate(Schema.Number, 0);
+const page = yield * RefSubject.hydrate(Schema.NumberFromString, 1, { name: "page" });
+
+html`<section ref=${RefSubject.hydrateAll(count, page)}>${count}</section>`;
+```
+
+The returned state is directly callable as the specialized DOM ref; there is no separate hydration property. Unnamed states share a versioned `data-typed-refsubject` tuple that is consumed and removed without installing an ongoing subscription. A named state uses its string codec directly in `data-<name>`, retains that attribute, and keeps it synchronized with exactly one scope-owned subscription. Closing the scope stops named synchronization.
+
 **Derived**
 
 - `map(ref, f)` — Computed that applies f to the value.
@@ -223,7 +260,7 @@ Mutable reactive reference: observable state that can be read (as Effect), updat
 
 **Typed refs** (each has `make` and domain-specific helpers)
 
-- `RefArray` — Array ref; e.g. prepend, append, remove.
+- `RefArray` — Array ref; e.g. prepend, append, insertAt, replaceAt, drop, and filterValues.
 - `RefBoolean` — Boolean ref; e.g. toggle, setTrue, setFalse.
 - `RefOption` — Option ref.
 - `RefResult` — Result ref.
@@ -256,15 +293,15 @@ Multicast point: both an Fx and a Sink; multiple subscribers share one run of th
 
 **Constructors**
 
-- `Subject.make(replay?)` — Create a subject; optional replay buffer size.
-- `Subject.unsafeMake(replay?)` — Create without Scope (unsafe for cleanup).
+- `Subject.make(replay?)` — Create a subject; optional replay buffer size must be an integer from 0 through 4,294,967,295, otherwise the Effect fails with `IllegalArgumentError`.
+- `Subject.unsafeMake(replay?)` — Create without Scope (unsafe for cleanup); replay capacity has the same bounds and throws `IllegalArgumentError` when invalid.
 
 **Combinators**
 
 - `Subject.share(fx, subject)` — Multicast Fx through a subject (one run, many subscribers).
 - `Subject.multicast(fx)` — Share Fx with a fresh subject.
 - `Subject.hold(fx)` — Fx that holds last value for late subscribers.
-- `Subject.replay(fx, n)` — Replay last n values to new subscribers.
+- `Subject.replay(fx, n)` — Replay the last `n` values to new subscribers. Invalid capacities fail through the Fx error channel with `IllegalArgumentError`; valid capacities retain storage under the caller's memory policy.
 
 **Service**
 
@@ -311,7 +348,7 @@ Consumer of values: two callbacks, one for success and one for failure.
 - `tapEffect(sink, f)` — Tap with Effect, pass value through.
 - `flip(sink)` — Swap success and error types.
 - `exit(sink)` — Sink for Exit (success/failure).
-- `dropAfter(sink, n)` — Drop values after the nth.
+- `dropAfter(sink, predicate, run)` — Run with a derived sink that forwards through the first predicate match, then exits early.
 - `skipInterrupt(sink)` — Ignore interrupt at the Sink.
 
 **Service**

package/dist/Fx/Fx.d.ts

@@ -2,7 +2,7 @@ import * as Effect from "effect/Effect";
 import type { Layer } from "effect/Layer";
 import { type Pipeable } from "effect/Pipeable";
 import type * as Scope from "effect/Scope";
-import * as ServiceMap from "effect/ServiceMap";
+import * as Context from "effect/Context";
 import type * as Types from "effect/Types";
 import type * as Sink from "../Sink/Sink.js";
 import { FxTypeId } from "./TypeId.js";
@@ -19,78 +19,430 @@ import { FxTypeId } from "./TypeId.js";
  * 0, 1, or many values over time. It is similar to RxJS Observables or
  * AsyncIterables, but built on top of Effect's fiber-based concurrency model.
  *
+ * @remarks
+ * ## Why
+ *
+ * Browser events, clocks, sockets, and users decide when work exists. `Fx`
+ * models that producer-driven direction while retaining Effect's explicit
+ * success, error, and service channels. An `Effect`, `Stream`, `Promise`,
+ * `ReadableStream`, iterable, or custom source can participate through an
+ * explicit constructor; `Fx` extends the Effect ecosystem rather than
+ * replacing it.
+ *
+ * ## Ownership and lifetime
+ *
+ * Constructing an `Fx` starts no work. Calling `run` returns an `Effect` whose
+ * running fiber and `Scope` own subscriptions, child fibers, and finalizers.
+ * Interruption propagates through that Effect lifetime. The supplied `Sink`
+ * contributes its requirements to `run`; failures are delivered to the Sink,
+ * which is why the returned Effect itself cannot fail.
+ *
+ * ## Composition
+ *
+ * The type parameters follow Effect's `A`, `E`, `R` vocabulary. Consequently,
+ * an `Fx<RenderEvent, E, R>` can describe arbitrary UI without hiding its
+ * failures or required services.
+ *
+ * ## Effect foundations
+ *
+ * `Fx` execution is an [Effect](https://effect.website/docs/v4/api/effect/Effect),
+ * resource ownership uses [Scope](https://effect.website/docs/v4/api/effect/Scope),
+ * concurrent runs use [Fiber](https://effect.website/docs/v4/api/effect/Fiber), and
+ * failures retain Effect's structured [Cause](https://effect.website/docs/v4/api/effect/Cause).
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const keys: Fx.Fx<KeyboardEvent> = Fx.callback((emit) => {
+ *   const onKey = (event: KeyboardEvent) => emit.succeed(event)
+ *   document.addEventListener("keydown", onKey)
+ *   return Effect.sync(() => document.removeEventListener("keydown", onKey))
+ * })
+ * ```
+ *
  * @since 1.0.0
- * @category models
+ * @category Type contracts
  */
 export interface Fx<A, E = never, R = never> extends Pipeable {
+    /**
+     * Identifies this value as an `Fx` and records its success, error, and service variance.
+     *
+     * @remarks
+     * ## Why
+     *
+     * The marker makes `Fx` distinguishable at runtime without executing it, while its
+     * type carries the three channels through structural composition.
+     *
+     * ## Ownership and lifetime
+     *
+     * Reading the marker starts no work and acquires no resources.
+     *
+     * @since 1.0.0
+     * @category symbols
+     */
     readonly [FxTypeId]: Fx.Variance<A, E, R>;
     /**
-     * Runs the Fx stream by providing a Sink to consume the values.
-     * The result is an Effect that runs the stream process.
+     * Connects this producer to a `Sink` and returns the `Effect` that owns the connection.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Keeping execution behind an `Effect` preserves typed services, structured
+     * concurrency, and interruption instead of starting hidden work during construction.
+     * Values are offered to the sink in the order chosen by this `Fx`; the producer may
+     * emit zero, one, or many values.
+     *
+     * ## Ownership and lifetime
+     *
+     * Work starts when the returned `Effect` runs. Its fiber owns the subscription and
+     * any child scopes. Interrupting it interrupts the producer and runs its finalizers.
+     * Producer failures are delivered to `sink.onFailure`, so they are not repeated in
+     * the returned Effect's error channel.
+     *
+     * @since 1.0.0
+     * @category runners
      */
     readonly run: <RSink>(sink: Sink.Sink<A, E, RSink>) => Effect.Effect<unknown, never, R | RSink>;
 }
 export declare namespace Fx {
     /**
-     * Any Fx type with wildcards.
+     * Matches any `Fx` regardless of its value, error, or service channels.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Generic helpers sometimes need to retain an entire unknown `Fx` type before
+     * extracting its channels with `Success`, `Error`, and `Services`.
+     *
+     * ## Ownership and lifetime
+     *
+     * This type alias performs no acquisition and starts no stream.
+     *
      * @since 1.0.0
      * @category models
      */
     type Any = Fx<any, any, any>;
     /**
-     * Variance markers for Fx types.
+     * Describes how an `Fx` varies in its value, error, and service channels.
+     *
+     * @remarks
+     * ## Why
+     *
+     * The phantom fields preserve `Fx<A, E, R>` relationships through TypeScript's
+     * structural type system and power channel extraction without runtime sampling.
+     *
+     * ## Ownership and lifetime
+     *
+     * Variance markers are type-level metadata and retain no values or resources.
+     *
+     * @example
+     * ```ts
+     * import type { Fx } from "@typed/fx/Fx"
+     *
+     * type NumberFxVariance = Fx.Variance<number, never, never>
+     * ```
+     *
      * @since 1.0.0
      * @category models
      */
     interface Variance<A, E, R> {
+        /**
+         * Covariant marker for emitted values.
+         *
+         * @remarks
+         * ## Why
+         *
+         * Preserves the `A` relationship without retaining an emitted value.
+         *
+         * ## Ownership and lifetime
+         *
+         * This phantom field starts no work and owns no resource.
+         *
+         * @since 1.0.0
+         * @category models
+         */
         readonly _A: Types.Covariant<A>;
+        /**
+         * Covariant marker for typed failures.
+         *
+         * @remarks
+         * ## Why
+         *
+         * Preserves the `E` relationship without manufacturing a failure.
+         *
+         * ## Ownership and lifetime
+         *
+         * This phantom field starts no work and owns no resource.
+         *
+         * @since 1.0.0
+         * @category models
+         */
         readonly _E: Types.Covariant<E>;
+        /**
+         * Covariant marker for required services.
+         *
+         * @remarks
+         * ## Why
+         *
+         * Preserves the `R` relationship without reading an Effect context.
+         *
+         * ## Ownership and lifetime
+         *
+         * This phantom field starts no work and owns no resource.
+         *
+         * @since 1.0.0
+         * @category models
+         */
         readonly _R: Types.Covariant<R>;
     }
     /**
-     * Extract the success type from an Fx.
+     * Extracts the emitted value type from an `Fx`.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Higher-order APIs can preserve a producer's value channel without restating all
+     * three `Fx` type parameters. `never` remains `never` rather than distributing.
+     *
+     * ## Ownership and lifetime
+     *
+     * This conditional type performs no runtime work.
      * @since 1.0.0
-     * @category type-level
+     * @category Type contracts
      */
     type Success<T> = [T] extends [never] ? never : T extends Fx<infer _A, infer _E, infer _R> ? _A : never;
     /**
-     * Extract the error type from an Fx.
+     * Extracts the typed error from an `Fx`.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Higher-order APIs can combine an unknown producer's failure channel precisely.
+     * `never` remains `never` rather than distributing.
+     *
+     * ## Ownership and lifetime
+     *
+     * This conditional type performs no runtime work.
      * @since 1.0.0
-     * @category type-level
+     * @category Type contracts
      */
     type Error<T> = [T] extends [never] ? never : T extends Fx<infer _A, infer _E, infer _R> ? _E : never;
     /**
-     * Extract the required services from an Fx.
+     * Extracts the services required to run an `Fx`.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Combinators and helpers can expose the complete environment of a producer without
+     * evaluating it. The tuple wrapper prevents unwanted conditional distribution.
+     *
+     * ## Ownership and lifetime
+     *
+     * This conditional type performs no runtime work.
      * @since 1.0.0
-     * @category type-level
+     * @category Type contracts
      */
     type Services<T> = [T] extends [never] ? never : [T] extends [Fx<infer _A, infer _E, infer _R>] ? _R : never;
+    /**
+     * An `Fx` whose implementation is obtained from an Effect service.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Long-lived producers can be selected and replaced through Effect's service graph
+     * while remaining directly usable as `Fx<A, E, Self>`.
+     *
+     * ## Ownership and lifetime
+     *
+     * The service declaration owns nothing. A layer made with `make` owns the supplied
+     * producer for that layer's scope; each run reads the installed service.
+     *
+     * @example
+     * ```ts
+     * import { Fx } from "@typed/fx"
+     * import type { Fx as FxModel } from "@typed/fx/Fx"
+     *
+     * class Ticks extends Fx.Service<Ticks, number>()("app/Ticks") {}
+     * const service: FxModel.Service<Ticks, "app/Ticks", number, never> = Ticks
+     * ```
+     *
+     * @since 1.0.0
+     * @category Providing services
+     */
     interface Service<Self, Id extends string, A, E> extends Fx<A, E, Self> {
+        /**
+         * Stable diagnostic identifier used to create the Effect service.
+         *
+         * @remarks
+         * ## Why
+         *
+         * Keeps the service identity visible to diagnostics and tooling.
+         *
+         * ## Ownership and lifetime
+         *
+         * Reading the identifier starts no work and owns no resource.
+         *
+         * @since 1.0.0
+         * @category models
+         */
         readonly id: Id;
-        readonly service: ServiceMap.Service<Self, Fx<A, E>>;
+        /**
+         * Effect service tag containing the installed producer.
+         *
+         * @remarks
+         * ## Why
+         *
+         * Exposes the underlying Effect service for direct context and layer composition.
+         *
+         * ## Ownership and lifetime
+         *
+         * The tag is inert; the layer that installs its value owns the producer lifetime.
+         *
+         * @since 1.0.0
+         * @category models
+         */
+        readonly service: Context.Service<Self, Fx<A, E>>;
+        /**
+         * Builds a layer from an `Fx`, or from an `Effect` that acquires one.
+         *
+         * @remarks
+         * ## Why
+         *
+         * Connects producer acquisition directly to Effect's service graph.
+         *
+         * ## Ownership and lifetime
+         *
+         * Scope is removed from the layer requirements because layer acquisition supplies
+         * it. Other services and typed failures remain visible.
+         *
+         * @since 1.0.0
+         * @category layers
+         */
         readonly make: <R = never>(fx: Fx<A, E, R> | Effect.Effect<Fx<A, E, R>, E, R>) => Layer<Self, E, Exclude<R, Scope.Scope>>;
     }
+    /**
+     * The constructible service class returned by `Fx.Service`.
+     *
+     * @remarks
+     * ## Why
+     *
+     * A single value can act as the service tag, the service-backed `Fx`, and the owner
+     * of its [Layer](https://effect.website/docs/v4/api/effect/Layer) constructor,
+     * matching Effect's class-based service ergonomics.
+     *
+     * ## Ownership and lifetime
+     *
+     * Constructing the class returns the class value and starts no producer. Installed
+     * layer scopes own actual implementations.
+     *
+     * @example
+     * ```ts
+     * import { Fx } from "@typed/fx"
+     * import type { Fx as FxModel } from "@typed/fx/Fx"
+     *
+     * class Ticks extends Fx.Service<Ticks, number>()("app/Ticks") {}
+     * const definition: FxModel.Class<Ticks, "app/Ticks", number, never> = Ticks
+     * ```
+     *
+     * @since 1.0.0
+     * @category models
+     */
     interface Class<Self, Id extends string, A, E> extends Service<Self, Id, A, E> {
+        /**
+         * Returns the service class as its service-backed `Fx` value.
+         *
+         * @remarks
+         * ## Why
+         *
+         * Supports Effect's class-as-tag ergonomics without allocating wrapper instances.
+         *
+         * ## Ownership and lifetime
+         *
+         * Construction starts no producer. The installed layer owns the implementation.
+         *
+         * @since 1.0.0
+         * @category constructors
+         */
         new (): Service<Self, Id, A, E>;
     }
 }
 /**
- * Extract the success type from an Fx.
+ * Alias of `Fx.Success` for extracting an `Fx` value channel.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The top-level alias supports type-only imports without requiring namespace syntax.
+ *
+ * ## Ownership and lifetime
+ *
+ * This type alias performs no runtime work.
  * @since 1.0.0
- * @category type-level
+ * @category Type contracts
  */
 export type Success<T> = Fx.Success<T>;
 /**
- * Extract the error type from an Fx.
+ * Alias of `Fx.Error` for extracting an `Fx` error channel.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The top-level alias supports type-only imports without requiring namespace syntax.
+ *
+ * ## Ownership and lifetime
+ *
+ * This type alias performs no runtime work.
  * @since 1.0.0
- * @category type-level
+ * @category Type contracts
  */
 export type Error<T> = Fx.Error<T>;
 /**
- * Extract the required services from an Fx.
+ * Alias of `Fx.Services` for extracting an `Fx` service channel.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The top-level alias supports type-only imports without requiring namespace syntax.
+ *
+ * ## Ownership and lifetime
+ *
+ * This type alias performs no runtime work.
  * @since 1.0.0
- * @category type-level
+ * @category Type contracts
  */
 export type Services<T> = Fx.Services<T>;
+/**
+ * Defines an Effect service whose value is also a directly runnable `Fx`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Applications often need a producer selected by the Effect environment: a clock,
+ * event source, transport, or domain feed. `Service` keeps that dependency in `R`
+ * and provides the corresponding layer constructor without a parallel wrapper API.
+ *
+ * ## Ownership and lifetime
+ *
+ * Defining the class starts no work. `Class.make` acquires the producer when its layer
+ * is built, supplies the acquisition context to it, and binds its lifetime to the
+ * layer scope. Running the class reads the currently installed implementation.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Layer } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * class Ticks extends Fx.Service<Ticks, number>()("app/Ticks") {}
+ *
+ * const TicksLive = Ticks.make(Fx.succeed(1))
+ * const values = Fx.collectAll(Ticks).pipe(Effect.provide(TicksLive))
+ * const program = Effect.map(values, (items) => items[0])
+ * ```
+ *
+ * @since 1.0.0
+ * @category Providing services
+ */
 export declare function Service<Self, A, E = never>(): <const Id extends string>(id: Id) => Fx.Class<Self, Id, A, E>;
 //# sourceMappingURL=Fx.d.ts.map