@everystack/model 0.4.18 → 0.4.19

package/CHANGELOG.md

@@ -4,11 +4,12 @@ All notable changes to `@everystack/model` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
-## [Unreleased]
+## [0.4.19] - 2026-09-16
 
 ### Added
 
 - automate the version-drift check — a manual note is not a gate
+- validate: false on a foreign key, and a per-key apply preflight
 
 ## [0.4.18] - 2026-09-16
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.18",
+  "version": "0.4.19",
   "description": "Declare a table's schema, validation, and authorization once — compiled to migrations, RLS, and handler config",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/constraints.ts

@@ -25,7 +25,10 @@ export type TableConstraint =
    * `.references()` can't carry. Local field keys, a model thunk for the target, and the target's
    * field keys; optional `onDelete`/`onUpdate` referential actions.
    */
-  | { kind: 'foreignKey'; columns: string[]; references: () => unknown; refColumns: string[]; onDelete?: ReferentialAction; onUpdate?: ReferentialAction; constraintName?: string };
+  | { kind: 'foreignKey'; columns: string[]; references: () => unknown; refColumns: string[]; onDelete?: ReferentialAction; onUpdate?: ReferentialAction; constraintName?: string;
+      /** `validate: false` — see {@link foreignKey}. Stored only when FALSE; the default
+       *  (validate against the rows already there) is the absence of the field. */
+      validate?: boolean };
 
 /** A composite unique constraint over the given field keys: `unique('authorId', 'slug')`. */
 export function unique(...columns: string[]): TableConstraint {
@@ -42,12 +45,17 @@ export function check(predicate: RawSql): TableConstraint {
  * surface can express: `foreignKey(['orgId', 'teamId'], () => Team, ['orgId', 'teamId'])`. The
  * target columns are explicit (a composite FK references a composite key, not just the PK), and
  * the referential actions ride here the same way they ride on `.references()`.
+ *
+ * `validate: false` means the same thing it means on `.references()` — "enforce forward,
+ * grandfather legacy": the key is installed `NOT VALID` and is never asked to prove itself
+ * against the rows that were already there. See {@link FieldBuilder.references} for the whole
+ * rationale; it is one declared intent with two surfaces, not two features.
  */
 export function foreignKey(
   columns: string[],
   references: () => unknown,
   refColumns: string[],
-  opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction; name?: string },
+  opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction; name?: string; validate?: boolean },
 ): TableConstraint {
   return {
     kind: 'foreignKey',
@@ -58,9 +66,32 @@ export function foreignKey(
     ...(opts?.onUpdate ? { onUpdate: opts.onUpdate } : {}),
     // The generated name is the FALLBACK; an adopted database keeps the name it arrived with.
     ...(opts?.name !== undefined ? { constraintName: assertConstraintName(opts.name, 'foreign key') } : {}),
+    // FALSE is the only value worth storing: `true` is the default, and storing it would make
+    // two declarations of the same intent compile to two different shapes.
+    ...(assertFkValidate(opts?.validate, `foreignKey(${columns.join(', ')})`) === false ? { validate: false } : {}),
   };
 }
 
+/**
+ * Validate a `validate:` option, returning it. Declared at the DECLARATION, like
+ * {@link assertConstraintName}, because the value decides whether a `VALIDATE CONSTRAINT`
+ * is ever emitted — and a truthy string (`validate: 'no'`) would silently read as "yes,
+ * validate", which is the reverse of what the author wrote.
+ *
+ * `undefined` passes through (the option was not given). Anything that is not a boolean is
+ * refused by name: there is no third state for this flag, so a coercion could only guess.
+ */
+export function assertFkValidate(value: unknown, where: string): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'boolean') {
+    throw new Error(
+      `${where}: validate must be true or false, not ${typeof value === 'object' ? JSON.stringify(value) : JSON.stringify(String(value))}. `
+      + 'It decides whether the foreign key is ever checked against the rows already in the table, so it is refused here rather than coerced.',
+    );
+  }
+  return value;
+}
+
 /**
  * A standalone index over the given keys, chainable: `index('authorId')`,
  * `index('authorId').unique()`, `index('slug').where(sql\`deleted_at IS NULL\`)` (partial),

package/src/field.ts

@@ -13,7 +13,7 @@
 
 import type { RawSql } from './raw-sql';
 import { pgTypeRefusal } from './pg-type';
-import { assertConstraintName } from './constraints';
+import { assertConstraintName, assertFkValidate } from './constraints';
 
 export type FieldType =
   | 'text'
@@ -93,6 +93,29 @@ export interface FieldSpec {
    * stayed green. Same defect as index names, one object over.
    */
   constraintName?: string;
