@prisma-next/sql-relational-core 0.3.0-dev.3 → 0.3.0-dev.31

package/src/schema.ts

@@ -0,0 +1,406 @@
+import type { OperationRegistry } from '@prisma-next/operations';
+import { planInvalid } from '@prisma-next/plan';
+import type {
+  ExtractCodecTypes,
+  ExtractOperationTypes,
+  SqlContract,
+  SqlStorage,
+  StorageColumn,
+} from '@prisma-next/sql-contract/types';
+import type { BinaryOp, ColumnRef, ExpressionSource, TableRef } from './ast/types';
+import { attachOperationsToColumnBuilder } from './operations-registry';
+import type { QueryLaneContext } from './query-lane-context';
+import type {
+  BinaryBuilder,
+  CodecTypes as CodecTypesType,
+  ColumnBuilder,
+  ComputeColumnJsType,
+  OperationTypeSignature,
+  OperationTypes,
+  OrderBuilder,
+  ParamPlaceholder,
+} from './types';
+
+type TableColumns<Table extends { columns: Record<string, StorageColumn> }> = Table['columns'];
+
+type ColumnBuilders<
+  Contract extends SqlContract<SqlStorage>,
+  TableName extends string,
+  Columns extends Record<string, StorageColumn>,
+  CodecTypes extends CodecTypesType,
+  Operations extends OperationTypes,
+> = {
+  readonly [K in keyof Columns]: ColumnBuilder<
+    K & string,
+    Columns[K],
+    ComputeColumnJsType<Contract, TableName, K & string, Columns[K], CodecTypes>,
+    Operations
+  >;
+};
+
+export class ColumnBuilderImpl<
+  ColumnName extends string,
+  ColumnMeta extends StorageColumn,
+  JsType = unknown,
+> implements ExpressionSource
+{
+  readonly kind = 'column' as const;
+
+  constructor(
+    readonly table: string,
+    readonly column: ColumnName,
+    private readonly storageColumn: ColumnMeta,
+  ) {}
+
+  get columnMeta(): ColumnMeta {
+    return this.storageColumn;
+  }
+
+  // Type-level helper property (not used at runtime)
+  get __jsType(): JsType {
+    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 Object.freeze({
+      kind: 'col' as const,
+      table: this.table,
+      column: this.column,
+    });
+  }
+
+  private createBinaryBuilder(
+    op: BinaryOp,
+    value: ParamPlaceholder | ExpressionSource,
+  ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+    if (value == null) {
+      throw planInvalid(
+        'Parameter placeholder or expression source required for column comparison',
+      );
+    }
+    // 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.toExpr(),
+        right: value,
+      }) as BinaryBuilder<ColumnName, ColumnMeta, JsType>;
+    }
+    // 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 | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+    return this.createBinaryBuilder('eq', value);
+  }
+
+  neq(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+    return this.createBinaryBuilder('neq', value);
+  }
+
+  gt(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+    return this.createBinaryBuilder('gt', value);
+  }
+
+  lt(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+    return this.createBinaryBuilder('lt', value);
+  }
+
+  gte(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+    return this.createBinaryBuilder('gte', value);
+  }
+
+  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.toExpr(),
+      dir: 'asc' as const,
+    }) as OrderBuilder<ColumnName, ColumnMeta, JsType>;
+  }
+
+  desc(): OrderBuilder<ColumnName, ColumnMeta, JsType> {
+    return Object.freeze({
+      kind: 'order' as const,
+      expr: this.toExpr(),
+      dir: 'desc' as const,
+    }) as OrderBuilder<ColumnName, ColumnMeta, JsType>;
+  }
+}
+
+export class TableBuilderImpl<
+  Contract extends SqlContract<SqlStorage>,
+  TableName extends string,
+  Columns extends Record<string, StorageColumn>,
+  CodecTypes extends CodecTypesType,
+  Operations extends OperationTypes,
+> implements TableRef
+{
+  readonly kind = 'table' as const;
+  readonly columns: ColumnBuilders<Contract, TableName, Columns, CodecTypes, Operations>;
+  private readonly _name: TableName;
+
+  constructor(
+    name: TableName,
+    columns: ColumnBuilders<Contract, TableName, Columns, CodecTypes, Operations>,
+  ) {
+    this._name = name;
+    this.columns = columns;
+  }
+
+  get name(): string {
+    return this._name;
+  }
+}
+
+function buildColumns<
+  Contract extends SqlContract<SqlStorage>,
+  TableName extends keyof Contract['storage']['tables'] & string,
+  CodecTypes extends CodecTypesType,
+  Operations extends OperationTypes,
+>(
+  tableName: TableName,
+  storage: SqlStorage,
+  _contract: Contract,
+  operationRegistry?: OperationRegistry,
+  contractCapabilities?: Record<string, Record<string, boolean>>,
+): ColumnBuilders<
+  Contract,
+  TableName,
+  Contract['storage']['tables'][TableName]['columns'],
+  CodecTypes,
+  Operations
+> {
+  const table = storage.tables[tableName];
+
+  if (!table) {
+    throw planInvalid(`Unknown table ${tableName}`);
+  }
+
+  type Columns = Contract['storage']['tables'][TableName]['columns'];
+  const tableColumns = table.columns as Columns;
+
+  const result = {} as {
+    [K in keyof Columns]: ColumnBuilder<
+      K & string,
+      Columns[K],
+      ComputeColumnJsType<Contract, TableName, K & string, Columns[K], CodecTypes>,
+      Operations
+    >;
+  };
+
+  const assignColumn = <ColumnKey extends keyof Columns & string>(
+    columnName: ColumnKey,
+    columnDef: Columns[ColumnKey],
+  ) => {
+    type JsType = ComputeColumnJsType<
+      Contract,
+      TableName,
+      ColumnKey,
+      Columns[ColumnKey],
+      CodecTypes
+    >;
+
+    const columnBuilder = new ColumnBuilderImpl<ColumnKey, Columns[ColumnKey], JsType>(
+      tableName,
+      columnName,
+      columnDef,
+    );
+
+    const builderWithOps = attachOperationsToColumnBuilder<
+      ColumnKey,
+      Columns[ColumnKey],
+      JsType,
+      Operations
+    >(
+      columnBuilder as unknown as ColumnBuilder<
+        ColumnKey,
+        Columns[ColumnKey],
+        JsType,
+        Record<string, never>
+      >,
+      columnDef,
+      operationRegistry,
+      contractCapabilities,
+    );
+
+    (result as Record<string, unknown>)[columnName] = builderWithOps;
+  };
+
+  for (const columnName of Object.keys(tableColumns) as Array<keyof Columns & string>) {
+    const columnDef = tableColumns[columnName];
+    if (!columnDef) continue;
+    assignColumn(columnName, columnDef);
+  }
+
+  return result as ColumnBuilders<Contract, TableName, Columns, CodecTypes, Operations>;
+}
+
+/**
+ * Creates a Proxy that enables accessing table columns directly on the table object,
+ * in addition to the standard `table.columns.columnName` syntax.
+ *
+ * This allows both access patterns:
+ * - `tables.user.columns.id` (standard access)
+ * - `tables.user.id` (convenience access via proxy)
+ *
+ * The proxy intercepts property access and routes column name lookups to
+ * `table.columns[prop]`, while preserving direct access to table properties
+ * like `name`, `kind`, and `columns`.
+ */
+function createTableProxy<
+  Contract extends SqlContract<SqlStorage>,
+  TableName extends string,
+  Columns extends Record<string, StorageColumn>,
+  CodecTypes extends CodecTypesType,
+  Operations extends OperationTypes,
+>(
+  table: TableBuilderImpl<Contract, TableName, Columns, CodecTypes, Operations>,
+): TableBuilderImpl<Contract, TableName, Columns, CodecTypes, Operations> {
+  return new Proxy(table, {
+    get(target, prop) {
+      if (prop === 'name' || prop === 'kind' || prop === 'columns') {
+        return Reflect.get(target, prop);
+      }
+      if (typeof prop === 'string' && prop in target.columns) {
+        return target.columns[prop as keyof typeof target.columns];
+      }
+      return undefined;
+    },
+  });
+}
+
+type ExtractSchemaTables<
+  Contract extends SqlContract<SqlStorage>,
+  CodecTypes extends CodecTypesType,
+  Operations extends OperationTypes,
+> = {
+  readonly [TableName in keyof Contract['storage']['tables']]: TableBuilderImpl<
+    Contract,
+    TableName & string,
+    TableColumns<Contract['storage']['tables'][TableName]>,
+    CodecTypes,
+    Operations
+  > &
+    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<
+  Contract,
+  ExtractCodecTypes<Contract>,
+  ToOperationTypes<ExtractOperationTypes<Contract>>
+>;
+
+type NormalizeOperationTypes<T> = {
+  [TypeId in keyof T]: {
+    [Method in keyof T[TypeId]]: T[TypeId][Method] extends OperationTypeSignature
+      ? T[TypeId][Method]
+      : OperationTypeSignature;
+  };
+};
+
+type ToOperationTypes<T> = T extends OperationTypes ? T : NormalizeOperationTypes<T>;
+
+/**
+ * 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 and type helpers
+ *
+ * @example
+ * ```typescript
+ * const schemaHandle = schema<Contract>(context);
+ * const userTable = schemaHandle.tables.user;
+ * const vectorType = schemaHandle.types.Vector1536;
+ * ```
+ */
+export function schema<Contract extends SqlContract<SqlStorage>>(
+  context: QueryLaneContext<Contract>,
+): SchemaReturnType<Contract> {
+  const contract = context.contract;
+  const storage = contract.storage;
+  type CodecTypes = ExtractCodecTypes<Contract>;
+  type Operations = ToOperationTypes<ExtractOperationTypes<Contract>>;
+  const tables = {} as ExtractSchemaTables<Contract, CodecTypes, Operations>;
+  const contractCapabilities = contract.capabilities;
+
+  const operationRegistry = context.operations;
+
+  for (const tableName of Object.keys(storage.tables) as Array<
+    keyof Contract['storage']['tables'] & string
+  >) {
+    const columns = buildColumns<Contract, typeof tableName, CodecTypes, Operations>(
+      tableName,
+      storage,
+      contract,
+      operationRegistry,
+      contractCapabilities,
+    );
+    const table = new TableBuilderImpl<
+      Contract,
+      typeof tableName & string,
+      Contract['storage']['tables'][typeof tableName]['columns'],
+      CodecTypes,
+      Operations
+    >(tableName, columns);
+    const proxiedTable = createTableProxy<
+      Contract,
+      typeof tableName & string,
+      Contract['storage']['tables'][typeof tableName]['columns'],
+      CodecTypes,
+      Operations
+    >(table);
+    (tables as Record<string, unknown>)[tableName] = Object.freeze(
+      proxiedTable,
+    ) as ExtractSchemaTables<Contract, CodecTypes, Operations>[typeof tableName];
+  }
+
+  // Get type helpers from context (populated by createRuntimeContext)
+  const types = (context.types ?? {}) as ExtractSchemaTypes<Contract>;
+
+  return Object.freeze({ tables, types }) as SchemaReturnType<Contract>;
+}
+
+export type { ColumnBuilderImpl as Column, TableBuilderImpl as Table };