@minnowdb/core 0.4.1 → 0.6.0

package/dist/engine/result-wire.d.ts

@@ -1,3 +1,4 @@
+import type { SqlDomain } from "../storage/types.js";
 import type { QueryResult, QueryRow, QueryValue } from "./query.js";
 /**
  * The shape a query result takes on the worker channel. A result is rows of objects at the
@@ -49,6 +50,7 @@ export type WireResultColumn = {
 export interface WireQueryResult {
     readonly kind: "columnar-result";
     readonly columns: string[];
+    readonly columnDomains: Array<SqlDomain | null>;
     readonly rowCount: number;
     readonly values: WireResultColumn[];
 }

package/dist/engine/result-wire.js

@@ -1,6 +1,7 @@
 import { dateMilliseconds } from "../date-value.js";
+import { unknownColumnDomains } from "./query.js";
 export function encodeQueryResult(result) {
-    return encodeRows(result.columns, result.rows);
+    return encodeRows(result.columns, result.rows, result.columnDomains);
 }
 /**
  * Encodes a bare row array (`run()` returns rows without a column list). Every row of one result
@@ -8,13 +9,18 @@ export function encodeQueryResult(result) {
  */
 export function encodeQueryRows(rows) {
     const first = rows[0];
-    return encodeRows(first === undefined ? [] : Object.keys(first), rows);
+    const columns = first === undefined ? [] : Object.keys(first);
+    return encodeRows(columns, rows, unknownColumnDomains(columns));
 }
 export function decodeQueryResult(payload) {
     if (!isWireQueryResult(payload)) {
         throw new TypeError("Expected a columnar query result frame");
     }
     const columns = [...payload.columns];
+    if (payload.values.length !== columns.length || payload.columnDomains.length !== columns.length) {
+        throw new TypeError("Columnar result frame metadata is not aligned");
+    }
+    const columnDomains = structuredClone(payload.columnDomains);
     const rows = [];
     for (let index = 0; index < payload.rowCount; index += 1)
         rows.push({});
@@ -26,17 +32,21 @@ export function decodeQueryResult(payload) {
             throw new TypeError("Columnar result frame is missing a column");
         fillColumn(rows, name, column);
     }
-    return { columns, rows };
+    return { columns, columnDomains, rows };
 }
 export function isWireQueryResult(value) {
     return (typeof value === "object" &&
         value !== null &&
         value.kind === "columnar-result" &&
         Array.isArray(value.columns) &&
+        Array.isArray(value.columnDomains) &&
         Array.isArray(value.values) &&
         typeof value.rowCount === "number");
 }
