@prisma-next/sql-relational-core 0.3.0-dev.5 → 0.3.0-dev.50

package/package.json

@@ -1,79 +1,62 @@
 {
   "name": "@prisma-next/sql-relational-core",
-  "version": "0.3.0-dev.5",
+  "version": "0.3.0-dev.50",
   "type": "module",
   "sideEffects": false,
   "description": "Schema and column builders, operation attachment, and AST types for Prisma Next",
   "dependencies": {
+    "arktype": "^2.1.29",
     "ts-toolbelt": "^9.6.0",
-    "@prisma-next/contract": "0.3.0-dev.5",
-    "@prisma-next/operations": "0.3.0-dev.5",
-    "@prisma-next/plan": "0.3.0-dev.5",
-    "@prisma-next/sql-contract": "0.3.0-dev.5",
-    "@prisma-next/sql-operations": "0.3.0-dev.5"
+    "@prisma-next/contract": "0.3.0-dev.50",
+    "@prisma-next/operations": "0.3.0-dev.50",
+    "@prisma-next/sql-contract": "0.3.0-dev.50",
+    "@prisma-next/plan": "0.3.0-dev.50",
+    "@prisma-next/sql-operations": "0.3.0-dev.50",
+    "@prisma-next/utils": "0.3.0-dev.50"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "4.0.16",
-    "tsup": "8.5.1",
+    "tsdown": "0.18.4",
     "typescript": "5.9.3",
-    "vitest": "4.0.16",
-    "@prisma-next/sql-contract-ts": "0.3.0-dev.5",
-    "@prisma-next/test-utils": "0.0.1"
+    "vitest": "4.0.17",
+    "@prisma-next/sql-contract-ts": "0.3.0-dev.50",
+    "@prisma-next/test-utils": "0.0.1",
+    "@prisma-next/tsconfig": "0.0.0",
+    "@prisma-next/tsdown": "0.0.0"
   },
   "files": [
     "dist",
     "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",
+    "./guards": "./dist/exports/guards.mjs",
+    "./operations-registry": "./dist/exports/operations-registry.mjs",
+    "./param": "./dist/exports/param.mjs",
+    "./plan": "./dist/exports/plan.mjs",
+    "./query-lane-context": "./dist/exports/query-lane-context.mjs",
+    "./schema": "./dist/exports/schema.mjs",
+    "./types": "./dist/exports/types.mjs",
+    "./utils/guards": "./dist/exports/utils/guards.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",
-    "lint": "biome check . --config-path ../../../../biome.json --error-on-warnings",
-    "lint:fix": "biome check --write . --config-path ../../../../biome.json",
-    "lint:fix:unsafe": "biome check --write --unsafe . --config-path ../../../../biome.json",
-    "clean": "node ../../../../scripts/clean.mjs"
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
   }
 }

package/src/ast/codec-types.ts

@@ -1,5 +1,32 @@
+import { ifDefined } from '@prisma-next/utils/defined';
+import type { Type } from 'arktype';
 import type { O } from 'ts-toolbelt';
 
+/**
+ * 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.
@@ -20,7 +47,13 @@ export interface CodecMeta {
  * Codecs are pure, synchronous functions with no side effects or IO.
  * They provide deterministic conversion between database wire types and JS values.
  */
