@everystack/model 0.4.21 → 0.4.23

package/src/derive.ts

@@ -23,15 +23,24 @@ export interface RelationConfig {
   from: string;
   to: string;
   many?: boolean;
+  /** To-one from the parent side: the first target row in `orderBy` order, or null. */
+  hasOne?: true;
+  orderBy?: Array<{ column: string; order: 'asc' | 'desc' }>;
+  limit?: number;
+  where?: Record<string, string | number | boolean | null>;
 }
 
 export interface DerivedHandlerConfig {
   exposedTables: string[];
   hiddenColumns: Record<string, string[]>;
+  /** Plain manage roles that may read lifecycle metadata; private fields stay hidden. */
+  hiddenColumnsExceptRoles?: Record<string, string[]>;
   protectedFields: Record<string, string[]>;
   /** `exceptRoles` is present only when a `can('manage', { role })` exists for the table. */
   rowOwnership: Record<string, { column: string; userField: string; exceptRoles?: string[] }>;
-  softDelete: { tables: string[] };
+  /** `lifecycle` (present only when a lifecycle model exists) lists the `lifecycle: true` tables;
+   *  each is also in `tables`, so the read filter applies to it. */
+  softDelete: { tables: string[]; lifecycle?: string[] };
   relations: Record<string, Record<string, RelationConfig>>;
   hooks: Record<string, ModelHooks>;
 }
@@ -50,9 +59,11 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
   linkModels(models);
   const exposedTables: string[] = [];
   const hiddenColumns: Record<string, string[]> = {};
+  const hiddenColumnsExceptRoles: Record<string, string[]> = {};
   const protectedFields: Record<string, string[]> = {};
   const rowOwnership: DerivedHandlerConfig['rowOwnership'] = {};
   const softDeleteTables: string[] = [];
+  const lifecycleTables: string[] = [];
   const relations: Record<string, Record<string, RelationConfig>> = {};
   const hooks: Record<string, ModelHooks> = {};
 
@@ -79,6 +90,13 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
     // The first owner-shaped ability → the handler's rowOwnership IDOR backstop.
     // (RLS, compiled from the same ability in Phase 1, is the primary enforcement;
     // this is the HTTP-path guard. A model's owner abilities share one column.)
