@everystack/model 0.4.22 → 0.4.23

package/src/relation-display.ts

@@ -0,0 +1,48 @@
+/**
+ * The link-time half of the relation display options: the checks and the orderBy normalization
+ * that need the resolved TARGET model. A leaf: it imports only types, so linkModels can use it
+ * without an import cycle through relations.ts (which imports referenceThunk from link.ts).
+ */
+
+import type { ModelDescriptor } from './model';
+import type { Relation, RelationOrder } from './relations';
+
+/** True when linkModels must evaluate this relation's target to normalize its display options. */
+export function hasDisplayOptions(rel: Relation): boolean {
+  return rel.kind === 'hasOne' || rel.orderBy !== undefined || rel.where !== undefined;
+}
+
+const nameOf = (m: ModelDescriptor): string => (!m.schema || m.schema === 'public' ? m.table : `${m.schema}.${m.table}`);
+
+/**
+ * The normalized orderBy of a hasMany or hasOne against its resolved TARGET, or undefined when
+ * there is none (a hasMany with no orderBy keeps today's order: none is added). Pure: linkModels
+ * writes the result, once every reference in the set has resolved.
+ *
+ * Every orderBy and where field must be a field of the target. The target's primary key is
+ * appended, ascending, for each key column the orderBy does not list, so the order is total. A
+ * hasOne with no orderBy is ordered by that key. Idempotent: a normalized orderBy lists the key.
+ */
+export function normalizeRelationDisplay(model: string, name: string, rel: Relation, target: ModelDescriptor): RelationOrder[] | undefined {
+  const at = `model '${model}': relation '${name}'`;
+  for (const key of Object.keys(rel.where ?? {})) {
+    if (!Object.prototype.hasOwnProperty.call(target.fields, key)) {
+      throw new Error(`${at}: where field '${key}' is not a field of model '${nameOf(target)}'`);
+    }
+  }
+  if (rel.orderBy === undefined && rel.kind !== 'hasOne') return undefined;
+  const declared = rel.orderBy ?? [];
+  for (const term of declared) {
+    if (!Object.prototype.hasOwnProperty.call(target.fields, term.field)) {
+      throw new Error(`${at}: orderBy field '${term.field}' is not a field of model '${nameOf(target)}'`);
+    }
+  }
+  if (target.primaryKey.length === 0) {
+    throw new Error(`${at}: model '${nameOf(target)}' has no primary key to break orderBy ties; declare one`);
+  }
+  const listed = new Set(declared.map((t) => t.field));
+  return [
+    ...declared.map((t) => ({ field: t.field, order: t.order })),
+    ...target.primaryKey.filter((k) => !listed.has(k)).map((k) => ({ field: k, order: 'asc' as const })),
+  ];
+}

package/src/relations.ts

@@ -4,16 +4,74 @@
  *
  *   belongsTo(() => Author, 'authorId')   // this.authorId → Author.<pk>
  *   hasMany(() => Comment, 'postId')      // this.<pk> → Comment.postId
+ *   hasMany(() => Comment, 'postId', { dependent: 'nullify' })   // delete a post → postId NULL
+ *   hasOne(() => Image, 'postId')         // the first Image whose postId is this.<pk>
  *
  * A table-name target avoids sibling imports; linkModels resolves it against the
  * complete set. Model thunks remain supported for forward references.
+ *
+ * The third argument is a string (the `references` key, as it always was) or an options object
+ * (the ratified F7 API). `dependent` is the parent's word about delete behaviour; it compiles to
+ * the ON DELETE of the CHILD's foreign key (see dependents.ts). `orderBy`, `limit` and `where`
+ * are DISPLAY ONLY: they emit no SQL and never narrow a dependent. Their shape is checked at
+ * defineModel; their field names are TARGET fields, so linkModels checks them and normalizes the
+ * orderBy once (relation-display.ts): the target's primary key is appended as the tie-breaker.
  */
 
 import type { ModelDescriptor } from './model';
 import { referenceThunk } from './link';
 
