@prisma-next/sql-relational-core 0.3.0-dev.12 → 0.3.0-dev.122

package/src/schema.ts

@@ -1,27 +1,27 @@
 import type { OperationRegistry } from '@prisma-next/operations';
 import { planInvalid } from '@prisma-next/plan';
 import type {
-  ExtractCodecTypes,
-  ExtractOperationTypes,
+  ExtractTypeMapsFromContract,
+  ResolveCodecTypes,
+  ResolveOperationTypes,
   SqlContract,
   SqlStorage,
   StorageColumn,
 } from '@prisma-next/sql-contract/types';
-import type { BinaryOp, TableRef } from './ast/types';
+import { type BinaryOp, ColumnRef, type ExpressionSource, type TableRef } from './ast/types';
 import { attachOperationsToColumnBuilder } from './operations-registry';
-import type { QueryLaneContext } from './query-lane-context';
+import type { ExecutionContext } from './query-lane-context';
 import type {
-  AnyColumnBuilderBase,
   BinaryBuilder,
   CodecTypes as CodecTypesType,
   ColumnBuilder,
   ComputeColumnJsType,
+  NullCheckBuilder,
   OperationTypeSignature,
   OperationTypes,
   OrderBuilder,
   ParamPlaceholder,
 } from './types';
-import { isColumnBuilder } from './types';
 
 type TableColumns<Table extends { columns: Record<string, StorageColumn> }> = Table['columns'];
 
@@ -44,7 +44,8 @@ export class ColumnBuilderImpl<
   ColumnName extends string,
   ColumnMeta extends StorageColumn,
   JsType = unknown,