+    const exceptRoles = [
+      ...new Set(
+        model.abilities
+          .filter((a) => a.action === 'manage' && isPlainRole(a.condition))
+          .map((a) => a.condition.role as string),
+      ),
+    ];
     const ownerAbility = model.abilities.find((a) => a.condition.owner);
     if (ownerAbility) {
       rowOwnership[table] = {
@@ -90,19 +108,20 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
       // counts: a role-scoped update or delete alone does not lift it, and neither does a
       // manage ability with any other condition, which narrows what RLS lets it write
       // (fail closed: a whitelist of `role`, not a blacklist of the rest).
-      const exceptRoles = [
-        ...new Set(
-          model.abilities
-            .filter((a) => a.action === 'manage' && isPlainRole(a.condition))
-            .map((a) => a.condition.role as string),
-        ),
-      ];
       if (exceptRoles.length) rowOwnership[table].exceptRoles = exceptRoles;
     }
 
     // Declared, not inferred — one `softDelete` decision drives both the API filter and the
     // RLS guard, so the two can never disagree about what a soft-deleted row is.
     if (model.softDelete) softDeleteTables.push(table);
+    // A lifecycle table soft-deletes in the database (its delete trigger); the handler reads it as
+    // a soft-delete table and drives that machinery instead of writing deleted_at itself.
+    if (model.lifecycle) {
+      softDeleteTables.push(table);
+      lifecycleTables.push(table);
+      hiddenColumns[table] = [...new Set([...(hiddenColumns[table] ?? []), 'deletedBy', 'deletedBatch', 'deletedXid'])];
+      hiddenColumnsExceptRoles[table] = exceptRoles;
+    }
 
     if (model.hooks) hooks[table] = model.hooks;
 
@@ -112,7 +131,18 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
       for (const name of relationNames) {
         const rel = model.relations[name];
         const target = rel.target();
-        if (rel.kind === 'belongsTo') {
+        if (rel.kind === 'hasOne') {
+          // this.<pk> → target.<column>, one row. linkModels normalized the orderBy: it always
+          // ends with the target's key, so the handler chooses the same row every time.
+          resolved[name] = {
+            table: target.table,
+            from: rel.references ?? primaryKeyOf(model),
+            to: rel.column,
+            hasOne: true,
+            orderBy: (rel.orderBy ?? []).map((t) => ({ column: t.field, order: t.order })),
+          };
+          if (rel.where) resolved[name].where = { ...rel.where };
+        } else if (rel.kind === 'belongsTo') {
           // this.<column> → target.<pk>
           resolved[name] = {
             table: target.table,
@@ -127,18 +157,23 @@ export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerCo
             to: rel.column,
             many: true,
           };
+          // Model field names are the schema property names the handler resolves.
+          if (rel.orderBy) resolved[name].orderBy = rel.orderBy.map((t) => ({ column: t.field, order: t.order }));
+          if (rel.limit !== undefined) resolved[name].limit = rel.limit;
+          if (rel.where) resolved[name].where = { ...rel.where };
         }
       }
-      relations[table] = resolved;
+      if (Object.keys(resolved).length) relations[table] = resolved;
     }
   }
 
   return {
     exposedTables,
     hiddenColumns,
+    ...(lifecycleTables.length ? { hiddenColumnsExceptRoles } : {}),
     protectedFields,
     rowOwnership,
-    softDelete: { tables: softDeleteTables },
+    softDelete: { tables: softDeleteTables, ...(lifecycleTables.length ? { lifecycle: lifecycleTables } : {}) },
     relations,
     hooks,
   };

package/src/derived.ts