-export interface Codec<Id extends string = string, TWire = unknown, TJs = unknown> {
+export interface Codec<
+  Id extends string = string,
+  TWire = unknown,
+  TJs = unknown,
+  TParams = Record<string, unknown>,
+  THelper = unknown,
+> {
   /**
    * Namespaced codec identifier in format 'namespace/name@version'
    * Examples: 'pg/text@1', 'pg/uuid@1', 'pg/timestamptz@1'
@@ -39,6 +72,31 @@ export interface Codec<Id extends string = string, TWire = unknown, TJs = unknow
    */
   readonly meta?: CodecMeta;
 
+  /**
+   * Optional params schema for parameterized codecs.
+   * If provided, typeParams are validated against this schema.
+   */
+  readonly paramsSchema?: Type<TParams>;
+
+  /**
+   * Optional init hook for building runtime helper state from validated params.
+   *
+   * Useful when parameterized types need derived data at runtime, for example:
+   * - normalize typeParams into a stable helper shape consumed by lanes/adapters
+   * - precompute reusable values once during context creation
+   * - avoid repeating typeParams parsing logic during query execution
+   *
+   * Example:
+   *   { length: 255 } -> { kind: 'variable', maxLength: 255 }
+   *
+   * **Convention for JSON/JSONB codecs**: When the helper includes a `validate`
+   * property of type `JsonSchemaValidateFn`, the runtime will use it to enforce
+   * JSON Schema conformance during encoding and decoding. The property is
+   * discovered via duck typing (`helper?.validate`) for flexibility across
+   * different codec types.
+   */
+  readonly init?: (params: TParams) => THelper;
+
   /**
    * Decode a wire value (from database) to JavaScript type.
    * Must be synchronous and pure (no side effects).
@@ -157,17 +215,27 @@ class CodecRegistryImpl implements CodecRegistry {
 /**
  * Codec factory - creates a codec with typeId and encode/decode functions.
  */
-export function codec<Id extends string, TWire, TJs>(config: {
+export function codec<
+  Id extends string,
+  TWire,
+  TJs,
+  TParams = Record<string, unknown>,
+  THelper = unknown,
+>(config: {
   typeId: Id;
   targetTypes: readonly string[];
   encode: (value: TJs) => TWire;
   decode: (wire: TWire) => TJs;
   meta?: CodecMeta;
-}): Codec<Id, TWire, TJs> {
+  paramsSchema?: Type<TParams>;
+  init?: (params: TParams) => THelper;
+}): Codec<Id, TWire, TJs, TParams, THelper> {
   return {
     id: config.typeId,
     targetTypes: config.targetTypes,
-    ...(config.meta ? { meta: config.meta } : {}),
+    ...ifDefined('meta', config.meta),
+    ...ifDefined('paramsSchema', config.paramsSchema),
+    ...ifDefined('init', config.init),
     encode: config.encode,
     decode: config.decode,
   };
@@ -176,11 +244,12 @@ 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 }
+export type CodecId<T> =
+  T extends Codec<infer Id, unknown, unknown>
     ? Id
-    : never;
+    : 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;
 

package/src/ast/delete.ts

@@ -1,9 +1,9 @@
-import type { BinaryExpr, ColumnRef, DeleteAst, TableRef } from './types';
+import type { ColumnRef, DeleteAst, TableRef, WhereExpr } from './types';
 import { compact } from './util';
 
 export interface CreateDeleteAstOptions {
   readonly table: TableRef;
-  readonly where: BinaryExpr;
+  readonly where: WhereExpr;
   readonly returning?: ReadonlyArray<ColumnRef>;
 }
 

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>;
 }

package/src/ast/predicate.ts

@@ -1,17 +1,19 @@
 import type {
   BinaryExpr,
   BinaryOp,
-  ColumnRef,
   ExistsExpr,
-  OperationExpr,
+  Expression,
+  ListLiteralExpr,
+  LiteralExpr,
+  NullCheckExpr,
   ParamRef,
   SelectAst,
 } from './types';
 
 export function createBinaryExpr(
   op: BinaryOp,
-  left: ColumnRef | OperationExpr,
-  right: ColumnRef | ParamRef,
+  left: Expression,
+  right: Expression | ParamRef | LiteralExpr | ListLiteralExpr,
 ): BinaryExpr {
   return {
     kind: 'bin',
@@ -28,3 +30,11 @@ export function createExistsExpr(not: boolean, subquery: SelectAst): ExistsExpr
     subquery,
   };
 }
+
+export function createNullCheckExpr(expr: Expression, isNull: boolean): NullCheckExpr {
+  return {
+    kind: 'nullCheck',
+    expr,
+    isNull,
+  };
+}

package/src/ast/select.ts

@@ -1,14 +1,13 @@
 import type {
-  BinaryExpr,
   ColumnRef,
   Direction,
-  ExistsExpr,
   IncludeAst,
   IncludeRef,
   JoinAst,
   OperationExpr,
   SelectAst,
   TableRef,
+  WhereExpr,
 } from './types';
 import { compact } from './util';
 
@@ -20,9 +19,10 @@ export interface CreateSelectAstOptions {
     alias: string;
     expr: ColumnRef | IncludeRef | OperationExpr;
   }>;
-  readonly where?: BinaryExpr | ExistsExpr;
+  readonly where?: WhereExpr;
   readonly orderBy?: ReadonlyArray<{ expr: ColumnRef | OperationExpr; dir: Direction }>;
   readonly limit?: number;
+  readonly selectAllIntent?: { table?: string };
 }
 
 export function createSelectAst(options: CreateSelectAstOptions): SelectAst {
@@ -35,5 +35,6 @@ export function createSelectAst(options: CreateSelectAstOptions): SelectAst {
     where: options.where,
     orderBy: options.orderBy,
     limit: options.limit,
+    selectAllIntent: options.selectAllIntent,
   }) as SelectAst;
 }

