durcno 1.0.0-alpha.15 → 1.0.0-alpha.16

package/dist/bin.cjs

@@ -10455,7 +10455,7 @@ async function status(options) {
 }
 
 // src/cli/index.ts
-program.version("1.0.0-alpha.14");
+program.version("1.0.0-alpha.15");
 var Options = {
   config: ["--config <path>", "Path to the config file"]
 };

package/dist/src/constraints/foreign-key.d.mts

@@ -0,0 +1,61 @@
+import { Column, OnDeleteAction } from "../columns/common.mjs";
+import { AnyColumn, StdTableColumn } from "../table.mjs";
+
+//#region src/constraints/foreign-key.d.ts
+/**
+ * Intermediate builder returned by `fk(column)`.
+ * Call `.references(refColumn)` to finalise into a `ForeignKey`.
+ */
+declare class ForeignKeyBuilder<TCol extends AnyColumn> {
+  #private;
+  constructor(column: StdTableColumn<TCol>);
+  /**
+   * Specify the referenced column.
+   * The referenced column's value type must match the source column's value type.
+   */
+  references<TRefCol extends Column<any, TCol["ValType"]>>(ref: StdTableColumn<TRefCol>): ForeignKey;
+}
+/**
+ * Represents a finalised table-level foreign key constraint.
+ * Created via `fk(column).references(refColumn)`.
+ */
+declare class ForeignKey {
+  #private;
+  constructor(column: StdTableColumn, reference: StdTableColumn, onDelete: OnDeleteAction);
+  /**
+   * Override the default `CASCADE` delete action.
+   *
+   * @param action - The `ON DELETE` action to apply.
+   * @returns `this` for chaining.
+   */
+  onDelete(action: OnDeleteAction): this;
+  _: {
+    /** Returns the source column of the foreign key. */getColumn: () => StdTableColumn; /** Returns the referenced column of the foreign key. */
+    getReference: () => StdTableColumn; /** Returns the configured `ON DELETE` action. */
+    getOnDelete: () => OnDeleteAction;
+  };
+}
+/**
+ * Entry point for defining a table-level foreign key constraint.
+ * Use inside the `foreignKeys` callback in `TableExtra`.
+ *
+ * Because `foreignKeys` receives the fully-constructed table as a typed
+ * parameter `t`, column references are already resolved — no thunk needed.
+ *
+ * @param column - The source column on this table.
+ * @returns A `ForeignKeyBuilder` to chain `.references(refColumn)` on.
+ *
+ * @example
+ * ```ts
+ * table("public", "comments", { ... }, {
+ *   foreignKeys: (t, fk) => [
+ *     fk(t.parentId).references(t.id).onDelete("SET NULL"),
+ *   ],
+ * });
+ * ```
+ */
+declare function fk<TCol extends AnyColumn>(column: StdTableColumn<TCol>): ForeignKeyBuilder<TCol>;
+/** The type of the `fk` helper injected into the `foreignKeys` callback. */
+type ForeignKeyFn = typeof fk;
+//#endregion
+export { ForeignKey, ForeignKeyFn };

package/dist/src/constraints/foreign-key.mjs

