effect-qb 0.13.0 → 0.15.0

package/src/internal/table-options.d.ts

@@ -0,0 +1,94 @@
+import { type AnyColumnDefinition, type IsNullable } from "./column-state.js";
+import type { Any as AnyExpression } from "./scalar.js";
+import type { Any as AnySchemaExpression } from "./schema-expression.js";
+import type { TableFieldMap } from "./schema-derivation.js";
+/** Non-empty list of column names. */
+export type ColumnList = readonly [string, ...string[]];
+export type DdlExpressionLike = AnyExpression | AnySchemaExpression;
+export type ReferentialAction = "noAction" | "restrict" | "cascade" | "setNull" | "setDefault";
+export type IndexKeySpec = {
+    readonly kind: "column";
+    readonly column: string;
+    readonly order?: "asc" | "desc";
+    readonly nulls?: "first" | "last";
+    readonly operatorClass?: string;
+    readonly collation?: string;
+} | {
+    readonly kind: "expression";
+    readonly expression: DdlExpressionLike;
+    readonly order?: "asc" | "desc";
+    readonly nulls?: "first" | "last";
+    readonly operatorClass?: string;
+    readonly collation?: string;
+};
+/** Normalized table-level option record. */
+export type TableOptionSpec = {
+    readonly kind: "index";
+    readonly columns?: ColumnList;
+    readonly name?: string;
+    readonly unique?: boolean;
+    readonly method?: string;
+    readonly include?: readonly string[];
+    readonly predicate?: DdlExpressionLike;
+    readonly keys?: readonly [IndexKeySpec, ...IndexKeySpec[]];
+} | {
+    readonly kind: "unique";
+    readonly columns: ColumnList;
+    readonly name?: string;
+    readonly nullsNotDistinct?: boolean;
+    readonly deferrable?: boolean;
+    readonly initiallyDeferred?: boolean;
+} | {
+    readonly kind: "primaryKey";
+    readonly columns: ColumnList;
+    readonly name?: string;
+    readonly deferrable?: boolean;
+    readonly initiallyDeferred?: boolean;
+} | {
+    readonly kind: "foreignKey";
+    readonly columns: ColumnList;
+    readonly name?: string;
+    readonly references: () => {
+        readonly tableName: string;
+        readonly schemaName?: string;
+        readonly columns: ColumnList;
+        readonly knownColumns?: readonly string[];
+    };
+    readonly onUpdate?: ReferentialAction;
+    readonly onDelete?: ReferentialAction;
+    readonly deferrable?: boolean;
+    readonly initiallyDeferred?: boolean;
+} | {
+    readonly kind: "check";
+    readonly name: string;
+    readonly predicate: DdlExpressionLike;
+    readonly noInherit?: boolean;
+};
+/** Thin wrapper used by the public `Table.*` option builders. */
+export interface TableOptionBuilder<Spec extends TableOptionSpec = TableOptionSpec> {
+    readonly option: Spec;
+}
+/** Collection of declared table options. */
+export type DeclaredTableOptions = readonly TableOptionBuilder[];
+type ColumnNameUnion<Fields extends TableFieldMap> = Extract<keyof Fields, string>;
+type NullableColumnNames<Fields extends TableFieldMap> = {
+    [K in keyof Fields]: Fields[K] extends AnyColumnDefinition ? IsNullable<Fields[K]> extends true ? K : never : never;
+}[keyof Fields];
+type TupleFromColumns<Columns> = Columns extends readonly [infer Head extends string, ...infer Tail extends string[]] ? readonly [Head, ...Tail] : Columns extends readonly string[] ? Columns extends readonly [string, ...string[]] ? Columns : never : Columns extends string ? readonly [Columns] : never;
+type AssertKnownColumns<Fields extends TableFieldMap, Columns extends readonly string[]> = Exclude<Columns[number], ColumnNameUnion<Fields>> extends never ? Columns : never;
+type AssertPrimaryKeyColumns<Fields extends TableFieldMap, Columns extends readonly string[]> = Extract<Columns[number], NullableColumnNames<Fields>> extends never ? Columns : never;
+/** Normalizes a string or tuple input into a non-empty column list. */
+export declare const normalizeColumnList: (columns: string | readonly string[]) => ColumnList;
+/** Converts inline column flags into normalized table option records. */
+export declare const collectInlineOptions: <Fields extends TableFieldMap>(fields: Fields) => readonly TableOptionSpec[];
+/** Resolves the effective primary-key columns for a table. */
+export declare const resolvePrimaryKeyColumns: <Fields extends TableFieldMap>(fields: Fields, declaredOptions: readonly TableOptionSpec[]) => readonly (keyof Fields & string)[];
+/** Validates that options reference known, legal columns for the table. */
+export declare const validateOptions: <Fields extends TableFieldMap>(tableName: string, fields: Fields, options: readonly TableOptionSpec[]) => void;
+/** Compile-time validation that option columns exist on the table. */
+export type ValidateKnownColumns<Fields extends TableFieldMap, Columns extends readonly string[]> = AssertKnownColumns<Fields, Columns>;
+/** Compile-time validation that primary-key columns are known and non-nullable. */
+export type ValidatePrimaryKeyColumns<Fields extends TableFieldMap, Columns extends readonly string[]> = AssertPrimaryKeyColumns<Fields, AssertKnownColumns<Fields, Columns>>;
+/** Normalizes a public column input into the internal tuple form. */
+export type NormalizeColumns<Columns extends string | readonly string[]> = TupleFromColumns<Columns>;
+export {};