+  /**
+   * `validate: false` — install the foreign key `NOT VALID` and never ask it to prove itself
+   * against the rows that were already there. Present (and FALSE) only when declared; the
+   * default is a key that must be fully valid, exactly as before.
+   *
+   * WHY IT EXISTS — "enforce forward, grandfather legacy", the pattern a long-lived database
+   * reaches for when referential integrity is adopted late. A `NOT VALID` foreign key is fully
+   * enforced on every NEW write; what it skips is the one-time scan of the existing rows. On a
+   * schema that ran for years without the constraint, some of those rows legitimately point at
+   * parents that were deleted — 11,500 of them across 12 keys on one adopted database, all of
+   * it ordinary decay. Validating is then not a migration, it is a data-archaeology project,
+   * and holding every unrelated change behind it is the wrong trade.
+   *
+   * So this is a FIRST-CLASS, PERMANENT declared state, not a temporary escape hatch: a live
+   * `NOT VALID` key that matches a `validate: false` declaration is a clean match forever, and
+   * stays one until someone edits the model to drop the flag. The compiler turns it into
+   * `ForeignKey.notValid`, the differ emits `ADD CONSTRAINT … NOT VALID` with no paired
+   * `VALIDATE`, and the apply's row preflight is never asked about the key at all.
+   *
+   * It is the opposite of `NOT ENFORCED`: new writes are still refused. Nothing here ever
+   * deletes or rewrites a row — the orphans stay, named for a human to decide about.
+   */
+  referencesValidate?: boolean;
   /**
    * `GENERATED ALWAYS AS IDENTITY` / `GENERATED BY DEFAULT AS IDENTITY`.
    *
@@ -210,12 +233,22 @@ export class FieldBuilder {
    * Declare a foreign key. The target is a model thunk (forward-reference safe). Optional
    * `onDelete`/`onUpdate` referential actions are column-scoped, so they live here, not on
    * the table — `field.uuid().references(() => User, { onDelete: 'cascade' })`.
+   *
+   * `validate: false` declares "enforce forward, grandfather legacy": the key is installed
+   * `NOT VALID`, so every new write is refused as normal while the rows that were already
+   * there are never scanned. It is a permanent declared state, not a migration step — see
+   * {@link FieldSpec.referencesValidate} for why a fifteen-year-old schema needs to be able
+   * to say it.
    */
-  references(target: () => unknown, opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction; name?: string }): this {
+  references(target: () => unknown, opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction; name?: string; validate?: boolean }): this {
     this.spec.references = target;
     if (opts?.onDelete) this.spec.onDelete = opts.onDelete;
     if (opts?.onUpdate) this.spec.onUpdate = opts.onUpdate;
     if (opts?.name !== undefined) this.spec.constraintName = assertConstraintName(opts.name, 'foreign key');
+    // Only FALSE is recorded — `true` is the default, and storing it would give one intent two
+    // compiled shapes. A non-boolean is refused by name rather than coerced (a truthy string
+    // would read as the OPPOSITE of what the author wrote).
+    if (assertFkValidate(opts?.validate, 'references(…)') === false) this.spec.referencesValidate = false;
     return this;
   }