+/** What deleting a parent row does to its children, through the child's foreign key. */
+export type HasManyDependent = 'restrict' | 'nullify' | 'cascade';
+
+/** One ordering term of a relation's display order. */
+export interface RelationOrder {
+  field: string;
+  order: 'asc' | 'desc';
+}
+
+/** An equality filter on the related rows: field → value. */
+export type RelationWhere = Record<string, string | number | boolean | null>;
+
+export interface BelongsToOptions {
+  /** The key on the target, when it is not the target's primary key. */
+  references?: string;
+}
+
+export interface HasManyOptions {
+  /** The key on this table, when it is not this table's primary key. */
+  references?: string;
+  /**
+   * What a delete of this row does to the target rows, through the target's foreign key on
+   * `column`: `'restrict'` → ON DELETE RESTRICT, `'nullify'` → ON DELETE SET NULL, `'cascade'` →
+   * ON DELETE CASCADE (Rails `delete_all`: the database removes the children and runs none of
+   * their hooks). The target field must declare `.references()` to this model; a dependent never
+   * creates a foreign key.
+   */
+  dependent?: HasManyDependent;
+  /**
+   * Display order: fields of the target. linkModels appends the target's primary key as the
+   * tie-breaker. Without it the order is unchanged (none is added).
+   */
+  orderBy?: RelationOrder[];
+  /** Display limit: a positive integer. */
+  limit?: number;
+  /** Display filter: equality on target fields; `null` means IS NULL. Not access control. */
+  where?: RelationWhere;
+}
+
+/** hasOne is one row: no `limit`, and no `dependent` in v1 (declare it on a hasMany). */
+export interface HasOneOptions {
+  /** The key on this table, when it is not this table's primary key. */
+  references?: string;
+  /** Which row: target fields, then the target's primary key. Default: the primary key ascending. */
+  orderBy?: RelationOrder[];
+  /** Display filter: equality on target fields; `null` means IS NULL. Not access control. */
+  where?: RelationWhere;
+}
+
 export interface Relation {
-  kind: 'belongsTo' | 'hasMany';
+  kind: 'belongsTo' | 'hasMany' | 'hasOne';
   /** Thunk to the related model (forward-reference safe). */
   target: () => ModelDescriptor;
   /**
@@ -28,22 +86,166 @@ export interface Relation {
    * - hasMany:   overrides RelationConfig.from (default: this table's pk)
    */
   references?: string;
+  /** hasMany only. Present only when declared. */
+  dependent?: HasManyDependent;
+  /**
+   * Present only when declared, or on a hasOne. After linkModels it is normalized: it ends with
+   * every primary-key column of the target (a hasOne with none declared is the key ascending).
+   */
+  orderBy?: RelationOrder[];
+  limit?: number;
+  where?: RelationWhere;
+}
+
+type Kind = Relation['kind'];
+
+const OPTION_KEYS: Record<Kind, readonly string[]> = {
+  belongsTo: ['references'],
+  hasMany: ['references', 'dependent', 'orderBy', 'limit', 'where'],
+  hasOne: ['references', 'orderBy', 'where'],
+};
+
+/**
+ * Build a descriptor. A string or absent third argument yields exactly the legacy shape
+ * (`references` always present as a key), so an existing model's descriptor is unchanged. An
+ * options object adds a key only for an option it declares.
+ */
+function relation(kind: Kind, target: (() => ModelDescriptor) | string, column: string, opts: unknown): Relation {
+  const call = `${kind}(…, '${column}')`;
+  if (opts === undefined || typeof opts === 'string') {
+    return { kind, target: referenceThunk(target), column, references: opts };
+  }
+  if (opts === null || typeof opts !== 'object' || Array.isArray(opts)) {
+    throw new Error(`${call}: the third argument is ${opts === null ? 'null' : Array.isArray(opts) ? 'an array' : typeof opts}; pass a references string or an options object`);
+  }
+  const allowed = OPTION_KEYS[kind];
+  for (const key of Object.keys(opts)) {
+    if (allowed.includes(key)) continue;
+    if (kind === 'hasOne' && key === 'dependent') {
+      throw new Error(`${call}: hasOne takes no dependent; declare dependent on a hasMany over the same column`);
+    }
+    if (kind === 'hasOne' && key === 'limit') throw new Error(`${call}: hasOne takes no limit: it is one row`);
+    const hint = key === 'dependent' ? "; dependent is declared on the parent's hasMany" : '';
+    throw new Error(`${call}: unknown option '${key}' (expected ${allowed.join(', ')})${hint}`);
+  }
+  const o = opts as HasManyOptions;
+  if (o.references !== undefined && typeof o.references !== 'string') {
+    throw new Error(`${call}: references must be a string`);
+  }
+  const out: Relation = { kind, target: referenceThunk(target), column, references: o.references };
+  if (o.dependent !== undefined) out.dependent = o.dependent;
+  // Copied, so a later edit to the caller's array or object changes nothing. Shapes are checked
+  // at defineModel (assertRelationShape); a malformed value is kept as given for that message.
+  if (o.orderBy !== undefined) {
+    out.orderBy = Array.isArray(o.orderBy)
+      ? o.orderBy.map((t) => (t !== null && typeof t === 'object' && !Array.isArray(t) ? { ...t } : t))
+      : o.orderBy;
+  }
+  if (o.limit !== undefined) out.limit = o.limit;
+  if (o.where !== undefined) {
+    out.where = o.where !== null && typeof o.where === 'object' && !Array.isArray(o.where) ? { ...o.where } : o.where;
+  }
+  return out;
 }
 
 /** Many-to-one: this row points at one target row via `column`. */
 export function belongsTo(
   target: (() => ModelDescriptor) | string,
   column: string,
-  references?: string,
+  opts?: string | BelongsToOptions,
 ): Relation {
-  return { kind: 'belongsTo', target: referenceThunk(target), column, references };
+  return relation('belongsTo', target, column, opts);
 }
 
 /** One-to-many: target rows point back at this row via `column`. */
 export function hasMany(
   target: (() => ModelDescriptor) | string,
   column: string,
-  references?: string,
+  opts?: string | HasManyOptions,
+): Relation {
+  return relation('hasMany', target, column, opts);
+}
+
+/**
+ * One-to-one from the parent side: the first target row pointing back via `column`, in `orderBy`
+ * (default: the target's primary key ascending). Display only: it compiles no SQL.
+ */
+export function hasOne(
+  target: (() => ModelDescriptor) | string,
+  column: string,
+  opts?: HasOneOptions,
 ): Relation {
-  return { kind: 'hasMany', target: referenceThunk(target), column, references };
+  return relation('hasOne', target, column, opts);
+}
+
+/**
+ * The declaration rules that need no other model, checked by defineModel: an option or kind that
+ * is not implemented yet is refused by name, never silently ignored.
+ */
+export function assertRelationShape(model: string, name: string, rel: Relation): void {
+  const at = `model '${model}': relation '${name}'`;
+  if (rel.kind !== 'belongsTo' && rel.kind !== 'hasMany' && rel.kind !== 'hasOne') {
+    throw new Error(`${at}: unknown relation kind '${String(rel.kind)}' (expected belongsTo, hasMany or hasOne)`);
+  }
+  if (rel.kind === 'belongsTo') {
+    for (const key of ['orderBy', 'limit', 'where'] as const) {
+      if (rel[key] !== undefined) throw new Error(`${at}: ${key} is a hasMany or hasOne option; belongsTo takes none`);
+    }
+  }
+  if (rel.kind === 'hasOne' && rel.limit !== undefined) throw new Error(`${at}: limit is a hasMany option; hasOne is one row`);
+  assertDisplayShape(at, rel);
+  if (rel.dependent === undefined) return;
+  if (rel.kind !== 'hasMany') throw new Error(`${at}: dependent is a hasMany option; ${rel.kind} takes none`);
+  if (rel.dependent !== 'restrict' && rel.dependent !== 'nullify' && rel.dependent !== 'cascade') {
+    throw new Error(`${at}: dependent '${String(rel.dependent)}' is not a dependent value (expected 'restrict', 'nullify' or 'cascade')`);
+  }
+}
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** A value as an error message shows it. */
+const shown = (v: unknown): string => {
+  if (v === undefined || typeof v === 'number') return String(v);
+  if (typeof v === 'string') return `'${v}'`;
+  try { return JSON.stringify(v) ?? String(v); } catch { return String(v); }
+};
+
+/**
+ * The display options' shape, checked at defineModel (no other model needed). Their field names
+ * name TARGET fields, so `normalizeRelationDisplay` (relation-display.ts) checks those once the target is known.
+ */
+function assertDisplayShape(at: string, rel: Relation): void {
+  if (rel.orderBy !== undefined) {
+    const orderBy: unknown = rel.orderBy;
+    if (!Array.isArray(orderBy) || orderBy.length === 0) throw new Error(`${at}: orderBy must be a non-empty array of { field, order }`);
+    const seen = new Set<string>();
+    orderBy.forEach((term: unknown, i) => {
+      if (!isPlainObject(term) || typeof term.field !== 'string' || term.field === ''
+        || Object.keys(term).some((k) => k !== 'field' && k !== 'order')) {
+        throw new Error(`${at}: orderBy[${i}] must be { field: string, order: 'asc' | 'desc' }`);
+      }
+      if (term.order !== 'asc' && term.order !== 'desc') {
+        throw new Error(`${at}: orderBy[${i}].order is ${shown(term.order)}; expected 'asc' or 'desc'`);
+      }
+      if (seen.has(term.field)) throw new Error(`${at}: orderBy lists field '${term.field}' twice`);
+      seen.add(term.field);
+    });
+  }
+  if (rel.limit !== undefined) {
+    const limit: unknown = rel.limit;
+    if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1) {
+      throw new Error(`${at}: limit must be a positive integer, got ${shown(limit)}`);
+    }
+  }
+  if (rel.where !== undefined) {
+    const where: unknown = rel.where;
+    if (!isPlainObject(where) || Object.keys(where).length === 0) {
+      throw new Error(`${at}: where must be a non-empty object of field → value`);
+    }
+    for (const [key, value] of Object.entries(where)) {
+      const ok = value === null || typeof value === 'string' || typeof value === 'boolean'
+        || (typeof value === 'number' && Number.isFinite(value));
+      if (!ok) throw new Error(`${at}: where '${key}' must be a string, a finite number, a boolean or null, got ${shown(value)}`);
+    }
+  }
 }

package/src/wire.ts

@@ -45,8 +45,9 @@
  * accept risks wrong ownership or a wrong derived object on a production database.
  *
  * v1 — the first version. Shapes as they stood when the guard was introduced.
+ * v2 — ProvisionWirePayload gains `lifecycleRole` (provision the reserved lifecycle role).
  */
-export const MODEL_WIRE_CONTRACT = 1;
+export const MODEL_WIRE_CONTRACT = 2;
 
 /**
  * Every Model-derived wire payload carries this. The server refuses a payload whose `modelContract`
@@ -101,6 +102,8 @@ export interface Adoptee {
 export interface ProvisionWirePayload extends ModelWireEnvelope {
   /** The declared schema set, ordered and `public`-trailing — set as the ROLE default search_path. */
   searchPath?: string[];
+  /** The Models declare a `lifecycle: true` model: provision the reserved role everystack_lifecycle. */
+  lifecycleRole?: boolean;
   /** Accepted by the action's payload type; convergence itself runs as db:converge-ownership. */
   declaredOwners?: DeclaredOwner[];
   declaredObjects?: Adoptee[];