-function encodeRows(columns, rows) {
+function encodeRows(columns, rows, columnDomains) {
+    if (columnDomains.length !== columns.length) {
+        throw new TypeError("Query result column domains must align with the result columns");
+    }
     const transfer = [];
     const values = columns.map((name) => {
         const column = encodeColumn(name, rows);
@@ -53,7 +63,13 @@ function encodeRows(columns, rows) {
         return column;
     });
     return {
-        payload: { kind: "columnar-result", columns: [...columns], rowCount: rows.length, values },
+        payload: {
+            kind: "columnar-result",
+            columns: [...columns],
+            columnDomains: structuredClone([...columnDomains]),
+            rowCount: rows.length,
+            values,
+        },
         transfer,
     };
 }

package/dist/engine/schema-wire.d.ts

@@ -1,4 +1,4 @@
-import type { ColumnDefault, SqlDomain } from "../storage/types.js";
+import type { ColumnDefault, ColumnGenerated, SqlDomain } from "../storage/types.js";
 import { type AnyTable, type MigrationStep, type ReferentialAction, type SchemaColumnType, type SchemaDefinition, type TableCheck, type TableForeignKey } from "./schema.js";
 /**
  * Structured-clone-safe mirror of the schema DSL. Column builders and table validators carry
@@ -12,11 +12,13 @@ export interface WireColumn {
     readonly integer?: true;
     readonly sqlDomain?: SqlDomain;
     readonly defaultSpec?: ColumnDefault;
+    readonly generatedSpec?: ColumnGenerated;
     readonly renamedFromName?: string;
     readonly reference?: {
         table: string;
         column: string;
         onDelete: ReferentialAction;
+        enforced?: boolean;
     };
     readonly enumValues?: readonly string[];
     /** Already frozen by planning, so the wire carries a value and never a generator. */
@@ -83,6 +85,17 @@ export type WireMigrationStep = {
     tableName: string;
     columnName: string;
     defaultValue: ColumnDefault | null;
+} | {
+    kind: "alter-generated";
+    tableName: string;
+    columnName: string;
+    generatedValue: ColumnGenerated | null;
+} | {
+    kind: "alter-foreign-keys";
+    tableName: string;
+    foreignKeys: Extract<MigrationStep, {
+        kind: "alter-foreign-keys";
+    }>["foreignKeys"];
 } | {
     kind: "replace-view";
     view: WireView;

package/dist/engine/schema-wire.js

@@ -14,6 +14,9 @@ function serializeColumn(definition, frozen) {
             ? {}
             : { sqlDomain: structuredClone(definition.sqlDomain) }),
         ...(definition.defaultSpec === undefined ? {} : { defaultSpec: { ...definition.defaultSpec } }),
+        ...(definition.generatedSpec === undefined
+            ? {}
+            : { generatedSpec: { ...definition.generatedSpec } }),
         ...(definition.renamedFromName === undefined
             ? {}
             : { renamedFromName: definition.renamedFromName }),
@@ -95,8 +98,11 @@ function deserializeColumn(wire) {
         integer: wire.integer === true,
         ...(wire.sqlDomain === undefined ? {} : { sqlDomain: structuredClone(wire.sqlDomain) }),
         ...(wire.defaultSpec === undefined ? {} : { defaultSpec: wire.defaultSpec }),
+        ...(wire.generatedSpec === undefined ? {} : { generatedSpec: wire.generatedSpec }),
         ...(wire.renamedFromName === undefined ? {} : { renamedFromName: wire.renamedFromName }),
-        ...(wire.reference === undefined ? {} : { reference: wire.reference }),
+        ...(wire.reference === undefined
+            ? {}
+            : { reference: { ...wire.reference, enforced: wire.reference.enforced !== false } }),
         ...(wire.enumValues === undefined ? {} : { enumValues: wire.enumValues }),
         ...(wire.backfillValue === undefined ? {} : { backfillValue: wire.backfillValue }),
     });

package/dist/engine/schema.d.ts

@@ -1,6 +1,6 @@
 import { type ColumnDefault, type SqlDomain, type TableColumnRecord, type TableRecord } from "../storage/types.js";
 import { type Catalog, type CatalogColumn, type CatalogTable } from "./catalog.js";
-import { type QueryValue } from "./query.js";
+import { type Expression, type QueryValue } from "./query.js";
 /**
  * Typed schema DSL and catalog migration planning. Column builders carry compile-time value and
  * nullability types; `planMigration` diffs a schema against the live catalog into metadata-only
@@ -9,6 +9,14 @@ import { type QueryValue } from "./query.js";
  * catalog-only, and older segments read the new column as NULL.
  */
 export type SchemaColumnType = "boolean" | "number" | "string" | "datetime";
+/** Compiles and validates one immutable, row-local generated-column expression. */
+export declare function compileGeneratedColumnExpression(tableName: string, columnName: string, sql: string, columns: ReadonlyArray<{
+    readonly name: string;
+    readonly generatedValue?: {
+        readonly kind: "stored";
+        readonly sql: string;
+    };
+}>): Expression;
 /** What a FOREIGN KEY does to child rows when the parent row is deleted (E141-04). */
 export type ReferentialAction = "restrict" | "cascade" | "set null";
 /** A declared relation. `onDelete` defaults to "restrict", matching SQL's own default. */
@@ -16,6 +24,7 @@ export interface ColumnReferenceSpec {
     readonly table: string;
     readonly column: string;
     readonly onDelete: ReferentialAction;
+    readonly enforced: boolean;
 }
 /** A row condition every write must satisfy (E141-06); `sql` is a boolean expression. */
 export interface TableCheck {
@@ -31,6 +40,8 @@ export interface TableForeignKey<TColumnName extends string = string> {
         readonly columns: readonly string[];
     };
     readonly onDelete?: ReferentialAction;
+    /** False keeps the relationship in the catalog without validating or cascading rows. */
+    readonly enforced?: boolean;
 }
 /**
  * The constraint name `migrate()` gives a declared relation. It matches the name the SQL parser
@@ -44,22 +55,29 @@ export declare function foreignKeyName(tableName: string, columnName: string): s
 export type HasDefault<TValue> = TValue & {
     readonly __minnowHasDefault?: true;
 };
-export interface ColumnBuilder<TValue extends SchemaValue, TNullable extends boolean, TUnique extends boolean = false, THasDefault extends boolean = false, TInput extends SchemaValue = TValue> {
+export interface ColumnBuilder<TValue extends SchemaValue, TNullable extends boolean, TUnique extends boolean = false, THasDefault extends boolean = false, TInput extends SchemaValue = TValue, TDomain extends SqlDomain["kind"] | undefined = undefined, TGenerated extends boolean = false> {
     readonly kind: "column";
     readonly type: SchemaColumnType;
     readonly isNullable: TNullable;
     readonly isUnique: TUnique;
     readonly hasDefault: THasDefault;
+    readonly isGenerated: TGenerated;
     /** Type-only metadata consumed by adapters; optional so it emits no runtime payload. */
     readonly "~types"?: {
         readonly select: TValue;
         readonly input: TInput;
+        readonly domain: TDomain;
+        readonly generated: TGenerated;
     };
     /** True for exact SQL integer columns; ordinary number columns use Float64 semantics. */
     readonly integer: boolean;
     /** Logical SQL semantics layered over the stable string storage encoding. */
     readonly sqlDomain?: SqlDomain;
     readonly defaultSpec?: ColumnDefault;
+    readonly generatedSpec?: {
+        readonly kind: "stored";
+        readonly sql: string;
+    };
     /** Present on `column.enum()` builders: the closed set of values writes must draw from. */
     readonly enumValues?: readonly string[];
     /** What rows written before this column existed read as; see `.backfill()`. */
@@ -67,11 +85,11 @@ export interface ColumnBuilder<TValue extends SchemaValue, TNullable extends boo
     readonly renamedFromName?: string;
     readonly reference?: ColumnReferenceSpec;
     /** Marks the column nullable; inserts may omit it and reads may return null. */
-    nullable(): ColumnBuilder<TValue, true, TUnique, THasDefault, TInput>;
+    nullable(): ColumnBuilder<TValue, true, TUnique, THasDefault, TInput, TDomain, TGenerated>;
     /** Marks the table's unique key; exactly one non-nullable column may carry it. */
-    unique(this: ColumnBuilder<TValue, false, TUnique, THasDefault, TInput>): ColumnBuilder<TValue, TNullable, true, THasDefault, TInput>;
+    unique(this: ColumnBuilder<TValue, false, TUnique, THasDefault, TInput, TDomain, TGenerated>): ColumnBuilder<TValue, TNullable, true, THasDefault, TInput, TDomain, TGenerated>;
     /** Declares this column as the rename target of an existing catalog column. */
-    renamedFrom(name: string): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput>;
+    renamedFrom(name: string): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput, TDomain, TGenerated>;
     /**
      * What rows written before this column existed read as, instead of NULL. Giving one is what
      * makes adding a non-nullable column possible: no stored byte is rewritten, and reads
@@ -81,7 +99,7 @@ export interface ColumnBuilder<TValue extends SchemaValue, TNullable extends boo
      * catalog — so it can derive a value (a timestamp, a version stamp) without readers ever
      * disagreeing. It cannot derive from other columns; that would need a value per row.
      */
-    backfill(this: ColumnBuilder<TValue, false, TUnique, THasDefault, TInput>, value: TInput | (() => TInput)): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput>;
+    backfill(this: ColumnBuilder<TValue, false, TUnique, THasDefault, TInput, TDomain, TGenerated>, value: TInput | (() => TInput)): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput, TDomain, TGenerated>;
     /**
      * Declares a FOREIGN KEY onto another table's unique key. `migrate()` creates it as a real
      * constraint, so a write naming a parent row that does not exist is rejected — the same
@@ -89,26 +107,33 @@ export interface ColumnBuilder<TValue extends SchemaValue, TNullable extends boo
      *
      * `onDelete` defaults to `"restrict"`. `"set null"` requires a nullable column.
      */
-    references(this: ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput>, table: string, column: string, options?: {
+    references(this: ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput, TDomain, TGenerated>, table: string, column: string, options?: {
         onDelete?: Exclude<ReferentialAction, "set null">;
-    }): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput>;
-    references(this: ColumnBuilder<TValue, true, TUnique, THasDefault, TInput>, table: string, column: string, options: {
+        enforced?: true;
+    } | {
+        enforced: false;
+        onDelete?: never;
+    }): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput, TDomain, TGenerated>;
+    references(this: ColumnBuilder<TValue, true, TUnique, THasDefault, TInput, TDomain, TGenerated>, table: string, column: string, options: {
         onDelete: "set null";
-    }): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput>;
+        enforced?: true;
+    }): ColumnBuilder<TValue, TNullable, TUnique, THasDefault, TInput, TDomain, TGenerated>;
     /** Declares a literal SQL default. Omission or SQL `DEFAULT` invokes it; NULL does not. */
-    default(value: TInput): ColumnBuilder<TValue, TNullable, TUnique, true, TInput>;
+    default(value: TInput): ColumnBuilder<TValue, TNullable, TUnique, true, TInput, TDomain, TGenerated>;
     /**
      * Declares a variable-free SQL default expression, such as `CURRENT_TIMESTAMP`,
      * `gen_random_uuid()`, or `nextval('orders_id_seq')`. The engine parses and type-checks it
      * before migration and evaluates it once per omitted row.
      */
-    defaultSql(sql: string): ColumnBuilder<TValue, TNullable, TUnique, true, TInput>;
+    defaultSql(sql: string): ColumnBuilder<TValue, TNullable, TUnique, true, TInput, TDomain, TGenerated>;
+    /** Declares a stored expression over sibling columns. Callers never insert or update it. */
+    generatedSql(sql: string): ColumnBuilder<TValue, TNullable, TUnique, false, TInput, TDomain, true>;
     /**
      * Generates monotonically increasing integers for omitted or SQL `DEFAULT` slots from a persistent
      * per-table counter that is atomic across tabs. Explicit values are allowed and bump the
      * counter past their maximum. Number unique-key columns only.
      */
-    autoIncrement: TValue extends number ? (this: ColumnBuilder<TValue, false, true, THasDefault, TInput>) => ColumnBuilder<TValue, TNullable, TUnique, true, TInput> : never;
+    autoIncrement: TValue extends number ? (this: ColumnBuilder<TValue, false, true, THasDefault, TInput, TDomain, TGenerated>) => ColumnBuilder<TValue, TNullable, TUnique, true, TInput, TDomain, TGenerated> : never;
 }
 type SchemaValue = boolean | number | string | Date;
 /**
@@ -122,9 +147,14 @@ interface AnyColumn {
     readonly isNullable: boolean;
     readonly isUnique: boolean;
     readonly hasDefault: boolean;
+    readonly isGenerated: boolean;
     readonly integer: boolean;
     readonly sqlDomain?: SqlDomain;
     readonly defaultSpec?: ColumnDefault;
+    readonly generatedSpec?: {
+        readonly kind: "stored";
+        readonly sql: string;
+    };
     readonly enumValues?: readonly string[];
     readonly backfillValue?: SchemaValue | (() => SchemaValue);
     readonly renamedFromName?: string;
@@ -136,28 +166,30 @@ interface AnyColumn {
  */
 export declare function columnWithDefaultSpec(base: Pick<AnyColumn, "type" | "isNullable" | "isUnique" | "renamedFromName" | "reference" | "enumValues"> & Partial<Pick<AnyColumn, "integer" | "sqlDomain">>, spec: ColumnDefault): AnyColumn;
 /** Rebuilds a fluent column from structured-clone-safe metadata. */
-export declare function columnFromState(state: Pick<AnyColumn, "type" | "isNullable" | "isUnique"> & Partial<Pick<AnyColumn, "integer" | "sqlDomain" | "renamedFromName" | "reference" | "defaultSpec" | "enumValues" | "backfillValue">>): AnyColumn;
+export declare function columnFromState(state: Pick<AnyColumn, "type" | "isNullable" | "isUnique"> & Partial<Pick<AnyColumn, "integer" | "sqlDomain" | "renamedFromName" | "reference" | "defaultSpec" | "generatedSpec" | "enumValues" | "backfillValue">>): AnyColumn;
 export declare const column: {
-    boolean: () => ColumnBuilder<boolean, false, false, false, boolean>;
-    number: () => ColumnBuilder<number, false, false, false, number>;
+    boolean: () => ColumnBuilder<boolean, false, false, false, boolean, undefined, false>;
+    number: () => ColumnBuilder<number, false, false, false, number, undefined, false>;
     /** Exact safe-integer semantics, matching SQL INTEGER/SMALLINT/BIGINT. */
-    integer: () => ColumnBuilder<number, false, false, false, number>;
-    string: () => ColumnBuilder<string, false, false, false, string>;
-    datetime: () => ColumnBuilder<Date, false, false, false, Date>;
+    integer: () => ColumnBuilder<number, false, false, false, number, undefined, false>;
+    string: () => ColumnBuilder<string, false, false, false, string, undefined, false>;
+    datetime: () => ColumnBuilder<Date, false, false, false, Date, undefined, false>;
     /** Exact decimal SQL NUMERIC. Selects return strings; writes accept strings or numbers. */
     numeric: (options?: {
         precision?: number;
         scale?: number;
-    }) => ColumnBuilder<string, false, false, false, string | number>;
-    json: () => ColumnBuilder<string, false, false, false, string>;
-    jsonb: () => ColumnBuilder<string, false, false, false, string>;
-    uuid: () => ColumnBuilder<string, false, false, false, string>;
-    time: () => ColumnBuilder<string, false, false, false, string>;
-    interval: () => ColumnBuilder<string, false, false, false, string>;
+    }) => ColumnBuilder<string, false, false, false, string | number, "numeric", false>;
+    json: () => ColumnBuilder<string, false, false, false, string, "json", false>;
+    jsonb: () => ColumnBuilder<string, false, false, false, string, "jsonb", false>;
+    uuid: () => ColumnBuilder<string, false, false, false, string, "uuid", false>;
+    /** A zoneless calendar date, represented publicly as canonical `YYYY-MM-DD` text. */
+    date: () => ColumnBuilder<string, false, false, false, string, "date", false>;
+    time: () => ColumnBuilder<string, false, false, false, string, "time", false>;
+    interval: () => ColumnBuilder<string, false, false, false, string, "interval", false>;
     /** JSON array text at the JavaScript boundary, with the SQL element type retained in metadata. */
