effect 4.0.0-beta.71 → 4.0.0-beta.72

package/src/unstable/process/ChildProcessSpawner.ts

@@ -37,7 +37,7 @@ import type { Command, KillOptions } from "./ChildProcess.ts"
 export type ExitCode = Brand.Branded<number, "ExitCode">
 
 /**
- * Brand constructor for child process `ExitCode` values.
+ * Constructs branded child process `ExitCode` values.
  *
  * @category constructors
  * @since 4.0.0
@@ -54,7 +54,7 @@ export const ExitCode: Brand.Constructor<ExitCode> = Brand.nominal<ExitCode>()
 export type ProcessId = Brand.Branded<number, "ProcessId">
 
 /**
- * Brand constructor for child process `ProcessId` values.
+ * Constructs branded child process `ProcessId` values.
  *
  * @category constructors
  * @since 4.0.0

package/src/unstable/reactivity/AsyncResult.ts

@@ -422,9 +422,10 @@ export const touch = <A extends AsyncResult<any, any>>(result: A): A => {
 }
 
 /**
- * For a `Failure`, replaces its stored previous success with the latest success found in another result; non-failures are returned unchanged.
+ * Replaces a `Failure` value's stored previous success with the latest success
+ * found in another result.
  *
- * @category constructors
+ * @category combinators
  * @since 4.0.0
  */
 export const replacePrevious = <R extends AsyncResult<any, any>, XE, A>(
@@ -560,21 +561,51 @@ export const map: {
 })
 
 /**
- * Flat maps a success result with a function returning another `AsyncResult`, leaves initial results unchanged, and preserves failure causes while remapping stored previous successes when possible.
+ * Maps the success value of an `AsyncResult` and flattens the result.
+ *
+ * **When to use**
+ *
+ * Use to sequence computations that may return another `AsyncResult` while
+ * preserving initial and failure states.
+ *
+ * **Details**
+ *
+ * Initial results are left unchanged. Failures preserve their cause and remap
+ * the stored previous success when the mapping function returns a success.
  *
  * @category combinators
  * @since 4.0.0
  */
 export const flatMap: {
   /**
-   * Flat maps a success result with a function returning another `AsyncResult`, leaves initial results unchanged, and preserves failure causes while remapping stored previous successes when possible.
+   * Maps the success value of an `AsyncResult` and flattens the result.
+   *
+   * **When to use**
+   *
+   * Use to sequence computations that may return another `AsyncResult` while
+   * preserving initial and failure states.
+   *
+   * **Details**
+   *
+   * Initial results are left unchanged. Failures preserve their cause and remap
+   * the stored previous success when the mapping function returns a success.
    *
    * @category combinators
    * @since 4.0.0
    */
   <A, E, B, E2>(f: (a: A, prev: Success<A, E>) => AsyncResult<A, E2>): (self: AsyncResult<A, E>) => AsyncResult<B, E | E2>
   /**
-   * Flat maps a success result with a function returning another `AsyncResult`, leaves initial results unchanged, and preserves failure causes while remapping stored previous successes when possible.
+   * Maps the success value of an `AsyncResult` and flattens the result.
+   *
+   * **When to use**
+   *
+   * Use to sequence computations that may return another `AsyncResult` while
+   * preserving initial and failure states.
+   *
+   * **Details**
+   *
+   * Initial results are left unchanged. Failures preserve their cause and remap
+   * the stored previous success when the mapping function returns a success.
    *
    * @category combinators
    * @since 4.0.0
@@ -594,13 +625,33 @@ export const flatMap: {
         return self as any as AsyncResult<B, E>
       case "Failure":
         return failure</**
-         * Flat maps a success result with a function returning another `AsyncResult`, leaves initial results unchanged, and preserves failure causes while remapping stored previous successes when possible.
+         * Maps the success value of an `AsyncResult` and flattens the result.
+         *
+         * **When to use**
+         *
+         * Use to sequence computations that may return another `AsyncResult` while
+         * preserving initial and failure states.
+         *
+         * **Details**
+         *
+         * Initial results are left unchanged. Failures preserve their cause and remap
+         * the stored previous success when the mapping function returns a success.
          *
          * @category combinators
          * @since 4.0.0
          */
         B, /**
-         * Flat maps a success result with a function returning another `AsyncResult`, leaves initial results unchanged, and preserves failure causes while remapping stored previous successes when possible.
+         * Maps the success value of an `AsyncResult` and flattens the result.
+         *
+         * **When to use**
+         *
+         * Use to sequence computations that may return another `AsyncResult` while
+         * preserving initial and failure states.
+         *
+         * **Details**
+         *
+         * Initial results are left unchanged. Failures preserve their cause and remap
+         * the stored previous success when the mapping function returns a success.
          *
          * @category combinators
          * @since 4.0.0

package/src/unstable/reactivity/Atom.ts

@@ -917,10 +917,15 @@ export const defaultMemoMap: Layer.MemoMap = Layer.makeMemoMapUnsafe()
 export const runtime: RuntimeFactory = context({ memoMap: defaultMemoMap })
 
 /**
- * An alias to `Rx.runtime.withReactivity`, for refreshing an atom whenever the
+ * Returns `Rx.runtime.withReactivity` for refreshing an atom whenever the
  * keys change in the `Reactivity` service.
  *
- * @category Reactivity
+ * **When to use**
+ *
+ * Use to refresh an atom whenever one or more invalidation keys change in the
+ * default reactivity runtime.
+ *
+ * @category reactivity
  * @since 4.0.0
  */
 export const withReactivity: (
@@ -1237,7 +1242,12 @@ export interface AtomResultFn<Arg, A, E = never>
 {}
 
 /**
- * Control symbol that can be written to an `AtomResultFn` to reset it to its initial state.
+ * Defines the control symbol that can be written to an `AtomResultFn` to reset it to its initial state.
+ *
+ * **When to use**
+ *
+ * Use to write to an `AtomResultFn` when you need to clear the current async
+ * result and return it to the initial state.
  *
  * @category symbols
  * @since 4.0.0
@@ -1253,7 +1263,12 @@ export const Reset = Symbol.for("effect/reactivity/atom/Atom/Reset")
 export type Reset = typeof Reset
 
 /**
- * Control symbol that can be written to an `AtomResultFn` to interrupt the current asynchronous computation.
+ * Defines the control symbol that can be written to an `AtomResultFn` to interrupt the current asynchronous computation.
+ *
+ * **When to use**
+ *
+ * Use to write to an `AtomResultFn` when you need to interrupt the currently
+ * running async computation.
  *
  * @category symbols
  * @since 4.0.0
@@ -1658,7 +1673,7 @@ export const keepAlive = <A extends Atom<any>>(self: A): A =>
   })
 
 /**
- * Reverts the `keepAlive` behavior of a reactive value, allowing it to be disposed of when not in use.
+ * Allows a reactive value to be disposed of when it is not in use.
  *
  * **Details**
  *
@@ -1785,6 +1800,10 @@ export const withLabel: {
 /**
  * Pairs an atom with an initial value for registry initialization.
  *
+ * **When to use**
+ *
+ * Use to preload an atom value when constructing or seeding a registry.
+ *
  * **Details**
  *
  * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
@@ -1797,6 +1816,10 @@ export const initialValue: {
   /**
    * Pairs an atom with an initial value for registry initialization.
    *
+   * **When to use**
+   *
+   * Use to preload an atom value when constructing or seeding a registry.
+   *
    * **Details**
    *
    * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
@@ -1809,6 +1832,10 @@ export const initialValue: {
   /**
    * Pairs an atom with an initial value for registry initialization.
    *
+   * **When to use**
+   *
+   * Use to preload an atom value when constructing or seeding a registry.
+   *
    * **Details**
    *
    * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
@@ -1822,6 +1849,10 @@ export const initialValue: {
   /**
    * Pairs an atom with an initial value for registry initialization.
    *
+   * **When to use**
+   *
+   * Use to preload an atom value when constructing or seeding a registry.
+   *
    * **Details**
    *
    * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
@@ -1834,6 +1865,10 @@ export const initialValue: {
   /**
    * Pairs an atom with an initial value for registry initialization.
    *
+   * **When to use**
+   *
+   * Use to preload an atom value when constructing or seeding a registry.
+   *
    * **Details**
    *
    * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
@@ -2522,7 +2557,7 @@ export const batch: (f: () => void) => void = Registry.batch
 // -----------------------------------------------------------------------------
 
 /**
- * A browser-only signal atom that increments when the document becomes visible.
+ * Creates a browser-only signal atom that increments when the document becomes visible.
  *
  * **Details**
  *
@@ -2882,7 +2917,12 @@ export const getResult = <A, E>(
 ): Effect.Effect<A, E, AtomRegistry> => AtomRegistry.use(Registry.getResult(self, options))
 
 /**
- * Requests a refresh of an atom through the `AtomRegistry` service.
+ * Runs a refresh request for an atom through the `AtomRegistry` service.
+ *
+ * **When to use**
+ *
+ * Use to invalidate and recompute an atom from an Effect that has access to the
+ * active registry.
  *
  * @category converting
  * @since 4.0.0
@@ -2911,7 +2951,7 @@ export const mount = <A>(self: Atom<A>): Effect.Effect<void, never, AtomRegistry
 /**
  * The type id used to mark atoms that carry serialization metadata.
  *
- * @category Serializable
+ * @category type IDs
  * @since 4.0.0
  */
 export const SerializableTypeId: SerializableTypeId = "~effect-atom/atom/Atom/Serializable"
@@ -2919,7 +2959,7 @@ export const SerializableTypeId: SerializableTypeId = "~effect-atom/atom/Atom/Se
 /**
  * The literal type of the serializable atom marker.
  *
- * @category Serializable
+ * @category type IDs
  * @since 4.0.0
  */
 export type SerializableTypeId = "~effect-atom/atom/Atom/Serializable"
@@ -3017,27 +3057,27 @@ export const serializable: {
 /**
  * The type id used to mark atoms with a server-side read override.
  *
- * @category ServerValue
+ * @category type IDs
  * @since 4.0.0
  */
 export const ServerValueTypeId = "~effect-atom/atom/Atom/ServerValue" as const
 
 /**
- * Overrides the value of an Atom when read on the server.
+ * Sets the value of an Atom when read on the server.
  *
  * @category ServerValue
  * @since 4.0.0
  */
 export const withServerValue: {
   /**
-   * Overrides the value of an Atom when read on the server.
+   * Sets the value of an Atom when read on the server.
    *
    * @category ServerValue
    * @since 4.0.0
    */
   <A extends Atom<any>>(read: (get: <A>(atom: Atom<A>) => A) => Type<A>): (self: A) => A
   /**
-   * Overrides the value of an Atom when read on the server.
+   * Sets the value of an Atom when read on the server.
    *
    * @category ServerValue
    * @since 4.0.0

package/src/unstable/reactivity/AtomRegistry.ts

@@ -197,9 +197,14 @@ export const make = (
   )
 
 /**
- * The `Context` service tag for the current `AtomRegistry`.
+ * Service tag for the active atom runtime cache.
  *
- * @category Tags
+ * **When to use**
+ *
+ * Use to access or provide the registry that stores atom values,
+ * dependencies, subscriptions, and disposal state for a reactive lifetime.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export const AtomRegistry = Context.Service<AtomRegistry>(TypeId)

package/src/unstable/reactivity/Hydration.ts

@@ -132,7 +132,12 @@ export const dehydrate = (
 export const toValues = (state: ReadonlyArray<DehydratedAtom>): Array<DehydratedAtomValue> => state as any
 
 /**
- * Loads dehydrated atom state into a registry.
+ * Applies dehydrated atom state to a registry.
+ *
+ * **When to use**
+ *
+ * Use to preload serialized atom values into a target registry before those
+ * atoms are read.
  *
  * **Details**
  *

package/src/unstable/reactivity/Reactivity.ts

@@ -53,7 +53,12 @@ import * as Scope from "../../Scope.ts"
 import * as Stream from "../../Stream.ts"
 
 /**
- * A service for key-based reactive invalidation.
+ * Service for key-based reactive invalidation.
+ *
+ * **When to use**
+ *
+ * Use to provide the invalidation service that refreshes queries, streams, and
+ * atoms when application keys change.
  *
  * **Details**
  *

package/src/unstable/rpc/Rpc.ts

@@ -72,7 +72,7 @@ const TypeId = "~effect/rpc/Rpc"
 export const isRpc = (u: unknown): u is Rpc<any, any, any> => Predicate.hasProperty(u, TypeId)
 
 /**
- * A schema for RPC defects.
+ * Schema for RPC defects.
  *
  * **Details**
  *
@@ -202,7 +202,12 @@ export interface Rpc<
 }
 
 /**
- * Server-side metadata for the client associated with an RPC request.
+ * Represents server-side metadata for the client associated with an RPC request.
+ *
+ * **When to use**
+ *
+ * Use to inspect or annotate the connected client while handling an RPC request
+ * on the server.
  *
  * **Details**
  *
@@ -1184,7 +1189,7 @@ const WrapperTypeId = "~effect/rpc/Rpc/Wrapper"
  * `fork` requests concurrent execution, and `uninterruptible` requests
  * uninterruptible execution.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export interface Wrapper<A> {
@@ -1198,7 +1203,7 @@ export interface Wrapper<A> {
  * A value that may be returned directly or wrapped with RPC server execution
  * options.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export type WrapperOr<A> = A | Wrapper<A>
@@ -1206,7 +1211,7 @@ export type WrapperOr<A> = A | Wrapper<A>
 /**
  * Returns `true` when the value is an RPC `Wrapper`.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export const isWrapper = (u: object): u is Wrapper<any> => WrapperTypeId in u
@@ -1219,7 +1224,7 @@ export const isWrapper = (u: object): u is Wrapper<any> => WrapperTypeId in u
  * When the value is already wrapped, unspecified options are inherited from the
  * existing wrapper.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export const wrap = (options: {
@@ -1245,7 +1250,7 @@ export const wrap = (options: {
  * Returns the wrapped response value when the input is an RPC `Wrapper`, or the
  * input itself when it is already unwrapped.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export const unwrap = <A extends object>(value: WrapperOr<A>): A => isWrapper(value) ? value.value : value
@@ -1254,7 +1259,7 @@ export const unwrap = <A extends object>(value: WrapperOr<A>): A => isWrapper(va
  * Maps the value inside an RPC wrapper, preserving wrapper options such as
  * `fork` and `uninterruptible`; unwrapped values are mapped directly.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export const wrapMap = <A extends object, B extends object>(self: WrapperOr<A>, f: (value: A) => B): WrapperOr<B> => {
@@ -1265,19 +1270,18 @@ export const wrapMap = <A extends object, B extends object>(self: WrapperOr<A>,
 }
 
 /**
- * You can use `fork` to wrap a response Effect or Stream, to ensure that the
- * response is executed concurrently regardless of the RpcServer concurrency
- * setting.
+ * Wraps a response Effect or Stream so the RPC server executes it concurrently
+ * regardless of the server concurrency setting.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export const fork: <A extends object>(value: A) => Wrapper<A> = wrap({ fork: true })
 
 /**
- * You can use `uninterruptible` to wrap a response Effect or Stream, to ensure that it is run in an uninterruptible region.
+ * Wraps a response Effect or Stream so the RPC server runs it in an uninterruptible region.
  *
- * @category Wrapper
+ * @category wrapping
  * @since 4.0.0
  */
 export const uninterruptible: <A extends object>(value: A) => Wrapper<A> = wrap({ uninterruptible: true })

package/src/unstable/rpc/RpcClient.ts

@@ -824,9 +824,14 @@ const rpcSchemas = (rpc: Rpc.AnyWithProps) => {
 }
 
 /**
- * A fiber-local reference containing headers that are merged into outgoing RPC
+ * Fiber reference containing headers that are merged into outgoing RPC
  * client requests.
  *
+ * **When to use**
+ *
+ * Use to set request headers that should be automatically merged into outgoing
+ * RPC client messages.
+ *
  * @category headers
  * @since 4.0.0
  */
@@ -865,10 +870,15 @@ export const withHeaders: {
 )
 
 /**
- * Service interface for an RPC client transport, responsible for running the
+ * Defines the service interface for an RPC client transport, responsible for running the
  * receive loop and sending encoded client messages.
  *
- * @category protocol
+ * **When to use**
+ *
+ * Use to provide the transport boundary for RPC clients over HTTP, WebSocket,
+ * workers, sockets, or custom protocols.
+ *
+ * @category protocols
  * @since 4.0.0
  */
 export class Protocol extends Context.Service<Protocol, {
@@ -896,7 +906,7 @@ export class Protocol extends Context.Service<Protocol, {
  * Creates a client `Protocol` that sends each RPC request through the supplied
  * `HttpClient` and decodes responses with the current `RpcSerialization`.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const makeProtocolHttp = (client: HttpClient.HttpClient): Effect.Effect<
@@ -987,7 +997,7 @@ export const makeProtocolHttp = (client: HttpClient.HttpClient): Effect.Effect<
  * Provides a client `Protocol` backed by `HttpClient`, targeting the configured
  * URL and optionally transforming the client before use.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const layerProtocolHttp = (options: {
@@ -1009,7 +1019,7 @@ export const layerProtocolHttp = (options: {
  * `RpcSerialization`, connection hooks, ping timeouts, and the configured retry
  * policy.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const makeProtocolSocket = (options?: {
@@ -1176,7 +1186,7 @@ const makePinger = Effect.fnUntraced(function*<A, E, R>(writePing: Effect.Effect
  * Provides a client `Protocol` backed by the current `Socket` and
  * `RpcSerialization` services.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const layerProtocolSocket = (options?: {
@@ -1191,7 +1201,7 @@ export const layerProtocolSocket = (options?: {
  * Creates a client `Protocol` backed by a pool of workers, routing RPC requests
  * to workers and supporting transferable values when the platform does.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const makeProtocolWorker = (
@@ -1357,7 +1367,7 @@ export const makeProtocolWorker = (
  * Provides a client `Protocol` backed by a worker pool using the current worker
  * platform and spawner services.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export const layerProtocolWorker: (
@@ -1379,10 +1389,15 @@ export const layerProtocolWorker: (
 > = flow(makeProtocolWorker, Layer.effect(Protocol))
 
 /**
- * Optional client protocol hooks that run when a transport connects and
- * disconnects.
+ * Represents optional client protocol hooks that run when a transport connects
+ * and disconnects.
+ *
+ * **When to use**
+ *
+ * Use to run setup or cleanup effects when an RPC client transport opens or
+ * closes.
  *
- * @category ConnectionHooks
+ * @category connection hooks
  * @since 4.0.0
  */
 export class ConnectionHooks extends Context.Service<ConnectionHooks, {

package/src/unstable/rpc/RpcClientError.ts

@@ -52,8 +52,8 @@ export class RpcClientDefect extends Schema.ErrorClass<RpcClientDefect>("effect/
 }) {}
 
 /**
- * The public RPC client error type, wrapping worker, socket, HTTP client, and
- * client protocol defect failures.
+ * Error wrapper for RPC client failures, including worker, socket, HTTP client,
+ * and client protocol defect failures.
  *
  * @category errors
  * @since 4.0.0

package/src/unstable/rpc/RpcMessage.ts

@@ -182,7 +182,7 @@ export interface Ping {
 }
 
 /**
- * The reusable `Eof` message value.
+ * Represents the reusable `Eof` message value.
  *
  * @category request
  * @since 4.0.0
@@ -190,7 +190,7 @@ export interface Ping {
 export const constEof: Eof = { _tag: "Eof" }
 
 /**
- * The reusable `Ping` message value.
+ * Represents the reusable `Ping` message value.
  *
  * @category request
  * @since 4.0.0
@@ -225,7 +225,7 @@ export type FromServerEncoded =
 /**
  * The brand identifier used by the `ResponseId` type.
  *
- * @category response
+ * @category type IDs
  * @since 4.0.0
  */
 export const ResponseIdTypeId = "~effect//rpc/RpcServer/ResponseId"
@@ -233,7 +233,7 @@ export const ResponseIdTypeId = "~effect//rpc/RpcServer/ResponseId"
 /**
  * The literal type of the `ResponseId` brand identifier.
  *
- * @category response
+ * @category type IDs
  * @since 4.0.0
  */
 export type ResponseIdTypeId = typeof ResponseIdTypeId
@@ -420,7 +420,7 @@ export interface Pong {
 }
 
 /**
- * The reusable `Pong` message value.
+ * Represents the reusable `Pong` message value.
  *
  * @category response
  * @since 4.0.0

package/src/unstable/rpc/RpcSchema.ts

@@ -105,7 +105,7 @@ export function Stream<A extends Schema.Top, E extends Schema.Top>(success: A, e
 }
 
 /**
- * Cause annotation used to mark interruptions that originate from an RPC client
+ * Annotation that marks interruptions that originate from an RPC client
  * abort.
  *
  * @category Cause annotations