@prisma-next/sql-relational-core 0.3.0-pr.99.6 → 0.3.0

package/dist/types-V1qiC5DO.d.mts

@@ -0,0 +1,200 @@
+import { G as ParamRef, d as AnyQueryAst, h as ColumnRef } from "./types-CLCtwVWx.mjs";
+import { t as SqlQueryPlan } from "./plan-5qUWdlJM.mjs";
+import { n as ExecutionContext } from "./query-lane-context-UlR8vOkd.mjs";
+import { Contract, ExecutionPlan, PlanRefs, ResultType } from "@prisma-next/contract/types";
+import { ParamSpec } from "@prisma-next/operations";
+import { SqlLoweringSpec } from "@prisma-next/sql-operations";
+import { ExtractFieldOutputTypes, SqlStorage, StorageColumn } from "@prisma-next/sql-contract/types";
+
+//#region src/types.d.ts
+type Expr = ColumnRef | ParamRef;
+/**
+ * Extracts the model name for a given table by iterating models to find the one
+ * whose `storage.table` matches.
+ */
+type ExtractTableToModel<TContract extends Contract<SqlStorage>, TableName extends string> = TContract['models'] extends infer Models extends Record<string, unknown> ? { [M in keyof Models & string]: Models[M] extends {
+  readonly storage: {
+    readonly table: TableName;
+  };
+} ? M : never }[keyof Models & string] : never;
+/**
+ * Extracts the field name for a given column by finding the field in
+ * `model.storage.fields` whose `column` matches.
+ */
+type ExtractColumnToField<TContract extends Contract<SqlStorage>, TableName extends string, ColumnName extends string> = ExtractTableToModel<TContract, TableName> extends infer ModelName extends string ? TContract['models'] extends infer Models extends Record<string, unknown> ? ModelName & keyof Models extends infer MKey extends string ? Models[MKey] extends {
+  readonly storage: {
+    readonly fields: infer Fields extends Record<string, unknown>;
+  };
+} ? { [F in keyof Fields & string]: Fields[F] extends {
+  readonly column: ColumnName;
+} ? F : never }[keyof Fields & string] : never : never : never : never;
+type FallbackCodecLookup<ColumnMeta extends StorageColumn, CodecTypes$1 extends Record<string, {
+  readonly output: unknown;
+}>> = ColumnMeta extends {
+  codecId: infer CodecId extends string;
+} ? CodecId extends keyof CodecTypes$1 ? CodecTypes$1[CodecId] extends {
+  readonly output: infer O;
+} ? ColumnMeta extends {
+  nullable: true;
+} ? O | null : O : unknown : unknown : unknown;
+/**
+ * Type-level operation signature.
+ * Represents an operation at the type level for use in contract type maps.
+ */
+type OperationTypeSignature = {
+  readonly args: ReadonlyArray<ParamSpec>;
+  readonly returns: ParamSpec;
+  readonly lowering: SqlLoweringSpec;
+  readonly capabilities?: ReadonlyArray<string>;
+};
+/**
+ * Type-level operation registry.
+ * Maps typeId → operations, where operations is a record of method name → operation signature.
+ *
+ * Example:
+ * ```typescript
+ * type MyOperations: OperationTypes = {
+ *   'pg/vector@1': {
+ *     cosineDistance: {
+ *       args: [{ codecId: 'pg/vector@1'; nullable: false }];
+ *       returns: { codecId: 'core/float8'; nullable: false };
+ *       lowering: { targetFamily: 'sql'; strategy: 'function'; template: '...' };
+ *     };
+ *   };
+ * };
+ * ```
+ */
+type OperationTypes = Record<string, Record<string, OperationTypeSignature>>;
+/**
+ * CodecTypes represents a map of typeId to codec definitions.
+ * Each codec definition must have an `output` property indicating the JavaScript type.
+ *
+ * Example:
+ * ```typescript
+ * type MyCodecTypes: CodecTypes = {
+ *   'pg/int4@1': { output: number };
+ *   'pg/text@1': { output: string };
+ * };
+ * ```
+ */
+type CodecTypes = Record<string, {
+  readonly output: unknown;
+}>;
+/**
+ * Extracts operations for a given typeId from the operation registry.
+ * Returns an empty record if the typeId is not found.
+ *
+ * @example
+ * ```typescript
+ * type Ops = OperationsForTypeId<'pg/vector@1', MyOperations>;
+ * // Ops = { cosineDistance: { ... }, l2Distance: { ... } }
+ * ```
+ */
+type OperationsForTypeId<TypeId extends string, Operations extends OperationTypes> = Operations extends Record<string, never> ? Record<string, never> : TypeId extends keyof Operations ? Operations[TypeId] : Record<string, never>;
+type ComputeColumnJsType<TContract extends Contract<SqlStorage>, TableName extends string, ColumnName extends string, ColumnMeta extends StorageColumn, CodecTypes$1 extends Record<string, {
+  readonly output: unknown;
+}>> = ExtractTableToModel<TContract, TableName> extends infer ModelName ? [ModelName] extends [never] ? FallbackCodecLookup<ColumnMeta, CodecTypes$1> : ModelName extends string ? ExtractColumnToField<TContract, TableName, ColumnName> extends infer FieldName ? [FieldName] extends [never] ? FallbackCodecLookup<ColumnMeta, CodecTypes$1> : FieldName extends string ? ModelName extends keyof ExtractFieldOutputTypes<TContract> ? FieldName extends keyof ExtractFieldOutputTypes<TContract>[ModelName] ? ExtractFieldOutputTypes<TContract>[ModelName][FieldName] : never : never : never : never : never : never;
+/**
+ * Utility type to check if a contract has the required capabilities for includeMany.
+ * Requires both `lateral` and `jsonAgg` to be `true` in the contract's capabilities for the target.
+ * Capabilities are nested by target: `{ [target]: { lateral: true, jsonAgg: true } }`
+ */
+type HasIncludeManyCapabilities<TContract extends Contract<SqlStorage>> = TContract extends {
+  capabilities: infer C;
+  target: infer T;
+} ? T extends string ? C extends Record<string, Record<string, boolean>> ? C extends { [K in T]: infer TargetCaps } ? TargetCaps extends {
+  lateral: true;
+  jsonAgg: true;
+} ? true : false : false : false : false : false;
+/**
+ * SQL-specific Plan type that refines the ast field to use AnyQueryAst.
+ * This is the type used by SQL query builders.
+ */
+type SqlPlan<Row = unknown> = ExecutionPlan<Row, AnyQueryAst>;
+/**
+ * Helper types for extracting contract structure.
+ */
+type TablesOf<TContract> = TContract extends {
+  storage: {
+    tables: infer U;
+  };
+} ? U : never;
+type TableKey<TContract> = Extract<keyof TablesOf<TContract>, string>;
+/**
+ * Unique symbol for metadata property to avoid collisions with user-defined properties
+ */
+declare const META: unique symbol;
+/**
+ * Extracts metadata from a type that has a META property
+ */
+type Meta<T$1 extends {
+  [META]: unknown;
+}> = T$1[typeof META];
+/**
+ * Metadata interface for table definitions
+ */
+interface TableMetadata<Name extends string> {
+  name: Name;
+}
+/**
+ * Metadata interface for model definitions
+ */
+interface ModelMetadata<Name extends string> {
+  name: Name;
+}
+/**
+ * Base interface for table definitions with metadata
+ * Used in contract.d.ts to define storage-level table types
+ */
+interface TableDef<Name extends string> {
+  readonly [META]: TableMetadata<Name>;
+}
+/**
+ * Base interface for model definitions with metadata
+ * Used in contract.d.ts to define application-level model types
+ */
+interface ModelDef<Name extends string> {
+  readonly [META]: ModelMetadata<Name>;
+}
+type ColumnsOf<TContract, K extends TableKey<TContract>> = K extends keyof TablesOf<TContract> ? TablesOf<TContract>[K] extends {
+  columns: infer C;
+} ? C : never : never;
+interface RawTemplateOptions {
+  readonly refs?: PlanRefs;
+  readonly annotations?: Record<string, unknown>;
+  readonly projection?: ReadonlyArray<string>;
+}
+interface RawFunctionOptions extends RawTemplateOptions {
+  readonly params: ReadonlyArray<unknown>;
+}
+type RawTemplateFactory = (strings: TemplateStringsArray, ...values: readonly unknown[]) => ExecutionPlan;
+interface RawFactory extends RawTemplateFactory {
+  (text: string, options: RawFunctionOptions): ExecutionPlan;
+  with(options: RawTemplateOptions): RawTemplateFactory;
+}
+interface RuntimeError extends Error {
+  readonly code: string;
+  readonly category: 'PLAN';
+  readonly severity: 'error';
+  readonly details?: Record<string, unknown>;
+  readonly hints?: readonly string[];
+  readonly docs?: readonly string[];
+}
+interface BuildParamsMap {
+  readonly [name: string]: unknown;
+}
+interface BuildOptions {
+  readonly params?: BuildParamsMap;
+}
+interface SqlBuilderOptions<TContract extends Contract<SqlStorage> = Contract<SqlStorage>> {
+  readonly context: ExecutionContext<TContract>;
+}
+/**
+ * SQL-specific ResultType that works with both Plan and SqlQueryPlan.
+ * This extends the core ResultType to also handle SqlQueryPlan.
+ * Example: `type Row = ResultType<typeof plan>`
+ */
+type ResultType$1<P> = P extends SqlQueryPlan<infer R> ? R : ResultType<P>;
+//#endregion
+export { TableDef as C, TablesOf as E, SqlPlan as S, TableMetadata as T, RawTemplateFactory as _, ComputeColumnJsType as a, RuntimeError as b, META as c, ModelMetadata as d, OperationTypeSignature as f, RawFunctionOptions as g, RawFactory as h, ColumnsOf as i, Meta as l, OperationsForTypeId as m, BuildParamsMap as n, Expr as o, OperationTypes as p, CodecTypes as r, HasIncludeManyCapabilities as s, BuildOptions as t, ModelDef as u, RawTemplateOptions as v, TableKey as w, SqlBuilderOptions as x, ResultType$1 as y };
+//# sourceMappingURL=types-V1qiC5DO.d.mts.map