package/src/internal/table-options.ts

@@ -4,40 +4,82 @@ import {
   type AnyColumnDefinition,
   type IsNullable
 } from "./column-state.js"
-import type { Any as AnyExpression } from "./expression.js"
+import type { Any as AnyExpression } from "./scalar.js"
+import type { Any as AnySchemaExpression } from "./schema-expression.js"
 import type { TableFieldMap } from "./schema-derivation.js"
 
 /** Non-empty list of column names. */
 export type ColumnList = readonly [string, ...string[]]
 
+export type DdlExpressionLike = AnyExpression | AnySchemaExpression
+
+export type ReferentialAction = "noAction" | "restrict" | "cascade" | "setNull" | "setDefault"
+
+export type IndexKeySpec =
+  | {
+      readonly kind: "column"
+      readonly column: string
+      readonly order?: "asc" | "desc"
+      readonly nulls?: "first" | "last"
+      readonly operatorClass?: string
+      readonly collation?: string
+    }
+  | {
+      readonly kind: "expression"
+      readonly expression: DdlExpressionLike
+      readonly order?: "asc" | "desc"
+      readonly nulls?: "first" | "last"
+      readonly operatorClass?: string
+      readonly collation?: string
+    }
+
 /** Normalized table-level option record. */
 export type TableOptionSpec =
   | {
       readonly kind: "index"
-      readonly columns: ColumnList
+      readonly columns?: ColumnList
+      readonly name?: string
+      readonly unique?: boolean
+      readonly method?: string
+      readonly include?: readonly string[]
+      readonly predicate?: DdlExpressionLike
+      readonly keys?: readonly [IndexKeySpec, ...IndexKeySpec[]]
     }
   | {
       readonly kind: "unique"
       readonly columns: ColumnList
+      readonly name?: string
+      readonly nullsNotDistinct?: boolean
+      readonly deferrable?: boolean
+      readonly initiallyDeferred?: boolean
     }
   | {
       readonly kind: "primaryKey"
       readonly columns: ColumnList
+      readonly name?: string
+      readonly deferrable?: boolean
+      readonly initiallyDeferred?: boolean
     }
   | {
       readonly kind: "foreignKey"
       readonly columns: ColumnList
+      readonly name?: string
       readonly references: () => {
         readonly tableName: string
         readonly schemaName?: string
         readonly columns: ColumnList
         readonly knownColumns?: readonly string[]
       }
+      readonly onUpdate?: ReferentialAction
+      readonly onDelete?: ReferentialAction
+      readonly deferrable?: boolean
+      readonly initiallyDeferred?: boolean
     }
   | {
       readonly kind: "check"
       readonly name: string
-      readonly predicate: AnyExpression
+      readonly predicate: DdlExpressionLike
+      readonly noInherit?: boolean
     }
 
 /** Thin wrapper used by the public `Table.*` option builders. */
