Statement.ts

Statement.ts overview

Low-level SQL statement and fragment primitives.

SqlClient uses this module to build executable, parameterized SQL from reusable fragments. A statement can be executed, streamed, run without row transformation, or compiled to SQL text and parameters for a specific dialect. The module also contains helpers for identifiers, parameters, inserts, updates, custom dialect fragments, statement compilation, and row transformation.

Since v4.0.0

---

Exports Grouped by Category

• compiler
  • Compiler (interface)
  • CompilerOptions (type alias)
  • makeCompiler
  • makeCompilerSqlite
• constructors
  • and
  • arrayHelper
  • csv
  • custom
  • defaultEscape
  • fragment
  • identifier
  • join
  • literal
  • make
  • or
  • parameter
  • recordInsertHelper
  • recordUpdateHelper
  • recordUpdateHelperSingle
  • statement
• guards
  • isCustom
  • isFragment
• models
  • ArrayHelper (interface)
  • Constructor (interface)
  • Custom (interface)
  • Dialect (type alias)
  • Fragment (interface)
  • Helper (type alias)
  • Identifier (interface)
  • Literal (interface)
  • Parameter (interface)
  • PrimitiveKind (type alias)
  • RecordInsertHelper (interface)
  • RecordUpdateHelper (interface)
  • RecordUpdateHelperSingle (interface)
  • Segment (type alias)
  • Statement (interface)
  • Transformer (type alias)
• predicates
  • primitiveKind
• transformer
  • CurrentTransformer
• transforming
  • defaultTransforms

---

compiler

Compiler (interface)

Dialect-specific compiler that converts a SQL Fragment into SQL text and bind parameters, with a no-transform variant.

Signature

export interface Compiler {
  readonly dialect: Dialect
  readonly compile: (
    statement: Fragment,
    withoutTransform: boolean
  ) => readonly [sql: string, params: ReadonlyArray<unknown>]
  readonly withoutTransform: this
}

Source

Since v4.0.0

CompilerOptions (type alias)

Callbacks used by makeCompiler to render dialect placeholders, identifiers, insert helpers, update helpers, and custom SQL segments.

Signature

type CompilerOptions<C> = {
  readonly dialect: Dialect
  readonly placeholder: (index: number, value: unknown) => string
  readonly onIdentifier: (value: string, withoutTransform: boolean) => string
  readonly onRecordUpdate: (
    placeholders: string,
    alias: string,
    columns: string,
    values: ReadonlyArray<ReadonlyArray<unknown>>,
    returning: readonly [sql: string, params: ReadonlyArray<unknown>] | undefined
  ) => readonly [sql: string, params: ReadonlyArray<unknown>]
  readonly onCustom: (
    type: C,
    placeholder: (u: unknown) => string,
    withoutTransform: boolean
  ) => readonly [sql: string, params: ReadonlyArray<unknown>]
  readonly onInsert?: (
    columns: ReadonlyArray<string>,
    placeholders: string,
    values: ReadonlyArray<ReadonlyArray<unknown>>,
    returning: readonly [sql: string, params: ReadonlyArray<unknown>] | undefined
  ) => readonly [sql: string, binds: ReadonlyArray<unknown>]
  readonly onRecordUpdateSingle?: (
    columns: ReadonlyArray<string>,
    values: ReadonlyArray<unknown>,
    returning: readonly [sql: string, params: ReadonlyArray<unknown>] | undefined
  ) => readonly [sql: string, params: ReadonlyArray<unknown>]
}

Source

Since v4.0.0

makeCompiler

Creates a dialect-specific SQL Compiler from rendering callbacks.

Signature

declare const makeCompiler: <C extends Custom<any, any, any, any> = any>(options: CompilerOptions<C>) => Compiler

Source

Since v4.0.0

makeCompilerSqlite

Creates a SQLite compiler that uses ? placeholders and quoted identifiers, optionally transforming identifier names before escaping.

Signature

declare const makeCompilerSqlite: (transform?: ((_: string) => string) | undefined) => Compiler

Source

Since v4.0.0

constructors

and

Combines clauses with AND, parenthesizing multiple clauses and returning 1=1 when the list is empty.

Signature

declare const and: (clauses: ReadonlyArray<string | Fragment>) => Fragment

Source

Since v4.0.0

arrayHelper

Constructs an ArrayHelper segment for an array of values or fragments.

Signature

declare const arrayHelper: (value: ReadonlyArray<unknown | Fragment>) => ArrayHelper

