effect 4.0.0-beta.67 → 4.0.0-beta.69

package/src/unstable/sql/index.ts

@@ -5,47 +5,224 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
+ * Effect SQL migration helpers for loading, ordering, and running schema
+ * changes against a `SqlClient`.
+ *
+ * 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.
+ *
+ * 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.
+ *
  * @since 4.0.0
  */
 export * as Migrator from "./Migrator.ts"
 
 /**
+ * Defines the `SqlClient` service, the central runtime entry point for Effect's
+ * unstable SQL support.
+ *
+ * A `SqlClient` combines the tagged-template statement constructor with a
+ * scoped connection acquirer, dialect compiler, tracing attributes, optional row
+ * transforms, reactive query helpers, and transaction management. Applications
+ * typically consume it from `Context` to build parameterized queries, stream
+ * rows, run raw driver operations, reserve a connection for lower-level work, or
+ * wrap several query effects in `withTransaction`.
+ *
+ * Transactions are tracked through a per-client context service. Top-level
+ * transactions acquire the configured transaction connection and issue the
+ * dialect's begin/commit/rollback SQL; nested transactions reuse that
+ * connection and rely on dialect-provided savepoint SQL. A query only joins a
+ * transaction when it is run with the same client service, so avoid mixing
+ * clients or manually reserved connections when atomicity matters. Dialect
+ * integrations are also responsible for the compiler and transaction
+ * statements, which means placeholder syntax, identifier escaping, row
+ * transforms, savepoint support, and unprepared/raw statement behavior can
+ * differ by database.
+ *
  * @since 4.0.0
  */
 export * as SqlClient from "./SqlClient.ts"
 
 /**
+ * Defines the low-level SQL connection service and shared row/acquirer types
+ * used by Effect's unstable SQL driver integrations.
+ *
+ * A `Connection` is the driver-facing layer underneath `SqlClient`: it executes
+ * already-compiled SQL with positional parameters and exposes transformed row
+ * results, raw driver results, streams, value arrays, and unprepared statement
+ * execution. Most applications should work through `SqlClient`, while driver
+ * integrations and advanced code use this module to provide scoped connection
+ * acquisition, implement pooling, reserve a connection for a workflow, or adapt
+ * a dialect-specific client into Effect.
+ *
+ * Connections are resources and should be acquired through an `Acquirer` in a
+ * `Scope` so pool checkout, transaction pinning, and release semantics are
+ * preserved. Transaction coordination lives at the `SqlClient` layer, so mixing
+ * manually reserved connections with transactional client queries can bypass the
+ * expected atomic boundary. Raw, unprepared, streaming, parameter, and row
+ * transformation behavior ultimately comes from the driver and dialect; check
+ * each integration for differences in placeholders, prepared statement support,
+ * cursor lifetime, and result shapes.
+ *
  * @since 4.0.0
  */
 export * as SqlConnection from "./SqlConnection.ts"
 
 /**
+ * Structured SQL errors used by the unstable SQL APIs.
+ *
+ * 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.
+ *
+ * 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.
+ *
  * @since 4.0.0
  */
 export * as SqlError from "./SqlError.ts"
 
 /**
- * @category models
+ * Builds SQL repositories and request resolvers from Effect schema models.
+ *
+ * Use this module when a `Model` describes rows in a concrete SQL table and
+ * you want the common insert, update, find-by-id, and delete operations without
+ * hand-writing the schema encoding, row decoding, and resolver batching each
+ * time. The helpers are intended for model-backed tables where the model field
+ * names line up with the encoded table columns and the chosen `idColumn` is
+ * present in both the model fields and update schema.
+ *
+ * Returned rows are decoded with the full model schema, while insert and update
+ * requests are encoded with the model's dedicated input schemas. Soft deletes
+ * are opt-in via `softDeleteColumn`: reads and updates only see rows where that
+ * column is `null`, and deletes set it to `CURRENT_TIMESTAMP` instead of
+ * removing the row. Dialects with `returning` support return changed rows
+ * directly; MySQL performs a follow-up `select`, so generated ids, defaults,
+ * and trigger-updated values must be observable from that query.
+ *
  * @since 4.0.0
  */
 export * as SqlModel from "./SqlModel.ts"
 
 /**
+ * Schema-aware `RequestResolver` helpers for SQL-backed data loading.
+ *
+ * This module bridges `Effect.request` with `SqlClient` by representing each
+ * lookup or mutation as a `SqlRequest` and batching concurrent requests into a
+ * single SQL operation. Request payloads are encoded with the request schema
+ * before `execute` is called, and rows returned by the query are decoded with
+ * the result schema before entries are completed.
+ *
+ * Use `ordered` when a query returns exactly one row per request in the same
+ * order, `findById` for `where id in (...)` lookups, `grouped` for one-to-many
+ * relationships, and `void` for inserts, updates, deletes, or other
+ * side-effecting statements where no row is needed.
+ *
+ * **Gotchas**
+ *
+ * - `ordered` requires the result count and order to match the request batch.
+ * - `grouped` and `findById` rely on stable request/result keys and fail
+ *   missing requests with `NoSuchElementError`.
+ * - Equal payloads are equal `SqlRequest`s, which enables request batching,
+ *   deduplication, and cache reuse; model payload identity deliberately.
+ * - Batches are split by the active SQL transaction connection, so requests
+ *   made in different transactions are not resolved together.
+ * - Queries like `where id in (...)` often return rows in database order; use
+ *   `findById` or `grouped`, or preserve input order explicitly before choosing
+ *   `ordered`.
+ *
  * @since 4.0.0
  */
 export * as SqlResolver from "./SqlResolver.ts"
 
 /**
+ * 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.
+ *
  * @since 4.0.0
  */
 export * as SqlSchema from "./SqlSchema.ts"
 
 /**
+ * Low-level helpers for adapting push-based SQL row sources into Effect
+ * streams.
+ *
+ * SQL drivers often expose large query results through cursors, event emitters,
+ * or driver-specific streams that push rows as they arrive. This module
+ * provides the small interop layer used by SQL integrations to turn those
+ * producers into `Stream` values for `Statement.stream` and
+ * `Connection.executeStream`, so callers can process large result sets
+ * incrementally instead of materializing every row in memory.
+ *
+ * The adapter is scoped: driver cursors, query streams, or reserved
+ * connections should be acquired in the registration effect and released with
+ * finalizers. The internal queue is bounded and calls the producer's
+ * `onPause`/`onResume` hooks when downstream consumption falls behind, but the
+ * underlying driver still has to honor those hooks for backpressure to be
+ * effective. Slow consumers may keep a database cursor and connection open for
+ * the lifetime of the stream, so integrations should close or destroy driver
+ * resources on interruption, failure, or normal completion and should signal
+ * terminal events with `fail` or `end` exactly once.
+ *
  * @since 4.0.0
  */
 export * as SqlStream from "./SqlStream.ts"
 
 /**
+ * Building blocks for Effect's unstable SQL statement API.
+ *
+ * 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.
+ *
+ * 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.
+ *
  * @since 4.0.0
  */
 export * as Statement from "./Statement.ts"