-    array: (element: string) => ColumnBuilder<string, false, false, false, string>;
+    array: (element: string) => ColumnBuilder<string, false, false, false, string, "array", false>;
     /** A named SQL enum domain, distinct from the lightweight `column.enum()` restriction. */
-    sqlEnum: <const TValues extends readonly [string, ...string[]]>(name: string, values: TValues) => ColumnBuilder<TValues[number], false>;
+    sqlEnum: <const TValues extends readonly [string, ...string[]]>(name: string, values: TValues) => ColumnBuilder<TValues[number], false, false, false, TValues[number], "enum">;
     /**
      * A string column restricted to a closed set of values, typed as their literal union:
      *
@@ -234,6 +266,7 @@ export declare function declaredForeignKeys(definition: AnyTable): Array<{
     parentTable: string;
     parentColumns: string[];
     onDelete: ReferentialAction;
+    enforced: boolean;
 }>;
 /**
  * A view declared in the schema: the query it stands for, plus the column shape the author
@@ -299,11 +332,15 @@ type NullableKeys<TTable extends AnyTable> = {
 type DefaultKeys<TTable extends AnyTable> = {
     [K in keyof TTable["columns"]]: TTable["columns"][K]["hasDefault"] extends true ? K : never;
 }[keyof TTable["columns"]];
-type OptionalInsertKeys<TTable extends AnyTable> = NullableKeys<TTable> | DefaultKeys<TTable>;
+type GeneratedKeys<TTable extends AnyTable> = {
+    [K in keyof TTable["columns"]]: TTable["columns"][K]["isGenerated"] extends true ? K : never;
+}[keyof TTable["columns"]];
+type OptionalInsertKeys<TTable extends AnyTable> = Exclude<NullableKeys<TTable> | DefaultKeys<TTable>, GeneratedKeys<TTable>>;
+type RequiredInsertKeys<TTable extends AnyTable> = Exclude<keyof TTable["columns"], OptionalInsertKeys<TTable> | GeneratedKeys<TTable>>;
 /** Insert rows require every non-nullable column and may omit nullable or default-bearing ones. */