Source

Since v4.0.0

csv

Creates a comma-separated SQL fragment from values, optionally adding a prefix, and returns an empty fragment when no values are provided.

Signature

declare const csv: {
  (values: ReadonlyArray<string | Fragment>): Fragment
  (prefix: string, values: ReadonlyArray<string | Fragment>): Fragment
}

Source

Since v4.0.0

custom

Creates a constructor for custom SQL segments of a specific kind handled by the active compiler.

Signature

declare const custom: <C extends Custom<any, any, any, any>>(
  kind: C["kind"]
) => (paramA: C["paramA"], paramB: C["paramB"], paramC: C["paramC"]) => C

Source

Since v4.0.0

defaultEscape

Creates an identifier escaping function that wraps names in the given delimiter, doubles delimiter characters, and escapes dots between identifier parts.

Signature

declare const defaultEscape: (c: string) => (str: string) => string

Source

Since v4.0.0

fragment

Constructs a SQL Fragment from low-level statement segments.

Signature

declare const fragment: (segments: ReadonlyArray<Segment>) => Fragment

Source

Since v4.0.0

identifier

Constructs a SQL identifier segment that will be escaped by the active compiler.

Signature

declare const identifier: (value: string) => Identifier

Source

Since v4.0.0

join

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.

Signature

declare const join: (
  lit: string,
  addParens?: boolean,
  fallback?: string
) => (clauses: ReadonlyArray<string | Fragment>) => Fragment

Source

Since v4.0.0

literal

Constructs a raw SQL literal segment. The literal text is not escaped, so use bound parameters for untrusted values.

Signature

declare const literal: (value: string, params?: ReadonlyArray<unknown> | undefined) => Literal

Source

Since v4.0.0

make

Creates a cached SQL statement constructor from a connection acquirer, compiler, tracing attributes, and optional row transformation function.

Signature

declare const make: (
  acquirer: Acquirer,
  compiler: Compiler,
  spanAttributes: ReadonlyArray<readonly [string, unknown]>,
  transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
) => Constructor

Source

Since v4.0.0

or

Combines clauses with OR, parenthesizing multiple clauses and returning 1=1 when the list is empty.

Signature

declare const or: (clauses: ReadonlyArray<string | Fragment>) => Fragment

Source

Since v4.0.0

parameter

Constructs a bound parameter segment for a statement value.

Signature

declare const parameter: (value: unknown) => Parameter

Source

Since v4.0.0

recordInsertHelper

Constructs a RecordInsertHelper from one or more row objects.

Signature

declare const recordInsertHelper: (value: ReadonlyArray<Record<string, unknown>>) => RecordInsertHelper

Source

Since v4.0.0

recordUpdateHelper

Constructs a RecordUpdateHelper for multi-row update compilation using the provided alias.

Signature

declare const recordUpdateHelper: (value: ReadonlyArray<Record<string, unknown>>, alias: string) => RecordUpdateHelper

Source

Since v4.0.0

recordUpdateHelperSingle

Constructs a RecordUpdateHelperSingle from a record and a list of columns to omit from the update.

Signature

declare const recordUpdateHelperSingle: (
  value: Record<string, unknown>,
  omit: ReadonlyArray<string>
) => RecordUpdateHelperSingle

Source

Since v4.0.0

statement

Builds a Statement from template strings and arguments, preserving fragments and helper segments while converting ordinary interpolated values into bound parameters.

Signature

declare const statement: <A = Row>(
  acquirer: Acquirer,
  compiler: Compiler,
  strings: TemplateStringsArray,
  args: Array<any>,
  spanAttributes: ReadonlyArray<readonly [string, unknown]>,
  transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
) => Statement<A>

Source

Since v4.0.0

guards

isCustom

Creates a type guard for custom SQL segments with the specified custom kind.

Signature

declare const isCustom: <A extends Custom<any, any, any, any>>(kind: A["kind"]) => (u: unknown) => u is A

Source

Since v4.0.0

isFragment

Returns true when a value is a SQL Fragment.

Signature

declare const isFragment: (u: unknown) => u is Fragment

Source

Since v4.0.0

models

ArrayHelper (interface)

Helper segment for compiling an array of values, commonly used to produce placeholder lists for IN clauses.

Signature

export interface ArrayHelper {
  readonly _tag: "ArrayHelper"
  readonly value: ReadonlyArray<unknown | Fragment>
}

Source