package/src/ast/sql-codecs.ts

@@ -0,0 +1,67 @@
+import { type as arktype } from 'arktype';
+import { codec, defineCodecs } from './codec-types';
+
+export const SQL_CHAR_CODEC_ID = 'sql/char@1' as const;
+export const SQL_VARCHAR_CODEC_ID = 'sql/varchar@1' as const;
+export const SQL_INT_CODEC_ID = 'sql/int@1' as const;
+export const SQL_FLOAT_CODEC_ID = 'sql/float@1' as const;
+
+const lengthParamsSchema = arktype({
+  length: 'number.integer > 0',
+});
+
+type LengthTypeHelper = {
+  readonly kind: 'fixed' | 'variable';
+  readonly maxLength: number;
+};
+
+function createLengthTypeHelper(
+  kind: LengthTypeHelper['kind'],
+): (params: Record<string, unknown>) => LengthTypeHelper {
+  return (params) => ({
+    kind,
+    maxLength: params['length'] as number,
+  });
+}
+
+const sqlCharCodec = codec<typeof SQL_CHAR_CODEC_ID, string, string>({
+  typeId: SQL_CHAR_CODEC_ID,
+  targetTypes: ['char'],
+  encode: (value: string): string => value,
+  decode: (wire: string): string => wire.trimEnd(),
+  paramsSchema: lengthParamsSchema,
+  init: createLengthTypeHelper('fixed'),
+});
+
+const sqlVarcharCodec = codec<typeof SQL_VARCHAR_CODEC_ID, string, string>({
+  typeId: SQL_VARCHAR_CODEC_ID,
+  targetTypes: ['varchar'],
+  encode: (value: string): string => value,
+  decode: (wire: string): string => wire,
+  paramsSchema: lengthParamsSchema,
+  init: createLengthTypeHelper('variable'),
+});
+
+const sqlIntCodec = codec<typeof SQL_INT_CODEC_ID, number, number>({
+  typeId: SQL_INT_CODEC_ID,
+  targetTypes: ['int'],
+  encode: (value) => value,
+  decode: (wire) => wire,
+});
+
+const sqlFloatCodec = codec<typeof SQL_FLOAT_CODEC_ID, number, number>({
+  typeId: SQL_FLOAT_CODEC_ID,
+  targetTypes: ['float'],
+  encode: (value) => value,
+  decode: (wire) => wire,
+});
+
+const codecs = defineCodecs()
+  .add('char', sqlCharCodec)
+  .add('varchar', sqlVarcharCodec)
+  .add('int', sqlIntCodec)
+  .add('float', sqlFloatCodec);
+
+export const sqlCodecDefinitions = codecs.codecDefinitions;
+export const sqlDataTypes = codecs.dataTypes;
+export type SqlCodecTypes = typeof codecs.CodecTypes;

