effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/reactivity/AtomHttpApi.ts

@@ -1,4 +1,31 @@
 /**
+ * The `AtomHttpApi` module adapts typed `HttpApi` clients to the unstable atom
+ * reactivity runtime. Use it to define a `Context.Service` whose generated HTTP
+ * API client is available directly and whose endpoints can also be invoked as
+ * atoms: `query` creates an atom of `AsyncResult` for reads, while `mutation`
+ * creates an `AtomResultFn` for writes.
+ *
+ * It is intended for applications that want server state to participate in atom
+ * caching, invalidation, and hydration. Queries can be associated with
+ * `reactivityKeys` so they refresh when those keys are invalidated, mutations can
+ * invalidate the same keys after the request succeeds, and `timeToLive` controls
+ * whether idle query atoms expire, stay alive for a duration, or are kept alive.
+ *
+ * Serialization is schema-based and intentionally limited to decoded values.
+ * Mutation atoms are serializable only in `"decoded-only"` mode, while query
+ * atoms are serializable only in `"decoded-only"` mode when a stable
+ * `serializationKey` is supplied. Choose serialization keys that uniquely
+ * identify the endpoint request, keep reactivity keys stable across client and
+ * server registries during hydration, and avoid serializing response modes that
+ * expose raw `HttpClientResponse` values.
+ *
+ * The service wraps `HttpApiClient.make`, so the same `HttpApi` definition,
+ * schemas, base URL, middleware services, and HTTP client layer must be available
+ * wherever the atom runtime is constructed. Use `transformClient` and
+ * `transformResponse` for cross-cutting client behavior, and remember that
+ * schema or low-level HTTP client failures are raised as defects while endpoint
+ * and middleware failures remain typed errors.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -22,8 +49,13 @@ import * as Atom from "./Atom.ts"
 import * as Reactivity from "./Reactivity.ts"
 
 /**
+ * A `Context.Service` for an HTTP API client integrated with atom reactivity.
+ *
+ * It exposes the generated HTTP API client, an atom runtime, mutation helpers that
+ * return `AtomResultFn`s, and query helpers that return atoms of endpoint results.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface AtomHttpApiClient<Self, Id extends string, Groups extends HttpApiGroup.Any>
   extends Context.Service<Self, HttpApiClient.Client<Groups, never, never>>
@@ -139,8 +171,15 @@ declare global {
 }
 
 /**
+ * Creates a `Context.Service` class for an HTTP API client backed by an atom
+ * runtime.
+ *
+ * The options provide the API definition, HTTP client layer, optional client and
+ * response transforms, base URL, and runtime factory used by the query and
+ * mutation helpers.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const Service = <Self>() =>
 <const Id extends string, ApiId extends string, Groups extends HttpApiGroup.Any>(

package/src/unstable/reactivity/AtomRef.ts

@@ -1,24 +1,51 @@
 /**
+ * Mutable reactive references for local, in-memory state that should be read,
+ * updated, and observed without going through an `AtomRegistry`.
+ *
+ * `AtomRef` is useful for small state models, form-like state, and collections
+ * of item references where callers need direct mutation methods together with
+ * subscriptions. A ref exposes its current `value`, notifies subscribers after
+ * `set` or `update`, can derive read-only views with `map`, and can focus on
+ * nested object or array properties with `prop`.
+ *
+ * Notifications are equality-aware: setting a value that is `Equal.equals` to
+ * the current value is ignored, and mapped or property subscriptions only emit
+ * when their derived value changes. Mutate state through `set`, `update`, or a
+ * property ref so subscribers are notified; direct mutation of the stored value
+ * does not notify listeners. Collection subscribers are notified when items are
+ * inserted, removed, or when an item ref changes, while `toArray` returns the
+ * current raw item values.
+ *
  * @since 4.0.0
  */
 import * as Equal from "../../Equal.ts"
 import * as Hash from "../../Hash.ts"
 
 /**
+ * The literal type used to identify `AtomRef` values.
+ *
+ * @category type IDs
  * @since 4.0.0
- * @category type ids
  */
 export type TypeId = "~effect/reactivity/AtomRef"
 
 /**
+ * The runtime type id used to identify `AtomRef` values.
+ *
+ * @category type IDs
  * @since 4.0.0
- * @category type ids
  */
 export const TypeId: TypeId = "~effect/reactivity/AtomRef"
 
 /**
- * @since 4.0.0
+ * A read-only reactive reference.
+ *
+ * It exposes a stable key, the current value, subscriptions to value changes, and
+ * `map` for creating derived read-only references. Equality and hashing are based
+ * on the current value.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface ReadonlyRef<A> extends Equal.Equal {
   readonly [TypeId]: TypeId
@@ -29,8 +56,13 @@ export interface ReadonlyRef<A> extends Equal.Equal {
 }
 
 /**
- * @since 4.0.0
+ * A mutable reactive reference.
+ *
+ * It supports replacing the whole value, updating it from the current value, and
+ * creating mutable references to nested properties.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface AtomRef<A> extends ReadonlyRef<A> {
   readonly prop: <K extends keyof A>(prop: K) => AtomRef<A[K]>
@@ -39,8 +71,13 @@ export interface AtomRef<A> extends ReadonlyRef<A> {
 }
 
 /**
- * @since 4.0.0
+ * A reactive collection of mutable item references.
+ *
+ * The collection can push, insert, and remove item refs, and `toArray` returns the
+ * current raw item values.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Collection<A> extends ReadonlyRef<ReadonlyArray<AtomRef<A>>> {
   readonly push: (item: A) => Collection<A>
@@ -50,14 +87,21 @@ export interface Collection<A> extends ReadonlyRef<ReadonlyArray<AtomRef<A>>> {
 }
 
 /**
- * @since 4.0.0
+ * Creates a mutable reactive reference initialized with the supplied value.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <A>(value: A): AtomRef<A> => new AtomRefImpl(value)
 
 /**
- * @since 4.0.0
+ * Creates a reactive collection from an iterable of initial item values.
+ *
+ * Each item is wrapped in an `AtomRef`, and changes to item refs notify the
+ * collection subscribers.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const collection = <A>(items: Iterable<A>): Collection<A> => new CollectionImpl(items)
 

package/src/unstable/reactivity/AtomRegistry.ts

@@ -1,4 +1,23 @@
 /**
+ * The `AtomRegistry` module provides the runtime cache used by reactivity
+ * atoms. A registry owns the node graph for a group of atoms, stores their
+ * current values, records parent/child dependencies while atoms are read, and
+ * coordinates writes, refreshes, stream conversions, and node disposal.
+ *
+ * Create a registry directly with {@link make} or provide it with {@link layer}
+ * or {@link layerOptions} when a UI root, request, test, or other Effect scope
+ * needs its own atom state. The same atom can have different cached values in
+ * different registries, while serializable atoms are keyed by their
+ * serialization key so preloaded values can hydrate a node before its first
+ * read.
+ *
+ * Subscriptions and {@link mount} keep nodes alive and must be released when
+ * the consumer is done; scoped helpers install finalizers for this. Unobserved
+ * non-`keepAlive` atoms may be removed immediately or after their `idleTTL` (or
+ * the registry `defaultIdleTTL`), which means later reads can rebuild derived
+ * state. Disposing a registry clears its cache and makes future atom access an
+ * error.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -18,26 +37,38 @@ import * as Result from "./AsyncResult.ts"
 import type * as Atom from "./Atom.ts"
 
 /**
+ * The literal type used to identify `AtomRegistry` services and values.
+ *
+ * @category type IDs
  * @since 4.0.0
- * @category type ids
  */
 export type TypeId = "~effect/reactivity/AtomRegistry"
 
 /**
+ * The runtime type id used to identify `AtomRegistry` services and values.
+ *
+ * @category type IDs
  * @since 4.0.0
- * @category type ids
  */
 export const TypeId: TypeId = "~effect/reactivity/AtomRegistry"
 
 /**
- * @since 4.0.0
+ * Returns `true` when the value has the `AtomRegistry` type id.
+ *
  * @category guards
+ * @since 4.0.0
  */
 export const isAtomRegistry = (u: unknown): u is AtomRegistry => hasProperty(u, TypeId)
 
 /**
- * @since 4.0.0
+ * The runtime registry that stores atom nodes and coordinates reads, writes,
+ * refreshes, subscriptions, and disposal.
+ *
+ * It also manages scheduler configuration, serializable preloaded values, and node
+ * addition/removal callbacks.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface AtomRegistry {
   readonly [TypeId]: TypeId
@@ -61,8 +92,13 @@ export interface AtomRegistry {
 }
 
 /**
- * @since 4.0.0
+ * A registry node for a single atom.
+ *
+ * Nodes expose the current value, parent and child dependency links, listener set,
+ * and current lifecycle state.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Node<A> {
   readonly atom: Atom.Atom<A>
@@ -74,8 +110,14 @@ export interface Node<A> {
 }
 
 /**
- * @since 4.0.0
+ * Creates an `AtomRegistry`.
+ *
+ * Options can preload initial atom values, provide a custom task scheduler,
+ * configure timeout bucket resolution, and set a default idle time-to-live for
+ * unused atoms.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (
   options?: {
@@ -93,14 +135,21 @@ export const make = (
   )
 
 /**
- * @since 4.0.0
+ * The `Context` service tag for the current `AtomRegistry`.
+ *
  * @category Tags
+ * @since 4.0.0
  */
 export const AtomRegistry = Context.Service<AtomRegistry>(TypeId)
 
 /**
+ * Creates a layer that provides an `AtomRegistry` configured with the supplied
+ * options.
+ *
+ * The registry is disposed when the layer scope is finalized.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layerOptions = (options?: {
   readonly initialValues?: Iterable<readonly [Atom.Atom<any>, any]> | undefined
@@ -122,8 +171,10 @@ export const layerOptions = (options?: {
   )
 
 /**
+ * The default layer that provides a fresh `AtomRegistry`.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layer: Layer.Layer<AtomRegistry> = layerOptions()
 
@@ -132,8 +183,13 @@ export const layer: Layer.Layer<AtomRegistry> = layerOptions()
 // -----------------------------------------------------------------------------
 
 /**
+ * Converts an atom in this registry into a stream.
+ *
+ * The stream emits the current value immediately, emits subsequent changes, and
+ * unsubscribes from the registry when the stream scope closes.
+ *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export const toStream: {
   // -----------------------------------------------------------------------------
@@ -141,8 +197,13 @@ export const toStream: {
   // -----------------------------------------------------------------------------
 
   /**
+   * Converts an atom in this registry into a stream.
+   *
+   * The stream emits the current value immediately, emits subsequent changes, and
+   * unsubscribes from the registry when the stream scope closes.
+   *
+   * @category converting
    * @since 4.0.0
-   * @category Conversions
    */
   <A>(atom: Atom.Atom<A>): (self: AtomRegistry) => Stream.Stream<A>
   // -----------------------------------------------------------------------------
