effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/sql/SqlError.ts

@@ -1,4 +1,22 @@
 /**
+ * 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
  */
 import * as Predicate from "../../Predicate.ts"
@@ -14,6 +32,8 @@ const ReasonFields = {
 }
 
 /**
+ * SQL error reason for connection or open failures; marked retryable.
+ *
  * @since 4.0.0
  */
 export class ConnectionError extends Schema.TaggedErrorClass<ConnectionError>("effect/sql/SqlError/ConnectionError")(
@@ -21,11 +41,15 @@ export class ConnectionError extends Schema.TaggedErrorClass<ConnectionError>("e
   ReasonFields
 ) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -34,17 +58,24 @@ export class ConnectionError extends Schema.TaggedErrorClass<ConnectionError>("e
 }
 
 /**
+ * SQL error reason for authentication failures such as invalid credentials; not
+ * marked retryable.
+ *
  * @since 4.0.0
  */
 export class AuthenticationError extends Schema.TaggedErrorClass<AuthenticationError>(
   "effect/sql/SqlError/AuthenticationError"
 )("AuthenticationError", ReasonFields) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -53,17 +84,24 @@ export class AuthenticationError extends Schema.TaggedErrorClass<AuthenticationE
 }
 
 /**
+ * SQL error reason for authorization or permission failures; not marked
+ * retryable.
+ *
  * @since 4.0.0
  */
 export class AuthorizationError extends Schema.TaggedErrorClass<AuthorizationError>(
   "effect/sql/SqlError/AuthorizationError"
 )("AuthorizationError", ReasonFields) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -72,6 +110,8 @@ export class AuthorizationError extends Schema.TaggedErrorClass<AuthorizationErr
 }
 
 /**
+ * SQL error reason for invalid SQL syntax; not marked retryable.
+ *
  * @since 4.0.0
  */
 export class SqlSyntaxError extends Schema.TaggedErrorClass<SqlSyntaxError>("effect/sql/SqlError/SqlSyntaxError")(
@@ -79,11 +119,15 @@ export class SqlSyntaxError extends Schema.TaggedErrorClass<SqlSyntaxError>("eff
   ReasonFields
 ) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -97,6 +141,9 @@ const UniqueViolationFields = {
 }
 
 /**
+ * SQL error reason for a unique constraint violation, including the violated
+ * constraint identifier; not marked retryable.
+ *
  * @since 4.0.0
  */
 export class UniqueViolation extends Schema.TaggedErrorClass<UniqueViolation>("effect/sql/SqlError/UniqueViolation")(
@@ -104,11 +151,15 @@ export class UniqueViolation extends Schema.TaggedErrorClass<UniqueViolation>("e
   UniqueViolationFields
 ) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -117,6 +168,8 @@ export class UniqueViolation extends Schema.TaggedErrorClass<UniqueViolation>("e
 }
 
 /**
+ * SQL error reason for a non-unique constraint violation; not marked retryable.
+ *
  * @since 4.0.0
  */
 export class ConstraintError extends Schema.TaggedErrorClass<ConstraintError>("effect/sql/SqlError/ConstraintError")(
@@ -124,11 +177,15 @@ export class ConstraintError extends Schema.TaggedErrorClass<ConstraintError>("e
   ReasonFields
 ) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -137,6 +194,8 @@ export class ConstraintError extends Schema.TaggedErrorClass<ConstraintError>("e
 }
 
 /**
+ * SQL error reason for a database deadlock; marked retryable.
+ *
  * @since 4.0.0
  */
 export class DeadlockError extends Schema.TaggedErrorClass<DeadlockError>("effect/sql/SqlError/DeadlockError")(
@@ -144,11 +203,15 @@ export class DeadlockError extends Schema.TaggedErrorClass<DeadlockError>("effec
   ReasonFields
 ) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -157,17 +220,24 @@ export class DeadlockError extends Schema.TaggedErrorClass<DeadlockError>("effec
 }
 
 /**
+ * SQL error reason for a transaction serialization or isolation conflict;
+ * marked retryable.
+ *
  * @since 4.0.0
  */
 export class SerializationError extends Schema.TaggedErrorClass<SerializationError>(
   "effect/sql/SqlError/SerializationError"
 )("SerializationError", ReasonFields) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -176,6 +246,9 @@ export class SerializationError extends Schema.TaggedErrorClass<SerializationErr
 }
 
 /**
+ * SQL error reason for timing out while waiting on a database lock; marked
+ * retryable.
+ *
  * @since 4.0.0
  */
 export class LockTimeoutError extends Schema.TaggedErrorClass<LockTimeoutError>("effect/sql/SqlError/LockTimeoutError")(
@@ -183,11 +256,15 @@ export class LockTimeoutError extends Schema.TaggedErrorClass<LockTimeoutError>(
   ReasonFields
 ) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -196,17 +273,23 @@ export class LockTimeoutError extends Schema.TaggedErrorClass<LockTimeoutError>(
 }
 
 /**
+ * SQL error reason for a statement or query timeout; marked retryable.
+ *
  * @since 4.0.0
  */
 export class StatementTimeoutError extends Schema.TaggedErrorClass<StatementTimeoutError>(
   "effect/sql/SqlError/StatementTimeoutError"
 )("StatementTimeoutError", ReasonFields) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -215,6 +298,8 @@ export class StatementTimeoutError extends Schema.TaggedErrorClass<StatementTime
 }
 
 /**
+ * SQL error reason for an unclassified database failure; not marked retryable.
+ *
  * @since 4.0.0
  */
 export class UnknownError extends Schema.TaggedErrorClass<UnknownError>("effect/sql/SqlError/UnknownError")(
@@ -222,11 +307,15 @@ export class UnknownError extends Schema.TaggedErrorClass<UnknownError>("effect/
   ReasonFields
 ) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -235,6 +324,9 @@ 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.
+ *
  * @since 4.0.0
  */
 export type SqlErrorReason =
@@ -251,6 +343,8 @@ export type SqlErrorReason =
   | UnknownError
 
 /**
+ * Schema union for encoding and decoding `SqlErrorReason` values.
+ *
  * @since 4.0.0
  */
 export const SqlErrorReason: Schema.Union<[
@@ -280,22 +374,31 @@ export const SqlErrorReason: Schema.Union<[
 ])
 
 /**
+ * Top-level SQL error wrapper whose `message`, `cause`, and `isRetryable`
+ * values are derived from its `SqlErrorReason`.
+ *
  * @since 4.0.0
  */
 export class SqlError extends Schema.TaggedErrorClass<SqlError>("effect/sql/SqlError")("SqlError", {
   reason: SqlErrorReason
 }) {
   /**
+   * Marks this value as the top-level SQL error wrapper for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
 
   /**
+   * Exposes the structured SQL reason as the JavaScript error cause.
+   *
    * @since 4.0.0
    */
   override readonly cause = this.reason
 
   /**
+   * Uses the reason message when present, otherwise falls back to the reason tag.
+   *
    * @since 4.0.0
    */
   override get message(): string {
@@ -303,6 +406,8 @@ export class SqlError extends Schema.TaggedErrorClass<SqlError>("effect/sql/SqlE
   }
 
   /**
+   * Delegates retryability to the underlying SQL error reason.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -311,11 +416,15 @@ export class SqlError extends Schema.TaggedErrorClass<SqlError>("effect/sql/SqlE
 }
 
 /**
+ * Returns `true` when a value is a `SqlError`.
+ *
  * @since 4.0.0
  */
 export const isSqlError = (u: unknown): u is SqlError => Predicate.hasProperty(u, TypeId)
 
 /**
+ * Returns `true` when a value is a `SqlErrorReason`.
+ *
  * @since 4.0.0
  */
 export const isSqlErrorReason = (u: unknown): u is SqlErrorReason => Predicate.hasProperty(u, ReasonTypeId)
@@ -388,6 +497,9 @@ 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.
+ *
  * @since 4.0.0
  */
 export const classifySqliteError = (
@@ -447,6 +559,9 @@ export const classifySqliteError = (
 }
 
 /**
+ * Error raised when an ordered batched SQL resolver receives a different number
+ * of result rows than requests.
+ *
  * @since 4.0.0
  */
 export class ResultLengthMismatch
@@ -456,6 +571,8 @@ export class ResultLengthMismatch
   })
 {
   /**
+   * Explains the mismatch between expected and actual batched SQL result counts.
+   *
    * @since 4.0.0
    */
   override get message() {

package/src/unstable/sql/SqlModel.ts

@@ -1,6 +1,23 @@
 /**
- * @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
  */
 import type * as Cause from "../../Cause.ts"
 import * as Effect from "../../Effect.ts"
@@ -14,10 +31,13 @@ import * as SqlResolver from "./SqlResolver.ts"
 import * as SqlSchema from "./SqlSchema.ts"
 
 /**
- * Create a simple CRUD repository from a model.
+ * Creates a CRUD repository for a schema model backed by a SQL table, with
+ * insert, update, find-by-id, and delete operations. When `softDeleteColumn` is
+ * supplied, reads ignore soft-deleted rows and delete updates that column
+ * instead of removing the row.
  *
- * @since 4.0.0
  * @category repository
+ * @since 4.0.0
  */
 export const makeRepository = <
   S extends Model.Any,
@@ -210,10 +230,11 @@ select * from ${sql(options.tableName)} where ${withSoftDeleteFilter(sql`${sql(i
   })
 
 /**
- * Create some simple data loaders from a model.
+ * Creates batched request resolvers for a schema model's insert, insert-void,
+ * find-by-id, and delete operations, honoring the optional soft-delete column.
  *
- * @since 4.0.0
  * @category repository
+ * @since 4.0.0
  */
 export const makeResolvers = <
   S extends Model.Any,

package/src/unstable/sql/SqlResolver.ts

@@ -1,4 +1,30 @@
 /**
+ * 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
  */
 import * as Arr from "../../Array.ts"
@@ -16,8 +42,11 @@ import * as SqlClient from "./SqlClient.ts"
 import { ResultLengthMismatch } from "./SqlError.ts"
 
 /**
- * @since 4.0.0
+ * Request type used by SQL request resolvers, carrying the input payload
+ * together with the resolver's result, error, and environment types.
+ *
  * @category requests
+ * @since 4.0.0
  */
 export interface SqlRequest<In, A, E, R> extends Request.Request<A, E | Schema.SchemaError, R> {
   readonly payload: In
@@ -37,18 +66,27 @@ const SqlRequestProto = {
 }
 
 /**
- * @since 4.0.0
+ * Submits a payload as a `SqlRequest` to a request resolver, either directly
+ * with a payload and resolver or curried by resolver.
+ *
  * @category requests
+ * @since 4.0.0
  */
 export const request: {
   /**
-   * @since 4.0.0
+   * Submits a payload as a `SqlRequest` to a request resolver, either directly
+   * with a payload and resolver or curried by resolver.
+   *
    * @category requests
+   * @since 4.0.0
    */
   <In, A, E, R>(resolver: RequestResolver.RequestResolver<SqlRequest<In, A, E, R>>): (payload: In) => Effect.Effect<A, E | Schema.SchemaError, R>
   /**
-   * @since 4.0.0
+   * Submits a payload as a `SqlRequest` to a request resolver, either directly
+   * with a payload and resolver or curried by resolver.
+   *
    * @category requests
+   * @since 4.0.0
    */
   <In, A, E, R>(
     payload: In,
@@ -63,8 +101,11 @@ export const request: {
 } as any
 
 /**
- * @since 4.0.0
+ * Constructs a `SqlRequest` from a payload. Equality and hashing are based on
+ * the payload so equal requests can be batched and deduplicated.
+ *
  * @category requests
+ * @since 4.0.0
  */
 export const SqlRequest = <In, A, E, R>(payload: In): SqlRequest<In, A, E, R> => {
   const self = Object.create(SqlRequestProto)
@@ -80,8 +121,8 @@ export const SqlRequest = <In, A, E, R>(payload: In): SqlRequest<In, A, E, R> =>
  *
  * Results are mapped to the requests in order, so the length of the results must match the length of the requests.
  *
- * @since 4.0.0
  * @category resolvers
+ * @since 4.0.0
  */
 export const ordered = <Req extends Schema.Top, Res extends Schema.Top, _, E, R>(
   options: {
@@ -124,12 +165,12 @@ export const ordered = <Req extends Schema.Top, Res extends Schema.Top, _, E, R>
 }
 
 /**
- * Create a resolver the can return multiple results for a single request.
+ * Creates a batched SQL request resolver that encodes requests, decodes result
+ * rows, groups decoded results by matching request and result keys, and fails a
+ * request with `NoSuchElementError` when no result group exists.
  *
- * Results are grouped by a common key extracted from the request and result.
- *
- * @since 4.0.0
  * @category resolvers
+ * @since 4.0.0
  */
 export const grouped = <Req extends Schema.Top, Res extends Schema.Top, K, Row, E, R>(
   options: {
@@ -193,10 +234,12 @@ export const grouped = <Req extends Schema.Top, Res extends Schema.Top, K, Row,
 }
 
 /**
- * Create a resolver that resolves results by id.
+ * Creates a batched resolver that fetches rows for encoded ids, decodes
+ * results, completes each matching request using `ResultId`, and fails missing
+ * ids with `NoSuchElementError`.
  *
- * @since 4.0.0
  * @category resolvers
+ * @since 4.0.0
  */
 export const findById = <Id extends Schema.Top, Res extends Schema.Top, Row, E, R>(
   options: {
@@ -295,8 +338,8 @@ export {
   /**
    * Create a resolver that performs side effects.
    *
-   * @since 4.0.0
    * @category resolvers
+   * @since 4.0.0
    */
   void_ as void
 }

package/src/unstable/sql/SqlSchema.ts

@@ -1,4 +1,22 @@
 /**
+ * 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
  */
 import * as Arr from "../../Array.ts"
@@ -8,10 +26,11 @@ import type * as Option from "../../Option.ts"
 import * as Schema from "../../Schema.ts"
 
 /**
- * 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.
  *
- * @since 4.0.0
  * @category constructor
+ * @since 4.0.0
  */
 export const findAll = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
   options: {
@@ -34,8 +53,8 @@ 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.
  *
- * @since 4.0.0
  * @category constructor
+ * @since 4.0.0
  */
 export const findNonEmpty = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
   options: {
@@ -74,17 +93,18 @@ export {
   /**
    * Run a sql query with a request schema and discard the result.
    *
-   * @since 4.0.0
    * @category constructor
+   * @since 4.0.0
    */
   void_ as void
 }
 
 /**
- * Run a sql query with a request schema and a result schema and return the first result.
+ * Builds a query function that encodes the request, decodes the first result
+ * row, and fails with `NoSuchElementError` when no rows are returned.
  *
- * @since 4.0.0
  * @category constructor
+ * @since 4.0.0
  */
 export const findOne = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
   options: {
@@ -113,10 +133,11 @@ export const findOne = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
 }
 
 /**
- * Run a sql query with a request schema and a result schema and return the first result.
+ * 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.
  *
- * @since 4.0.0
  * @category constructor
+ * @since 4.0.0
  */
 export const findOneOption = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
   options: {

package/src/unstable/sql/SqlStream.ts

@@ -1,4 +1,24 @@
 /**
+ * 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
  */
 import * as Cause from "../../Cause.ts"
@@ -8,6 +28,9 @@ import type * as Scope from "../../Scope.ts"
 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.
+ *
  * @since 4.0.0
  */
 export const asyncPauseResume = <A, E = never, R = never>(