package/src/ast/types.ts

@@ -1,3 +1,4 @@
+import type { ParamDescriptor } from '@prisma-next/contract/types';
 import type { ReturnSpec } from '@prisma-next/operations';
 import type { SqlLoweringSpec } from '@prisma-next/sql-operations';
 
@@ -32,23 +33,62 @@ export interface OperationExpr {
   readonly kind: 'operation';
   readonly method: string;
   readonly forTypeId: string;
-  readonly self: ColumnRef | OperationExpr;
-  readonly args: ReadonlyArray<ColumnRef | ParamRef | LiteralExpr | OperationExpr>;
+  readonly self: Expression;
+  readonly args: ReadonlyArray<Expression | ParamRef | LiteralExpr>;
   readonly returns: ReturnSpec;
   readonly lowering: SqlLoweringSpec;
 }
 
-export function isOperationExpr(expr: ColumnRef | OperationExpr): expr is OperationExpr {
+/**
+ * Unified expression type - the canonical AST representation for column references
+ * and operation expressions. This is what all builders convert to via toExpr().
+ */
+export type Expression = ColumnRef | OperationExpr;
+
+/**
+ * Interface for any builder that can produce an Expression.
+ * Implemented by ColumnBuilder and ExpressionBuilder.
+ */
+export interface ExpressionSource {
+  toExpr(): Expression;
+}
+
+export function isOperationExpr(expr: Expression): expr is OperationExpr {
   return expr.kind === 'operation';
 }
 
-export type BinaryOp = 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte';
+export type BinaryOp =
+  | 'eq'
+  | 'neq'
+  | 'gt'
+  | 'lt'
+  | 'gte'
+  | 'lte'
+  | 'like'
+  | 'ilike'
+  | 'in'
+  | 'notIn';
 
 export interface BinaryExpr {
   readonly kind: 'bin';
   readonly op: BinaryOp;
-  readonly left: ColumnRef | OperationExpr;
-  readonly right: ColumnRef | ParamRef;
+  readonly left: Expression;
+  readonly right: Expression | ParamRef | LiteralExpr | ListLiteralExpr;
+}
+
+export interface ListLiteralExpr {
+  readonly kind: 'listLiteral';
+  readonly values: ReadonlyArray<ParamRef | LiteralExpr>;
+}
+
+export interface AndExpr {
+  readonly kind: 'and';
+  readonly exprs: ReadonlyArray<WhereExpr>;
+}
+
+export interface OrExpr {
+  readonly kind: 'or';
+  readonly exprs: ReadonlyArray<WhereExpr>;
 }
 
 export interface ExistsExpr {
@@ -57,11 +97,40 @@ export interface ExistsExpr {
   readonly subquery: SelectAst;
 }
 
-export type JoinOnExpr = {
-  readonly kind: 'eqCol';
-  readonly left: ColumnRef;
-  readonly right: ColumnRef;
-};
+/**
+ * Unary expression for IS NULL / IS NOT NULL checks.
+ * Used in WHERE clauses to check for null values.
+ */
+export interface NullCheckExpr {
+  readonly kind: 'nullCheck';
+  readonly expr: Expression;
+  readonly isNull: boolean;
+}
+
+/**
+ * Union type for WHERE clause expressions.
+ */
+export type WhereExpr = BinaryExpr | ExistsExpr | NullCheckExpr | AndExpr | OrExpr;
+
+export interface BoundWhereExpr {
+  readonly expr: WhereExpr;
+  readonly params: readonly unknown[];
+  readonly paramDescriptors: ReadonlyArray<ParamDescriptor>;
+}
+
+export interface ToWhereExpr {
+  toWhereExpr(): BoundWhereExpr;
+}
+
+export type WhereArg = WhereExpr | ToWhereExpr;
+
+export type JoinOnExpr =
+  | {
+      readonly kind: 'eqCol';
+      readonly left: ColumnRef;
+      readonly right: ColumnRef;
+    }
+  | WhereExpr;
 
 export interface JoinAst {
   readonly kind: 'join';
@@ -81,10 +150,10 @@ export interface IncludeAst {
   readonly child: {
     readonly table: TableRef;
     readonly on: JoinOnExpr;
-    readonly where?: BinaryExpr | ExistsExpr;
-    readonly orderBy?: ReadonlyArray<{ expr: ColumnRef | OperationExpr; dir: Direction }>;
+    readonly where?: WhereExpr;
+    readonly orderBy?: ReadonlyArray<{ expr: Expression; dir: Direction }>;
     readonly limit?: number;
-    readonly project: ReadonlyArray<{ alias: string; expr: ColumnRef | OperationExpr }>;
+    readonly project: ReadonlyArray<{ alias: string; expr: Expression }>;
   };
 }
 
@@ -95,11 +164,12 @@ export interface SelectAst {
   readonly includes?: ReadonlyArray<IncludeAst>;
   readonly project: ReadonlyArray<{
     alias: string;
-    expr: ColumnRef | IncludeRef | OperationExpr | LiteralExpr;
+    expr: Expression | IncludeRef | LiteralExpr;
   }>;
-  readonly where?: BinaryExpr | ExistsExpr;
-  readonly orderBy?: ReadonlyArray<{ expr: ColumnRef | OperationExpr; dir: Direction }>;
+  readonly where?: WhereExpr;
+  readonly orderBy?: ReadonlyArray<{ expr: Expression; dir: Direction }>;
   readonly limit?: number;
+  readonly selectAllIntent?: { table?: string };
 }
 
 export interface InsertAst {
@@ -113,14 +183,14 @@ export interface UpdateAst {
   readonly kind: 'update';
   readonly table: TableRef;
   readonly set: Record<string, ColumnRef | ParamRef>;
-  readonly where: BinaryExpr;
+  readonly where?: WhereExpr;
   readonly returning?: ReadonlyArray<ColumnRef>;
 }
 
 export interface DeleteAst {
   readonly kind: 'delete';
   readonly table: TableRef;
-  readonly where: BinaryExpr;
+  readonly where?: WhereExpr;
   readonly returning?: ReadonlyArray<ColumnRef>;
 }
 

package/src/ast/update.ts

@@ -1,10 +1,10 @@
-import type { BinaryExpr, ColumnRef, ParamRef, TableRef, UpdateAst } from './types';
+import type { ColumnRef, ParamRef, TableRef, UpdateAst, WhereExpr } from './types';
 import { compact } from './util';
 
 export interface CreateUpdateAstOptions {
   readonly table: TableRef;
   readonly set: Record<string, ColumnRef | ParamRef>;
-  readonly where: BinaryExpr;
+  readonly where?: WhereExpr;
   readonly returning?: ReadonlyArray<ColumnRef>;
 }
 

package/src/exports/ast.ts

@@ -8,6 +8,7 @@ export * from '../ast/join';
 export * from '../ast/order';
 export * from '../ast/predicate';
 export * from '../ast/select';
+export * from '../ast/sql-codecs';
 export * from '../ast/types';
 export * from '../ast/update';
 export * from '../ast/util';

package/src/exports/guards.ts

@@ -1,10 +1,15 @@
 export {
   collectColumnRefs,
+  expressionFromSource,
   extractBaseColumnRef,
   getColumnInfo,
   getColumnMeta,
   getOperationExpr,
   isColumnBuilder,
+  isExpressionBuilder,
+  isExpressionSource,
   isOperationExpr,
   isParamPlaceholder,
+  isValueSource,
+  toExpression,
 } from '../utils/guards';

package/src/exports/utils/guards.ts

@@ -0,0 +1 @@
+export * from '../guards';