effect-qb 0.13.0 → 0.15.0

package/src/internal/renderer.ts

@@ -1,6 +1,5 @@
 import * as Query from "./query.js"
 import { type Projection, validateProjections } from "./projections.js"
-import { renderPostgresPlan } from "./postgres-renderer.js"
 
 /** Symbol used to attach rendered-query phantom row metadata. */
 export const TypeId: unique symbol = Symbol.for("effect-qb/Renderer")
@@ -41,12 +40,12 @@ export type RowOf<Value extends RenderedQuery<any, any>> = Value[typeof TypeId][
  */
 export interface Renderer<Dialect extends string = string> {
   readonly dialect: Dialect
-  render<PlanValue extends Query.QueryPlan<any, any, any, any, any, any, any, any, any>>(
+  render<PlanValue extends Query.Plan.Any>(
     plan: Query.DialectCompatiblePlan<PlanValue, Dialect>
   ): RenderedQuery<any, Dialect>
 }
 
-type CustomRender<Dialect extends string> = <PlanValue extends Query.QueryPlan<any, any, any, any, any, any, any, any, any>>(
+type CustomRender<Dialect extends string> = <PlanValue extends Query.Plan.Any>(
   plan: Query.DialectCompatiblePlan<PlanValue, Dialect>
 ) => {
   readonly sql: string
@@ -55,33 +54,23 @@ type CustomRender<Dialect extends string> = <PlanValue extends Query.QueryPlan<a
 }
 
 /**
- * Constructs a renderer from a dialect and optional implementation callback.
- *
- * When no callback is provided, the library supplies a built-in renderer for
- * `"postgres"` that consumes the query AST directly and produces SQL text plus
- * parameter values.
+ * Constructs a renderer from a dialect and implementation callback.
  */
-export function make(dialect: "postgres"): Renderer<"postgres">
 export function make<Dialect extends string>(
   dialect: Dialect,
   render: CustomRender<Dialect>
 ): Renderer<Dialect>
 export function make<Dialect extends string>(
   dialect: Dialect,
-  render?: CustomRender<Dialect>
+  render: CustomRender<Dialect>
 ): Renderer<Dialect> {
-  const implementation = render ?? ((dialect === "postgres"
-    ? renderPostgresPlan
-    : undefined) as CustomRender<Dialect> | undefined)
-
-  if (!implementation) {
-    throw new Error(`No built-in renderer for dialect: ${dialect}`)
+  if (typeof render !== "function") {
+    throw new Error(`Renderer.make requires an explicit render implementation for dialect: ${dialect}`)
   }
-
   return {
     dialect,
     render(plan) {
-      const rendered = implementation(plan)
+      const rendered = render(plan)
       const projections = rendered.projections ?? []
       validateProjections(projections)
       return {
@@ -97,6 +86,3 @@ export function make<Dialect extends string>(
     }
   } as Renderer<Dialect>
 }
-
-/** Built-in Postgres renderer backed by the current query AST. */
-export const postgres = make("postgres")

package/src/internal/row-set.d.ts

@@ -0,0 +1,53 @@
+import type { Pipeable } from "effect/Pipeable";
+import type { PredicateFormula } from "./predicate/formula.js";
+/** Symbol used to attach logical-plan metadata to runtime values. */
+export declare const TypeId: unique symbol;
+export type TypeId = typeof TypeId;
+/**
+ * Source availability mode within a query scope.
+ *
+ * `required` means the source is guaranteed to produce a row at this point in
+ * the plan. `optional` means the source may be absent, such as the nullable
+ * side of a left join.
+ */
+export type SourceMode = "required" | "optional";
+/** Source made available to a plan. */
+export interface Source<Name extends string = string, Mode extends SourceMode = SourceMode, PresentFormula extends PredicateFormula = PredicateFormula, PresenceWitness extends string = never> {
+    readonly name: Name;
+    readonly mode: Mode;
+    readonly baseName?: string;
+    readonly _presentFormula?: PresentFormula;
+    readonly _presenceWitnesses?: readonly PresenceWitness[];
+}
+export type AnySource = Source<string, SourceMode, PredicateFormula, string>;
+/**
+ * Canonical static metadata stored on a plan.
+ *
+ * `required` tracks sources that the selection references but which are not yet
+ * in scope. `available` tracks sources already in scope for subsequent query
+ * operations.
+ */
+export interface State<Columns, Required, Available extends Record<string, AnySource>, Dialect extends string> {
+    readonly selection: Columns;
+    readonly required: Required;
+    readonly available: Available;
+    readonly dialect: Dialect;
+}
+/**
+ * A composable logical row set.
+ *
+ * Tables implement this interface as already-complete plans. Future query
+ * builders such as `select()` and `from()` should produce and transform values
+ * with this same structure.
+ */
+export interface RowSet<Columns, Required = never, Available extends Record<string, AnySource> = {}, Dialect extends string = never> extends Pipeable {
+    readonly [TypeId]: State<Columns, Required, Available, Dialect>;
+}
+/** Convenience alias for any plan-like value. */
+export type Any = RowSet<any, any, Record<string, AnySource>, string>;
+/** Extracts a row set's columns shape. */
+export type ColumnsOf<Value extends Any> = Value[typeof TypeId]["selection"];
+/** Extracts a plan's selection shape. */
+export type SelectionOf<Value extends Any> = ColumnsOf<Value>;
+/** Extracts a plan's effective dialect. */
+export type DialectOf<Value extends Any> = Value[typeof TypeId]["dialect"];

package/src/internal/{plan.ts → row-set.ts}

@@ -1,4 +1,5 @@
 import type { Pipeable } from "effect/Pipeable"
+import type { PredicateFormula } from "./predicate/formula.js"
 
 /** Symbol used to attach logical-plan metadata to runtime values. */
 export const TypeId: unique symbol = Symbol.for("effect-qb/Plan")
@@ -15,12 +16,21 @@ export type TypeId = typeof TypeId
 export type SourceMode = "required" | "optional"
 
 /** Source made available to a plan. */
-export interface Source<Name extends string = string, Mode extends SourceMode = SourceMode> {
+export interface Source<
+  Name extends string = string,
+  Mode extends SourceMode = SourceMode,
+  PresentFormula extends PredicateFormula = PredicateFormula,
+  PresenceWitness extends string = never
+> {
   readonly name: Name
   readonly mode: Mode
   readonly baseName?: string
+  readonly _presentFormula?: PresentFormula
+  readonly _presenceWitnesses?: readonly PresenceWitness[]
 }
 
+export type AnySource = Source<string, SourceMode, PredicateFormula, string>
+
 /**
  * Canonical static metadata stored on a plan.
  *
@@ -29,36 +39,38 @@ export interface Source<Name extends string = string, Mode extends SourceMode =
  * operations.
  */
 export interface State<
-  Selection,
+  Columns,
   Required,
-  Available extends Record<string, Source>,
+  Available extends Record<string, AnySource>,
   Dialect extends string
 > {
-  readonly selection: Selection
+  readonly selection: Columns
   readonly required: Required
   readonly available: Available
   readonly dialect: Dialect
 }
 
 /**
- * A composable logical query plan.
+ * A composable logical row set.
  *
  * Tables implement this interface as already-complete plans. Future query
  * builders such as `select()` and `from()` should produce and transform values
  * with this same structure.
  */
-export interface Plan<
-  Selection,
+export interface RowSet<
+  Columns,
   Required = never,
-  Available extends Record<string, Source> = {},
+  Available extends Record<string, AnySource> = {},
   Dialect extends string = never
 > extends Pipeable {
-  readonly [TypeId]: State<Selection, Required, Available, Dialect>
+  readonly [TypeId]: State<Columns, Required, Available, Dialect>
 }
 
 /** Convenience alias for any plan-like value. */
-export type Any = Plan<any, any, Record<string, Source>, string>
+export type Any = RowSet<any, any, Record<string, AnySource>, string>
+/** Extracts a row set's columns shape. */
+export type ColumnsOf<Value extends Any> = Value[typeof TypeId]["selection"]
 /** Extracts a plan's selection shape. */
-export type SelectionOf<Value extends Any> = Value[typeof TypeId]["selection"]
+export type SelectionOf<Value extends Any> = ColumnsOf<Value>
 /** Extracts a plan's effective dialect. */
 export type DialectOf<Value extends Any> = Value[typeof TypeId]["dialect"]

package/src/internal/{runtime-normalize.ts → runtime/normalize.ts}

@@ -1,22 +1,5 @@
-import type * as Expression from "./expression.js"
-import { mysqlDatatypeKinds } from "../mysql/datatypes/spec.js"
-import { postgresDatatypeKinds } from "../postgres/datatypes/spec.js"
-import type { RuntimeTag } from "./datatypes/shape.js"
-
-const stripParameterizedKind = (kind: string): string => {
-  const openParen = kind.indexOf("(")
-  return openParen === -1 ? kind : kind.slice(0, openParen)
-}
-
-const stripArrayKind = (kind: string): string => {
-  let current = kind
-  while (current.endsWith("[]")) {
-    current = current.slice(0, -2)
-  }
-  return current
-}
-
-const baseKind = (kind: string): string => stripArrayKind(stripParameterizedKind(kind))
+import type * as Expression from "../scalar.js"
+import type { RuntimeTag } from "../datatypes/shape.js"
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value)
@@ -39,17 +22,9 @@ const formatLocalDateTime = (value: Date): string => {
 }
 
 const runtimeTagOfBaseDbType = (
-  dialect: string,
-  kind: string
+  dbType: Expression.DbType.Base<string, string>
 ): RuntimeTag | undefined => {
-  const normalizedKind = baseKind(kind)
-  if (dialect === "postgres") {
-    return postgresDatatypeKinds[normalizedKind as keyof typeof postgresDatatypeKinds]?.runtime
-  }
-  if (dialect === "mysql") {
-    return mysqlDatatypeKinds[normalizedKind as keyof typeof mysqlDatatypeKinds]?.runtime
-  }
-  return undefined
+  return dbType.runtime
 }
 
 const expectString = (value: unknown, label: string): string => {
@@ -225,7 +200,10 @@ const normalizeBytes = (value: unknown): Uint8Array => {
   if (value instanceof Uint8Array) {
     return new Uint8Array(value)
   }
-  if (typeof Buffer !== "undefined" && value instanceof Buffer) {
+  const BufferConstructor = (globalThis as {
+    readonly Buffer?: abstract new (...args: never[]) => Uint8Array
+  }).Buffer
+  if (BufferConstructor !== undefined && value instanceof BufferConstructor) {
     return new Uint8Array(value)
   }
   throw new Error("Expected a byte array value")
@@ -298,7 +276,7 @@ export const normalizeDbValue = (
   if ("variant" in dbType && (dbType.variant === "enum" || dbType.variant === "set")) {
     return expectString(value, "text")
   }
-  switch (runtimeTagOfBaseDbType(dbType.dialect, dbType.kind)) {
+  switch (runtimeTagOfBaseDbType(dbType)) {
     case "string":
       return expectString(value, "text")
     case "number":

package/src/internal/{runtime-schema.ts → runtime/schema.ts}

@@ -1,11 +1,19 @@
 import * as Schema from "effect/Schema"
 import * as SchemaAST from "effect/SchemaAST"
 
-import * as Expression from "./expression.js"
-import * as ExpressionAst from "./expression-ast.js"
-import * as Query from "./query.js"
-import * as JsonPath from "./json/path.js"
-import { flattenSelection } from "./projections.js"
+import * as Expression from "../scalar.js"
+import * as ExpressionAst from "../expression-ast.js"
+import * as Query from "../query.js"
+import * as JsonPath from "../json/path.js"
+import type { PredicateFormula } from "../predicate/formula.js"
+import {
+  assumeFormulaFalse,
+  assumeFormulaTrue,
+  contradictsFormula,
+  formulaOfExpression as formulaOfExpressionRuntime,
+  impliesFormula
+} from "../predicate/runtime.js"
+import { flattenSelection } from "../projections.js"
 import {
   BigIntStringSchema,
   DecimalStringSchema,
@@ -16,29 +24,16 @@ import {
   LocalTimeStringSchema,
   OffsetTimeStringSchema,
   YearStringSchema
-} from "./runtime-value.js"
-import { mysqlDatatypeKinds } from "../mysql/datatypes/spec.js"
-import { postgresDatatypeKinds } from "../postgres/datatypes/spec.js"
-import type { RuntimeTag } from "./datatypes/shape.js"
+} from "./value.js"
+import type { RuntimeTag } from "../datatypes/shape.js"
 
 export type RuntimeSchema = Schema.Schema<any, any, any>
 
-const schemaCache = new WeakMap<Expression.Any, RuntimeSchema | undefined>()
-
-const stripParameterizedKind = (kind: string): string => {
-  const openParen = kind.indexOf("(")
-  return openParen === -1 ? kind : kind.slice(0, openParen)
-}
-
-const stripArrayKind = (kind: string): string => {
-  let current = kind
-  while (current.endsWith("[]")) {
-    current = current.slice(0, -2)
-  }
-  return current
+type SchemaContext = {
+  readonly assumptions: PredicateFormula
 }
 
-const baseKind = (kind: string): string => stripArrayKind(stripParameterizedKind(kind))
+const schemaCache = new WeakMap<Expression.Any, RuntimeSchema | undefined>()
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value)
@@ -86,17 +81,9 @@ const runtimeSchemaForTag = (tag: RuntimeTag): RuntimeSchema | undefined => {
 }
 
 const runtimeTagOfBaseDbType = (
-  dialect: string,
-  kind: string
+  dbType: Expression.DbType.Base<string, string>
 ): RuntimeTag | undefined => {
-  const normalizedKind = baseKind(kind)
-  if (dialect === "postgres") {
-    return postgresDatatypeKinds[normalizedKind as keyof typeof postgresDatatypeKinds]?.runtime
-  }
-  if (dialect === "mysql") {
-    return mysqlDatatypeKinds[normalizedKind as keyof typeof mysqlDatatypeKinds]?.runtime
-  }
-  return undefined
+  return dbType.runtime
 }
 
 export const runtimeSchemaForDbType = (
@@ -120,7 +107,7 @@ export const runtimeSchemaForDbType = (
   if ("variant" in dbType && (dbType.variant === "enum" || dbType.variant === "set")) {
     return Schema.String
   }
-  const runtimeTag = runtimeTagOfBaseDbType(dbType.dialect, dbType.kind)
+  const runtimeTag = runtimeTagOfBaseDbType(dbType)
   return runtimeTag === undefined ? undefined : runtimeSchemaForTag(runtimeTag)
 }
 
@@ -245,7 +232,7 @@ const unionSchemas = (schemas: ReadonlyArray<RuntimeSchema | undefined>): Runtim
 }
 
 const firstSelectedExpression = (
-  plan: Query.QueryPlan<any, any, any, any, any, any, any, any, any, any>
+  plan: Query.Plan.Any
 ): Expression.Any | undefined => {
   const selection = Query.getAst(plan).select
   return flattenSelection(selection as Record<string, unknown>)[0]?.expression
@@ -284,18 +271,59 @@ const jsonCompatibleSchema = (schema: RuntimeSchema | undefined): RuntimeSchema
 }
 
 const buildStructSchema = (
-  entries: readonly { readonly key: string; readonly value: Expression.Any }[]
+  entries: readonly { readonly key: string; readonly value: Expression.Any }[],
+  context?: SchemaContext
 ): RuntimeSchema => {
   const fields = Object.fromEntries(
-    entries.map((entry) => [entry.key, expressionRuntimeSchema(entry.value) ?? JsonValueSchema])
+    entries.map((entry) => [entry.key, expressionRuntimeSchema(entry.value, context) ?? JsonValueSchema])
   )
   return Schema.Struct(fields as Record<string, RuntimeSchema>)
 }
 
-const buildTupleSchema = (values: readonly Expression.Any[]): RuntimeSchema =>
-  Schema.Tuple(...values.map((value) => expressionRuntimeSchema(value) ?? JsonValueSchema))
+const buildTupleSchema = (values: readonly Expression.Any[], context?: SchemaContext): RuntimeSchema =>
+  Schema.Tuple(...values.map((value) => expressionRuntimeSchema(value, context) ?? JsonValueSchema))
+
+const deriveCaseSchema = (
+  ast: ExpressionAst.CaseNode,
+  context?: SchemaContext
+): RuntimeSchema | undefined => {
+  if (context === undefined) {
+    return unionSchemas([
+      ...ast.branches.map((branch) => expressionRuntimeSchema(branch.then)),
+      expressionRuntimeSchema(ast.else)
+    ])
+  }
+
+  const schemas: RuntimeSchema[] = []
+  let elseAssumptions = context.assumptions
 
-const deriveRuntimeSchema = (expression: Expression.Any): RuntimeSchema | undefined => {
+  for (const branch of ast.branches) {
+    const whenFormula = formulaOfExpressionRuntime(branch.when)
+    if (contradictsFormula(elseAssumptions, whenFormula)) {
+      continue
+    }
+
+    const branchContext = { assumptions: assumeFormulaTrue(elseAssumptions, whenFormula) }
+    const branchSchema = expressionRuntimeSchema(branch.then, branchContext)
+    if (branchSchema !== undefined) {
+      schemas.push(branchSchema)
+    }
+
+    if (impliesFormula(elseAssumptions, whenFormula)) {
+      return unionSchemas(schemas)
+    }
+
+    elseAssumptions = assumeFormulaFalse(elseAssumptions, whenFormula)
+  }
+
+  const elseSchema = expressionRuntimeSchema(ast.else, { assumptions: elseAssumptions })
+  return unionSchemas(elseSchema === undefined ? schemas : [...schemas, elseSchema])
+}
+
+const deriveRuntimeSchema = (
+  expression: Expression.Any,
+  context?: SchemaContext
+): RuntimeSchema | undefined => {
   const state = expression[Expression.TypeId]
   if (state.runtimeSchema !== undefined) {
     return state.runtimeSchema
@@ -363,28 +391,25 @@ const deriveRuntimeSchema = (expression: Expression.Any): RuntimeSchema | undefi
       return Schema.Number
     case "max":
     case "min":
-      return expressionRuntimeSchema(ast.value)
+      return expressionRuntimeSchema(ast.value, context)
     case "case":
-      return unionSchemas([
-        ...ast.branches.map((branch) => expressionRuntimeSchema(branch.then)),
-        expressionRuntimeSchema(ast.else)
-      ])
+      return deriveCaseSchema(ast, context)
     case "coalesce":
-      return unionSchemas(ast.values.map(expressionRuntimeSchema))
+      return unionSchemas(ast.values.map((value) => expressionRuntimeSchema(value, context)))
     case "scalarSubquery":
       {
         const selection = firstSelectedExpression(ast.plan)
-        return selection === undefined ? undefined : expressionRuntimeSchema(selection)
+        return selection === undefined ? undefined : expressionRuntimeSchema(selection, context)
       }
     case "window":
       return ast.function === "over" && ast.value !== undefined
-        ? expressionRuntimeSchema(ast.value)
+        ? expressionRuntimeSchema(ast.value, context)
         : Schema.Number
     case "jsonGet":
     case "jsonPath":
     case "jsonAccess":
     case "jsonTraverse": {
-      const baseSchema = expressionRuntimeSchema(ast.base!)
+      const baseSchema = expressionRuntimeSchema(ast.base!, context)
       const segments = ast.segments
       if (baseSchema === undefined || segments === undefined || !exactJsonSegments(segments)) {
         return JsonValueSchema
@@ -397,27 +422,31 @@ const deriveRuntimeSchema = (expression: Expression.Any): RuntimeSchema | undefi
     case "jsonRemove":
     case "jsonSet":
     case "jsonInsert":
-      return expressionRuntimeSchema(ast.base!)
+      return expressionRuntimeSchema(ast.base!, context)
     case "jsonStripNulls":
-      return expressionRuntimeSchema(ast.value!)
+      return expressionRuntimeSchema(ast.value!, context)
     case "jsonConcat":
     case "jsonMerge":
       return JsonValueSchema
     case "jsonBuildObject":
-      return buildStructSchema(ast.entries ?? [])
+      return buildStructSchema(ast.entries ?? [], context)
     case "jsonBuildArray":
-      return buildTupleSchema(ast.values ?? [])
+      return buildTupleSchema(ast.values ?? [], context)
     case "jsonToJson":
     case "jsonToJsonb":
-      return jsonCompatibleSchema(expressionRuntimeSchema(ast.value!))
+      return jsonCompatibleSchema(expressionRuntimeSchema(ast.value!, context))
     case "jsonKeys":
       return Schema.Array(Schema.String)
   }
 }
 
 export const expressionRuntimeSchema = (
-  expression: Expression.Any
+  expression: Expression.Any,
+  context?: SchemaContext
 ): RuntimeSchema | undefined => {
+  if (context !== undefined) {
+    return deriveRuntimeSchema(expression, context) ?? runtimeSchemaForDbType(expression[Expression.TypeId].dbType)
+  }
   const cached = schemaCache.get(expression)
   if (cached !== undefined || schemaCache.has(expression)) {
     return cached

package/src/internal/runtime/value.d.ts

@@ -0,0 +1,22 @@
+import type * as Brand from "effect/Brand";
+import * as Schema from "effect/Schema";
+import type { JsonPrimitive, JsonValue } from "../json/types.js";
+export type { JsonPrimitive, JsonValue } from "../json/types.js";
+export type LocalDateString = string & Brand.Brand<"LocalDateString">;
+export type LocalTimeString = string & Brand.Brand<"LocalTimeString">;
+export type OffsetTimeString = string & Brand.Brand<"OffsetTimeString">;
+export type LocalDateTimeString = string & Brand.Brand<"LocalDateTimeString">;
+export type InstantString = string & Brand.Brand<"InstantString">;
+export type YearString = string & Brand.Brand<"YearString">;
+export type BigIntString = string & Brand.Brand<"BigIntString">;
+export type DecimalString = string & Brand.Brand<"DecimalString">;
+export declare const LocalDateStringSchema: Schema.Schema<string & Brand.Brand<"LocalDateString">, string & Brand.Brand<"LocalDateString">, never>;
+export declare const LocalTimeStringSchema: Schema.Schema<string & Brand.Brand<"LocalTimeString">, string & Brand.Brand<"LocalTimeString">, never>;
+export declare const OffsetTimeStringSchema: Schema.Schema<string & Brand.Brand<"OffsetTimeString">, string & Brand.Brand<"OffsetTimeString">, never>;
+export declare const LocalDateTimeStringSchema: Schema.Schema<string & Brand.Brand<"LocalDateTimeString">, string & Brand.Brand<"LocalDateTimeString">, never>;
+export declare const InstantStringSchema: Schema.Schema<string & Brand.Brand<"InstantString">, string & Brand.Brand<"InstantString">, never>;
+export declare const YearStringSchema: Schema.Schema<string & Brand.Brand<"YearString">, string & Brand.Brand<"YearString">, never>;
+export declare const BigIntStringSchema: Schema.Schema<string & Brand.Brand<"BigIntString">, string & Brand.Brand<"BigIntString">, never>;
+export declare const DecimalStringSchema: Schema.Schema<string & Brand.Brand<"DecimalString">, string & Brand.Brand<"DecimalString">, never>;
+export declare const JsonValueSchema: Schema.Schema<JsonValue>;
+export declare const JsonPrimitiveSchema: Schema.Schema<JsonPrimitive>;

package/src/internal/{runtime-value.ts → runtime/value.ts}

@@ -1,9 +1,9 @@
 import type * as Brand from "effect/Brand"
 import * as Schema from "effect/Schema"
 
-import type { JsonPrimitive, JsonValue } from "./json/types.js"
+import type { JsonPrimitive, JsonValue } from "../json/types.js"
 
-export type { JsonPrimitive, JsonValue } from "./json/types.js"
+export type { JsonPrimitive, JsonValue } from "../json/types.js"
 
 export type LocalDateString = string & Brand.Brand<"LocalDateString">
 export type LocalTimeString = string & Brand.Brand<"LocalTimeString">

package/src/internal/scalar.d.ts

@@ -0,0 +1,107 @@
+import type { Pipeable } from "effect/Pipeable";
+import type * as Schema from "effect/Schema";
+import type { RuntimeOfDbType as RuntimeOfDbTypeLookup } from "./datatypes/lookup.js";
+import type { DatatypeTraits, RuntimeTag } from "./datatypes/shape.js";
+export type { BigIntString, DecimalString, InstantString, JsonPrimitive, JsonValue, LocalDateString, LocalDateTimeString, LocalTimeString, OffsetTimeString, YearString } from "./runtime/value.js";
+/** Symbol used to attach expression metadata to runtime values. */
+export declare const TypeId: unique symbol;
+export type TypeId = typeof TypeId;
+/** Scope-local binding identifier used for dependency tracking. */
+export type BindingId = string;
+/**
+ * Three-state nullability lattice.
+ *
+ * `"never"` means non-null, `"maybe"` means nullable, and `"always"` means the
+ * expression is known to be `null`.
+ */
+export type Nullability = "never" | "maybe" | "always";
+/**
+ * High-level classification of an expression.
+ *
+ * - `scalar`: regular per-row expression
+ * - `aggregate`: grouped expression such as `count(*)`
+ * - `window`: windowed expression such as `row_number() over (...)`
+ */
+export type ScalarKind = "scalar" | "aggregate" | "window";
+/** Database-type descriptors carried alongside decoded runtime types. */
+export declare namespace DbType {
+    /** Base SQL type descriptor. */
+    interface Base<Dialect extends string, Kind extends string> {
+        readonly dialect: Dialect;
+        readonly kind: Kind;
+        readonly family?: string;
+        readonly runtime?: RuntimeTag;
+        readonly compareGroup?: string;
+        readonly castTargets?: readonly string[];
+        readonly traits?: DatatypeTraits;
+    }
+    /** JSON-like database type. */
+    interface Json<Dialect extends string = string, SchemaName extends string = "json"> extends Base<Dialect, SchemaName> {
+        readonly variant: SchemaName extends "jsonb" ? "jsonb" : "json";
+    }
+    /** Array database type. */
+    interface Array<Dialect extends string = string, Element extends Any = any, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly element: Element;
+    }
+    /** Range database type. */
+    interface Range<Dialect extends string = string, Subtype extends Any = any, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly subtype: Subtype;
+    }
+    /** Multirange database type. */
+    interface Multirange<Dialect extends string = string, Subtype extends Any = any, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly subtype: Subtype;
+    }
+    /** Composite/record database type. */
+    interface Composite<Dialect extends string = string, Fields extends Record<string, Any> = Record<string, any>, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly fields: Fields;
+    }
+    /** Named domain database type. */
+    interface Domain<Dialect extends string = string, BaseType extends Any = any, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly base: BaseType;
+    }
+    /** Enumeration database type. */
+    interface Enum<Dialect extends string = string, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly variant: "enum";
+    }
+    /** Set database type. */
+    interface Set<Dialect extends string = string, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly variant: "set";
+    }
+    type Any = Json | Base<string, string> | Array<string, any, string> | Range<string, any, string> | Multirange<string, any, string> | Composite<string, Record<string, any>, string> | Domain<string, any, string> | Enum<string, string> | Set<string, string>;
+}
+/** Canonical static metadata stored on an expression. */
+export interface State<Runtime, Db extends DbType.Any, Nullable extends Nullability, Dialect extends string, Kind extends ScalarKind, Deps extends BindingId = never> {
+    readonly runtime: Runtime;
+    readonly dbType: Db;
+    readonly runtimeSchema?: Schema.Schema.Any;
+    readonly nullability: Nullable;
+    readonly dialect: Dialect;
+    readonly kind: Kind;
+    readonly dependencies: Record<string, true>;
+}
+/**
+ * A typed scalar SQL expression.
+ *
+ * `Runtime` is the decoded TypeScript type while `Db` captures the SQL-level
+ * type identity. Both are needed: multiple SQL types may decode to the same
+ * runtime type but still have different comparison/cast semantics.
+ */
+export interface Scalar<Runtime, Db extends DbType.Any, Nullable extends Nullability = "never", Dialect extends string = Db["dialect"], Kind extends ScalarKind = "scalar", Deps extends BindingId = never, GroupKey extends string = string> extends Pipeable {
+    readonly [TypeId]: State<Runtime, Db, Nullable, Dialect, Kind, Deps>;
+}
+/** Convenience alias for any expression-like value. */
+export type Any = Scalar<any, DbType.Any, Nullability, string, ScalarKind, BindingId, string>;
+/** Extracts an expression's decoded runtime type. */
+export type RuntimeOf<Value extends Any> = Value[typeof TypeId]["runtime"];
+/** Extracts an expression's database-type descriptor. */
+export type DbTypeOf<Value extends Any> = Value[typeof TypeId]["dbType"];
+/** Extracts an expression's nullability state. */
+export type NullabilityOf<Value extends Any> = Value[typeof TypeId]["nullability"];
+/** Extracts an expression's kind. */
+export type KindOf<Value extends Any> = Value[typeof TypeId]["kind"];
+/** Extracts an expression's source dependency union. */
+export type DependenciesOf<Value extends Any> = Value extends Scalar<any, any, any, any, any, infer Deps> ? Deps : never;
+/** Extracts an expression's grouping identity. */
+export type GroupKeyOf<Value extends Any> = Value extends Scalar<any, any, any, any, any, any, infer GroupKey> ? GroupKey : never;
+/** Maps a database type descriptor back to its decoded runtime type. */
+export type RuntimeOfDbType<Db extends DbType.Any> = RuntimeOfDbTypeLookup<Db>;