@@ -150,8 +211,13 @@ export const toStream: {
   // -----------------------------------------------------------------------------
 
   /**
+   * Converts an atom in this registry into a stream.
+   *
+   * The stream emits the current value immediately, emits subsequent changes, and
+   * unsubscribes from the registry when the stream scope closes.
+   *
+   * @category converting
    * @since 4.0.0
-   * @category Conversions
    */
   <A>(self: AtomRegistry, atom: Atom.Atom<A>): Stream.Stream<A>
 } = dual(
@@ -162,8 +228,13 @@ export const toStream: {
     // -----------------------------------------------------------------------------
 
     /**
+     * Converts an atom in this registry into a stream.
+     *
+     * The stream emits the current value immediately, emits subsequent changes, and
+     * unsubscribes from the registry when the stream scope closes.
+     *
+     * @category converting
      * @since 4.0.0
-     * @category Conversions
      */
     A>((queue) =>
       Effect.suspend(() => {
@@ -178,18 +249,36 @@ export const toStream: {
 )
 
 /**
+ * Converts an `AsyncResult` atom in this registry into a stream of successful
+ * values.
+ *
+ * Initial results are skipped, failures fail the stream with their cause, and
+ * duplicate stream values are dropped with `Stream.changes`.
+ *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export const toStreamResult: {
   /**
+   * Converts an `AsyncResult` atom in this registry into a stream of successful
+   * values.
+   *
+   * Initial results are skipped, failures fail the stream with their cause, and
+   * duplicate stream values are dropped with `Stream.changes`.
+   *
+   * @category converting
    * @since 4.0.0
-   * @category Conversions
    */
   <A, E>(atom: Atom.Atom<Result.AsyncResult<A, E>>): (self: AtomRegistry) => Stream.Stream<A, E>
   /**
+   * Converts an `AsyncResult` atom in this registry into a stream of successful
+   * values.
+   *
+   * Initial results are skipped, failures fail the stream with their cause, and
+   * duplicate stream values are dropped with `Stream.changes`.
+   *
+   * @category converting
    * @since 4.0.0
-   * @category Conversions
    */
   <A, E>(self: AtomRegistry, atom: Atom.Atom<Result.AsyncResult<A, E>>): Stream.Stream<A, E>
 } = dual(
@@ -205,13 +294,23 @@ export const toStreamResult: {
 )
 
 /**
+ * Reads an `AsyncResult` atom from this registry as an effect.
+ *
+ * The effect waits for the result to leave `Initial`, and also waits through
+ * waiting results when `suspendOnWaiting` is enabled.
+ *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export const getResult: {
   /**
+   * Reads an `AsyncResult` atom from this registry as an effect.
+   *
+   * The effect waits for the result to leave `Initial`, and also waits through
+   * waiting results when `suspendOnWaiting` is enabled.
+   *
+   * @category converting
    * @since 4.0.0
-   * @category Conversions
    */
   <A, E>(
     atom: Atom.Atom<Result.AsyncResult<A, E>>,
@@ -220,8 +319,13 @@ export const getResult: {
     }
   ): (self: AtomRegistry) => Effect.Effect<A, E>
   /**
+   * Reads an `AsyncResult` atom from this registry as an effect.
+   *
+   * The effect waits for the result to leave `Initial`, and also waits through
+   * waiting results when `suspendOnWaiting` is enabled.
+   *
+   * @category converting
    * @since 4.0.0
-   * @category Conversions
    */
   <A, E>(
     self: AtomRegistry,
@@ -253,18 +357,33 @@ export const getResult: {
 )
 
 /**
+ * Mounts an atom in this registry for the lifetime of the current scope.
+ *
+ * The atom is subscribed with a no-op listener and the subscription is released
+ * when the scope finalizer runs.
+ *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export const mount: {
   /**
+   * Mounts an atom in this registry for the lifetime of the current scope.
+   *
+   * The atom is subscribed with a no-op listener and the subscription is released
+   * when the scope finalizer runs.
+   *
+   * @category converting
    * @since 4.0.0
-   * @category Conversions
    */
   <A>(atom: Atom.Atom<A>): (self: AtomRegistry) => Effect.Effect<void, never, Scope.Scope>
   /**
+   * Mounts an atom in this registry for the lifetime of the current scope.
+   *
+   * The atom is subscribed with a no-op listener and the subscription is released
+   * when the scope finalizer runs.
+   *
+   * @category converting
    * @since 4.0.0
-   * @category Conversions
    */
   <A>(self: AtomRegistry, atom: Atom.Atom<A>): Effect.Effect<void, never, Scope.Scope>
 } = dual(

package/src/unstable/reactivity/AtomRpc.ts

@@ -1,4 +1,26 @@
 /**
+ * The `AtomRpc` module connects typed RPC clients to the atom reactivity
+ * runtime. It builds a `Context.Service` that exposes the flattened
+ * `RpcClient`, an `AtomRuntime`, mutation helpers, and query helpers for every
+ * RPC in an `RpcGroup`.
+ *
+ * Use it when remote read models should be represented as atoms, mutations
+ * should refresh affected reads through `Reactivity` keys, or non-streaming
+ * query results need serialization metadata for hydration. The RPC `protocol`
+ * layer supplies the transport, and may be static or derived from the current
+ * atom context, so request headers, transport dependencies, and client
+ * middleware remain part of the normal Effect environment.
+ *
+ * Non-streaming queries produce atoms of `AsyncResult` values. Supplying a
+ * `serializationKey` marks those query atoms as serializable using codecs
+ * derived from the RPC success schema and the combined RPC, middleware, and
+ * client error schemas; choose stable, unique keys when dehydrating. Streaming
+ * RPCs produce writable pull atoms instead, so callers advance the stream by
+ * writing to the atom and should not expect serialization metadata. Query family
+ * caching includes the payload, normalized headers, reactivity keys, TTL, and
+ * serialization key, so use stable values for those inputs when atom identity
+ * matters.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -22,8 +44,14 @@ import * as Atom from "./Atom.ts"
 import * as Reactivity from "./Reactivity.ts"
 
 /**
+ * A `Context.Service` for a flattened RPC client integrated with atom reactivity.
+ *
+ * It exposes the RPC client, an atom runtime, mutation helpers that return
+ * `AtomResultFn`s, and query helpers that return atoms or pull atoms for RPC
+ * results.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface AtomRpcClient<Self, Id extends string, Rpcs extends Rpc.Any> extends
   Context.Service<
@@ -103,8 +131,14 @@ declare global {
 }
 
 /**
+ * Creates a `Context.Service` class for an RPC client backed by an atom runtime.
+ *
+ * The options provide the RPC group, protocol layer, tracing options, request id
+ * generation, optional custom client effect, and runtime factory used by the query
+ * and mutation helpers.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const Service = <Self>() =>
 <

package/src/unstable/reactivity/Hydration.ts

@@ -1,4 +1,21 @@
 /**
+ * Utilities for moving serializable reactivity state between atom registries.
+ *
+ * `dehydrate` snapshots atoms marked with `Atom.serializable` from an
+ * `AtomRegistry`, preserving their serialization keys, encoded values, and
+ * dehydration time so another registry can preload the same state with `hydrate`.
+ * This is useful for server rendering, browser bootstrapping, route transitions,
+ * and other handoffs where a registry should start from values that were already
+ * computed elsewhere.
+ *
+ * Only serializable atoms are included, and the receiving registry needs atoms
+ * with matching stable keys and compatible schemas. Values crossing a
+ * client/server boundary should be the encoded JSON-safe values produced by the
+ * atom codecs. The optional `resultPromise` used for `AsyncResult.Initial`
+ * handoffs is a live JavaScript promise, so it cannot be sent through JSON and
+ * should be omitted or replaced by an application-level streaming protocol when
+ * dehydrated state leaves the current runtime.
+ *
  * @since 4.0.0
  */
 import * as AsyncResult from "./AsyncResult.ts"
@@ -6,16 +23,24 @@ import * as Atom from "./Atom.ts"
 import type * as AtomRegistry from "./AtomRegistry.ts"
 
 /**
- * @since 4.0.0
+ * Marker interface for entries in a dehydrated atom registry state.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface DehydratedAtom {
   readonly "~effect/reactivity/DehydratedAtom": true
 }
 
 /**
- * @since 4.0.0
+ * A dehydrated serializable atom value.
+ *
+ * It stores the atom serialization key, encoded value, dehydration timestamp, and
+ * an optional promise used when an `AsyncResult.Initial` value is encoded as a
+ * future non-initial value.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface DehydratedAtomValue extends DehydratedAtom {
   readonly key: string
@@ -25,8 +50,15 @@ export interface DehydratedAtomValue extends DehydratedAtom {
 }
 
 /**
- * @since 4.0.0
+ * Encodes the serializable atoms currently stored in a registry into dehydrated
+ * state.
+ *
+ * Only atoms marked with `Atom.serializable` are included. `encodeInitialAs`
+ * controls whether `AsyncResult.Initial` values are ignored, encoded as values, or
+ * represented by promises that resolve when the atom leaves the initial state.
+ *
  * @category dehydration
+ * @since 4.0.0
  */
 export const dehydrate = (
   registry: AtomRegistry.AtomRegistry,
@@ -73,14 +105,22 @@ export const dehydrate = (
 }
 
 /**
- * @since 4.0.0
+ * Returns dehydrated state entries as `DehydratedAtomValue` records.
+ *
  * @category dehydration
+ * @since 4.0.0
  */
 export const toValues = (state: ReadonlyArray<DehydratedAtom>): Array<DehydratedAtomValue> => state as any
 
 /**
- * @since 4.0.0
+ * Loads dehydrated atom state into a registry.
+ *
+ * Encoded values are preloaded by serialization key. Entries with a
+ * `resultPromise` update the matching registry node, or preload the resolved value,
+ * when the promise resolves.
+ *
  * @category hydration
+ * @since 4.0.0
  */
 export const hydrate = (
   registry: AtomRegistry.AtomRegistry,