effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/sql/index.ts

@@ -5,47 +5,225 @@
 // @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"
 
 /**
- * @since 4.0.0
+ * 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.
+ *
  * @category models
+ * @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

@@ -1,5 +1,21 @@
 /**
- * @since 1.0.0
+ * 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
  */
 import * as Context from "../../Context.ts"
 import * as Effect from "../../Effect.ts"
@@ -8,8 +24,11 @@ import * as Schema from "../../Schema.ts"
 import * as Getter from "../../SchemaGetter.ts"
 
 /**
- * @since 1.0.0
+ * Service for collecting `Transferable` objects while encoding worker messages
+ * so they can be passed to `postMessage` transfer lists.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class Collector extends Context.Service<Collector, {
   readonly addAll: (
@@ -23,8 +42,11 @@ export class Collector extends Context.Service<Collector, {
 }>()("effect/workers/Transferable/Collector") {}
 
 /**
- * @since 1.0.0
+ * Creates a mutable `Collector` service directly, exposing unsafe synchronous
+ * methods for reading, adding, and clearing collected transferables.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeCollectorUnsafe = (): Collector["Service"] => {
   let tranferables: Array<globalThis.Transferable> = []
@@ -48,14 +70,20 @@ export const makeCollectorUnsafe = (): Collector["Service"] => {
 }
 
 /**
- * @since 1.0.0
+ * Effect that creates a fresh `Collector` service for accumulating
+ * transferables.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeCollector: Effect.Effect<Collector["Service"]> = Effect.sync(makeCollectorUnsafe)
 
 /**
- * @since 1.0.0
+ * Adds transferables to the current `Collector` when one is present in the
+ * context, and does nothing otherwise.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export const addAll = (
   tranferables: Iterable<globalThis.Transferable>
@@ -68,8 +96,11 @@ export const addAll = (
   })
 
 /**
- * @since 1.0.0
+ * Creates a schema getter that records transferables derived from a value in
+ * the current `Collector` while passing the value through unchanged.
+ *
  * @category Getter
+ * @since 4.0.0
  */
 export const getterAddAll = <A>(
   f: (_: A) => Iterable<globalThis.Transferable>
@@ -84,8 +115,11 @@ export const getterAddAll = <A>(
   )
 
 /**
- * @since 1.0.0
- * @category schema
+ * Schema wrapper whose encode path can record transferables with a `Collector`
+ * while preserving the wrapped schema's decoded type.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export interface Transferable<S extends Schema.Top> extends
   Schema.decodeTo<
@@ -95,18 +129,27 @@ export interface Transferable<S extends Schema.Top> extends
 {}
 
 /**
- * @since 1.0.0
- * @category schema
+ * Wraps a schema so encoding records transferables selected from the encoded
+ * value, enabling worker messages to populate a `postMessage` transfer list.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const schema: {
   /**
-   * @since 1.0.0
-   * @category schema
+   * Wraps a schema so encoding records transferables selected from the encoded
+   * value, enabling worker messages to populate a `postMessage` transfer list.
+   *
+   * @category schemas
+   * @since 4.0.0
    */
   <S extends Schema.Top>(f: (_: S["Encoded"]) => Iterable<globalThis.Transferable>): (self: S) => Transferable<S>
   /**
-   * @since 1.0.0
-   * @category schema
+   * Wraps a schema so encoding records transferables selected from the encoded
+   * value, enabling worker messages to populate a `postMessage` transfer list.
+   *
+   * @category schemas
+   * @since 4.0.0
    */
   <S extends Schema.Top>(self: S, f: (_: S["Encoded"]) => Iterable<globalThis.Transferable>): Transferable<S>
 } = dual(
@@ -131,8 +174,11 @@ const passthroughLink = Schema.link()(Schema.Any, {
 })
 
 /**
- * @since 1.0.0
- * @category schema
+ * Transferable schema for `ImageData` values that records the underlying pixel
+ * data buffer.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const ImageData: Transferable<Schema.declare<ImageData>> = schema(
   Schema.Any as any as Schema.declare<globalThis.ImageData>,
@@ -140,8 +186,11 @@ export const ImageData: Transferable<Schema.declare<ImageData>> = schema(
 )
 
 /**
- * @since 1.0.0
- * @category schema
+ * Transferable schema for `MessagePort` values that records the port itself as
+ * transferable.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const MessagePort: Transferable<Schema.declare<MessagePort>> = schema(
   Schema.Any as any as Schema.declare<MessagePort>,
@@ -149,8 +198,11 @@ export const MessagePort: Transferable<Schema.declare<MessagePort>> = schema(
 )
 
 /**
- * @since 1.0.0
- * @category schema
+ * Transferable schema for `Uint8Array` values that records the array's backing
+ * buffer.
+ *
+ * @category schemas
+ * @since 4.0.0
  */
 export const Uint8Array: Transferable<Schema.instanceOf<globalThis.Uint8Array<ArrayBuffer>>> = schema(
   Schema.Uint8Array as any,

package/src/unstable/workers/Worker.ts

@@ -1,4 +1,28 @@
 /**
+ * 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
  */
 import * as Context from "../../Context.ts"
@@ -11,8 +35,11 @@ import * as Scope from "../../Scope.ts"
 import { WorkerError, WorkerSendError } from "./WorkerError.ts"
 
 /**
- * @since 4.0.0
+ * Service that spawns effect `Worker` instances for numeric worker ids using
+ * the configured `Spawner`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class WorkerPlatform extends Context.Service<WorkerPlatform, {
   readonly spawn: <O = unknown, I = unknown>(
@@ -21,8 +48,12 @@ export class WorkerPlatform extends Context.Service<WorkerPlatform, {
 }>()("effect/workers/Worker/WorkerPlatform") {}
 
 /**
- * @since 4.0.0
+ * Effect-based worker abstraction that can send input messages and run a
+ * long-lived handler for output messages, failing with `WorkerError` or handler
+ * errors.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Worker<O = unknown, I = unknown> {
   readonly send: (
@@ -40,8 +71,12 @@ export interface Worker<O = unknown, I = unknown> {
 }
 
 /**
- * @since 4.0.0
+ * Wraps platform-specific send and run functions into a `Worker`, translating
+ * platform ready/data messages and running the optional `onSpawn` effect when
+ * the worker reports readiness.
+ *
  * @category models
+ * @since 4.0.0
  */
 export const makeUnsafe = (options: {
   readonly send: (
@@ -63,22 +98,30 @@ export const makeUnsafe = (options: {
 })
 
 /**
- * @since 4.0.0
+ * Internal worker platform protocol message: `[0]` signals readiness and
+ * `[1, payload]` carries data.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type PlatformMessage = readonly [ready: 0] | readonly [data: 1, unknown]
 
 /**
- * @since 4.0.0
+ * Phantom identifier for the service that maps worker ids to platform-specific
+ * worker instances.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Spawner {
   readonly _: unique symbol
 }
 
 /**
- * @since 4.0.0
+ * Context service tag for the worker `SpawnerFn`.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export const Spawner: Context.Service<
   Spawner,
@@ -86,22 +129,32 @@ export const Spawner: Context.Service<
 > = Context.Service("effect/workers/Worker/Spawner")
 
 /**
- * @since 4.0.0
+ * Function that creates or locates a platform-specific worker instance for a
+ * numeric worker id.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface SpawnerFn<W = unknown> {
   (id: number): W
 }
 
 /**
- * @since 4.0.0
+ * Creates a layer that provides a worker `Spawner` service from a `SpawnerFn`.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerSpawner: <W = unknown>(
   spawner: SpawnerFn<W>
 ) => Layer.Layer<Spawner> = Layer.succeed(Spawner)
 
 /**
+ * Creates a `WorkerPlatform` from platform-specific setup and listen hooks,
+ * 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

@@ -1,4 +1,23 @@
 /**
+ * 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
  */
 import { hasProperty } from "../../Predicate.ts"
@@ -7,20 +26,26 @@ import * as Schema from "../../Schema.ts"
 const TypeId = "~effect/workers/WorkerError" as const
 
 /**
- * @since 4.0.0
+ * Type-level identifier used to brand `WorkerError` values.
+ *
  * @category Symbols
+ * @since 4.0.0
  */
 export type TypeId = typeof TypeId
 
 /**
+ * Returns `true` when a value is a `WorkerError`.
+ *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export const isWorkerError = (u: unknown): u is WorkerError => hasProperty(u, TypeId)
 
 /**
+ * Worker error reason for failures while spawning or setting up a worker.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export class WorkerSpawnError extends Schema.ErrorClass<WorkerSpawnError>(
   "effect/workers/WorkerError/WorkerSpawnError"
@@ -31,8 +56,10 @@ export class WorkerSpawnError extends Schema.ErrorClass<WorkerSpawnError>(
 }) {}
 
 /**
+ * Worker error reason for failures while sending a message to a worker.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export class WorkerSendError extends Schema.ErrorClass<WorkerSendError>(
   "effect/workers/WorkerError/WorkerSendError"
@@ -43,8 +70,11 @@ export class WorkerSendError extends Schema.ErrorClass<WorkerSendError>(
 }) {}
 
 /**
+ * Worker error reason for failures while receiving or handling a message from a
+ * worker.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export class WorkerReceiveError extends Schema.ErrorClass<WorkerReceiveError>(
   "effect/workers/WorkerError/WorkerReceiveError"
@@ -55,8 +85,10 @@ export class WorkerReceiveError extends Schema.ErrorClass<WorkerReceiveError>(
 }) {}
 
 /**
+ * Worker error reason for an unclassified worker failure.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export class WorkerUnknownError extends Schema.ErrorClass<WorkerUnknownError>(
   "effect/workers/WorkerError/WorkerUnknownError"
@@ -67,8 +99,10 @@ export class WorkerUnknownError extends Schema.ErrorClass<WorkerUnknownError>(
 }) {}
 
 /**
+ * Union of the specific failure reasons that can be wrapped by a `WorkerError`.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type WorkerErrorReason =
   | WorkerSpawnError
@@ -77,8 +111,10 @@ export type WorkerErrorReason =
   | WorkerUnknownError
 
 /**
+ * Schema for decoding and encoding all supported worker error reason variants.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export const WorkerErrorReason: Schema.Union<[
   typeof WorkerSpawnError,
@@ -93,8 +129,11 @@ export const WorkerErrorReason: Schema.Union<[
 ])
 
 /**
+ * Error raised by worker APIs, wrapping a specific `WorkerErrorReason` and
+ * exposing its message and cause.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export class WorkerError extends Schema.ErrorClass<WorkerError>(TypeId)({
   _tag: Schema.tag("WorkerError"),
@@ -110,6 +149,8 @@ export class WorkerError extends Schema.ErrorClass<WorkerError>(TypeId)({
     } as any)
   }
   /**
+   * Marks this value as a worker error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId]: TypeId = TypeId