effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/unstable/socket/Socket.ts

@@ -59,7 +59,12 @@ export const TypeId = "~effect/socket/Socket"
 export const isSocket = (u: unknown): u is Socket => Predicate.hasProperty(u, TypeId)
 
 /**
- * Context service tag for the current `Socket` implementation.
+ * Service tag for bidirectional socket transports.
+ *
+ * **When to use**
+ *
+ * Use to access or provide the socket implementation used by programs that
+ * read and write frames through the Effect environment.
  *
  * @category tags
  * @since 4.0.0
@@ -161,7 +166,8 @@ const decoder = new TextDecoder()
 const CloseEventTypeId = "~effect/socket/Socket/CloseEvent"
 
 /**
- * Socket close event value carrying a close code and optional reason.
+ * Represents a socket close event value carrying a close code and optional
+ * reason.
  *
  * @category models
  * @since 4.0.0

package/src/unstable/socket/SocketServer.ts

@@ -45,7 +45,7 @@ export class SocketServer extends Context.Service<SocketServer, {
 /**
  * Runtime type identifier attached to `SocketServerError` values.
  *
- * @category errors
+ * @category type IDs
  * @since 4.0.0
  */
 export const ErrorTypeId: ErrorTypeId = "@effect/platform/SocketServer/SocketServerError"
@@ -53,7 +53,7 @@ export const ErrorTypeId: ErrorTypeId = "@effect/platform/SocketServer/SocketSer
 /**
  * Type-level identifier used to mark `SocketServerError` values.
  *
- * @category errors
+ * @category type IDs
  * @since 4.0.0
  */
 export type ErrorTypeId = "@effect/platform/SocketServer/SocketServerError"

package/src/unstable/socket/index.ts

@@ -5,55 +5,11 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * Effect-based socket abstractions for bidirectional connections that exchange
- * text frames, binary frames, and close events.
- *
- * This module defines the `Socket` service, constructors for WebSocket-backed
- * and transform-stream-backed sockets, typed socket errors, and adapters that
- * expose a socket as a bidirectional `Channel`. It is intended for WebSocket
- * clients, HTTP server upgrades, protocol clients and servers, and tests or
- * adapters that need a scoped duplex transport inside Effect programs.
- *
- * Incoming data can be consumed as raw frames, binary bytes, or strings.
- * `runRaw` preserves whether the transport delivered a string or `Uint8Array`,
- * while `run` encodes string frames as UTF-8 bytes and `runString` decodes
- * binary frames with `TextDecoder`. Use the raw or mapping APIs when preserving
- * frame boundaries, binary payloads, or text encodings matters.
- *
- * Writers are scoped to an active run and are gated until the underlying
- * connection is open; use `onOpen` when startup writes must wait for that
- * point. Outgoing strings and bytes are sent as data frames, while `CloseEvent`
- * values request a close. Close events are modeled as `SocketCloseError` by
- * default, and `closeCodeIsError` controls which close codes should fail a run
- * versus complete cleanly.
- *
  * @since 4.0.0
  */
 export * as Socket from "./Socket.ts"
 
 /**
- * Effect service model for servers that accept socket connections and hand each
- * accepted connection to an Effect handler as a `Socket.Socket`.
- *
- * This module contains the shared, platform-independent contract for socket
- * servers: a bound `address`, a long-running `run` accept loop, the TCP and
- * Unix socket address models, and the server-level errors reported while
- * opening or running a server. Concrete transports, such as Node TCP servers or
- * WebSocket servers, provide this service through platform-specific layers.
- *
- * `SocketServer` is commonly used as the server transport for RPC protocols,
- * cluster runners, developer tools, and tests that need an ephemeral TCP port or
- * Unix-domain socket. A server address may differ from the requested listen
- * options after binding, for example when listening on port `0`, so consumers
- * should read the provided `address` from the service.
- *
- * The `run` effect represents the server accept loop and is expected to remain
- * alive until interrupted or until the providing scope is closed. Protocol
- * framing is intentionally outside this module: handlers receive a generic
- * `Socket.Socket`, so callers are responsible for choosing byte, string, raw
- * frame, or higher-level protocol adapters and for treating connection-level
- * failures separately from `SocketServerError` values.
- *
  * @since 4.0.0
  */
 export * as SocketServer from "./SocketServer.ts"