package/src/unstable/workers/Transferable.ts

@@ -118,7 +118,7 @@ export const getterAddAll = <A>(
  * Schema wrapper whose encode path can record transferables with a `Collector`
  * while preserving the wrapped schema's decoded type.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export interface Transferable<S extends Schema.Top> extends
@@ -132,7 +132,7 @@ export interface Transferable<S extends Schema.Top> extends
  * Wraps a schema so encoding records transferables selected from the encoded
  * value, enabling worker messages to populate a `postMessage` transfer list.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schema: {
@@ -140,7 +140,7 @@ export const schema: {
    * Wraps a schema so encoding records transferables selected from the encoded
    * value, enabling worker messages to populate a `postMessage` transfer list.
    *
-   * @category schema
+   * @category schemas
    * @since 4.0.0
    */
   <S extends Schema.Top>(f: (_: S["Encoded"]) => Iterable<globalThis.Transferable>): (self: S) => Transferable<S>
@@ -148,7 +148,7 @@ export const schema: {
    * Wraps a schema so encoding records transferables selected from the encoded
    * value, enabling worker messages to populate a `postMessage` transfer list.
    *
-   * @category schema
+   * @category schemas
    * @since 4.0.0
    */
   <S extends Schema.Top>(self: S, f: (_: S["Encoded"]) => Iterable<globalThis.Transferable>): Transferable<S>
@@ -177,7 +177,7 @@ const passthroughLink = Schema.link()(Schema.Any, {
  * Transferable schema for `ImageData` values that records the underlying pixel
  * data buffer.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const ImageData: Transferable<Schema.declare<ImageData>> = schema(
@@ -189,7 +189,7 @@ export const ImageData: Transferable<Schema.declare<ImageData>> = schema(
  * Transferable schema for `MessagePort` values that records the port itself as
  * transferable.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const MessagePort: Transferable<Schema.declare<MessagePort>> = schema(
@@ -201,7 +201,7 @@ export const MessagePort: Transferable<Schema.declare<MessagePort>> = schema(
  * Transferable schema for `Uint8Array` values that records the array's backing
  * buffer.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const Uint8Array: Transferable<Schema.instanceOf<globalThis.Uint8Array<ArrayBuffer>>> = schema(

package/src/unstable/workers/Worker.ts

@@ -154,6 +154,7 @@ export const layerSpawner: <W = unknown>(
  * buffering sent messages until the worker is ready and scoping port cleanup to
  * the worker run.
  *
+ * @category constructors
  * @since 4.0.0
  */
 export const makePlatform = <W>() =>

package/src/unstable/workers/WorkerError.ts

@@ -36,7 +36,7 @@ export type TypeId = typeof TypeId
 /**
  * Returns `true` when a value is a `WorkerError`.
  *
- * @category Guards
+ * @category guards
  * @since 4.0.0
  */
 export const isWorkerError = (u: unknown): u is WorkerError => hasProperty(u, TypeId)
@@ -44,7 +44,7 @@ export const isWorkerError = (u: unknown): u is WorkerError => hasProperty(u, Ty
 /**
  * Worker error reason for failures while spawning or setting up a worker.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export class WorkerSpawnError extends Schema.ErrorClass<WorkerSpawnError>(
@@ -58,7 +58,7 @@ export class WorkerSpawnError extends Schema.ErrorClass<WorkerSpawnError>(
 /**
  * Worker error reason for failures while sending a message to a worker.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export class WorkerSendError extends Schema.ErrorClass<WorkerSendError>(
@@ -73,7 +73,7 @@ export class WorkerSendError extends Schema.ErrorClass<WorkerSendError>(
  * Worker error reason for failures while receiving or handling a message from a
  * worker.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export class WorkerReceiveError extends Schema.ErrorClass<WorkerReceiveError>(
@@ -87,7 +87,7 @@ export class WorkerReceiveError extends Schema.ErrorClass<WorkerReceiveError>(
 /**
  * Worker error reason for an unclassified worker failure.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export class WorkerUnknownError extends Schema.ErrorClass<WorkerUnknownError>(
@@ -101,7 +101,7 @@ export class WorkerUnknownError extends Schema.ErrorClass<WorkerUnknownError>(
 /**
  * Union of the specific failure reasons that can be wrapped by a `WorkerError`.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export type WorkerErrorReason =
@@ -113,7 +113,7 @@ export type WorkerErrorReason =
 /**
  * Schema for decoding and encoding all supported worker error reason variants.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export const WorkerErrorReason: Schema.Union<[
@@ -132,7 +132,7 @@ export const WorkerErrorReason: Schema.Union<[
  * Error raised by worker APIs, wrapping a specific `WorkerErrorReason` and
  * exposing its message and cause.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export class WorkerError extends Schema.ErrorClass<WorkerError>(TypeId)({

package/src/unstable/workers/index.ts

@@ -5,21 +5,101 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
+ * Utilities for marking the parts of worker messages that should be transferred
+ * through `postMessage` instead of copied by the structured clone algorithm.
+ *
+ * This module is used with worker message schemas to collect
+ * `globalThis.Transferable` values while encoding a message, so the worker
+ * platform can pass the collected list as the `postMessage` transfer list.
+ * Common cases include sending large `Uint8Array` payloads, `ImageData` pixel
+ * buffers, or `MessagePort` channels without paying for an extra copy.
+ *
+ * Transferable annotations do not make an otherwise unsupported value
+ * structured-cloneable; the encoded message still has to be valid for
+ * `postMessage`. Transferring also moves ownership to the receiver, so buffers
+ * are detached from the sender after the send completes. Be careful when a
+ * typed array view shares a backing buffer with other data, since collecting
+ * that buffer transfers ownership of the whole buffer.
+ *
  * @since 4.0.0
  */
 export * as Transferable from "./Transferable.ts"
 
 /**
+ * Client-side worker primitives shared by browser, Node, and Bun platform
+ * packages.
+ *
+ * A `WorkerPlatform` turns a numeric worker id into a long-lived `Worker`
+ * client using a runtime-specific `Spawner`. This module is the low-level
+ * building block used by worker-backed RPC clients and by platform adapters
+ * that need to communicate with dedicated workers, shared workers,
+ * `MessagePort`s, worker threads, or child-process transports while keeping
+ * setup, message handling, and cleanup inside `Effect` scopes.
+ *
+ * The worker protocol separates spawning from message delivery. Calls to
+ * `send` made before the platform reports readiness are buffered and flushed
+ * after `run` receives the ready signal, so a spawned worker must eventually be
+ * run or buffered messages will never leave the client. Message values are
+ * passed through `postMessage`, which means callers are responsible for
+ * encoding payloads into values supported by the selected runtime's structured
+ * clone implementation. Transfer lists can avoid copies for buffers, ports, or
+ * other transferable values, but ownership moves to the worker and invalid
+ * transfer lists surface as `WorkerSendError`s. Incoming messages are handled
+ * by forking each handler invocation into the worker run's `FiberSet`, so
+ * processing is concurrent rather than serialized; use an explicit queue,
+ * semaphore, or protocol-level acknowledgement when ordering or back pressure
+ * matters.
+ *
  * @since 4.0.0
  */
 export * as Worker from "./Worker.ts"
 
 /**
+ * Typed error definitions for the unstable worker APIs.
+ *
+ * `WorkerError` is the shared error channel for `WorkerPlatform` and
+ * `WorkerRunnerPlatform` implementations. The nested reason identifies where a
+ * platform failure happened: spawning or setting up a worker, sending through
+ * `postMessage`, receiving worker events, or handling a runtime-specific
+ * failure that does not fit the other categories. This is useful when building
+ * worker-backed RPC clients and servers, implementing a platform adapter, or
+ * recovering differently from startup, transport, and worker-exit failures.
+ *
+ * Worker transports cross browser, Node, Bun, and child-process runtimes, so the
+ * original cause is best treated as diagnostic data. Spawn failures can mean the
+ * runner is not actually executing inside a worker context, send failures often
+ * come from structured-clone or transfer-list problems, and receive failures
+ * may be reported as `messageerror`, `error`, or exit events depending on the
+ * runtime. The `WorkerErrorReason` schema supports encoding and decoding the
+ * tagged reasons, but message payloads still need to be valid for the selected
+ * worker protocol and runtime.
+ *
  * @since 4.0.0
  */
 export * as WorkerError from "./WorkerError.ts"
 
 /**
+ * Server-side worker runner primitives shared by the browser, Node, and Bun
+ * platform packages.
+ *
+ * A `WorkerRunnerPlatform` is installed in code that is already running inside
+ * a worker-like runtime. Starting it yields a `WorkerRunner`, which listens for
+ * parent or client requests, identifies each connection with a numeric port id,
+ * and sends responses back through the same transport. The main Effect use case
+ * is `RpcServer.layerProtocolWorkerRunner`, but platform adapters can also use
+ * these types to expose lower-level request handlers for dedicated workers,
+ * shared workers, worker threads, or child-process channels.
+ *
+ * The wire protocol is intentionally small: inbound messages are
+ * `PlatformMessage` values where `[0, payload]` is a request and `[1]` closes a
+ * port. Higher-level protocols are responsible for encoding request and
+ * response payloads before they cross the worker boundary. Values must still be
+ * accepted by the selected runtime's message mechanism, so structured-clone
+ * support, transfer lists, `messageerror` events, and single-port runtimes such
+ * as Node or Bun should be considered when choosing payload schemas and
+ * resource lifetimes. Handler effects run on the runtime captured by `run`, so
+ * services required by the handler must be provided to the running effect.
+ *
  * @since 4.0.0
  */
 export * as WorkerRunner from "./WorkerRunner.ts"

package/src/unstable/workflow/Activity.ts

@@ -43,7 +43,7 @@ const TypeId = "~effect/workflow/Activity"
  * result schemas, annotations, and encoded execution form for the workflow
  * engine.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface Activity<
@@ -100,7 +100,7 @@ export interface Activity<
  * Type-erased activity shape for APIs that only need the activity identity,
  * name, annotations, and encoded execution.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface Any {
@@ -114,7 +114,7 @@ export interface Any {
  * Type-erased activity shape that also exposes success and error schemas for
  * derived workflow APIs.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface AnyWithProps {
@@ -129,7 +129,7 @@ export interface AnyWithProps {
  * Creates a workflow activity from an effect, using the provided schemas to
  * encode successes and failures for durable execution.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const make = <
@@ -214,7 +214,7 @@ const retryOnInterrupt = (
  * Retries an effect with `Effect.retry` while updating `CurrentAttempt` for
  * each attempt.
  *
- * @category Error handling
+ * @category error handling
  * @since 4.0.0
  */
 export const retry: {
@@ -222,7 +222,7 @@ export const retry: {
    * Retries an effect with `Effect.retry` while updating `CurrentAttempt` for
    * each attempt.
    *
-   * @category Error handling
+   * @category error handling
    * @since 4.0.0
    */
   <E, O extends Types.NoExcessProperties<Omit<Effect.Retry.Options<E>, "schedule">, O>>(options: O): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Retry.Return<R, E, A, O>
@@ -230,7 +230,7 @@ export const retry: {
    * Retries an effect with `Effect.retry` while updating `CurrentAttempt` for
    * each attempt.
    *
-   * @category Error handling
+   * @category error handling
    * @since 4.0.0
    */
   <A, E, R, O extends Types.NoExcessProperties<Omit<Effect.Retry.Options<E>, "schedule">, O>>(self: Effect.Effect<A, E, R>, options: O): Effect.Retry.Return<R, E, A, O>

package/src/unstable/workflow/DurableClock.ts

@@ -29,7 +29,7 @@ const TypeId = "~effect/workflow/DurableClock"
  * Represents a durable workflow timer with a name, duration, and deferred
  * completed when the timer wakes.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface DurableClock {
@@ -43,7 +43,7 @@ export interface DurableClock {
  * Creates a durable clock definition and its associated deferred wake-up
  * signal.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const make = (options: {