effect 4.0.0-beta.67 → 4.0.0-beta.68

package/src/unstable/socket/index.ts

@@ -5,11 +5,55 @@
 // @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

@@ -36,7 +36,7 @@ import type { SqlError } from "./SqlError.ts"
  * Options for running SQL migrations, including the migration loader, optional
  * schema dump directory, and migrations table name.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface MigratorOptions<R = never> {
@@ -49,7 +49,7 @@ export interface MigratorOptions<R = never> {
  * Effect that resolves the available migrations for the migrator or fails with a
  * `MigrationError`.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export type Loader<R = never> = Effect.Effect<
@@ -62,7 +62,7 @@ export type Loader<R = never> = Effect.Effect<
  * Tuple produced by a migration loader, containing the migration id, migration
  * name, and an effect that loads the migration implementation.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export type ResolvedMigration = readonly [
@@ -75,7 +75,7 @@ export type ResolvedMigration = readonly [
  * Metadata for a migration recorded in the migrations table, including its id,
  * name, and creation timestamp.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface Migration {
@@ -107,7 +107,7 @@ export class MigrationError extends Data.TaggedError("MigrationError")<{
  * migrations in a transaction, and optionally dumps the schema after successful
  * migrations.
  *
- * @category constructor
+ * @category constructors
  * @since 4.0.0
  */
 export const make = <RD = never>({

package/src/unstable/sql/SqlClient.ts

@@ -304,6 +304,7 @@ export const makeWithTransaction = <I, S>(options: {
  * Phantom identifier for the scoped transaction connection service associated
  * with a SQL client.
  *
+ * @category models
  * @since 4.0.0
  */
 export interface TransactionConnection {
@@ -320,6 +321,7 @@ export declare namespace TransactionConnection {
    * Service payload stored during a transaction, containing the active
    * connection and nested transaction depth.
    *
+   * @category services
    * @since 4.0.0
    */
   export type Service = readonly [conn: Connection.Connection, depth: number]
@@ -329,6 +331,7 @@ export declare namespace TransactionConnection {
  * Creates a unique context service tag for the active transaction connection of
  * a specific SQL client.
  *
+ * @category tags
  * @since 4.0.0
  */
 export const TransactionConnection = (
@@ -340,6 +343,7 @@ export const TransactionConnection = (
  * Context reference used by SQL integrations to opt in to safe integer
  * handling; defaults to `false`.
  *
+ * @category references
  * @since 4.0.0
  */
 export const SafeIntegers = Context.Reference<boolean>("effect/sql/SqlClient/SafeIntegers", {

package/src/unstable/sql/SqlConnection.ts

@@ -32,7 +32,7 @@ import type { SqlError } from "./SqlError.ts"
  * transformed rows, raw results, streams, value arrays, or unprepared
  * statements.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface Connection {
@@ -73,7 +73,7 @@ export interface Connection {
  * Scoped effect that acquires a `Connection`, may fail with `SqlError`, and
  * requires a `Scope` for release.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export type Acquirer = Effect<Connection, SqlError, Scope>
@@ -89,7 +89,7 @@ export const Connection = Context.Service<Connection>("effect/sql/SqlConnection"
 /**
  * Generic SQL row shape mapping column names to unknown values.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export type Row = { readonly [column: string]: unknown }

package/src/unstable/sql/SqlError.ts

@@ -34,6 +34,7 @@ const ReasonFields = {
 /**
  * SQL error reason for connection or open failures; marked retryable.
  *
+ * @category errors
  * @since 4.0.0
  */
 export class ConnectionError extends Schema.TaggedErrorClass<ConnectionError>("effect/sql/SqlError/ConnectionError")(
@@ -61,6 +62,7 @@ export class ConnectionError extends Schema.TaggedErrorClass<ConnectionError>("e
  * SQL error reason for authentication failures such as invalid credentials; not
  * marked retryable.
  *
+ * @category errors
  * @since 4.0.0
  */
 export class AuthenticationError extends Schema.TaggedErrorClass<AuthenticationError>(
@@ -87,6 +89,7 @@ export class AuthenticationError extends Schema.TaggedErrorClass<AuthenticationE
  * SQL error reason for authorization or permission failures; not marked
  * retryable.
  *
+ * @category errors
  * @since 4.0.0
  */
 export class AuthorizationError extends Schema.TaggedErrorClass<AuthorizationError>(
@@ -112,6 +115,7 @@ export class AuthorizationError extends Schema.TaggedErrorClass<AuthorizationErr
 /**
  * SQL error reason for invalid SQL syntax; not marked retryable.
  *
+ * @category errors
  * @since 4.0.0
  */
 export class SqlSyntaxError extends Schema.TaggedErrorClass<SqlSyntaxError>("effect/sql/SqlError/SqlSyntaxError")(
@@ -144,6 +148,7 @@ const UniqueViolationFields = {
  * SQL error reason for a unique constraint violation, including the violated
  * constraint identifier; not marked retryable.
  *
+ * @category errors
  * @since 4.0.0
  */
 export class UniqueViolation extends Schema.TaggedErrorClass<UniqueViolation>("effect/sql/SqlError/UniqueViolation")(
@@ -170,6 +175,7 @@ export class UniqueViolation extends Schema.TaggedErrorClass<UniqueViolation>("e
 /**
  * SQL error reason for a non-unique constraint violation; not marked retryable.
  *
+ * @category errors
  * @since 4.0.0
  */
 export class ConstraintError extends Schema.TaggedErrorClass<ConstraintError>("effect/sql/SqlError/ConstraintError")(
@@ -196,6 +202,7 @@ export class ConstraintError extends Schema.TaggedErrorClass<ConstraintError>("e
 /**
  * SQL error reason for a database deadlock; marked retryable.
  *
+ * @category errors
  * @since 4.0.0
  */
 export class DeadlockError extends Schema.TaggedErrorClass<DeadlockError>("effect/sql/SqlError/DeadlockError")(
@@ -223,6 +230,7 @@ export class DeadlockError extends Schema.TaggedErrorClass<DeadlockError>("effec
  * SQL error reason for a transaction serialization or isolation conflict;
  * marked retryable.
  *
+ * @category errors
  * @since 4.0.0
  */
 export class SerializationError extends Schema.TaggedErrorClass<SerializationError>(
@@ -249,6 +257,7 @@ export class SerializationError extends Schema.TaggedErrorClass<SerializationErr
  * SQL error reason for timing out while waiting on a database lock; marked
  * retryable.
  *
+ * @category errors
  * @since 4.0.0
  */
 export class LockTimeoutError extends Schema.TaggedErrorClass<LockTimeoutError>("effect/sql/SqlError/LockTimeoutError")(
@@ -275,6 +284,7 @@ export class LockTimeoutError extends Schema.TaggedErrorClass<LockTimeoutError>(
 /**
  * SQL error reason for a statement or query timeout; marked retryable.
  *
+ * @category errors
  * @since 4.0.0
  */
 export class StatementTimeoutError extends Schema.TaggedErrorClass<StatementTimeoutError>(
@@ -300,6 +310,7 @@ export class StatementTimeoutError extends Schema.TaggedErrorClass<StatementTime
 /**
  * SQL error reason for an unclassified database failure; not marked retryable.
  *
+ * @category errors
  * @since 4.0.0
  */
 export class UnknownError extends Schema.TaggedErrorClass<UnknownError>("effect/sql/SqlError/UnknownError")(
@@ -327,6 +338,7 @@ export class UnknownError extends Schema.TaggedErrorClass<UnknownError>("effect/
  * Union of structured SQL error reasons, each carrying the original cause plus
  * optional message and operation metadata.
  *
+ * @category errors
  * @since 4.0.0
  */
 export type SqlErrorReason =
@@ -345,6 +357,7 @@ export type SqlErrorReason =
 /**
  * Schema union for encoding and decoding `SqlErrorReason` values.
  *
+ * @category schemas
  * @since 4.0.0
  */
 export const SqlErrorReason: Schema.Union<[
@@ -377,6 +390,7 @@ export const SqlErrorReason: Schema.Union<[
  * Top-level SQL error wrapper whose `message`, `cause`, and `isRetryable`
  * values are derived from its `SqlErrorReason`.
  *
+ * @category errors
  * @since 4.0.0
  */
 export class SqlError extends Schema.TaggedErrorClass<SqlError>("effect/sql/SqlError")("SqlError", {
@@ -418,6 +432,7 @@ export class SqlError extends Schema.TaggedErrorClass<SqlError>("effect/sql/SqlE
 /**
  * Returns `true` when a value is a `SqlError`.
  *
+ * @category guards
  * @since 4.0.0
  */
 export const isSqlError = (u: unknown): u is SqlError => Predicate.hasProperty(u, TypeId)
@@ -425,6 +440,7 @@ export const isSqlError = (u: unknown): u is SqlError => Predicate.hasProperty(u
 /**
  * Returns `true` when a value is a `SqlErrorReason`.
  *
+ * @category guards
  * @since 4.0.0
  */
 export const isSqlErrorReason = (u: unknown): u is SqlErrorReason => Predicate.hasProperty(u, ReasonTypeId)
@@ -500,6 +516,7 @@ const sqliteUniqueConstraintFromCause = (cause: unknown): string => {
  * Classifies a native SQLite error cause into a `SqlErrorReason` using its
  * `code` or `errno`, with optional message and operation metadata.
  *
+ * @category converting
  * @since 4.0.0
  */
 export const classifySqliteError = (
@@ -562,6 +579,7 @@ export const classifySqliteError = (
  * Error raised when an ordered batched SQL resolver receives a different number
  * of result rows than requests.
  *
+ * @category errors
  * @since 4.0.0
  */
 export class ResultLengthMismatch

package/src/unstable/sql/SqlModel.ts

@@ -16,7 +16,6 @@
  * directly; MySQL performs a follow-up `select`, so generated ids, defaults,
  * and trigger-updated values must be observable from that query.
  *
- * @category models
  * @since 4.0.0
  */
 import type * as Cause from "../../Cause.ts"

package/src/unstable/sql/SqlSchema.ts

@@ -29,7 +29,7 @@ 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.
  *
- * @category constructor
+ * @category constructors
  * @since 4.0.0
  */
 export const findAll = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
@@ -53,7 +53,7 @@ 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.
  *
- * @category constructor
+ * @category constructors
  * @since 4.0.0
  */
 export const findNonEmpty = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
@@ -93,7 +93,7 @@ export {
   /**
    * Run a sql query with a request schema and discard the result.
    *
-   * @category constructor
+   * @category constructors
    * @since 4.0.0
    */
   void_ as void
@@ -103,7 +103,7 @@ export {
  * Builds a query function that encodes the request, decodes the first result
  * row, and fails with `NoSuchElementError` when no rows are returned.
  *
- * @category constructor
+ * @category constructors
  * @since 4.0.0
  */
 export const findOne = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
@@ -136,7 +136,7 @@ export const findOne = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
  * Builds a query function that encodes the request, decodes the first result row
  * as `Option.some`, and returns `Option.none` when no rows are returned.
  *
- * @category constructor
+ * @category constructors
  * @since 4.0.0
  */
 export const findOneOption = <Req extends Schema.Top, Res extends Schema.Top, E, R>(

package/src/unstable/sql/SqlStream.ts

@@ -31,6 +31,7 @@ import * as Stream from "../../Stream.ts"
  * Creates a stream from a callback-style producer with pause and resume
  * callbacks that are triggered when the internal queue applies backpressure.
  *
+ * @category constructors
  * @since 4.0.0
  */
 export const asyncPauseResume = <A, E = never, R = never>(

package/src/unstable/sql/Statement.ts

@@ -38,7 +38,7 @@ const FragmentTypeId = "~effect/sql/Fragment"
  * Composable SQL fragment represented as low-level segments that can be
  * interpolated into statements.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface Fragment {
@@ -62,7 +62,7 @@ export const fragment = (
 /**
  * Supported SQL dialect identifiers used by statement compilers.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export type Dialect = "sqlite" | "pg" | "mysql" | "mssql" | "clickhouse"
@@ -72,7 +72,7 @@ export type Dialect = "sqlite" | "pg" | "mysql" | "mssql" | "clickhouse"
  * for raw execution, streaming, value rows, unprepared execution, no-transform
  * execution, and compilation.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface Statement<A> extends Fragment, Effect.Effect<ReadonlyArray<A>, SqlError> {
@@ -91,7 +91,7 @@ export interface Statement<A> extends Fragment, Effect.Effect<ReadonlyArray<A>,
  * Hook that can rewrite or wrap a `Statement` before execution, using the
  * current SQL constructor, fiber, and tracing span.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export type Transformer = (
@@ -134,7 +134,7 @@ export const isCustom = <A extends Custom<any, any, any, any>>(
 /**
  * Union of low-level segment types that make up a SQL `Fragment`.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export type Segment =
@@ -151,7 +151,7 @@ export type Segment =
  * Raw SQL literal segment. The literal text is inserted directly into the
  * compiled SQL, while optional `params` are appended as bind parameters.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface Literal {
@@ -176,7 +176,7 @@ export const literal = (value: string, params?: ReadonlyArray<unknown> | undefin
 /**
  * SQL identifier segment whose value is escaped by the active dialect compiler.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface Identifier {
@@ -200,7 +200,7 @@ export const identifier = (value: string): Identifier => ({
  * Bound parameter segment whose value is emitted as a dialect-specific
  * placeholder and bind value.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface Parameter {
@@ -223,7 +223,7 @@ export const parameter = (value: unknown): Parameter => ({
  * Helper segment for compiling an array of values, commonly used to produce
  * placeholder lists for `IN` clauses.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface ArrayHelper {
@@ -246,7 +246,7 @@ export const arrayHelper = (value: ReadonlyArray<unknown | Fragment>): ArrayHelp
  * Helper segment for compiling one or more record objects into an INSERT
  * column/value clause, with optional returning output.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface RecordInsertHelper {
@@ -286,7 +286,7 @@ export const recordInsertHelper = (
  * Helper segment for compiling multi-row update values with a table alias and
  * optional returning output.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface RecordUpdateHelper {
@@ -324,7 +324,7 @@ export const recordUpdateHelper = (
  * Helper segment for compiling a single record into update assignments,
  * omitting selected columns and optionally returning output.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface RecordUpdateHelperSingle {
@@ -362,7 +362,7 @@ export const recordUpdateHelperSingle = (
  * Custom SQL segment identified by `kind` and interpreted by the compiler's
  * `onCustom` callback.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface Custom<
@@ -382,7 +382,7 @@ export interface Custom<
  * Creates a constructor for custom SQL segments of a specific kind handled by
  * the active compiler.
  *
- * @category constructor
+ * @category constructors
  * @since 4.0.0
  */
 export const custom = <C extends Custom<any, any, any, any>>(
@@ -398,7 +398,7 @@ export const custom = <C extends Custom<any, any, any, any>>(
  * Names the primitive value categories recognized by SQL statement helpers and
  * `primitiveKind`.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export type PrimitiveKind =
@@ -414,7 +414,7 @@ export type PrimitiveKind =
 /**
  * Union of helper segment types accepted by the SQL statement constructor.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export type Helper =
@@ -431,7 +431,7 @@ export type Helper =
  * dialect-specific branches. Raw helpers such as `unsafe` and `literal` insert
  * SQL text directly.
  *
- * @category model
+ * @category models
  * @since 4.0.0
  */
 export interface Constructor {
@@ -528,7 +528,7 @@ export interface Constructor {
  * Creates a cached SQL statement constructor from a connection acquirer,
  * compiler, tracing attributes, and optional row transformation function.
  *
- * @category constructor
+ * @category constructors
  * @since 4.0.0
  */
 export const make = (
@@ -651,7 +651,7 @@ export const statement = <A = Row>(
  * wrapping multiple clauses in parentheses and using a fallback for an empty
  * list.
  *
- * @category constructor
+ * @category constructors
  * @since 4.0.0
  */
 export function join(lit: string, addParens = true, fallback = "") {
@@ -690,7 +690,7 @@ export function join(lit: string, addParens = true, fallback = "") {
  * Combines clauses with `AND`, parenthesizing multiple clauses and returning
  * `1=1` when the list is empty.
  *
- * @category constructor
+ * @category constructors
  * @since 4.0.0
  */
 export const and: (clauses: ReadonlyArray<string | Fragment>) => Fragment = join(" AND ", true, "1=1")
@@ -699,7 +699,7 @@ export const and: (clauses: ReadonlyArray<string | Fragment>) => Fragment = join
  * Combines clauses with `OR`, parenthesizing multiple clauses and returning
  * `1=1` when the list is empty.
  *
- * @category constructor
+ * @category constructors
  * @since 4.0.0
  */
 export const or: (clauses: ReadonlyArray<string | Fragment>) => Fragment = join(" OR ", true, "1=1")
@@ -708,7 +708,7 @@ export const or: (clauses: ReadonlyArray<string | Fragment>) => Fragment = join(
  * Creates a comma-separated SQL fragment from values, optionally adding a
  * prefix, and returns an empty fragment when no values are provided.
  *
- * @category constructor
+ * @category constructors
  * @since 4.0.0
  */
 export const csv: {
@@ -716,7 +716,7 @@ export const csv: {
    * Creates a comma-separated SQL fragment from values, optionally adding a
    * prefix, and returns an empty fragment when no values are provided.
    *
-   * @category constructor
+   * @category constructors
    * @since 4.0.0
    */
   (values: ReadonlyArray<string | Fragment>): Fragment
@@ -724,7 +724,7 @@ export const csv: {
    * Creates a comma-separated SQL fragment from values, optionally adding a
    * prefix, and returns an empty fragment when no values are provided.
    *
-   * @category constructor
+   * @category constructors
    * @since 4.0.0
    */
   (prefix: string, values: ReadonlyArray<string | Fragment>): Fragment
@@ -1092,6 +1092,7 @@ export const makeCompilerSqlite = (transform?: ((_: string) => string) | undefin
  * delimiter, doubles delimiter characters, and escapes dots between identifier
  * parts.
  *
+ * @category constructors
  * @since 4.0.0
  */
 export function defaultEscape(c: string) {
@@ -1107,6 +1108,7 @@ export function defaultEscape(c: string) {
  * Classifies a JavaScript value as a SQL primitive kind, treating `undefined`
  * as `null` and defaulting unrecognized objects to `string`.
  *
+ * @category predicates
  * @since 4.0.0
  */
 export const primitiveKind = (value: unknown): PrimitiveKind => {
@@ -1140,6 +1142,7 @@ export const primitiveKind = (value: unknown): PrimitiveKind => {
  * Builds value, object, and row-array transformers that rename object keys with
  * the supplied function and optionally recurse into nested object arrays.
  *
+ * @category transforming
  * @since 4.0.0
  */
 export const defaultTransforms = (