package/src/unstable/sql/Migrator.ts

@@ -1,24 +1,45 @@
 /**
- * Effect SQL migration helpers for loading, ordering, and running schema
- * changes against a `SqlClient`.
+ * SQL migration runner for Effect applications.
  *
- * This module provides a migrator constructor plus loaders for common migration
- * layouts, including dynamic glob imports, Babel-style glob records, in-memory
- * records, and filesystem directories. It is intended for applications and
- * libraries that need to apply numbered SQL migrations on startup, in tests, or
- * as part of deployment tooling while keeping migration effects inside the
- * Effect environment.
+ * A migrator loads numbered migration effects, records which ids have already
+ * run in a migrations table, and executes only the pending migrations through a
+ * `SqlClient`. The helpers in this module cover the common ways migrations are
+ * discovered: dynamic glob imports, Babel-style glob records, in-memory
+ * records, and filesystem directories.
  *
- * The migrator tracks applied migrations in a configurable table, defaults that
- * table to `effect_sql_migrations`, rejects duplicate migration ids, and only
- * runs migrations with an id greater than the latest recorded id. Pending
- * migrations are recorded and executed inside a `SqlClient` transaction; on
- * PostgreSQL the migrations table is explicitly locked, while other dialects
- * rely on the table's primary key or unique constraint to detect concurrent
- * runners. Migration effects should therefore be written to be transaction-aware,
- * and callers should account for dialect-specific DDL transaction behavior and
- * custom table names when coordinating schema dumps or external migration
- * tooling.
+ * **Mental model**
+ *
+ * - A {@link Loader} resolves an ordered list of {@link ResolvedMigration}
+ *   values
+ * - {@link make} creates a runner that ensures the migrations table exists,
+ *   reads the latest recorded id, loads pending migration effects, records
+ *   them, and runs them in a transaction
+ * - The default migrations table is `effect_sql_migrations`; pass `table` when
+ *   a database needs a different name
+ * - On PostgreSQL the migrations table is explicitly locked; other dialects use
+ *   the table constraint to detect concurrent runners
+ * - `schemaDirectory` runs the `dumpSchema` hook after successful migrations
+ *
+ * **Common tasks**
+ *
+ * - Load bundler migration modules with {@link fromGlob} or
+ *   {@link fromBabelGlob}
+ * - Load test or programmatic migrations with {@link fromRecord}
+ * - Load migration files from a directory with {@link fromFileSystem}
+ * - Customize schema dumps by passing `dumpSchema` to {@link make}
+ *
+ * **Gotchas**
+ *
+ * - Migration ids must be unique numbers; duplicate ids fail before any pending
+ *   migration is run
+ * - Only ids greater than the latest recorded id are considered pending, so
+ *   editing or inserting an older migration does not make it run again
+ * - File-based migrations must match `<id>_<name>.js`, `<id>_<name>.ts`,
+ *   `<id>_<name>.mjs`, or `<id>_<name>.mts`
+ * - File-based migration modules should default-export an `Effect` value that
+ *   uses the current `SqlClient`; records can supply effects directly
+ * - DDL transaction behavior is dialect-specific; coordinate custom table
+ *   names, schema dumps, and external migration tooling accordingly
  *
  * @since 4.0.0
  */

package/src/unstable/sql/SqlClient.ts