Since v4.0.0

Constructor (interface)

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.

Signature

export interface Constructor {
  <A extends object = Row>(strings: TemplateStringsArray, ...args: Array<any>): Statement<A>

  (value: string): Identifier

  /**
   * Create unsafe SQL query
   */
  readonly unsafe: <A extends object>(sql: string, params?: ReadonlyArray<unknown> | undefined) => Statement<A>

  readonly literal: (sql: string) => Fragment

  readonly in: {
    (value: ReadonlyArray<unknown>): ArrayHelper
    (column: string, value: ReadonlyArray<unknown>): Fragment
  }

  readonly insert: {
    (value: ReadonlyArray<Record<string, unknown>>): RecordInsertHelper
    (value: Record<string, unknown>): RecordInsertHelper
  }

  /** Update a single row */
  readonly update: <A extends Record<string, unknown>>(
    value: A,
    omit?: ReadonlyArray<keyof A>
  ) => RecordUpdateHelperSingle

  /**
   * Update multiple rows.
   *
   * **Gotchas**
   *
   * Not supported in sqlite.
   */
  readonly updateValues: (value: ReadonlyArray<Record<string, unknown>>, alias: string) => RecordUpdateHelper

  /**
   * Create an `AND` chain for a where clause
   */
  readonly and: (clauses: ReadonlyArray<string | Fragment>) => Fragment

  /**
   * Create an `OR` chain for a where clause
   */
  readonly or: (clauses: ReadonlyArray<string | Fragment>) => Fragment

  /**
   * Create comma seperated values, with an optional prefix.
   *
   * **When to use**
   *
   * Use when `ORDER BY` and `GROUP BY` clauses.
   */
  readonly csv: {
    (values: ReadonlyArray<string | Fragment>): Fragment
    (prefix: string, values: ReadonlyArray<string | Fragment>): Fragment
  }

  readonly join: (
    literal: string,
    addParens?: boolean,
    fallback?: string
  ) => (clauses: ReadonlyArray<string | Fragment>) => Fragment

  readonly onDialect: <A, B, C, D, E>(options: {
    readonly sqlite: () => A
    readonly pg: () => B
    readonly mysql: () => C
    readonly mssql: () => D
    readonly clickhouse: () => E
  }) => A | B | C | D | E

  readonly onDialectOrElse: <A, B = never, C = never, D = never, E = never, F = never>(options: {
    readonly orElse: () => A
    readonly sqlite?: () => B
    readonly pg?: () => C
    readonly mysql?: () => D
    readonly mssql?: () => E
    readonly clickhouse?: () => F
  }) => A | B | C | D | E | F
}

Source

Since v4.0.0

Custom (interface)

Custom SQL segment identified by kind and interpreted by the compiler’s onCustom callback.

Signature

export interface Custom<T extends string = string, A = void, B = void, C = void> {
  readonly _tag: "Custom"
  readonly kind: T
  readonly paramA: A
  readonly paramB: B
  readonly paramC: C
}

Source

Since v4.0.0

Dialect (type alias)

Supported SQL dialect identifiers used by statement compilers.

Signature

type Dialect = "sqlite" | "pg" | "mysql" | "mssql" | "clickhouse"

Source

Since v4.0.0

Fragment (interface)

Composable SQL fragment represented as low-level segments that can be interpolated into statements.

Signature

export interface Fragment {
  readonly [FragmentTypeId]: typeof FragmentTypeId
  readonly segments: ReadonlyArray<Segment>
}

Source

Since v4.0.0

Helper (type alias)

Union of helper segment types accepted by the SQL statement constructor.

Signature

type Helper = ArrayHelper | RecordInsertHelper | RecordUpdateHelper | RecordUpdateHelperSingle | Identifier | Custom

Source

Since v4.0.0

Identifier (interface)

SQL identifier segment whose value is escaped by the active dialect compiler.

Signature

export interface Identifier {
  readonly _tag: "Identifier"
  readonly value: string
}

Source

Since v4.0.0

Literal (interface)

Raw SQL literal segment. The literal text is inserted directly into the compiled SQL, while optional params are appended as bind parameters.

Signature

export interface Literal {
  readonly _tag: "Literal"
  readonly value: string
  readonly params?: ReadonlyArray<unknown> | undefined
}

Source

Since v4.0.0

Parameter (interface)

Bound parameter segment whose value is emitted as a dialect-specific placeholder and bind value.

Signature

