@everystack/model 0.4.21 → 0.4.22

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `@everystack/model` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.22] - 2026-10-16
+
+### Added
+
+- check() takes an explicit constraint name; db:pull keeps a live name
+
+### Fixed
+
+- db:apply runs a rename-only plan
+
 ## [0.4.21] - 2026-10-14
 
 ### Added
@@ -20,12 +30,6 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 - rowOwnership exceptRoles lifts the backstop for manage roles
 - only a plain manage role lifts the rowOwnership backstop
 
-## [Unreleased]
-
-### Added
-
-- apply state prerequisites atomically
-
 ## [0.4.20] - 2026-09-26
 
 ### BREAKING CHANGES

package/README.md

@@ -87,6 +87,8 @@ The table-level surface, composed in `constraints: [...]`, for what a column-sco
 - `check(sql\`a >= b\`)` — a multi-column CHECK.
 - `foreignKey(['a', 'b'], () => Other, ['x', 'y'], { onDelete })` — a composite foreign key.
 
+Each can carry the name the database calls it: `index('slug').name('posts_slug_lookup')`, `foreignKey([...], () => Other, [...], { name: 'posts_owner_fk' })`, and `check(sql\`ends_at >= starts_at\`, { name: 'events_window_check' })`. Undeclared, the compiler generates the name. A check is then named by its position among the table's unnamed checks (`events_check_0`, `events_check_1`), so inserting or reordering one renames the others; an explicit name is used verbatim and is stable under reordering. A name must be a bare lowercase identifier of at most 63 bytes, and two checks in one table cannot share a name or take one an unnamed check gets by position. Declaring a name on an existing constraint plans a `RENAME CONSTRAINT` (or `ALTER INDEX … RENAME`), never a drop and re-add. `db:apply` applies a rename like any other change, also when it is the only change in the plan. `db:pull` declares a live name only when it is not the one the compiler would generate.
+
 ## Authorization
 
 `can(action, condition)` declares one rule (default-deny: no matching `can()` means denied). Conditions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.21",
+  "version": "0.4.22",
   "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

@@ -16,8 +16,11 @@ import type { ReferentialAction } from './field';
 export type TableConstraint =
   /** `UNIQUE (a, b)` over two or more field keys — the composite the field builder can't carry. */
   | { kind: 'unique'; columns: string[] }