@@ -95,9 +95,14 @@ export interface SqlClient extends Constructor {
 }
 
 /**
- * Context service tag for the `SqlClient` service.
+ * Service tag for the active SQL client service.
  *
- * @category models
+ * **When to use**
+ *
+ * Use to access or provide the SQL client used to build statements, stream
+ * rows, reserve connections, and run transactions.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export const SqlClient = Context.Service<SqlClient>("effect/sql/SqlClient")

package/src/unstable/sql/SqlConnection.ts

@@ -79,7 +79,7 @@ export interface Connection {
 export type Acquirer = Effect<Connection, SqlError, Scope>
 
 /**
- * Context service tag for a low-level SQL `Connection`.
+ * Service tag for a low-level SQL `Connection`.
  *
  * @category tag
  * @since 4.0.0

package/src/unstable/sql/SqlError.ts

@@ -1,21 +1,37 @@
 /**
- * Structured SQL errors used by the unstable SQL APIs.
+ * Structured SQL failures for unstable SQL clients and driver integrations.
  *
- * This module defines the top-level `SqlError` wrapper, the concrete
- * `SqlErrorReason` variants used by drivers and adapters, and helpers for
- * recognizing and classifying database failures. It is useful when turning
- * native driver errors into typed Effect failures, choosing retry policies from
- * `isRetryable`, or distinguishing user-facing query problems such as syntax
- * and constraint failures from infrastructure problems such as connection,
- * lock, statement timeout, deadlock, and serialization failures.
+ * This module provides the top-level `SqlError` wrapper, the concrete
+ * `SqlErrorReason` variants used by adapters, schemas for encoding or decoding
+ * those errors, guards for recognizing them, and a SQLite classifier for native
+ * driver causes. The model keeps query mistakes, authentication and
+ * authorization failures, constraint violations, connection failures, lock
+ * waits, deadlocks, serialization conflicts, statement timeouts, and unknown
+ * failures distinguishable in the Effect error channel.
  *
- * Query, connection, and migration code should preserve the original cause and
- * operation metadata when constructing these errors. Retrying can be appropriate
- * for transient connection and concurrency failures, but syntax, authorization,
- * authentication, and constraint failures generally require changing the query,
- * credentials, permissions, or migration data. When classifying SQLite errors,
- * the helpers inspect `code` and `errno` values and extract unique constraint
- * names when available.
+ * **Mental model**
+ *
+ * `SqlError` wraps exactly one reason. Its `message`, `cause`, and
+ * `isRetryable` values are delegated to that reason, so recovery code can branch
+ * on either the reason tag or the retryability flag without losing the original
+ * native cause. Reasons are intentionally driver-neutral; adapters translate
+ * database-specific error codes into this shared vocabulary.
+ *
+ * **Common tasks**
+ *
+ * Construct a reason when adapting a driver failure, wrap it in `SqlError` for
+ * client APIs, use `isSqlError` or `isSqlErrorReason` at boundaries that receive
+ * unknown failures, and use `classifySqliteError` when mapping SQLite `code` or
+ * `errno` values.
+ *
+ * **Gotchas**
+ *
+ * Preserve the native `cause` and `operation` metadata when constructing these
+ * errors; they are often the only way to diagnose dialect-specific failures.
+ * Retryable reasons represent transient infrastructure or concurrency problems,
+ * while syntax, credential, permission, and constraint failures generally need a
+ * changed query, configuration, or data set. SQLite unique violations include a
+ * best-effort constraint name when one can be extracted.
  *
  * @since 4.0.0
  */