-export type InferInsertRow<TTable extends AnyTable> = Omit<{
-    [K in keyof TTable["columns"]]: ColumnInputValue<TTable["columns"][K]>;
-}, OptionalInsertKeys<TTable>> & {
+export type InferInsertRow<TTable extends AnyTable> = {
+    [K in RequiredInsertKeys<TTable>]: ColumnInputValue<TTable["columns"][K]>;
+} & {
     [K in OptionalInsertKeys<TTable>]?: ColumnInputValue<TTable["columns"][K]>;
 };
 /** Scalar `.unique()` keys plus columns named by a table-level primary key. */
@@ -316,7 +353,7 @@ export type PrimaryKeyKeys<TTable extends AnyTable> = {
  * stays assignable under `exactOptionalPropertyTypes`.
  */
 export type InferUpdateChanges<TTable extends AnyTable> = {
-    [K in keyof TTable["columns"] as K extends PrimaryKeyKeys<TTable> ? never : K]?: ColumnInputValue<TTable["columns"][K]> | undefined;
+    [K in keyof TTable["columns"] as K extends PrimaryKeyKeys<TTable> | GeneratedKeys<TTable> ? never : K]?: ColumnInputValue<TTable["columns"][K]> | undefined;
 };
 export type MigrationStep = {
     kind: "create-table";
@@ -365,6 +402,20 @@ export type MigrationStep = {
     tableName: string;
     columnName: string;
     defaultValue: ColumnDefault | null;
+} | {
+    kind: "alter-generated";
+    tableName: string;
+    columnName: string;
+    generatedValue: {
+        readonly kind: "stored";
+        readonly sql: string;
+    } | null;
+}
+/** Informational relationships are catalog-only and may change without scanning stored rows. */
+ | {
+    kind: "alter-foreign-keys";
+    tableName: string;
+    foreignKeys: ReturnType<typeof declaredForeignKeys>;
 }
 /**
  * A view is derived and disposable: nothing is stored under it, so replacing its body loses no