-  /** `CHECK (<predicate>)` — a raw SQL predicate, typically spanning columns. */
-  | { kind: 'check'; predicate: string }
+  /**
+   * `CHECK (<predicate>)` — a raw SQL predicate, typically spanning columns. `name` is present
+   * only when declared; absent, the compiler names it by position (see {@link positionalCheckName}).
+   */
+  | { kind: 'check'; predicate: string; name?: string }
   /** A standalone index — `CREATE [UNIQUE] INDEX [USING <method>] … (keys) [INCLUDE (cols)] [WHERE <predicate>]`. */
   | { kind: 'index'; columns: string[]; isUnique: boolean; predicate?: string; method?: string; includeColumns?: string[]; rawPositions?: boolean[]; indexName?: string }
   /**
@@ -35,9 +38,60 @@ export function unique(...columns: string[]): TableConstraint {
   return { kind: 'unique', columns };
 }
 
-/** A table CHECK from a raw predicate: `check(sql\`published_at >= created_at\`)`. */
-export function check(predicate: RawSql): TableConstraint {
-  return { kind: 'check', predicate: predicate.sql };
+/**
+ * A table CHECK from a raw predicate: `check(sql\`published_at >= created_at\`)`.
+ *
+ * `{ name }` declares the name the database calls it: `check(sql\`…\`, { name: 'contents_state_check' })`.
+ * Undeclared, the compiler names it by POSITION among the table's unnamed checks
+ * (`<table>_check_<n>`), which is fine for a greenfield model and fragile for everything that
+ * names a constraint: inserting or reordering an unnamed check renames its siblings. A declared
+ * name is used verbatim, does not take a position, and is stable under reordering. Same rule as
+ * `index().name()` and `foreignKey({ name })`: the generated name is the fallback.
+ */
+export function check(predicate: RawSql, opts?: { name?: string }): TableConstraint {
+  return {
+    kind: 'check',
+    predicate: predicate.sql,
+    ...(opts?.name !== undefined ? { name: assertConstraintName(opts.name, `check(sql\`${predicate.sql}\`)`, MAX_IDENTIFIER_BYTES) } : {}),
+  };
+}
+
+/**
+ * The name an UNNAMED table check gets: `<table>_check_<position>`, where position counts only
+ * the unnamed checks before it — a named check never takes a position, so naming one check
+ * cannot rename the others. ONE implementation, shared by the compiler, `db:pull` (which declares
+ * a live name exactly when it is not this) and {@link assertCheckNames}.
+ */
+export function positionalCheckName(table: string, position: number): string {
+  return `${table}_check_${position}`;
+}
+
+/**
+ * Refuse declared check names that cannot coexist in one table: the same name twice, or a name
+ * an unnamed check in the same table gets by position. Run by `defineModel`, the first point
+ * that knows the table — the identifier itself was already validated at {@link check}.
+ */
+export function assertCheckNames(table: string, constraints: readonly TableConstraint[]): void {
+  const positional = new Set<string>();
+  let position = 0;
+  for (const c of constraints) {
+    if (c.kind === 'check' && c.name === undefined) positional.add(positionalCheckName(table, position++));
+  }
+  const declared = new Set<string>();
+  for (const c of constraints) {
+    if (c.kind !== 'check' || c.name === undefined) continue;
+    const label = `check(sql\`${c.predicate}\`)`;
+    if (declared.has(c.name)) {
+      throw new Error(`model '${table}': two checks are named '${c.name}' (the second is ${label}). A constraint name is unique within its table.`);
+    }
+    if (positional.has(c.name)) {
+      throw new Error(
+        `model '${table}': ${label} is named '${c.name}', which an unnamed check in this table gets by position. `
+        + 'Name that check as well, or choose another name.',
+      );
+    }
+    declared.add(c.name);
+  }
 }
 
 /**
@@ -184,15 +238,27 @@ const INDEX_NAME = /^[a-z_][a-z0-9_$]*$/;
  * surface that lets a model name a database object — an index, a foreign key constraint —
  * because two copies of a validation rule is how one of them ends up laxer than the other.
  */
-export function assertConstraintName(name: string, what = 'constraint'): string {
+export function assertConstraintName(name: string, what = 'constraint', maxBytes?: number): string {
   if (!INDEX_NAME.test(name)) {
     throw new Error(
       `${what} name '${name}' is not a bare lowercase identifier (${INDEX_NAME}). It is interpolated into DDL that takes no parameters, so it is refused here rather than built into SQL.`,
     );
   }
+  // PostgreSQL truncates a longer identifier with only a NOTICE, so the database would hold a
+  // name the model does not declare, and every later plan would see the difference.
+  // Opt-in: index and foreign key names loaded without this limit before check names had it.
+  const bytes = new TextEncoder().encode(name).length;
+  if (maxBytes !== undefined && bytes > maxBytes) {
+    throw new Error(
+      `${what} name '${name}' is ${bytes} bytes. PostgreSQL identifiers are at most ${maxBytes} bytes and a longer one is truncated silently, so it is refused here.`,
+    );
+  }
   return name;
 }
 
+/** NAMEDATALEN - 1 on a stock PostgreSQL build. */
+const MAX_IDENTIFIER_BYTES = 63;
+
 export function index(...entries: Array<string | RawSql>): IndexBuilder {
   return new IndexBuilder(entries);
 }

package/src/index.ts

@@ -15,7 +15,7 @@ export { canonicalColumnType, fieldFactoryCall, pgTypeRefusal } from './pg-type'
 export { parseQualified } from './qualified';
 export { linkModels, ModelLinkError } from './link';
 
-export { unique, check, index, foreignKey, IndexBuilder } from './constraints';
+export { unique, check, index, foreignKey, IndexBuilder, positionalCheckName } from './constraints';
 export type { TableConstraint } from './constraints';
 
 export { sql } from './raw-sql';

package/src/model.ts

@@ -16,7 +16,7 @@ import { referenceLocation } from './link';
 import type { Ability } from './can';
 import { isPublicReadAbility, isDeleteAbility, needsSoftDeleteDeclaration, privilegesGrantDelete, sessionlessAudience } from './can';
 import type { Relation } from './relations';
-import type { TableConstraint } from './constraints';
+import { assertCheckNames, type TableConstraint } from './constraints';
 import type { RawSql } from './raw-sql';
 import { validateTriggersFor, type TriggerSpec, type DependsOnRef } from './derived';
 import { TABLE_PRIVILEGES, type TablePrivilege } from './privileges';
@@ -450,6 +450,8 @@ export function defineModel(table: string, def: ModelDefinition): ModelDescripto
     );
   }
 
+  assertCheckNames(table, def.constraints ?? []);
+
   return {
     table,
     fields: def.fields,