@@ -355,7 +371,7 @@ export type SqlErrorReason =
   | UnknownError
 
 /**
- * Schema union for encoding and decoding `SqlErrorReason` values.
+ * Schema for encoding and decoding SQL error reasons.
  *
  * @category schemas
  * @since 4.0.0
@@ -387,7 +403,7 @@ export const SqlErrorReason: Schema.Union<[
 ])
 
 /**
- * Top-level SQL error wrapper whose `message`, `cause`, and `isRetryable`
+ * Error wrapper for SQL failures whose `message`, `cause`, and `isRetryable`
  * values are derived from its `SqlErrorReason`.
  *
  * @category errors

package/src/unstable/sql/SqlResolver.ts

@@ -66,7 +66,7 @@ const SqlRequestProto = {
 }
 
 /**
- * Submits a payload as a `SqlRequest` to a request resolver, either directly
+ * Runs a payload as a `SqlRequest` through a request resolver, either directly
  * with a payload and resolver or curried by resolver.
  *
  * @category requests
@@ -74,7 +74,7 @@ const SqlRequestProto = {
  */
 export const request: {
   /**
-   * Submits a payload as a `SqlRequest` to a request resolver, either directly
+   * Runs a payload as a `SqlRequest` through a request resolver, either directly
    * with a payload and resolver or curried by resolver.
    *
    * @category requests
@@ -82,7 +82,7 @@ export const request: {
    */
   <In, A, E, R>(resolver: RequestResolver.RequestResolver<SqlRequest<In, A, E, R>>): (payload: In) => Effect.Effect<A, E | Schema.SchemaError, R>
   /**
-   * Submits a payload as a `SqlRequest` to a request resolver, either directly
+   * Runs a payload as a `SqlRequest` through a request resolver, either directly
    * with a payload and resolver or curried by resolver.
    *
    * @category requests

package/src/unstable/sql/SqlSchema.ts

@@ -1,21 +1,36 @@
 /**
- * Schema-driven helpers for wrapping SQL executions in typed query functions.
- *
- * This module connects `Schema` request and result definitions to an `execute`
- * callback that runs the actual SQL statement. The returned functions accept
- * the request schema's decoded `Type`, encode it to the SQL-facing `Encoded`
- * shape, run the callback, and then decode unknown driver rows through the
- * result schema. This is useful for repository methods, CRUD helpers, request
- * resolvers, and write operations where callers should work with domain values
- * instead of raw SQL parameters or rows.
- *
- * The `execute` callback always receives `Req["Encoded"]`, so schema
- * transformations, required encoding services, and database representations
- * such as nullable columns, JSON values, dates, and bigints must line up with
- * the statement builder and dialect in use. Result schemas decode the rows
- * returned by the driver after any SQL client row transforms; `findOne` and
- * `findOneOption` only inspect the first row, `findNonEmpty` requires at least
- * one row, and `void` discards any driver result after request encoding.
+ * Wraps SQL execution callbacks with request encoding and result decoding.
+ *
+ * `SqlSchema` is a small adapter between Effect Schema and SQL statements. Each
+ * helper builds a function that accepts the decoded request type used by
+ * application code, encodes it before calling `execute`, and decodes unknown
+ * driver rows into the result schema. The helpers differ only in how many rows
+ * they expect and how they represent an empty result set.
+ *
+ * **Mental model**
+ *
+ * The request schema protects the boundary going into SQL, and the result
+ * schema protects the boundary coming back out. `execute` still owns statement
+ * construction and database execution; this module only shapes the values that
+ * cross that boundary.
+ *
+ * **Common tasks**
+ *
+ * - Use {@link findAll} for queries that may return any number of rows.
+ * - Use {@link findNonEmpty} when an empty result is a failure.
+ * - Use {@link findOne} when the first row is required.
+ * - Use {@link findOneOption} when the first row is optional.
+ * - Use `void` for writes where the encoded request matters but the driver
+ *   result should be discarded.
+ *
+ * **Gotchas**
+ *
+ * `execute` receives `Req["Encoded"]`, not `Req["Type"]`. Any schema
+ * transformations, encoding services, nullable columns, JSON values, dates, and
+ * bigint representations must match the SQL builder and dialect in use. Result
+ * schemas decode rows after SQL client row transforms have run. {@link findOne}
+ * and {@link findOneOption} only inspect the first returned row; they do not
+ * assert that the query returned exactly one row.
  *
  * @since 4.0.0
  */
@@ -26,8 +41,15 @@ import type * as Option from "../../Option.ts"
 import * as Schema from "../../Schema.ts"
 
 /**
- * Builds a query function that encodes the request, decodes all result rows,
- * and fails with `NoSuchElementError` when the result set is empty.
+ * Builds a query function that encodes the request and decodes all result rows,
+ * allowing an empty result set.
+ *
+ * **When to use**
+ *
+ * Use when a query may return zero or more rows and an empty result should be
+ * represented as an empty array.
+ *
+ * @see {@link findNonEmpty} for queries where an empty result is a failure
  *
  * @category constructors
  * @since 4.0.0
@@ -51,7 +73,15 @@ export const findAll = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
 }
 
 /**
- * Run a sql query with a request schema and a result schema.
+ * Builds a query function that encodes the request, decodes all result rows,
+ * and fails with `NoSuchElementError` when the result set is empty.
+ *
+ * **When to use**
+ *
+ * Use when a query must return at least one row and an empty result should be
+ * treated as a failure.
+ *
+ * @see {@link findAll} for queries where an empty result should return an empty array
  *
  * @category constructors
  * @since 4.0.0
@@ -91,7 +121,7 @@ const void_ = <Req extends Schema.Top, E, R>(
 }
 export {
   /**
-   * Run a sql query with a request schema and discard the result.
+   * Runs a sql query with a request schema and discard the result.
    *
    * @category constructors
    * @since 4.0.0

package/src/unstable/sql/Statement.ts

@@ -1,20 +1,40 @@
 /**
- * Building blocks for Effect's unstable SQL statement API.
+ * Low-level SQL statement and fragment primitives.
  *
- * This module defines the low-level `Statement` and `Fragment` model used by
- * SQL clients, the tagged-template `Constructor` for creating executable
- * parameterized statements, and dialect compilers that turn statement segments
- * into SQL text plus bind parameters. It also provides helpers for escaped
- * identifiers, `IN` lists, comma-separated clause fragments, record inserts and
- * updates, custom segments, and row or identifier transforms.
+ * This module is the foundation used by SQL clients to build executable,
+ * parameterized SQL. It defines the {@link Statement} and {@link Fragment}
+ * models, the tagged-template {@link Constructor}, segment constructors for
+ * identifiers, parameters, literals, arrays, records, and custom dialect data,
+ * plus compilers that render those segments into dialect-specific SQL text and
+ * bind parameters.
  *
- * In tagged templates, interpolated `Fragment`s and known `Segment`s are
- * spliced into the statement, while ordinary values become bound parameters. Use
- * identifiers for table and column names and the record helpers for generated
- * column lists; `literal` and `unsafe` insert SQL text directly and should only
- * be used with trusted SQL. Compilation is dialect-specific, caches rendered SQL
- * on the statement, and has a `withoutTransform` path for bypassing identifier
- * transforms, so compiled output can differ from normal transformed execution.
+ * **Mental model**
+ *
+ * A statement is a sequence of {@link Segment} values. In a tagged template,
+ * nested fragments and known segments are spliced into that sequence, while
+ * ordinary interpolated values become bound parameters. A {@link Compiler}
+ * turns the sequence into SQL for one dialect, escaping identifiers and
+ * formatting placeholders for that dialect. Executing a {@link Statement} uses
+ * the connection acquirer captured by {@link make} and can return rows, raw
+ * results, streams, values, or unprepared execution paths.
+ *
+ * **Common tasks**
+ *
+ * - Build statements with a {@link Constructor} tagged template
+ * - Use {@link identifier} for table and column names rather than interpolating
+ *   plain strings
+ * - Compose optional clauses with {@link and}, {@link or}, {@link csv}, and
+ *   {@link join}
+ * - Create insert and update fragments with record helpers
+ * - Add custom segment handling with {@link custom} and {@link makeCompiler}
+ *
+ * **Gotchas**
+ *
+ * Bound parameters protect values, not SQL syntax. Use `literal` and `unsafe`
+ * only for trusted SQL text, and use identifiers for names that need escaping.
+ * Compiled SQL is dialect-specific and cached on the statement;
+ * `withoutTransform` intentionally bypasses identifier or row transforms, so
+ * its output can differ from normal execution.
  *
  * @since 4.0.0
  */
@@ -497,7 +517,7 @@ export interface Constructor {
    *
    * **When to use**
    *
-   * Useful for `ORDER BY` and `GROUP BY` clauses.
+   * Use when `ORDER BY` and `GROUP BY` clauses.
    */
   readonly csv: {
     (values: ReadonlyArray<string | Fragment>): Fragment