@@ -109,7 +151,11 @@ export const collectInlineOptions = <Fields extends TableFieldMap>(
     if (column.metadata.unique && !column.metadata.primaryKey) {
       options.push({
         kind: "unique",
-        columns: [columnName]
+        columns: [columnName],
+        name: column.metadata.uniqueConstraint?.name,
+        nullsNotDistinct: column.metadata.uniqueConstraint?.nullsNotDistinct,
+        deferrable: column.metadata.uniqueConstraint?.deferrable,
+        initiallyDeferred: column.metadata.uniqueConstraint?.initiallyDeferred
       })
     }
     if (column.metadata.references) {
@@ -125,7 +171,29 @@ export const collectInlineOptions = <Fields extends TableFieldMap>(
             schemaName: bound.schemaName,
             columns: [bound.columnName]
           }
-        }
+        },
+        name: column.metadata.references.name,
+        onUpdate: column.metadata.references.onUpdate,
+        onDelete: column.metadata.references.onDelete,
+        deferrable: column.metadata.references.deferrable,
+        initiallyDeferred: column.metadata.references.initiallyDeferred
+      })
+    }
+    if (column.metadata.index) {
+      options.push({
+        kind: "index",
+        keys: [{
+          kind: "column",
+          column: columnName,
+          order: column.metadata.index.order,
+          nulls: column.metadata.index.nulls,
+          operatorClass: column.metadata.index.operatorClass,
+          collation: column.metadata.index.collation
+        }],
+        name: column.metadata.index.name,
+        method: column.metadata.index.method,
+        include: column.metadata.index.include,
+        predicate: column.metadata.index.predicate
       })
     }
   }