export interface Parameter {
  readonly _tag: "Parameter"
  readonly value: unknown
}

Source

Since v4.0.0

PrimitiveKind (type alias)

Names the primitive value categories recognized by SQL statement helpers and primitiveKind.

Signature

type PrimitiveKind = "string" | "number" | "bigint" | "boolean" | "Date" | "null" | "Int8Array" | "Uint8Array"

Source

Since v4.0.0

RecordInsertHelper (interface)

Helper segment for compiling one or more record objects into an INSERT column/value clause, with optional returning output.

Signature

export interface RecordInsertHelper {
  readonly _tag: "RecordInsertHelper"
  readonly value: ReadonlyArray<Record<string, unknown>>
  /** @internal */
  readonly returningIdentifier: string | Fragment | undefined
  readonly returning: (sql: string | Identifier | Fragment) => RecordInsertHelper
}

Source

Since v4.0.0

RecordUpdateHelper (interface)

Helper segment for compiling multi-row update values with a table alias and optional returning output.

Signature

export interface RecordUpdateHelper {
  readonly _tag: "RecordUpdateHelper"
  readonly value: ReadonlyArray<Record<string, unknown>>
  readonly alias: string
  /** @internal */
  readonly returningIdentifier: string | Fragment | undefined
  readonly returning: (sql: string | Identifier | Fragment) => RecordUpdateHelper
}

Source

Since v4.0.0

RecordUpdateHelperSingle (interface)

Helper segment for compiling a single record into update assignments, omitting selected columns and optionally returning output.

Signature

export interface RecordUpdateHelperSingle {
  readonly _tag: "RecordUpdateHelperSingle"
  readonly value: Record<string, unknown>
  readonly omit: ReadonlyArray<string>
  /** @internal */
  readonly returningIdentifier: string | Fragment | undefined
  readonly returning: (sql: string | Identifier | Fragment) => RecordUpdateHelperSingle
}

Source

Since v4.0.0

Segment (type alias)

Union of low-level segment types that make up a SQL Fragment.

Signature

type Segment =
  | Literal
  | Identifier
  | Parameter
  | ArrayHelper
  | RecordInsertHelper
  | RecordUpdateHelper
  | RecordUpdateHelperSingle
  | Custom<any, any, any, any>

Source

Since v4.0.0

Statement (interface)

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.

Signature

export interface Statement<A> extends Fragment, Effect.Effect<ReadonlyArray<A>, SqlError> {
  readonly raw: Effect.Effect<unknown, SqlError>
  readonly withoutTransform: Effect.Effect<ReadonlyArray<A>, SqlError>
  readonly stream: Stream.Stream<A, SqlError>
  readonly values: Effect.Effect<ReadonlyArray<ReadonlyArray<unknown>>, SqlError>
  readonly valuesUnprepared: Effect.Effect<ReadonlyArray<ReadonlyArray<unknown>>, SqlError>
  readonly unprepared: Effect.Effect<ReadonlyArray<A>, SqlError>
  readonly compile: (withoutTransform?: boolean | undefined) => readonly [sql: string, params: ReadonlyArray<unknown>]
}

Source

Since v4.0.0

Transformer (type alias)

Hook that can rewrite or wrap a Statement before execution, using the current SQL constructor, fiber, and tracing span.

Signature

type Transformer = (
  self: Statement<unknown>,
  sql: Constructor,
  fiber: Fiber.Fiber<unknown, unknown>,
  span: Tracer.Span
) => Effect.Effect<Statement<unknown>>

Source

Since v4.0.0

predicates

primitiveKind

Classifies a JavaScript value as a SQL primitive kind, treating undefined as null and defaulting unrecognized objects to string.

Signature

declare const primitiveKind: (value: unknown) => PrimitiveKind

Source

Since v4.0.0

transformer

CurrentTransformer

Context reference for an optional current SQL statement transformer applied before statement execution.

Signature

declare const CurrentTransformer: Context.Reference<Transformer | undefined>

Source

Since v4.0.0

transforming

defaultTransforms

Builds value, object, and row-array transformers that rename object keys with the supplied function and optionally recurse into nested object arrays.

Signature

declare const defaultTransforms: (
  transformer: (str: string) => string,
  nested?: boolean
) => {
  readonly value: (value: any) => any
  readonly object: (obj: Record<string, any>) => any
  readonly array: <A extends object>(rows: ReadonlyArray<A>) => ReadonlyArray<A>
}

Source

Since v4.0.0