-> {
+> implements ExpressionSource
+{
   readonly kind = 'column' as const;
 
   constructor(
@@ -62,64 +63,72 @@ export class ColumnBuilderImpl<
     return undefined as unknown as JsType;
   }
 
+  /**
+   * Converts this column builder to a ColumnRef expression.
+   * This is the canonical way to get an AST node from a builder.
+   */
+  toExpr(): ColumnRef {
+    return new ColumnRef(this.table, this.column);
+  }
+
   private createBinaryBuilder(
     op: BinaryOp,
-    value: ParamPlaceholder | AnyColumnBuilderBase,
+    value: ParamPlaceholder | ExpressionSource,
   ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
     if (value == null) {
-      throw planInvalid('Parameter placeholder or column builder required for column comparison');
+      throw planInvalid(
+        'Parameter placeholder or expression source required for column comparison',
+      );
     }
-    if (value.kind === 'param-placeholder' || isColumnBuilder(value)) {
+    // Check for ExpressionSource first (has toExpr method)
+    if ('toExpr' in value && typeof value.toExpr === 'function') {
       return Object.freeze({
         kind: 'binary' as const,
         op,
-        left: this as unknown as ColumnBuilder<ColumnName, ColumnMeta, JsType>,
+        left: this.toExpr(),
         right: value,
       }) as BinaryBuilder<ColumnName, ColumnMeta, JsType>;
     }
-    throw planInvalid('Parameter placeholder or column builder required for column comparison');
+    // Must be a ParamPlaceholder
+    if ('kind' in value && value.kind === 'param-placeholder') {
+      return Object.freeze({
+        kind: 'binary' as const,
+        op,
+        left: this.toExpr(),
+        right: value,
+      }) as BinaryBuilder<ColumnName, ColumnMeta, JsType>;
+    }
+    throw planInvalid('Parameter placeholder or expression source required for column comparison');
   }
 
-  eq(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+  eq(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
     return this.createBinaryBuilder('eq', value);
   }
 
-  neq(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+  neq(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
     return this.createBinaryBuilder('neq', value);
   }
 
-  gt(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+  gt(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
     return this.createBinaryBuilder('gt', value);
   }
 
-  lt(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+  lt(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
     return this.createBinaryBuilder('lt', value);
   }
 
-  gte(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+  gte(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
     return this.createBinaryBuilder('gte', value);
   }
 
-  lte(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+  lte(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
     return this.createBinaryBuilder('lte', value);
   }
 
   asc(): OrderBuilder<ColumnName, ColumnMeta, JsType> {
     return Object.freeze({
       kind: 'order' as const,
-      expr: this as unknown as ColumnBuilder<ColumnName, ColumnMeta, JsType>,
+      expr: this.toExpr(),
       dir: 'asc' as const,
     }) as OrderBuilder<ColumnName, ColumnMeta, JsType>;
   }
@@ -127,10 +136,34 @@ export class ColumnBuilderImpl<
   desc(): OrderBuilder<ColumnName, ColumnMeta, JsType> {
     return Object.freeze({
       kind: 'order' as const,
-      expr: this as unknown as ColumnBuilder<ColumnName, ColumnMeta, JsType>,
+      expr: this.toExpr(),
       dir: 'desc' as const,
     }) as OrderBuilder<ColumnName, ColumnMeta, JsType>;
   }
+
+  /**
+   * Creates an IS NULL check for this column.
+   * Available on all columns at runtime, but typed to only be visible on nullable columns.
+   */
+  isNull(): NullCheckBuilder<ColumnName, ColumnMeta, JsType> {
+    return Object.freeze({
+      kind: 'nullCheck' as const,
+      expr: this.toExpr(),
+      isNull: true,
+    }) as NullCheckBuilder<ColumnName, ColumnMeta, JsType>;
+  }
+
+  /**
+   * Creates an IS NOT NULL check for this column.
+   * Available on all columns at runtime, but typed to only be visible on nullable columns.
+   */
+  isNotNull(): NullCheckBuilder<ColumnName, ColumnMeta, JsType> {
+    return Object.freeze({
+      kind: 'nullCheck' as const,
+      expr: this.toExpr(),
+      isNull: false,
+    }) as NullCheckBuilder<ColumnName, ColumnMeta, JsType>;
+  }
 }
 
 export class TableBuilderImpl<
@@ -290,18 +323,39 @@ type ExtractSchemaTables<
     TableRef;
 };
 
+/**
+ * Extracts the types registry shape from a contract.
+ * Each key is a type name from storage.types, and the value preserves the
+ * literal type from the contract (including codecId, nativeType, and typeParams).
+ * Returns an empty object type {} when storage.types is undefined.
+ */
+type ExtractSchemaTypes<Contract extends SqlContract<SqlStorage>> =
+  Contract['storage']['types'] extends infer Types
+    ? Types extends Record<string, unknown>
+      ? { readonly [TypeName in keyof Types]: Types[TypeName] }
+      : Record<string, never>
+    : Record<string, never>;
+
 export type SchemaHandle<
   Contract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
   CodecTypes extends CodecTypesType = CodecTypesType,
   Operations extends OperationTypes = Record<string, never>,
 > = {
   readonly tables: ExtractSchemaTables<Contract, CodecTypes, Operations>;
+  /**
+   * Initialized type helpers from storage.types.
+   * Each entry corresponds to a named type instance in the contract's storage.types.
+   */
+  readonly types: ExtractSchemaTypes<Contract>;
 };
 
-type SchemaReturnType<Contract extends SqlContract<SqlStorage>> = SchemaHandle<
+type SchemaReturnType<
+  Contract extends SqlContract<SqlStorage>,
+  TTypeMaps = ExtractTypeMapsFromContract<Contract>,
+> = SchemaHandle<
   Contract,
-  ExtractCodecTypes<Contract>,
-  ToOperationTypes<ExtractOperationTypes<Contract>>
+  ResolveCodecTypes<Contract, TTypeMaps>,
+  ToOperationTypes<ResolveOperationTypes<Contract, TTypeMaps>>
 >;
 
 type NormalizeOperationTypes<T> = {
@@ -318,21 +372,25 @@ type ToOperationTypes<T> = T extends OperationTypes ? T : NormalizeOperationType
  * Creates a schema handle for building SQL queries.
  *
  * @param context - Query lane context containing contract, codec and operation registries
- * @returns A schema handle with typed table builders
+ * @returns A schema handle with typed table builders and type helpers
  *
  * @example
  * ```typescript
+ * // No-emit: infers TypeMaps from ContractWithTypeMaps
  * const schemaHandle = schema<Contract>(context);
- * const userTable = schemaHandle.tables.user;
+ *
+ * // Emitted: pass TypeMaps explicitly
+ * const schemaHandle = schema<Contract, TypeMaps>(context);
  * ```
  */
-export function schema<Contract extends SqlContract<SqlStorage>>(
-  context: QueryLaneContext<Contract>,
-): SchemaReturnType<Contract> {
+export function schema<
+  Contract extends SqlContract<SqlStorage>,
+  TTypeMaps = ExtractTypeMapsFromContract<Contract>,
+>(context: ExecutionContext<Contract>): SchemaReturnType<Contract, TTypeMaps> {
   const contract = context.contract;
   const storage = contract.storage;
-  type CodecTypes = ExtractCodecTypes<Contract>;
-  type Operations = ToOperationTypes<ExtractOperationTypes<Contract>>;
+  type CodecTypes = ResolveCodecTypes<Contract, TTypeMaps>;
+  type Operations = ToOperationTypes<ResolveOperationTypes<Contract, TTypeMaps>>;
   const tables = {} as ExtractSchemaTables<Contract, CodecTypes, Operations>;
   const contractCapabilities = contract.capabilities;
 
@@ -367,7 +425,10 @@ export function schema<Contract extends SqlContract<SqlStorage>>(
     ) as ExtractSchemaTables<Contract, CodecTypes, Operations>[typeof tableName];
   }
 
-  return Object.freeze({ tables }) as SchemaReturnType<Contract>;
+  // Get type helpers from context (populated by runtime context creation)
+  const types = context.types as ExtractSchemaTypes<Contract>;
+
+  return Object.freeze({ tables, types }) as SchemaReturnType<Contract, TTypeMaps>;
 }
 
 export type { ColumnBuilderImpl as Column, TableBuilderImpl as Table };