@@ -174,17 +242,20 @@ export const validateOptions = <Fields extends TableFieldMap>(
       case "primaryKey":
       case "unique":
       case "foreignKey": {
-        if (option.columns.length === 0) {
+        const columns = option.kind === "index"
+          ? option.columns ?? []
+          : option.columns
+        if (columns.length === 0 && option.kind !== "index") {
           throw new Error(`Option '${option.kind}' on table '${tableName}' requires at least one column`)
         }
-        for (const column of option.columns) {
+        for (const column of columns) {
           if (!knownColumns.has(column)) {
             throw new Error(`Unknown column '${column}' on table '${tableName}'`)
           }
         }
         if (option.kind === "foreignKey") {
           const reference = option.references()
-          if (reference.columns.length !== option.columns.length) {
+          if (reference.columns.length !== columns.length) {
             throw new Error(`Foreign key on table '${tableName}' must reference the same number of columns`)
           }
           if (reference.knownColumns) {
@@ -196,6 +267,21 @@ export const validateOptions = <Fields extends TableFieldMap>(
             }
           }
         }
+        if (option.kind === "index") {
+          for (const column of option.include ?? []) {
+            if (!knownColumns.has(column)) {
+              throw new Error(`Unknown included column '${column}' on table '${tableName}'`)
+            }
+          }
+          for (const key of option.keys ?? []) {
+            if (key.kind === "column" && !knownColumns.has(key.column)) {
+              throw new Error(`Unknown index key column '${key.column}' on table '${tableName}'`)
+            }
+          }
+          if (option.columns === undefined && (option.keys === undefined || option.keys.length === 0)) {
+            throw new Error(`Index on table '${tableName}' requires at least one column or key`)
+          }
+        }
         break
       }
       case "check": {

package/src/internal/table.d.ts

@@ -0,0 +1,173 @@
+import { type Pipeable } from "effect/Pipeable";
+import * as Schema from "effect/Schema";
+import * as Plan from "./row-set.js";
+import type { TrueFormula } from "./predicate/formula.js";
+import type { BoundColumnFrom } from "./column-state.js";
+import { type DdlExpressionLike, type NormalizeColumns, type TableOptionSpec, type ValidateKnownColumns, type ValidatePrimaryKeyColumns } from "./table-options.js";
+import { type InsertRow, type SelectRow, type TableFieldMap, type UpdateRow } from "./schema-derivation.js";
+/** Symbol used to attach table-definition metadata. */
+export declare const TypeId: unique symbol;
+/** Symbol for the normalized table option list. */
+export declare const OptionsSymbol: unique symbol;
+/** Symbol used by `Table.Class` to declare table-level options. */
+export declare const options: unique symbol;
+declare const DeclaredOptionsSymbol: unique symbol;
+type InlinePrimaryKeyKeys<Fields extends TableFieldMap> = Extract<{
+    [K in keyof Fields]: Fields[K]["metadata"]["primaryKey"] extends true ? K : never;
+}[keyof Fields], string>;
+type TableDialect<Fields extends TableFieldMap> = Fields[keyof Fields][typeof import("./column-state.js").ColumnTypeId]["dbType"]["dialect"];
+type TableKind = "schema" | "alias";
+type DefaultSchemaName = "public";
+type ClassOptionSpec = Exclude<TableOptionSpec, {
+    readonly kind: "primaryKey";
+}>;
+interface TableOptionBuilderLike<Spec extends TableOptionSpec = TableOptionSpec> {
+    (table: TableDefinition<any, any, any, "schema", any>): TableDefinition<any, any, any, "schema", any>;
+    readonly option: Spec;
+}
+type ClassTableOption = TableOptionBuilderLike<ClassOptionSpec>;
+type ClassDeclaredTableOptions = readonly ClassTableOption[];
+type BuildPrimaryKey<Table extends TableDefinition<any, any, any, "schema", any>, Spec extends TableOptionSpec> = Spec extends {
+    readonly kind: "primaryKey";
+    readonly columns: infer Columns extends readonly string[];
+} ? Columns[number] & keyof Table[typeof TypeId]["fields"] & string : Table[typeof TypeId]["primaryKey"][number];
+type OptionInputTable<Table extends TableDefinition<any, any, any, "schema", any>, Spec extends TableOptionSpec> = Spec extends {
+    readonly kind: "primaryKey";
+    readonly columns: infer Columns extends readonly string[];
+} ? ValidatePrimaryKeyColumns<Table[typeof TypeId]["fields"], Columns> extends never ? never : Table : Spec extends {
+    readonly columns: infer Columns extends readonly string[];
+} ? ValidateKnownColumns<Table[typeof TypeId]["fields"], Columns> extends never ? never : Table : Table;
+type ApplyOption<Table extends TableDefinition<any, any, any, "schema", any>, Spec extends TableOptionSpec> = Spec extends {
+    readonly kind: "primaryKey";
+} ? TableDefinition<Table[typeof TypeId]["name"], Table[typeof TypeId]["fields"], BuildPrimaryKey<Table, Spec>, "schema"> : TableDefinition<Table[typeof TypeId]["name"], Table[typeof TypeId]["fields"], Table[typeof TypeId]["primaryKey"][number], "schema">;
+export type MissingSelfGeneric = "Missing `Self` generic - use `class Self extends Table.Class<Self>(...) {}`";
+/** Bound columns keyed by field name for a particular table. */
+export type BoundColumns<Name extends string, Fields extends TableFieldMap> = {
+    readonly [K in keyof Fields]: BoundColumnFrom<Fields[K], Name, Extract<K, string>>;
+};
+/** Derived runtime schemas exposed by a table definition. */
+export interface TableSchemas<Name extends string, Fields extends TableFieldMap, PrimaryKeyColumns extends keyof Fields & string> {
+    readonly select: Schema.Schema<SelectRow<Name, Fields>>;
+    readonly insert: Schema.Schema<InsertRow<Name, Fields>>;
+    readonly update: Schema.Schema<UpdateRow<Name, Fields, PrimaryKeyColumns>>;
+}
+interface TableState<Name extends string, Fields extends TableFieldMap, PrimaryKeyColumns extends keyof Fields & string, Kind extends TableKind = "schema", SchemaName extends string | undefined = DefaultSchemaName> {
+    readonly name: Name;
+    readonly baseName: string;
+    readonly schemaName: SchemaName;
+    readonly fields: Fields;
+    readonly primaryKey: readonly PrimaryKeyColumns[];
+    readonly kind: Kind;
+}
+/** Namespace-scoped table builder. */
+export interface TableSchemaNamespace<SchemaName extends string> {
+    readonly schemaName: SchemaName;
+    readonly table: <Name extends string, Fields extends TableFieldMap, PrimaryKeyColumns extends keyof Fields & string = InlinePrimaryKeyKeys<Fields>>(name: Name, fields: Fields, ...options: DeclaredTableOptions) => TableDefinition<Name, Fields, PrimaryKeyColumns, "schema", SchemaName>;
+}
+export type DeclaredTableOptions = readonly TableOptionBuilderLike[];
+export type { DdlExpressionLike, IndexKeySpec, NormalizeColumns, ReferentialAction } from "./table-options.js";
+export type TableDefinition<Name extends string, Fields extends TableFieldMap, PrimaryKeyColumns extends keyof Fields & string = InlinePrimaryKeyKeys<Fields>, Kind extends TableKind = "schema", SchemaName extends string | undefined = DefaultSchemaName> = Pipeable & {
+    readonly name: Name;
+    readonly columns: BoundColumns<Name, Fields>;
+    readonly schemas: TableSchemas<Name, Fields, PrimaryKeyColumns>;
+    readonly [TypeId]: TableState<Name, Fields, PrimaryKeyColumns, Kind, SchemaName>;
+    readonly [Plan.TypeId]: Plan.State<BoundColumns<Name, Fields>, never, Record<Name, Plan.Source<Name, "required", TrueFormula>>, TableDialect<Fields>>;
+    readonly [OptionsSymbol]: readonly TableOptionSpec[];
+    readonly [DeclaredOptionsSymbol]: readonly TableOptionSpec[];
+} & BoundColumns<Name, Fields> & Plan.RowSet<BoundColumns<Name, Fields>, never, Record<Name, Plan.Source<Name, "required", TrueFormula>>, TableDialect<Fields>>;
+/**
+ * Static class-based table definition.
+ *
+ * The class object itself acts as the table definition, exposing static bound
+ * columns, derived schemas, and plan metadata.
+ */
+export type TableClassStatic<Name extends string, Fields extends TableFieldMap, PrimaryKeyColumns extends keyof Fields & string = InlinePrimaryKeyKeys<Fields>, SchemaName extends string | undefined = DefaultSchemaName> = (abstract new (...args: any[]) => any) & Pipeable & {
+    readonly columns: BoundColumns<Name, Fields>;
+    readonly schemas: TableSchemas<Name, Fields, PrimaryKeyColumns>;
+    readonly [TypeId]: TableState<Name, Fields, PrimaryKeyColumns, "schema", SchemaName>;
+    readonly [Plan.TypeId]: Plan.State<BoundColumns<Name, Fields>, never, Record<Name, Plan.Source<Name, "required", TrueFormula>>, TableDialect<Fields>>;
+    readonly [OptionsSymbol]: readonly TableOptionSpec[];
+    readonly [DeclaredOptionsSymbol]?: readonly TableOptionSpec[];
+    readonly [options]?: ClassDeclaredTableOptions;
+    readonly tableName: Name;
+} & BoundColumns<Name, Fields> & Plan.RowSet<BoundColumns<Name, Fields>, never, Record<Name, Plan.Source<Name, "required", TrueFormula>>, TableDialect<Fields>>;
+/** Minimal structural table-like contract used across helper APIs. */
+export type AnyTable = TableDefinition<any, any, any, any, any> | TableClassStatic<any, any, any, any>;
+/** Public table-option builder type used by `Table.index`, `Table.primaryKey`, and friends. */
+export type TableOption<Spec extends TableOptionSpec = TableOptionSpec> = {
+    <Name extends string, Fields extends TableFieldMap, PrimaryKeyColumns extends keyof Fields & string>(table: OptionInputTable<TableDefinition<Name, Fields, PrimaryKeyColumns, "schema", any>, Spec>): ApplyOption<TableDefinition<Name, Fields, PrimaryKeyColumns, "schema", any>, Spec>;
+    readonly option: Spec;
+};
+export declare const option: <Spec extends TableOptionSpec>(spec: Spec) => TableOption<Spec>;
+export declare const optionFromTable: <Spec extends TableOptionSpec>(spec: Spec, resolve: (table: TableDefinition<any, any, any, "schema", any>) => Spec) => TableOption<Spec>;
+/** Creates a table definition from a name and field map. */
+export declare function make<Name extends string, Fields extends TableFieldMap, SchemaName extends string | undefined = DefaultSchemaName>(name: Name, fields: Fields, schemaName?: SchemaName): TableDefinition<Name, Fields, InlinePrimaryKeyKeys<Fields>, "schema", SchemaName>;
+/**
+ * Creates a namespace-scoped builder for a concrete SQL schema/database.
+ */
+export declare const schema: <SchemaName extends string>(schemaName: SchemaName) => TableSchemaNamespace<SchemaName>;
+/**
+ * Creates an aliased source from an existing table definition.
+ *
+ * The alias becomes the logical source identity used by the query layer while
+ * the original physical table name is retained in bound-column provenance for
+ * downstream SQL rendering work.
+ */
+export declare const alias: <Name extends string, Fields extends TableFieldMap, PrimaryKeyColumns extends keyof Fields & string, SchemaName extends string, AliasName extends string>(table: TableClassStatic<Name, Fields, PrimaryKeyColumns, SchemaName> | TableDefinition<Name, Fields, PrimaryKeyColumns, any, SchemaName>, aliasName: AliasName) => TableDefinition<AliasName, Fields, PrimaryKeyColumns, "alias", SchemaName>;
+/**
+ * Class-based table constructor mirroring `Schema.Class`.
+ *
+ * The returned base class can be extended and configured with
+ * `static readonly [Table.options]`.
+ */
+export declare function Class<Self = never, SchemaName extends string | undefined = DefaultSchemaName>(name: string, schemaName?: SchemaName): <Fields extends TableFieldMap>(fields: Fields) => [Self] extends [never] ? "Missing `Self` generic - use `class Self extends Table.Class<Self>(...) {}`" : TableClassStatic<string, Fields, Extract<{ [K in keyof Fields]: Fields[K]["metadata"]["primaryKey"] extends true ? K : never; }[keyof Fields], string>, SchemaName>;
+/** Declares a table-level primary key. */
+export declare const primaryKey: <const Columns extends string | readonly string[]>(columns: Columns) => TableOption<{
+    readonly kind: "primaryKey";
+    readonly columns: NormalizeColumns<Columns>;
+}>;
+/** Declares a table-level unique constraint. */
+export declare const unique: <const Columns extends string | readonly string[]>(columns: Columns) => TableOption<{
+    readonly kind: "unique";
+    readonly columns: NormalizeColumns<Columns>;
+}>;
+/** Declares a table-level index. */
+export declare const index: <const Columns extends string | readonly string[]>(columns: Columns) => TableOption<{
+    readonly kind: "index";
+    readonly columns: NormalizeColumns<Columns>;
+}>;
+/** Declares a table-level foreign key. */
+export declare const foreignKey: <const LocalColumns extends string | readonly string[], TargetTable extends AnyTable, const TargetColumns extends string | readonly string[]>(columns: LocalColumns, target: () => TargetTable, referencedColumns: TargetColumns) => TableOption<{
+    readonly kind: "foreignKey";
+    readonly columns: NormalizeColumns<LocalColumns>;
+    readonly references: () => {
+        readonly tableName: string;
+        readonly schemaName?: string | undefined;
+        readonly columns: NormalizeColumns<TargetColumns>;
+        readonly knownColumns: readonly string[];
+    };
+}>;
+/** Declares a check constraint expression. */
+export declare const check: <Name extends string>(name: Name, predicate: DdlExpressionLike) => TableOption<{
+    readonly kind: "check";
+    readonly name: Name;
+    readonly predicate: DdlExpressionLike;
+}>;
+/** Extracts the row type of a table's select schema. */
+export type SelectOf<Table extends {
+    readonly schemas: {
+        readonly select: Schema.Schema<any>;
+    };
+}> = Schema.Schema.Type<Table["schemas"]["select"]>;
+/** Extracts the payload type of a table's insert schema. */
+export type InsertOf<Table extends {
+    readonly schemas: {
+        readonly insert: Schema.Schema<any>;
+    };
+}> = Schema.Schema.Type<Table["schemas"]["insert"]>;
+/** Extracts the payload type of a table's update schema. */
+export type UpdateOf<Table extends {
+    readonly schemas: {
+        readonly update: Schema.Schema<any>;
+    };
+}> = Schema.Schema.Type<Table["schemas"]["update"]>;