@@ -88,7 +88,7 @@ function validateRelationFields(kind: string, name: string, fields: Record<strin
     const s = builder.spec;
     if (s.isPrimaryKey) throw new Error(`${at}: .primaryKey() is table structure — a relation column carries type, nullability, and array only.`);
     if (s.isUnique) throw new Error(`${at}: .unique() is a table constraint — enforce it on the base table (or a matview index).`);
-    if (s.references) throw new Error(`${at}: .references() is a table FK — declare it on the base table; the body carries the join.`);
+    if (s.references || s.referencesExternal) throw new Error(`${at}: .references() is a table FK — declare it on the base table; the body carries the join.`);
     if (s.defaultKind) throw new Error(`${at}: defaults are meaningless on a relation column — the body computes every value.`);
     if (s.isDeprecated) throw new Error(`${at}: .deprecated() is the table contract phase — remove the column from the body instead.`);
     if (s.isPrivate) throw new Error(`${at}: .private() hides a table column from the API — a relation exposes only what its body selects; drop the column from the body.`);

package/src/drizzle.ts

@@ -170,6 +170,10 @@ export function toDrizzleTable(model: ModelDescriptor): PgTableWithColumns<any>
 
     if (spec.references) {
       const target = spec.references as () => ModelDescriptor;
+      // The CHILD's declared actions only. A parent's hasMany `dependent` is a property of the
+      // model set (relationDeleteActions) and this table is built per model, so it is not here.
+      // The runtime table never emits DDL (the CLI does, from the set), so queries are unaffected.
+      // This is the one place it differs from the generated schema.generated.ts, which carries it.
       const refOpts: { onDelete?: FieldSpec['onDelete']; onUpdate?: FieldSpec['onUpdate'] } = {};
       if (spec.onDelete) refOpts.onDelete = spec.onDelete;
       if (spec.onUpdate) refOpts.onUpdate = spec.onUpdate;

package/src/external.ts

@@ -0,0 +1,119 @@
+/**
+ * An EXTERNAL foreign-key target: a table no model declares, named by its PostgreSQL identity.
+ *
+ * `field.uuid().references({ schema: 'auth', table: 'users', column: 'id' })` is how a model says
+ * "this column points into another system's table" (an auth provider's `auth.users`, a table a
+ * different service owns). Ratified rules:
+ *
+ *  - schema, table and column are all REQUIRED and are three separate identifiers. Nothing is
+ *    parsed for dots: an external FK crosses the governed boundary, so it says exactly where.
+ *  - A string target stays a MODEL name. Only this object form names a table.
+ *  - An object naming a table some model in the set declares is refused: use the model.
+ *  - It is FK state only. It is never a relation (no belongsTo/hasMany, no embedding).
+ *  - It compiles, diffs and fingerprints exactly like a model FK. Nothing downstream of the
+ *    compiler can tell the two apart, so a live FK nothing declares is still visible drift.
+ *
+ * The names are PostgreSQL names, taken verbatim (no snake_casing: there is no model field to
+ * derive them from). They reach DDL quoted, so a name is refused when quoting cannot carry it.
+ */
+
+import type { ModelDescriptor } from './model';
+
+/** A table no model declares: the composite `foreignKey(cols, { schema, table }, refColumns)` target. */
+export interface ExternalTableRef {
+  schema: string;
+  table: string;
+}
+
+/** A column of a table no model declares: the `.references({ schema, table, column })` target. */
+export interface ExternalColumnRef extends ExternalTableRef {
+  column: string;
+}
+
+/** NAMEDATALEN - 1 on a stock PostgreSQL build; a longer name is truncated with only a NOTICE. */
+const MAX_IDENTIFIER_BYTES = 63;
+
+/**
+ * Why a name cannot be an external identifier, or null when it can. The DDL quotes every part
+ * (`"auth"."users"`) without doubling quotes, and the FK IR carries `schema.table` as one dotted
+ * string, so a quote, a dot or a control character cannot be carried safely.
+ */
+export function externalIdentifierRefusal(name: unknown): string | null {
+  if (typeof name !== 'string') return `is ${name === null ? 'null' : typeof name}, not a string`;
+  if (name.length === 0) return 'is empty';
+  if (name.includes('"')) return 'holds a double quote';
+  // A line terminator or other control character: a name holding one could end a comment in
+  // generated source or forge a line in plan output and logs. No real table needs one.
+  if (/[\u0000-\u001f\u007f\u2028\u2029]/.test(name)) return 'holds a control character or line terminator';
+  if (name.includes('.')) return "holds a '.' (a name is one identifier; the schema is its own field)";
+  const bytes = new TextEncoder().encode(name).length;
+  if (bytes > MAX_IDENTIFIER_BYTES) return `is ${bytes} bytes (PostgreSQL identifiers are at most ${MAX_IDENTIFIER_BYTES})`;
+  return null;
+}
+
+/** `auth.users` — how every error and plan line names an external target. */
+export function externalTargetName(ref: ExternalTableRef): string {
+  return `${String(ref.schema)}.${String(ref.table)}`;
+}
+
+function readRef<K extends string>(target: object, keys: readonly K[], call: string): Record<K, string> {
+  const shown = externalTargetName(target as ExternalTableRef);
+  for (const key of Object.keys(target)) {
+    if (!(keys as readonly string[]).includes(key)) {
+      throw new Error(`${call} target ${shown}: unknown key '${key}' (expected ${keys.join(', ')})`);
+    }
+  }
+  const out = {} as Record<K, string>;
+  for (const key of keys) {
+    const value = (target as Record<string, unknown>)[key];
+    if (value === undefined) {
+      throw new Error(`${call} target ${shown}: ${key} is required (an external target names its ${keys.join(', ')}; there is no default)`);
+    }
+    const refusal = externalIdentifierRefusal(value);
+    if (refusal) throw new Error(`${call} target ${shown}: ${key} ${JSON.stringify(value)} ${refusal}`);
+    out[key] = value as string;
+  }
+  return out;
+}
+
+/** Validate and copy a `.references({ schema, table, column })` target. */
+export function externalColumnRef(target: object): ExternalColumnRef {
+  return Object.freeze(readRef(target, ['schema', 'table', 'column'] as const, 'references({ schema, table, column })'));
+}
+
+/** Validate and copy a composite `foreignKey(cols, { schema, table }, refColumns)` target and its columns. */
+export function externalTableRef(target: object, refColumns: readonly string[], call: string): ExternalTableRef {
+  const ref = readRef(target, ['schema', 'table'] as const, call);
+  for (const c of refColumns) {
+    const refusal = externalIdentifierRefusal(c);
+    if (refusal) throw new Error(`${call} target ${externalTargetName(ref)}: reference column ${JSON.stringify(c)} ${refusal}`);
+  }
+  return Object.freeze(ref);
+}
+
+/**
+ * Refuse an external target that a model in this set declares: the author must use the model.
+ * Compared on RESOLVED identities (the model's schema, default `public`, and its table) across
+ * the whole set. Called by linkModels and by every compile entry point that holds the set.
+ */
+export function assertExternalTargets(models: readonly ModelDescriptor[]): void {
+  const declared = new Map<string, ModelDescriptor>();
+  for (const m of models) declared.set(`${m.schema ?? 'public'}\u0000${m.table}`, m);
+  const owner = (m: ModelDescriptor): string => `${m.schema ?? 'public'}.${m.table}`;
+  const check = (m: ModelDescriptor, ref: ExternalTableRef, what: string): void => {
+    const hit = declared.get(`${ref.schema}\u0000${ref.table}`);
+    if (!hit) return;
+    throw new Error(
+      `model '${owner(m)}': ${what} references ${externalTargetName(ref)}, which model '${owner(hit)}' declares: `
+      + `use the model (.references(() => Model) or a model-name string), not the external { schema, table } form`,
+    );
+  };
+  for (const m of models) {
+    for (const [key, f] of Object.entries(m.fields)) {
+      if (f.spec.referencesExternal) check(m, f.spec.referencesExternal, `field '${key}'`);
+    }
+    for (const c of m.constraints) {
+      if (c.kind === 'foreignKey' && c.external) check(m, c.external, `foreignKey(${c.columns.join(', ')})`);
+    }
+  }
+}

package/src/field.ts

@@ -15,6 +15,7 @@ import type { RawSql } from './raw-sql';
 import { pgTypeRefusal } from './pg-type';
 import { assertConstraintName, assertFkValidate } from './constraints';
 import { referenceThunk } from './link';
+import { externalColumnRef, type ExternalColumnRef } from './external';
 
 export type FieldType =
   | 'text'
@@ -80,6 +81,13 @@ export interface FieldSpec {
   isDeprecated: boolean;
   /** `.references(() => Other)` — FK target, a model thunk. Used by relation/ownership work. */
   references?: () => unknown;
+  /**
+   * `.references({ schema, table, column })` — an FK to a table NO model declares (another
+   * system's `auth.users`). Set instead of {@link references}, never with it. FK state only: it is
+   * never a relation, so nothing that follows a model thunk ever sees it. It compiles, diffs and
+   * fingerprints exactly like a model FK. See external.ts.
+   */
+  referencesExternal?: ExternalColumnRef;
   /** `ON DELETE` action for the FK. Omitted (or `'no action'`) is the Postgres default. */
   onDelete?: ReferentialAction;
   /** `ON UPDATE` action for the FK. Omitted (or `'no action'`) is the Postgres default. */
@@ -231,8 +239,12 @@ export class FieldBuilder {
   }
 
   /**
-   * Declare a foreign key. The target is a table name or model thunk. Names are resolved
-   * by linkModels when the complete set is available. Optional
+   * Declare a foreign key. The target is a model thunk or a model NAME (a string is always a
+   * model name, resolved by linkModels when the complete set is available; one that names no
+   * model is an error, never a table). A table no model declares is named as an object:
+   * `.references({ schema: 'auth', table: 'users', column: 'id' })`, all three required, each a
+   * PostgreSQL name taken verbatim. That form is FK state only, never a relation, and is refused
+   * when a model in the set declares the table (use the model). Optional
    * `onDelete`/`onUpdate` referential actions are column-scoped, so they live here, not on
    * the table — `field.uuid().references(() => User, { onDelete: 'cascade' })`.
    *
@@ -242,8 +254,19 @@ export class FieldBuilder {
    * {@link FieldSpec.referencesValidate} for why a fifteen-year-old schema needs to be able
    * to say it.
    */
-  references(target: (() => unknown) | string, opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction; name?: string; validate?: boolean }): this {
-    this.spec.references = referenceThunk(target);
+  references(target: (() => unknown) | string | ExternalColumnRef, opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction; name?: string; validate?: boolean }): this {
+    // A second call REPLACES the target, as every other repeated modifier on this builder
+    // overwrites: each branch clears the other slot, so a field never holds both (the compiler
+    // would read one and relations or `via` the other).
+    if (typeof target === 'function' || typeof target === 'string') {
+      this.spec.references = referenceThunk(target);
+      delete this.spec.referencesExternal;
+    } else if (target !== null && typeof target === 'object') {
+      this.spec.referencesExternal = externalColumnRef(target);
+      delete this.spec.references;
+    } else {
+      throw new Error(`references(…): the target is ${target === null ? 'null' : typeof target}; pass a model thunk, a model name, or { schema, table, column }`);
+    }
     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');

package/src/index.ts

@@ -3,7 +3,7 @@
  * handler config. See docs/plans/v3-model-architecture.md.
  *
  * Ships the declaration surface (`defineModel`, `field`, `can`, `belongsTo`/
- * `hasMany`); `@everystack/cli` compiles models to migrations, RLS + grants, and
+ * `hasMany`/`hasOne`); `@everystack/cli` compiles models to migrations, RLS + grants, and
  * handler config (`deriveHandlerConfig`).
  */
 
@@ -14,8 +14,10 @@ export { canonicalColumnType, fieldFactoryCall, pgTypeRefusal } from './pg-type'
 
 export { parseQualified } from './qualified';
 export { linkModels, ModelLinkError } from './link';
+export { assertExternalTargets, externalTargetName, externalIdentifierRefusal } from './external';
+export type { ExternalTableRef, ExternalColumnRef } from './external';
 
-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';
@@ -25,11 +27,13 @@ export { can, isColumnAbility, isPublicReadAbility, isDeleteAbility, needsSoftDe
 export type { SoftDeleteFacts } from './can';
 export type { Ability, AbilityCondition, Action } from './can';
 
-export { belongsTo, hasMany } from './relations';
-export type { Relation } from './relations';
+export { belongsTo, hasMany, hasOne } from './relations';
+export type { Relation, BelongsToOptions, HasManyOptions, HasOneOptions, HasManyDependent, RelationOrder, RelationWhere } from './relations';
+export { relationDeleteActions } from './dependents';
+export type { DependentActions } from './dependents';
 
-export { defineModel, defineMaterializedTable, EXTRA_PRIVILEGES, DML_PRIVILEGES, TABLE_PRIVILEGES } from './model';
-export type { ModelDescriptor, ModelDefinition, ModelHooks, WrittenBy, ExtraPrivilege, TablePrivilege, DmlPrivilege, MaterializedTableMarker, MaterializedTableDefinition } from './model';
+export { defineModel, defineMaterializedTable, LIFECYCLE_COLUMNS, LIFECYCLE_OWNER_ROLE, EXTRA_PRIVILEGES, DML_PRIVILEGES, TABLE_PRIVILEGES } from './model';
+export type { ModelDescriptor, ModelDefinition, ModelHooks, DestroyContext, DestroyHook, WrittenBy, ExtraPrivilege, TablePrivilege, DmlPrivilege, MaterializedTableMarker, MaterializedTableDefinition } from './model';
 
 export { defineModule, moduleModels, moduleExtensions, moduleFunctionSql, moduleSequences, moduleDerived, moduleGovernedRoles } from './module';
 export type { Module, ModuleDefinition } from './module';

package/src/link.ts

@@ -1,5 +1,8 @@
 import type { ModelDescriptor } from './model';
 import { parseQualified } from './qualified';
+import { assertExternalTargets } from './external';
+import { relationDeleteActions } from './dependents';
+import { hasDisplayOptions, normalizeRelationDisplay } from './relation-display';
 
 /** A failed or conflicting name binding must never become a usable model. */
 export class ModelLinkError extends Error {
@@ -97,11 +100,14 @@ export function linkModels<T extends readonly ModelDescriptor[]>(models: T): T {
   // Resolve everything before changing descriptors, so a typo can be corrected and retried
   // without leaving earlier references bound to a different, incomplete set.
   const replacements: Array<() => void> = [];
+  // What each name reference resolves to in THIS set, before anything is bound.
+  const resolvedNames = new Map<unknown, ModelDescriptor>();
   for (const model of uniqueModels) {
     for (const [key, field] of Object.entries(model.fields)) {
       const target = field.spec.references;
       if (target && isNameReference(target)) {
         const resolved = resolve(target as NameReference<ModelDescriptor>, model, 'field', key);
+        resolvedNames.set(target, resolved);
         if (target.boundTarget) continue;
         const linked = Object.assign(() => resolved, {
           refName: target.refName, refLocation: target.refLocation, boundTarget: resolved,
@@ -113,6 +119,7 @@ export function linkModels<T extends readonly ModelDescriptor[]>(models: T): T {
       const target = relation.target;
       if (isNameReference(target)) {
         const resolved = resolve(target, model, 'relation', key);
+        resolvedNames.set(target, resolved);
         if (target.boundTarget) continue;
         const linked = Object.assign(() => resolved, {
           refName: target.refName, refLocation: target.refLocation, boundTarget: resolved,
@@ -121,6 +128,39 @@ export function linkModels<T extends readonly ModelDescriptor[]>(models: T): T {
       }
     }
   }
+  // An external `{ schema, table }` target naming a table this set models is refused: the
+  // author must use the model. Checked before anything is bound, like every error above.
+  try {
+    assertExternalTargets(uniqueModels);
+  } catch (err) {
+    throw new ModelLinkError(err instanceof Error ? err.message : String(err));
+  }
+  // hasMany `dependent` → the child FK's ON DELETE: checked here, before anything is bound, and
+  // never written into a spec (the compiler derives it per set). Only a relation that declares a
+  // dependent has its target (or its child's FK target) evaluated.
+  try {
+    relationDeleteActions(uniqueModels, (thunk) => resolvedNames.get(thunk) ?? thunk() as ModelDescriptor);
+  } catch (err) {
+    if (err instanceof ModelLinkError) throw err;
+    throw new ModelLinkError(err instanceof Error ? err.message : String(err));
+  }
+  // Display options (orderBy, where; every hasOne) name TARGET fields: checked here, before
+  // anything is bound, and the orderBy normalized once (the target's primary key appended).
+  // Only such a relation has its target evaluated. Display options never reach a dependent.
+  for (const model of uniqueModels) {
+    for (const [key, relation] of Object.entries(model.relations)) {
+      if (relation.kind === 'belongsTo' || !hasDisplayOptions(relation)) continue;
+      let orderBy: ReturnType<typeof normalizeRelationDisplay>;
+      try {
+        const target = resolvedNames.get(relation.target) ?? relation.target();
+        orderBy = normalizeRelationDisplay(modelName(model), key, relation, target);
+      } catch (err) {
+        if (err instanceof ModelLinkError) throw err;
+        throw new ModelLinkError(err instanceof Error ? err.message : String(err));
+      }
+      if (orderBy) replacements.push(() => { relation.orderBy = orderBy; });
+    }
+  }
   for (const replace of replacements) replace();
   return models;
 }