@@ -0,0 +1,74 @@
+//#region src/constraints/foreign-key.ts
+/**
+* Intermediate builder returned by `fk(column)`.
+* Call `.references(refColumn)` to finalise into a `ForeignKey`.
+*/
+var ForeignKeyBuilder = class {
+	#column;
+	constructor(column) {
+		this.#column = column;
+	}
+	/**
+	* Specify the referenced column.
+	* The referenced column's value type must match the source column's value type.
+	*/
+	references(ref) {
+		return new ForeignKey(this.#column, ref, "CASCADE");
+	}
+};
+/**
+* Represents a finalised table-level foreign key constraint.
+* Created via `fk(column).references(refColumn)`.
+*/
+var ForeignKey = class {
+	#column;
+	#reference;
+	#onDelete;
+	constructor(column, reference, onDelete) {
+		this.#column = column;
+		this.#reference = reference;
+		this.#onDelete = onDelete;
+	}
+	/**
+	* Override the default `CASCADE` delete action.
+	*
+	* @param action - The `ON DELETE` action to apply.
+	* @returns `this` for chaining.
+	*/
+	onDelete(action) {
+		this.#onDelete = action;
+		return this;
+	}
+	_ = {
+		/** Returns the source column of the foreign key. */
+		getColumn: () => this.#column,
+		/** Returns the referenced column of the foreign key. */
+		getReference: () => this.#reference,
+		/** Returns the configured `ON DELETE` action. */
+		getOnDelete: () => this.#onDelete
+	};
+};
+/**
+* Entry point for defining a table-level foreign key constraint.
+* Use inside the `foreignKeys` callback in `TableExtra`.
+*
+* Because `foreignKeys` receives the fully-constructed table as a typed
+* parameter `t`, column references are already resolved — no thunk needed.
+*
+* @param column - The source column on this table.
+* @returns A `ForeignKeyBuilder` to chain `.references(refColumn)` on.
+*
+* @example
+* ```ts
+* table("public", "comments", { ... }, {
+*   foreignKeys: (t, fk) => [
+*     fk(t.parentId).references(t.id).onDelete("SET NULL"),
+*   ],
+* });
+* ```
+*/
+function fk(column) {
+	return new ForeignKeyBuilder(column);
+}
+//#endregion
+export { fk };

package/dist/src/migration/snapshot.mjs

@@ -9,6 +9,7 @@ import { Enum } from "../enumtype.mjs";
 import { Sequence } from "../sequence.mjs";
 import chalk from "../node_modules/.pnpm/chalk@5.6.2/node_modules/chalk/source/index.mjs";
 import { check } from "../constraints/check.mjs";
+import { fk } from "../constraints/foreign-key.mjs";
 //#region src/migration/snapshot.ts
 const { red } = chalk;
 /**
@@ -72,6 +73,18 @@ function snapshot(entities) {
 				as: col.getGeneratedAs
 			};
 		});
+		const tableFks = table._.extra.foreignKeys?.(table, fk) ?? [];
+		for (const foreignKey of tableFks) {
+			const srcCol = foreignKey._.getColumn();
+			const refCol = foreignKey._.getReference();
+			const colEntry = ss.tables[`${table._.schemaSql}.${table._.nameSql}`].columns[srcCol.nameSql];
+			if (colEntry) colEntry.references = {
+				schema: refCol.table._.schemaSql,
+				table: refCol.table._.nameSql,
+				column: refCol.nameSql,
+				onDelete: foreignKey._.getOnDelete()
+			};
+		}
 		(table._.extra.indexes?.(table) ?? []).forEach((index) => {
 			ss.tables[`${table._.schemaSql}.${table._.nameSql}`].indexes[index._.getName(table)] = {
 				name: index._.getName(table),

package/dist/src/table.d.mts

@@ -2,6 +2,7 @@ import { CamelToSnake, Key, SnakeCase, Valueof } from "./types.mjs";
 import { Check, CheckExpression } from "./constraints/check.mjs";
 import { entityType } from "./symbols.mjs";
 import { Column } from "./columns/common.mjs";
+import { ForeignKey, ForeignKeyFn } from "./constraints/foreign-key.mjs";
 import { PrimaryKeyConstraint, PrimaryKeyConstraintFn } from "./constraints/primary-key.mjs";
 import { UniqueConstraint, UniqueConstraintFn } from "./constraints/unique.mjs";
 import { Index } from "./indexes.mjs";
@@ -13,6 +14,7 @@ type TableExtra<TSchema extends string, TName extends string, TColumns extends R
   primaryKeyConstraint?: (table: TableWithColumns<TSchema, TName, TColumns>, primaryKey: PrimaryKeyConstraintFn) => PrimaryKeyConstraint;
   uniqueConstraints?: (table: TableWithColumns<TSchema, TName, TColumns>, unique: UniqueConstraintFn) => UniqueConstraint[];
   checkConstraints?: (table: TableWithColumns<TSchema, TName, TColumns>, check: (name: string, expr: CheckExpression<Valueof<TableWithColumns<TSchema, TName, TColumns>["_"]["columns"]>>) => Check) => Check[];
+  foreignKeys?: (table: TableWithColumns<TSchema, TName, TColumns>, fk: ForeignKeyFn) => ForeignKey[];
 };
 type TableConfig<TSchema extends string, TName extends string, TColumns extends Record<string, AnyColumn>> = {
   /** The raw table name as provided by the user (may be camelCase). */readonly name: TName; /** The snake_case version of {@link TableConfig.name} used in generated SQL. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "durcno",
-  "version": "1.0.0-alpha.15",
+  "version": "1.0.0-alpha.16",
   "description": "A PostgreSQL Query Builder and Migration Manager for TypeScript, from the future.",
   "license": "Apache-2.0",
   "homepage": "https://durcno.dev",