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

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,10 @@ 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.
+ *
+ * @category constructors
  * @since 4.0.0
  */
 export const asyncPauseResume = <A, E = never, R = never>(

package/src/unstable/sql/Statement.ts

@@ -1,4 +1,21 @@
 /**
+ * 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
  */
 import { Clock } from "../../Clock.ts"
@@ -18,7 +35,10 @@ import type { SqlError } from "./SqlError.ts"
 const FragmentTypeId = "~effect/sql/Fragment"
 
 /**
- * @category model
+ * Composable SQL fragment represented as low-level segments that can be
+ * interpolated into statements.
+ *
+ * @category models
  * @since 4.0.0
  */
 export interface Fragment {
@@ -27,6 +47,8 @@ export interface Fragment {
 }
 
 /**
+ * Constructs a SQL `Fragment` from low-level statement segments.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -38,13 +60,19 @@ export const fragment = (
 })
 
 /**
- * @category model
+ * Supported SQL dialect identifiers used by statement compilers.
+ *
+ * @category models
  * @since 4.0.0
  */
 export type Dialect = "sqlite" | "pg" | "mysql" | "mssql" | "clickhouse"
 
 /**
- * @category model
+ * Executable SQL statement that is also a `Fragment` and `Effect`, with helpers
+ * for raw execution, streaming, value rows, unprepared execution, no-transform
+ * execution, and compilation.
+ *
+ * @category models
  * @since 4.0.0
  */
 export interface Statement<A> extends Fragment, Effect.Effect<ReadonlyArray<A>, SqlError> {
@@ -60,7 +88,10 @@ export interface Statement<A> extends Fragment, Effect.Effect<ReadonlyArray<A>,
 }
 
 /**
- * @category model
+ * Hook that can rewrite or wrap a `Statement` before execution, using the
+ * current SQL constructor, fiber, and tracing span.
+ *
+ * @category models
  * @since 4.0.0
  */
 export type Transformer = (
@@ -71,6 +102,9 @@ export type Transformer = (
 ) => Effect.Effect<Statement<unknown>>
 
 /**
+ * Context reference for an optional current SQL statement transformer applied
+ * before statement execution.
+ *
  * @category transformer
  * @since 4.0.0
  */
@@ -79,12 +113,16 @@ export const CurrentTransformer = Context.Reference<Transformer | undefined>("ef
 })
 
 /**
+ * Returns `true` when a value is a SQL `Fragment`.
+ *
  * @category guard
  * @since 4.0.0
  */
 export const isFragment = (u: unknown): u is Fragment => hasProperty(u, FragmentTypeId)
 
 /**
+ * Creates a type guard for custom SQL segments with the specified custom kind.
+ *
  * @category guard
  * @since 4.0.0
  */
@@ -94,7 +132,9 @@ export const isCustom = <A extends Custom<any, any, any, any>>(
 (u: unknown): u is A => hasProperty(u, "_tag") && u._tag === "Custom" && (u as any).kind === kind
 
 /**
- * @category model
+ * Union of low-level segment types that make up a SQL `Fragment`.
+ *
+ * @category models
  * @since 4.0.0
  */
 export type Segment =
@@ -108,7 +148,10 @@ export type Segment =
   | Custom<any, any, any, any>
 
 /**
- * @category model
+ * Raw SQL literal segment. The literal text is inserted directly into the
+ * compiled SQL, while optional `params` are appended as bind parameters.
+ *
+ * @category models
  * @since 4.0.0
  */
 export interface Literal {
@@ -118,6 +161,9 @@ export interface Literal {
 }
 
 /**
+ * Constructs a raw SQL literal segment. The literal text is not escaped, so use
+ * bound parameters for untrusted values.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -128,7 +174,9 @@ export const literal = (value: string, params?: ReadonlyArray<unknown> | undefin
 })
 
 /**
- * @category model
+ * SQL identifier segment whose value is escaped by the active dialect compiler.
+ *
+ * @category models
  * @since 4.0.0
  */
 export interface Identifier {
@@ -137,6 +185,9 @@ export interface Identifier {
 }
 
 /**
+ * Constructs a SQL identifier segment that will be escaped by the active
+ * compiler.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -146,7 +197,10 @@ export const identifier = (value: string): Identifier => ({
 })
 
 /**
- * @category model
+ * Bound parameter segment whose value is emitted as a dialect-specific
+ * placeholder and bind value.
+ *
+ * @category models
  * @since 4.0.0
  */
 export interface Parameter {
@@ -155,6 +209,8 @@ export interface Parameter {
 }
 
 /**
+ * Constructs a bound parameter segment for a statement value.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -164,7 +220,10 @@ export const parameter = (value: unknown): Parameter => ({
 })
 
 /**
- * @category model
+ * Helper segment for compiling an array of values, commonly used to produce
+ * placeholder lists for `IN` clauses.
+ *
+ * @category models
  * @since 4.0.0
  */
 export interface ArrayHelper {
@@ -173,6 +232,8 @@ export interface ArrayHelper {
 }
 
 /**
+ * Constructs an `ArrayHelper` segment for an array of values or fragments.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -182,7 +243,10 @@ export const arrayHelper = (value: ReadonlyArray<unknown | Fragment>): ArrayHelp
 })
 
 /**
- * @category model
+ * Helper segment for compiling one or more record objects into an INSERT
+ * column/value clause, with optional returning output.
+ *
+ * @category models
  * @since 4.0.0
  */
 export interface RecordInsertHelper {
@@ -205,6 +269,8 @@ const RecordInsertHelperProto = {
 }
 
 /**
+ * Constructs a `RecordInsertHelper` from one or more row objects.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -217,7 +283,10 @@ export const recordInsertHelper = (
   })
 
 /**
- * @category model
+ * Helper segment for compiling multi-row update values with a table alias and
+ * optional returning output.
+ *
+ * @category models
  * @since 4.0.0
  */
 export interface RecordUpdateHelper {
@@ -235,6 +304,9 @@ const RecordUpdateHelperProto = {
 }
 
 /**
+ * Constructs a `RecordUpdateHelper` for multi-row update compilation using the
+ * provided alias.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -249,7 +321,10 @@ export const recordUpdateHelper = (
   })
 
 /**
- * @category model
+ * Helper segment for compiling a single record into update assignments,
+ * omitting selected columns and optionally returning output.
+ *
+ * @category models
  * @since 4.0.0
  */
 export interface RecordUpdateHelperSingle {
@@ -267,6 +342,9 @@ const RecordUpdateHelperSingleProto = {
 }
 
 /**
+ * Constructs a `RecordUpdateHelperSingle` from a record and a list of columns
+ * to omit from the update.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -281,7 +359,10 @@ export const recordUpdateHelperSingle = (
   })
 
 /**
- * @category model
+ * Custom SQL segment identified by `kind` and interpreted by the compiler's
+ * `onCustom` callback.
+ *
+ * @category models
  * @since 4.0.0
  */
 export interface Custom<
@@ -298,7 +379,10 @@ export interface Custom<
 }
 
 /**
- * @category constructor
+ * Creates a constructor for custom SQL segments of a specific kind handled by
+ * the active compiler.
+ *
+ * @category constructors
  * @since 4.0.0
  */
 export const custom = <C extends Custom<any, any, any, any>>(
@@ -311,7 +395,10 @@ export const custom = <C extends Custom<any, any, any, any>>(
 ): C => ({ _tag: "Custom", kind, paramA, paramB, paramC } as C)
 
 /**
- * @category model
+ * Names the primitive value categories recognized by SQL statement helpers and
+ * `primitiveKind`.
+ *
+ * @category models
  * @since 4.0.0
  */
 export type PrimitiveKind =
@@ -325,7 +412,9 @@ export type PrimitiveKind =
   | "Uint8Array"
 
 /**
- * @category model
+ * Union of helper segment types accepted by the SQL statement constructor.
+ *
+ * @category models
  * @since 4.0.0
  */
 export type Helper =
@@ -337,7 +426,12 @@ export type Helper =
   | Custom
 
 /**
- * @category model
+ * SQL tagged-template constructor and helper API for building parameterized
+ * statements, escaped identifiers, fragments, record helpers, and
+ * dialect-specific branches. Raw helpers such as `unsafe` and `literal` insert
+ * SQL text directly.
+ *
+ * @category models
  * @since 4.0.0
  */
 export interface Constructor {
@@ -431,7 +525,10 @@ export interface Constructor {
 }
 
 /**
- * @category constructor
+ * Creates a cached SQL statement constructor from a connection acquirer,
+ * compiler, tracing attributes, and optional row transformation function.
+ *
+ * @category constructors
  * @since 4.0.0
  */
 export const make = (
@@ -513,6 +610,10 @@ const constructorCache = {
 }
 
 /**
+ * Builds a `Statement` from template strings and arguments, preserving
+ * fragments and helper segments while converting ordinary interpolated values
+ * into bound parameters.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -546,7 +647,11 @@ export const statement = <A = Row>(
 }
 
 /**
- * @category constructor
+ * Creates a helper that joins SQL clauses with a literal separator, optionally
+ * wrapping multiple clauses in parentheses and using a fallback for an empty
+ * list.
+ *
+ * @category constructors
  * @since 4.0.0
  */
 export function join(lit: string, addParens = true, fallback = "") {
@@ -582,29 +687,44 @@ export function join(lit: string, addParens = true, fallback = "") {
 }
 
 /**
- * @category constructor
+ * Combines clauses with `AND`, parenthesizing multiple clauses and returning
+ * `1=1` when the list is empty.
+ *
+ * @category constructors
  * @since 4.0.0
  */
 export const and: (clauses: ReadonlyArray<string | Fragment>) => Fragment = join(" AND ", true, "1=1")
 
 /**
- * @category constructor
+ * Combines clauses with `OR`, parenthesizing multiple clauses and returning
+ * `1=1` when the list is empty.
+ *
+ * @category constructors
  * @since 4.0.0
  */
 export const or: (clauses: ReadonlyArray<string | Fragment>) => Fragment = join(" OR ", true, "1=1")
 
 /**
- * @category constructor
+ * Creates a comma-separated SQL fragment from values, optionally adding a
+ * prefix, and returns an empty fragment when no values are provided.
+ *
+ * @category constructors
  * @since 4.0.0
  */
 export const csv: {
   /**
-   * @category constructor
+   * Creates a comma-separated SQL fragment from values, optionally adding a
+   * prefix, and returns an empty fragment when no values are provided.
+   *
+   * @category constructors
    * @since 4.0.0
    */
   (values: ReadonlyArray<string | Fragment>): Fragment
   /**
-   * @category constructor
+   * Creates a comma-separated SQL fragment from values, optionally adding a
+   * prefix, and returns an empty fragment when no values are provided.
+   *
+   * @category constructors
    * @since 4.0.0
    */
   (prefix: string, values: ReadonlyArray<string | Fragment>): Fragment
@@ -631,6 +751,9 @@ const csvRaw = join(",", false)
 const emptyFragment = fragment([literal("")])
 
 /**
+ * Dialect-specific compiler that converts a SQL `Fragment` into SQL text and
+ * bind parameters, with a no-transform variant.
+ *
  * @category compiler
  * @since 4.0.0
  */
@@ -644,6 +767,9 @@ export interface Compiler {
 }
 
 /**
+ * Callbacks used by `makeCompiler` to render dialect placeholders,
+ * identifiers, insert helpers, update helpers, and custom SQL segments.
+ *
  * @category compiler
  * @since 4.0.0
  */
@@ -677,6 +803,8 @@ export type CompilerOptions<C extends Custom<any, any, any, any> = any> = {
 }
 
 /**
+ * Creates a dialect-specific SQL `Compiler` from rendering callbacks.
+ *
  * @category compiler
  * @since 4.0.0
  */
@@ -934,6 +1062,9 @@ const CompilerProto = {
 }
 
 /**
+ * Creates a SQLite compiler that uses `?` placeholders and quoted identifiers,
+ * optionally transforming identifier names before escaping.
+ *
  * @category compiler
  * @since 4.0.0
  */
@@ -957,6 +1088,11 @@ export const makeCompilerSqlite = (transform?: ((_: string) => string) | undefin
   })
 
 /**
+ * Creates an identifier escaping function that wraps names in the given
+ * delimiter, doubles delimiter characters, and escapes dots between identifier
+ * parts.
+ *
+ * @category constructors
  * @since 4.0.0
  */
 export function defaultEscape(c: string) {
@@ -969,6 +1105,10 @@ 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 => {
@@ -999,6 +1139,10 @@ 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 = (