effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/unstable/reactivity/AtomRegistry.ts

@@ -64,6 +64,8 @@ export const isAtomRegistry = (u: unknown): u is AtomRegistry => hasProperty(u,
  * The runtime registry that stores atom nodes and coordinates reads, writes,
  * refreshes, subscriptions, and disposal.
  *
+ * **Details**
+ *
  * It also manages scheduler configuration, serializable preloaded values, and node
  * addition/removal callbacks.
  *
@@ -94,6 +96,8 @@ export interface AtomRegistry {
 /**
  * A registry node for a single atom.
  *
+ * **Details**
+ *
  * Nodes expose the current value, parent and child dependency links, listener set,
  * and current lifecycle state.
  *
@@ -112,6 +116,8 @@ export interface Node<A> {
 /**
  * Creates an `AtomRegistry`.
  *
+ * **Details**
+ *
  * 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.
@@ -146,6 +152,8 @@ export const AtomRegistry = Context.Service<AtomRegistry>(TypeId)
  * Creates a layer that provides an `AtomRegistry` configured with the supplied
  * options.
  *
+ * **Details**
+ *
  * The registry is disposed when the layer scope is finalized.
  *
  * @category layers
@@ -185,6 +193,8 @@ export const layer: Layer.Layer<AtomRegistry> = layerOptions()
 /**
  * Converts an atom in this registry into a stream.
  *
+ * **Details**
+ *
  * The stream emits the current value immediately, emits subsequent changes, and
  * unsubscribes from the registry when the stream scope closes.
  *
@@ -199,6 +209,8 @@ export const toStream: {
   /**
    * Converts an atom in this registry into a stream.
    *
+   * **Details**
+   *
    * The stream emits the current value immediately, emits subsequent changes, and
    * unsubscribes from the registry when the stream scope closes.
    *
@@ -213,6 +225,8 @@ export const toStream: {
   /**
    * Converts an atom in this registry into a stream.
    *
+   * **Details**
+   *
    * The stream emits the current value immediately, emits subsequent changes, and
    * unsubscribes from the registry when the stream scope closes.
    *
@@ -230,6 +244,8 @@ export const toStream: {
     /**
      * Converts an atom in this registry into a stream.
      *
+     * **Details**
+     *
      * The stream emits the current value immediately, emits subsequent changes, and
      * unsubscribes from the registry when the stream scope closes.
      *
@@ -252,6 +268,8 @@ export const toStream: {
  * Converts an `AsyncResult` atom in this registry into a stream of successful
  * values.
  *
+ * **Details**
+ *
  * Initial results are skipped, failures fail the stream with their cause, and
  * duplicate stream values are dropped with `Stream.changes`.
  *
@@ -263,6 +281,8 @@ export const toStreamResult: {
    * Converts an `AsyncResult` atom in this registry into a stream of successful
    * values.
    *
+   * **Details**
+   *
    * Initial results are skipped, failures fail the stream with their cause, and
    * duplicate stream values are dropped with `Stream.changes`.
    *
@@ -274,6 +294,8 @@ export const toStreamResult: {
    * Converts an `AsyncResult` atom in this registry into a stream of successful
    * values.
    *
+   * **Details**
+   *
    * Initial results are skipped, failures fail the stream with their cause, and
    * duplicate stream values are dropped with `Stream.changes`.
    *
@@ -296,6 +318,8 @@ export const toStreamResult: {
 /**
  * Reads an `AsyncResult` atom from this registry as an effect.
  *
+ * **Details**
+ *
  * The effect waits for the result to leave `Initial`, and also waits through
  * waiting results when `suspendOnWaiting` is enabled.
  *
@@ -306,6 +330,8 @@ export const getResult: {
   /**
    * Reads an `AsyncResult` atom from this registry as an effect.
    *
+   * **Details**
+   *
    * The effect waits for the result to leave `Initial`, and also waits through
    * waiting results when `suspendOnWaiting` is enabled.
    *
@@ -321,6 +347,8 @@ export const getResult: {
   /**
    * Reads an `AsyncResult` atom from this registry as an effect.
    *
+   * **Details**
+   *
    * The effect waits for the result to leave `Initial`, and also waits through
    * waiting results when `suspendOnWaiting` is enabled.
    *
@@ -359,6 +387,8 @@ export const getResult: {
 /**
  * Mounts an atom in this registry for the lifetime of the current scope.
  *
+ * **Details**
+ *
  * The atom is subscribed with a no-op listener and the subscription is released
  * when the scope finalizer runs.
  *
@@ -369,6 +399,8 @@ export const mount: {
   /**
    * Mounts an atom in this registry for the lifetime of the current scope.
    *
+   * **Details**
+   *
    * The atom is subscribed with a no-op listener and the subscription is released
    * when the scope finalizer runs.
    *
@@ -379,6 +411,8 @@ export const mount: {
   /**
    * Mounts an atom in this registry for the lifetime of the current scope.
    *
+   * **Details**
+   *
    * The atom is subscribed with a no-op listener and the subscription is released
    * when the scope finalizer runs.
    *

package/src/unstable/reactivity/AtomRpc.ts

@@ -46,9 +46,10 @@ 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.
+ * **Details**
+ *
+ * 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
@@ -133,9 +134,10 @@ 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.
+ * **Details**
+ *
+ * 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

package/src/unstable/reactivity/Hydration.ts

@@ -35,6 +35,8 @@ export interface DehydratedAtom {
 /**
  * A dehydrated serializable atom value.
  *
+ * **Details**
+ *
  * 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.
@@ -53,6 +55,8 @@ export interface DehydratedAtomValue extends DehydratedAtom {
  * Encodes the serializable atoms currently stored in a registry into dehydrated
  * state.
  *
+ * **Details**
+ *
  * 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.
@@ -115,6 +119,8 @@ export const toValues = (state: ReadonlyArray<DehydratedAtom>): Array<Dehydrated
 /**
  * Loads dehydrated atom state into a registry.
  *
+ * **Details**
+ *
  * 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.

package/src/unstable/reactivity/Reactivity.ts

@@ -37,9 +37,11 @@ import * as Stream from "../../Stream.ts"
 /**
  * A service for key-based reactive invalidation.
  *
- * It can register handlers for keys, invalidate those keys, wrap mutations so
- * successful effects invalidate keys, and turn query effects into queues or
- * streams that rerun when keys are invalidated.
+ * **Details**
+ *
+ * The service can register handlers for keys, invalidate those keys, wrap
+ * mutations so successful effects invalidate keys, and turn query effects into
+ * queues or streams that rerun when keys are invalidated.
  *
  * @category tags
  * @since 4.0.0
@@ -74,6 +76,8 @@ export class Reactivity extends Context.Service<
 /**
  * Creates an in-memory `Reactivity` service.
  *
+ * **Details**
+ *
  * The service tracks handlers by hashed keys and runs the registered handlers when
  * matching keys are invalidated.
  *
@@ -222,6 +226,8 @@ class PendingInvalidation extends Context.Service<PendingInvalidation, Set<strin
 /**
  * Wraps an effect so the supplied keys are invalidated after the effect succeeds.
  *
+ * **Gotchas**
+ *
  * If the effect fails, the keys are not invalidated.
  *
  * @category accessors
@@ -231,6 +237,8 @@ export const mutation: {
   /**
    * Wraps an effect so the supplied keys are invalidated after the effect succeeds.
    *
+   * **Gotchas**
+   *
    * If the effect fails, the keys are not invalidated.
    *
    * @category accessors
@@ -242,6 +250,8 @@ export const mutation: {
   /**
    * Wraps an effect so the supplied keys are invalidated after the effect succeeds.
    *
+   * **Gotchas**
+   *
    * If the effect fails, the keys are not invalidated.
    *
    * @category accessors
@@ -259,6 +269,8 @@ export const mutation: {
 /**
  * Runs an effect as a query tied to the supplied invalidation keys.
  *
+ * **Details**
+ *
  * The returned queue receives the initial result and each later result after the
  * keys are invalidated. The registration is removed when the current scope closes.
  *
@@ -269,6 +281,8 @@ export const query: {
   /**
    * Runs an effect as a query tied to the supplied invalidation keys.
    *
+   * **Details**
+   *
    * The returned queue receives the initial result and each later result after the
    * keys are invalidated. The registration is removed when the current scope closes.
    *
@@ -283,6 +297,8 @@ export const query: {
   /**
    * Runs an effect as a query tied to the supplied invalidation keys.
    *
+   * **Details**
+   *
    * The returned queue receives the initial result and each later result after the
    * keys are invalidated. The registration is removed when the current scope closes.
    *
@@ -303,6 +319,8 @@ export const query: {
  * Runs an effect as a stream of query results tied to the supplied invalidation
  * keys.
  *
+ * **Details**
+ *
  * The effect runs initially and reruns whenever the keys are invalidated.
  *
  * @category accessors
@@ -313,6 +331,8 @@ export const stream: {
    * Runs an effect as a stream of query results tied to the supplied invalidation
    * keys.
    *
+   * **Details**
+   *
    * The effect runs initially and reruns whenever the keys are invalidated.
    *
    * @category accessors
@@ -325,6 +345,8 @@ export const stream: {
    * Runs an effect as a stream of query results tied to the supplied invalidation
    * keys.
    *
+   * **Details**
+   *
    * The effect runs initially and reruns whenever the keys are invalidated.
    *
    * @category accessors
@@ -346,6 +368,8 @@ export const stream: {
 /**
  * Invalidates the supplied keys through the `Reactivity` service.
  *
+ * **Details**
+ *
  * Registered queries for matching keys are rerun immediately, or collected until
  * the enclosing reactivity batch completes.
  *

package/src/unstable/rpc/Rpc.ts

@@ -63,6 +63,8 @@ export const isRpc = (u: unknown): u is Rpc<any, any, any> => Predicate.hasPrope
 /**
  * A schema for RPC defects.
  *
+ * **Details**
+ *
  * Defect schemas decode and encode without services and can be constructed from
  * `null`, `undefined`, or an object value.
  *
@@ -81,6 +83,8 @@ export interface DefectSchema extends Schema.Top {
 /**
  * Represents a typed RPC definition.
  *
+ * **Details**
+ *
  * An RPC is identified by a tag and carries payload, success, error, defect,
  * middleware, and annotation metadata used by RPC clients and servers.
  *
@@ -189,6 +193,8 @@ export interface Rpc<
 /**
  * Server-side metadata for the client associated with an RPC request.
  *
+ * **Details**
+ *
  * It stores the client id and request annotations that handlers can read or
  * extend.
  *
@@ -214,6 +220,8 @@ export class ServerClient {
 /**
  * Represents the server-side implementation of an RPC.
  *
+ * **Details**
+ *
  * The handler receives the decoded request plus client, request id, headers,
  * and RPC metadata, and returns either an effectful result or a stream result.
  *
@@ -325,6 +333,8 @@ export type SuccessEncoded<R> = R extends Rpc<
 /**
  * Extracts the success schema used in an RPC exit.
  *
+ * **Details**
+ *
  * For streaming RPCs, this is the stream element schema; otherwise it is the
  * RPC success schema.
  *
@@ -336,6 +346,8 @@ export type SuccessExitSchema<R> = SuccessSchema<R> extends RpcSchema.Stream<inf
 /**
  * Extracts the decoded success value carried by an RPC exit.
  *
+ * **Details**
+ *
  * For streaming RPCs, the immediate exit success is `void` because stream
  * elements are delivered separately.
  *
@@ -383,6 +395,8 @@ export type Error<R> = Schema.Schema.Type<ErrorSchema<R>>
 /**
  * Extracts the error schema used in an RPC exit.
  *
+ * **Details**
+ *
  * For streaming RPCs, this includes both the stream error schema and the RPC
  * error schema; otherwise it is the RPC error schema.
  *
@@ -395,6 +409,8 @@ export type ErrorExitSchema<R> = SuccessSchema<R> extends RpcSchema.Stream<infer
 /**
  * Extracts the decoded error type used by an RPC exit.
  *
+ * **Details**
+ *
  * For streaming RPCs, this includes both stream errors and RPC errors.
  *
  * @category models
@@ -472,6 +488,8 @@ export type Services<R> = R extends Rpc<
 /**
  * Extracts the schema services required on the client side of an RPC.
  *
+ * **Details**
+ *
  * This includes payload encoding services and success, error, and middleware
  * error decoding services.
  *
@@ -495,6 +513,8 @@ export type ServicesClient<R> = R extends Rpc<
 /**
  * Extracts the schema services required on the server side of an RPC.
  *
+ * **Details**
+ *
  * This includes payload decoding services and success, error, and middleware
  * error encoding services.
  *
@@ -616,6 +636,8 @@ export type ToHandler<R extends Any> = R extends Rpc<
 /**
  * The function signature for implementing an RPC handler.
  *
+ * **Details**
+ *
  * The function receives the decoded payload and request metadata, and returns
  * the RPC result shape, optionally wrapped with `Wrapper` options.
  *
@@ -713,6 +735,8 @@ export type ExcludeProvides<Env, R extends Any, Tag extends string> = Exclude<
 /**
  * Computes the allowed handler result type for an RPC.
  *
+ * **Details**
+ *
  * Streaming RPCs may return a stream or an effect that produces a queue. Other
  * RPCs return an effect that succeeds with the success value or a deferred
  * success value.
@@ -882,6 +906,8 @@ const makeProto = <
 /**
  * Creates an RPC definition with the supplied tag and optional schemas.
  *
+ * **Details**
+ *
  * Payload options can be either a schema or struct fields. `stream: true` wraps
  * the success and error schemas in a stream schema and sets the normal error
  * schema to `Schema.Never`. `primaryKey` creates a payload class with a
@@ -943,9 +969,11 @@ export const make = <
 }
 
 /**
- * Create a custom Rpc constructor, that can transform the output schemas.
+ * Creates a custom `Rpc` constructor that can transform the output schemas.
+ *
+ * **Example** (Paginated RPC constructor)
  *
- * ```typescript
+ * ```ts
  * import { Schema } from "effect"
  * import { Rpc } from "effect/unstable/rpc"
  *
@@ -1031,6 +1059,8 @@ export const custom = <Def extends Custom>(
 /**
  * Defines the type-level contract for an RPC custom constructor.
  *
+ * **Details**
+ *
  * A custom constructor receives the original success, error, and defect schemas
  * and returns transformed output schemas through `out`.
  *
@@ -1096,6 +1126,8 @@ const exitSchemaCache = new WeakMap<Any, Schema.Exit<Schema.Top, Schema.Top, Def
 /**
  * Builds the `Schema.Exit` used to encode and decode RPC results.
  *
+ * **Details**
+ *
  * The failure side includes the RPC error schema, middleware error schemas, and
  * stream error schema for streaming RPCs. Streaming RPCs use `Schema.Void` for
  * the exit success value. The schema is cached per RPC definition.
@@ -1136,6 +1168,8 @@ const WrapperTypeId = "~effect/rpc/Rpc/Wrapper"
 /**
  * Wraps a handler result with execution options for the RPC server.
  *
+ * **Details**
+ *
  * `fork` requests concurrent execution, and `uninterruptible` requests
  * uninterruptible execution.
  *
@@ -1169,6 +1203,8 @@ export const isWrapper = (u: object): u is Wrapper<any> => WrapperTypeId in u
 /**
  * Wraps a handler result with RPC server execution options.
  *
+ * **Details**
+ *
  * When the value is already wrapped, unspecified options are inherited from the
  * existing wrapper.
  *

package/src/unstable/rpc/RpcSerialization.ts

@@ -497,6 +497,8 @@ export const msgPack: RpcSerialization["Service"] = makeMsgPack({ useRecords: tr
 /**
  * A rpc serialization layer that uses JSON for serialization.
  *
+ * **When to use**
+ *
  * Use this if your protocol supports framing for messages, otherwise use
  * {@link layerNdjson}.
  *
@@ -508,6 +510,8 @@ export const layerJson: Layer.Layer<RpcSerialization> = Layer.succeed(RpcSeriali
 /**
  * A rpc serialization layer that uses NDJSON for serialization.
  *
+ * **When to use**
+ *
  * Use this if your protocol does not support framing for messages, otherwise
  * use {@link layerJson}.
  *
@@ -540,6 +544,8 @@ export const layerNdJsonRpc = (options?: {
 /**
  * A rpc serialization layer that uses MessagePack for serialization.
  *
+ * **Details**
+ *
  * MessagePack has a more compact binary format compared to JSON and NDJSON. It
  * also has better support for binary data.
  *

package/src/unstable/rpc/RpcServer.ts

@@ -803,10 +803,12 @@ export const layer = <Rpcs extends Rpc.Any>(
 > => Layer.effectDiscard(Effect.forkScoped(make(group, options)))
 
 /**
- * Create a RPC server that registers a HTTP route with a `HttpRouter`.
+ * Creates a RPC server that registers a HTTP route with a `HttpRouter`.
  *
- * It defaults to using websockets for communication, but can be configured to
- * use HTTP.
+ * **Details**
+ *
+ * Defaults to using websockets for communication, but can be configured to use
+ * HTTP.
  *
  * @category protocol
  * @since 4.0.0

package/src/unstable/schema/Model.ts

@@ -78,12 +78,9 @@ export type VariantsJson = "json" | "jsonCreate" | "jsonUpdate"
 
 export {
   /**
-   * A base class used for creating domain model schemas.
+   * A base class used for creating domain model schemas with common database and
+   * JSON API variants.
    *
-   * It supports common variants for database and JSON apis.
-   *
-   * @category constructors
-   * @since 4.0.0
    * **Example** (Defining a variant model class)
    *
    * ```ts
@@ -120,39 +117,58 @@ export {
    *   }
    * }
    * ```
+   *
+   * @category constructors
+   * @since 4.0.0
    */
   Class,
   /**
+   * Extracts a generated variant schema from a model or variant struct.
+   *
    * @category extraction
    * @since 4.0.0
    */
   extract,
   /**
+   * Creates a variant field from schemas keyed by variant name.
+   *
    * @category fields
    * @since 4.0.0
    */
   Field,
   /**
+   * Transforms schemas inside a variant field or plain schema by variant name.
+   *
    * @category fields
    * @since 4.0.0
    */
   fieldEvolve,
   /**
+   * Creates a variant field that applies a schema to every variant except the
+   * supplied keys.
+   *
    * @category fields
    * @since 4.0.0
    */
   FieldExcept,
   /**
+   * Creates a variant field that applies a schema only to the supplied variants.
+   *
    * @category fields
    * @since 4.0.0
    */
   FieldOnly,
   /**
+   * Creates a variant struct from model field definitions.
+   *
    * @category constructors
    * @since 4.0.0
    */
   Struct,
   /**
+   * Creates a union over the default and generated variant schemas of multiple
+   * variant structs.
+   *
    * @category constructors
    * @since 4.0.0
    */
@@ -192,9 +208,7 @@ export interface GeneratedByDb<S extends Schema.Top> extends
 {}
 
 /**
- * A field that represents a column that is generated by the database.
- *
- * It is available for reads only.
+ * A field for a database-generated column that is available for reads only.
  *
  * @category generated
  * @since 4.0.0
@@ -225,10 +239,9 @@ export interface GeneratedByApp<S extends Schema.Top> extends
 {}
 
 /**
- * A field that represents a value generated by the application.
- *
- * It is present in the database variants and read JSON variant, but omitted from
- * the JSON create and update variants.
+ * A field for a value generated by the application that is present in database
+ * variants and the read JSON variant, but omitted from JSON create and update
+ * variants.
  *
  * @category generated
  * @since 4.0.0
@@ -302,6 +315,8 @@ export const optionalOption = <S extends Schema.Top>(schema: S): optionalOption<
 /**
  * Convert a field to one that is optional for all variants.
  *
+ * **Details**
+ *
  * For the database variants, it will accept `null`able values.
  * For the JSON variants, it will also accept missing keys.
  *
@@ -322,6 +337,8 @@ export interface FieldOption<S extends Schema.Top> extends
 /**
  * Convert a field to one that is optional for all variants.
  *
+ * **Details**
+ *
  * For the database variants, it will accept `null`able values.
  * For the JSON variants, it will also accept missing keys.
  *
@@ -467,6 +484,8 @@ export interface DateTimeInsert extends
  * A field that represents a date-time value that is inserted as the current
  * `DateTime.Utc`. It is serialized as a string for the database.
  *
+ * **Details**
+ *
  * It is omitted from updates and is available for selection.
  *
  * @category date & time
@@ -497,6 +516,8 @@ export interface DateTimeInsertFromDate extends
  * A field that represents a date-time value that is inserted as the current
  * `DateTime.Utc`. It is serialized as a `Date` for the database.
  *
+ * **Details**
+ *
  * It is omitted from updates and is available for selection.
  *
  * @category date & time
@@ -527,6 +548,8 @@ export interface DateTimeInsertFromNumber extends
  * A field that represents a date-time value that is inserted as the current
  * `DateTime.Utc`. It is serialized as a `number`.
  *
+ * **Details**
+ *
  * It is omitted from updates and is available for selection.
  *
  * @category date & time
@@ -558,6 +581,8 @@ export interface DateTimeUpdate extends
  * A field that represents a date-time value that is updated as the current
  * `DateTime.Utc`. It is serialized as a string for the database.
  *
+ * **Details**
+ *
  * It is set to the current `DateTime.Utc` on updates and inserts and is
  * available for selection.
  *
@@ -592,6 +617,8 @@ export interface DateTimeUpdateFromDate extends
  * A field that represents a date-time value that is updated as the current
  * `DateTime.Utc`. It is serialized as a `Date` for the database.
  *
+ * **Details**
+ *
  * It is set to the current `DateTime.Utc` on updates and inserts and is
  * available for selection.
  *
@@ -625,6 +652,8 @@ export interface DateTimeUpdateFromNumber extends
  * A field that represents a date-time value that is updated as the current
  * `DateTime.Utc`. It is serialized as a `number`.
  *
+ * **Details**
+ *
  * It is set to the current `DateTime.Utc` on updates and inserts and is
  * available for selection.
  *
@@ -659,6 +688,8 @@ export interface JsonFromString<S extends Schema.Top> extends
 /**
  * A field that represents a JSON value stored as text in the database.
  *
+ * **Details**
+ *
  * The "json" variants will use the object schema directly.
  *
  * @category json

package/src/unstable/sql/SqlClient.ts

@@ -107,7 +107,7 @@ export const SqlClient = Context.Service<SqlClient>("effect/sql/SqlClient")
  *
  * @since 4.0.0
  */
-export namespace SqlClient {
+export declare namespace SqlClient {
   /**
    * Options used to construct a `SqlClient`, including connection acquirers,
    * the SQL compiler, transaction SQL, row transformation, tracing attributes,