package/dist/types-V1qiC5DO.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-V1qiC5DO.d.mts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":"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"}

package/package.json

@@ -1,23 +1,26 @@
 {
   "name": "@prisma-next/sql-relational-core",
-  "version": "0.3.0-pr.99.6",
+  "version": "0.3.0",
   "type": "module",
   "sideEffects": false,
-  "description": "Schema and column builders, operation attachment, and AST types for Prisma Next",
+  "description": "AST types, query lane context, and type utilities for Prisma Next SQL lanes",
   "dependencies": {
+    "arktype": "^2.1.29",
     "ts-toolbelt": "^9.6.0",
-    "@prisma-next/contract": "0.3.0-pr.99.6",
-    "@prisma-next/plan": "0.3.0-pr.99.6",
-    "@prisma-next/sql-contract": "0.3.0-pr.99.6",
-    "@prisma-next/operations": "0.3.0-pr.99.6",
-    "@prisma-next/sql-operations": "0.3.0-pr.99.6"
+    "@prisma-next/contract": "0.3.0",
+    "@prisma-next/operations": "0.3.0",
+    "@prisma-next/sql-contract": "0.3.0",
+    "@prisma-next/utils": "0.3.0",
+    "@prisma-next/sql-operations": "0.3.0",
+    "@prisma-next/framework-components": "0.3.0"
   },
   "devDependencies": {
-    "tsup": "8.5.1",
+    "tsdown": "0.18.4",
     "typescript": "5.9.3",
-    "vitest": "4.0.16",
-    "@prisma-next/sql-contract-ts": "0.3.0-pr.99.6",
+    "vitest": "4.0.17",
+    "@prisma-next/sql-contract-ts": "0.3.0",
     "@prisma-next/test-utils": "0.0.1",
+    "@prisma-next/tsdown": "0.0.0",
     "@prisma-next/tsconfig": "0.0.0"
   },
   "files": [
@@ -25,49 +28,24 @@
     "src"
   ],
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./schema": {
-      "types": "./dist/exports/schema.d.ts",
-      "import": "./dist/exports/schema.js"
-    },
-    "./param": {
-      "types": "./dist/exports/param.d.ts",
-      "import": "./dist/exports/param.js"
-    },
-    "./types": {
-      "types": "./dist/exports/types.d.ts",
-      "import": "./dist/exports/types.js"
-    },
-    "./operations-registry": {
-      "types": "./dist/exports/operations-registry.d.ts",
-      "import": "./dist/exports/operations-registry.js"
-    },
-    "./errors": {
-      "types": "./dist/exports/errors.d.ts",
-      "import": "./dist/exports/errors.js"
-    },
-    "./ast": {
-      "types": "./dist/exports/ast.d.ts",
-      "import": "./dist/exports/ast.js"
-    },
-    "./plan": {
-      "types": "./dist/exports/plan.d.ts",
-      "import": "./dist/exports/plan.js"
-    },
-    "./query-lane-context": {
-      "types": "./dist/exports/query-lane-context.d.ts",
-      "import": "./dist/exports/query-lane-context.js"
-    },
-    "./utils/guards": {
-      "types": "./dist/exports/guards.d.ts",
-      "import": "./dist/exports/guards.js"
-    }
+    ".": "./dist/index.mjs",
+    "./ast": "./dist/exports/ast.mjs",
+    "./errors": "./dist/exports/errors.mjs",
+    "./plan": "./dist/exports/plan.mjs",
+    "./query-lane-context": "./dist/exports/query-lane-context.mjs",
+    "./types": "./dist/exports/types.mjs",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/2-sql/4-lanes/relational-core"
   },
   "scripts": {
-    "build": "tsup --config tsup.config.ts && tsc --project tsconfig.build.json",
+    "build": "tsdown",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --project tsconfig.json --noEmit",

package/src/ast/adapter-types.ts

@@ -2,6 +2,11 @@ import type { CodecRegistry } from './codec-types';
 
 export type AdapterTarget = string;
 
+export interface MarkerStatement {
+  readonly sql: string;
+  readonly params: readonly unknown[];
+}
+
 export interface AdapterProfile<TTarget extends AdapterTarget = AdapterTarget> {
   readonly id: string;
   readonly target: TTarget;
@@ -12,6 +17,12 @@ export interface AdapterProfile<TTarget extends AdapterTarget = AdapterTarget> {
    * between wire types and JavaScript types.
    */
   codecs(): CodecRegistry;
+  /**
+   * Returns the SQL statement to read the contract marker from the database.
+   * Each adapter provides target-specific SQL (e.g. schema-qualified table names,
+   * parameter placeholder style).
+   */
+  readMarkerStatement(): MarkerStatement;
 }
 
 export interface LoweredPayload<TBody = unknown> {

package/src/ast/codec-types.ts

@@ -1,5 +1,36 @@
+import type { JsonValue } from '@prisma-next/contract/types';
+import type { Codec as BaseCodec, CodecTrait } from '@prisma-next/framework-components/codec';
+import { ifDefined } from '@prisma-next/utils/defined';
+import type { Type } from 'arktype';
 import type { O } from 'ts-toolbelt';
 
+export type { CodecTrait } from '@prisma-next/framework-components/codec';
+
+/**
+ * Descriptor for parameterized codecs that require type parameter validation.
+ * Shared between adapter (compile-time) and runtime layers to avoid duplication.
+ *
+ * @template TParams - The shape of the type parameters (e.g., `{ length: number }`)
+ * @template THelper - The type returned by the optional `init` hook
+ */
+export interface CodecParamsDescriptor<TParams = Record<string, unknown>, THelper = unknown> {
+  /** The codec ID this descriptor applies to (e.g., 'pg/vector@1') */
+  readonly codecId: string;
+
+  /**
+   * Arktype schema for validating typeParams.
+   * Used to validate both storage.types entries and inline column typeParams.
+   */
+  readonly paramsSchema: Type<TParams>;
+
+  /**
+   * Optional init hook called during runtime context creation.
+   * Receives validated params and returns a helper object to be stored in context.types.
+   * If not provided, the validated params are stored directly.
+   */
+  readonly init?: (params: TParams) => THelper;
+}
+
 /**
  * Codec metadata for database-specific type information.
  * Used for schema introspection and verification.
@@ -15,42 +46,23 @@ export interface CodecMeta {
 }
 
 /**
- * Codec interface for encoding/decoding values between wire format and JavaScript types.
+ * SQL codec interface — extends the framework base with SQL-specific fields.
  *
  * Codecs are pure, synchronous functions with no side effects or IO.
- * They provide deterministic conversion between database wire types and JS values.
+ * They provide deterministic conversion between database wire types and JS values,
+ * and between JS values and contract JSON.
  */
-export interface Codec<Id extends string = string, TWire = unknown, TJs = unknown> {
-  /**
-   * Namespaced codec identifier in format 'namespace/name@version'
-   * Examples: 'pg/text@1', 'pg/uuid@1', 'pg/timestamptz@1'
-   */
-  readonly id: Id;
-
-  /**
-   * Contract scalar type IDs that this codec can handle.
-   * Examples: ['text'], ['int4', 'float8'], ['timestamp', 'timestamptz']
-   */
-  readonly targetTypes: readonly string[];
-
-  /**
-   * Optional metadata for database-specific type information.
-   * Used for schema introspection and verification.
-   */
+export interface Codec<
+  Id extends string = string,
+  TTraits extends readonly CodecTrait[] = readonly CodecTrait[],
+  TWire = unknown,
+  TJs = unknown,
+  TParams = Record<string, unknown>,
+  THelper = unknown,
+> extends BaseCodec<Id, TTraits, TWire, TJs> {
   readonly meta?: CodecMeta;
-
-  /**
-   * Decode a wire value (from database) to JavaScript type.
-   * Must be synchronous and pure (no side effects).
-   */
-  decode(wire: TWire): TJs;
-
-  /**
-   * Encode a JavaScript value to wire format (for database).
-   * Optional - if not provided, values pass through unchanged.
-   * Must be synchronous and pure (no side effects).
-   */
-  encode?(value: TJs): TWire;
+  readonly paramsSchema?: Type<TParams>;
+  readonly init?: (params: TParams) => THelper;
 }
 
 /**
@@ -67,6 +79,10 @@ export interface CodecRegistry {
   getByScalar(scalar: string): readonly Codec<string>[];
   getDefaultCodec(scalar: string): Codec<string> | undefined;
   register(codec: Codec<string>): void;
+  /** Returns true if the codec with this ID has the given trait. */
+  hasTrait(codecId: string, trait: CodecTrait): boolean;
+  /** Returns all traits for a codec, or an empty array if not found. */
+  traitsOf(codecId: string): readonly CodecTrait[];
   [Symbol.iterator](): Iterator<Codec<string>>;
   values(): IterableIterator<Codec<string>>;
 }
@@ -136,6 +152,15 @@ class CodecRegistryImpl implements CodecRegistry {
     }
   }
 
+  hasTrait(codecId: string, trait: CodecTrait): boolean {
+    const codec = this._byId.get(codecId);
+    return codec?.traits?.includes(trait) ?? false;
+  }
+
+  traitsOf(codecId: string): readonly CodecTrait[] {
+    return this._byId.get(codecId)?.traits ?? [];
+  }
+
   /**
    * Returns an iterator over all registered codecs.
    * Useful for iterating through codecs from another registry.
@@ -156,20 +181,44 @@ class CodecRegistryImpl implements CodecRegistry {
 
 /**
  * Codec factory - creates a codec with typeId and encode/decode functions.
+ * Provides identity defaults for encodeJson/decodeJson when not supplied.
  */
-export function codec<Id extends string, TWire, TJs>(config: {
+export function codec<
+  Id extends string,
+  const TTraits extends readonly CodecTrait[],
+  TWire,
+  TJs,
+  TParams = Record<string, unknown>,
+  THelper = unknown,
+>(config: {
   typeId: Id;
   targetTypes: readonly string[];
   encode: (value: TJs) => TWire;
   decode: (wire: TWire) => TJs;
+  encodeJson?: (value: TJs) => JsonValue;
+  decodeJson?: (json: JsonValue) => TJs;
   meta?: CodecMeta;
-}): Codec<Id, TWire, TJs> {
+  paramsSchema?: Type<TParams>;
+  init?: (params: TParams) => THelper;
+  traits?: TTraits;
+  renderOutputType?: (typeParams: Record<string, unknown>) => string | undefined;
+}): Codec<Id, TTraits, TWire, TJs, TParams, THelper> {
+  const identity = (v: unknown) => v;
   return {
     id: config.typeId,
     targetTypes: config.targetTypes,
-    ...(config.meta ? { meta: config.meta } : {}),
+    ...ifDefined('meta', config.meta),
+    ...ifDefined('paramsSchema', config.paramsSchema),
+    ...ifDefined('init', config.init),
+    ...ifDefined(
+      'traits',
+      config.traits ? (Object.freeze([...config.traits]) as TTraits) : undefined,
+    ),
+    ...ifDefined('renderOutputType', config.renderOutputType),
     encode: config.encode,
     decode: config.decode,
+    encodeJson: (config.encodeJson ?? identity) as (value: TJs) => JsonValue,
+    decodeJson: (config.decodeJson ?? identity) as (json: JsonValue) => TJs,
   };
 }
 
@@ -177,13 +226,13 @@ export function codec<Id extends string, TWire, TJs>(config: {
  * Type helpers to extract codec types.
  */
 export type CodecId<T> =
-  T extends Codec<infer Id, unknown, unknown>
-    ? Id
-    : T extends { readonly id: infer Id }
-      ? Id
-      : never;
-export type CodecInput<T> = T extends Codec<string, unknown, infer JsT> ? JsT : never;
-export type CodecOutput<T> = T extends Codec<string, unknown, infer JsT> ? JsT : never;
+  T extends Codec<infer Id> ? Id : T extends { readonly id: infer Id } ? Id : never;
+export type CodecInput<T> =
+  T extends Codec<string, readonly CodecTrait[], unknown, infer JsT> ? JsT : never;
+export type CodecOutput<T> =
+  T extends Codec<string, readonly CodecTrait[], unknown, infer JsT> ? JsT : never;
+export type CodecTraits<T> =
+  T extends Codec<string, infer TTraits> ? TTraits[number] & CodecTrait : never;
 
 /**
  * Type helper to extract codec types from builder instance.
@@ -191,11 +240,10 @@ export type CodecOutput<T> = T extends Codec<string, unknown, infer JsT> ? JsT :
 export type ExtractCodecTypes<
   ScalarNames extends { readonly [K in keyof ScalarNames]: Codec<string> } = Record<never, never>,
 > = {
-  readonly [K in keyof ScalarNames as ScalarNames[K] extends Codec<infer Id, unknown, unknown>
-    ? Id
-    : never]: {
+  readonly [K in keyof ScalarNames as ScalarNames[K] extends Codec<infer Id> ? Id : never]: {
     readonly input: CodecInput<ScalarNames[K]>;
     readonly output: CodecOutput<ScalarNames[K]>;
+    readonly traits: CodecTraits<ScalarNames[K]>;
   };
 };
 
@@ -231,9 +279,7 @@ export interface CodecDefBuilder<
 
   readonly codecDefinitions: {
     readonly [K in keyof ScalarNames]: {
-      readonly typeId: ScalarNames[K] extends Codec<infer Id extends string, unknown, unknown>
-        ? Id
-        : never;
+      readonly typeId: ScalarNames[K] extends Codec<infer Id extends string> ? Id : never;
       readonly scalar: K;
       readonly codec: ScalarNames[K];
       readonly input: CodecInput<ScalarNames[K]>;
@@ -269,12 +315,16 @@ class CodecDefBuilderImpl<
     this._codecs = codecs;
 
     // Populate CodecTypes from codecs
-    const codecTypes: Record<string, { readonly input: unknown; readonly output: unknown }> = {};
+    const codecTypes: Record<
+      string,
+      { readonly input: unknown; readonly output: unknown; readonly traits: unknown }
+    > = {};
     for (const [, codecImpl] of Object.entries(this._codecs)) {
       const codecImplTyped = codecImpl as Codec<string>;
       codecTypes[codecImplTyped.id] = {
         input: undefined as unknown as CodecInput<typeof codecImplTyped>,
         output: undefined as unknown as CodecOutput<typeof codecImplTyped>,
+        traits: undefined as unknown as CodecTraits<typeof codecImplTyped>,
       };
     }
     this.CodecTypes = codecTypes as ExtractCodecTypes<ScalarNames>;
@@ -314,7 +364,7 @@ class CodecDefBuilderImpl<
    */
   get codecDefinitions(): {
     readonly [K in keyof ScalarNames]: {
-      readonly typeId: ScalarNames[K] extends Codec<infer Id, unknown, unknown> ? Id : never;
+      readonly typeId: ScalarNames[K] extends Codec<infer Id> ? Id : never;
       readonly scalar: K;
       readonly codec: ScalarNames[K];
       readonly input: CodecInput<ScalarNames[K]>;
@@ -348,9 +398,7 @@ class CodecDefBuilderImpl<
 
     return result as {
       readonly [K in keyof ScalarNames]: {
-        readonly typeId: ScalarNames[K] extends Codec<infer Id extends string, unknown, unknown>
-          ? Id
-          : never;
+        readonly typeId: ScalarNames[K] extends Codec<infer Id extends string> ? Id : never;
         readonly scalar: K;
         readonly codec: ScalarNames[K];
         readonly input: CodecInput<ScalarNames[K]>;

package/src/ast/driver-types.ts

@@ -13,13 +13,30 @@ export interface SqlExplainResult<Row = Record<string, unknown>> {
   readonly rows: ReadonlyArray<Row>;
 }
 
-export interface SqlDriver {
-  connect(): Promise<void>;
+export type SqlDriverState = 'unbound' | 'connected' | 'closed';
+
+export interface SqlDriver<TBinding = void> extends SqlQueryable {
+  readonly state?: SqlDriverState;
+  connect(binding: TBinding): Promise<void>;
+  acquireConnection(): Promise<SqlConnection>;
+  close(): Promise<void>;
+}
+
+export interface SqlConnection extends SqlQueryable {
+  beginTransaction(): Promise<SqlTransaction>;
+  release(): Promise<void>;
+}
+
+export interface SqlTransaction extends SqlQueryable {
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+}
+
+export interface SqlQueryable {
   execute<Row = Record<string, unknown>>(request: SqlExecuteRequest): AsyncIterable<Row>;
   explain?(request: SqlExecuteRequest): Promise<SqlExplainResult>;
   query<Row = Record<string, unknown>>(
     sql: string,
     params?: readonly unknown[],
   ): Promise<SqlQueryResult<Row>>;
-  close(): Promise<void>;
 }