@substrat-run/contracts 0.143.0 → 0.144.0

package/dist/operations.js

@@ -26,7 +26,9 @@
  */
 import { LIST_PAGE_MAX } from './pagination.js';
 import { z } from 'zod';
-import { DERIVED_KINDS, primaryKeyOf, } from './model.js';
+import { entityStateName, entityStateOutput } from './entity-state.js';
+import { DERIVED_KINDS, primaryKeyOf, stampsOf, } from './model.js';
+import { acceptsNull, baseDefOf } from './zod-read.js';
 // ---------------------------------------------------------------------------
 // The composer.
 // ---------------------------------------------------------------------------
@@ -489,27 +491,6 @@ const DERIVATION_PLANS = new WeakMap();
 export function derivationPlanOf(operation) {
     return DERIVATION_PLANS.get(operation);
 }
-/**
- * A schema read structurally, through the wrappers that only change optionality: the zod def
- * underneath, and whether any wrapper on the way admits `null`.
- */
-function unwrapped(schema) {
-    let current = schema;
-    let nullable = false;
-    for (let depth = 0; depth < 8; depth++) {
-        const def = current?._zod?.def;
-        if (!def)
-            return { base: undefined, nullable };
-        if (def.type === 'nullable' || def.type === 'nullish')
-            nullable = true;
-        else if (def.type !== 'optional' && def.type !== 'readonly')
-            return { base: def, nullable };
-        current = def.innerType;
-    }
-    return { base: undefined, nullable };
-}
-const baseDefOf = (schema) => unwrapped(schema).base;
-const acceptsNull = (schema) => unwrapped(schema).nullable;
 /** The column kinds a derived write binds as they arrive: a JSON or boolean column needs encoding. */
 const DERIVED_WRITE_KINDS = new Set(['string', 'number', 'literal']);
 /** This module's entity whose `fields` the output IS, by identity — a projection is not the row. */
@@ -560,13 +541,16 @@ function inputFields(decl) {
 }
 /** Clauses every derived shape shares: no per-row walk, no per-field projection, no bin access. */
 function commonClause(decl, kind) {
-    if (decl.narrows !== undefined)
+    // The bin page's per-row check is `ctx.pageTrashed`'s own, so its `narrows` is part of its shape.
+    if (decl.narrows !== undefined && kind !== 'trashed') {
         return 'it narrows per row (`narrows`), which is a walk the handler composes';
+    }
     if (decl.gates !== undefined)
         return 'it gates fields (`gates`), a projection the handler applies';
     if (decl.inputOptional !== undefined)
         return 'it declares `inputOptional`';
-    if (decl.trashed !== undefined && !(kind === 'delete' && decl.trashed === 'purges')) {
+    const reachesBin = (kind === 'delete' && decl.trashed === 'purges') || (kind === 'restore' && decl.trashed === 'admits');
+    if (decl.trashed !== undefined && !reachesBin) {
         return `it declares \`trashed: '${String(decl.trashed)}'\` — reaching the bin is authored`;
     }
     return null;
@@ -614,6 +598,15 @@ function filterTypeIssue(decl, field, column, entity) {
     }
     return null;
 }
+/** One optional input as a declared filter of the page, or the clause it fails. */
+function optionalFilterOf(decl, field, filterable, entity) {
+    const column = snakeCaseField(field);
+    if (!filterable.has(column))
+        return `input field '${field}' is not a declared \`filterable\` column`;
+    if (inputDefaultIssue(decl.input?.shape[field]) !== null)
+        return `input field '${field}' has a default`;
+    return filterTypeIssue(decl, field, column, entity) ?? { field, column };
+}
 function listPlan(decl, entities) {
     const over = decl.paged?.over;
     if (over === undefined)
@@ -636,18 +629,13 @@ function listPlan(decl, entities) {
     const filterable = new Set(over.filterable ?? []);
     const filters = [];
     const { required, optional } = inputFields(decl);
+    let parent;
     if (permission.entity !== undefined) {
-        if (!(base.def.parents ?? []).includes(permission.entity)) {
-            return `its check narrows to '${permission.entity}', which is not a parent of '${name}'`;
-        }
-        const idFrom = permission.idFrom;
-        const column = snakeCaseField(idFrom);
-        // The filter is what scopes the page to the checked parent, so it must BE the link to that
-        // parent — a filter on any other column passes the check on one row and pages another set.
-        const link = `${snakeCaseField(permission.entity)}_id`;
-        if (column !== link) {
-            return `the parent's id '${idFrom}' filters column '${column}', which is not the link to '${permission.entity}' ('${link}')`;
-        }
+        const target = parentTarget(name, base.def, permission, entities, 'filters');
+        if (typeof target === 'string')
+            return target;
+        parent = target;
+        const { idFrom, column } = target;
         if (!required.includes(idFrom) || !filterable.has(column)) {
             return `the parent's id '${idFrom}' is not a required input filtering the declared \`filterable\` column '${column}'`;
         }
@@ -660,18 +648,67 @@ function listPlan(decl, entities) {
         if (field !== permission.idFrom)
             return `input field '${field}' is required, and only the parent's id may be`;
     }
+    let viewFrom;
     for (const field of optional) {
-        const column = snakeCaseField(field);
-        if (!filterable.has(column))
-            return `input field '${field}' is not a declared \`filterable\` column`;
-        if (inputDefaultIssue(decl.input?.shape[field]) !== null)
-            return `input field '${field}' has a default`;
-        const issue = filterTypeIssue(decl, field, column, base.def);
-        if (issue)
-            return issue;
-        filters.push({ field, column });
+        if (field === VIEW_FIELD && base.def.archive !== undefined) {
+            const issue = viewIssue(decl.input?.shape[field], filterable);
+            if (issue)
+                return issue;
+            viewFrom = field;
+            continue;
+        }
+        const filter = optionalFilterOf(decl, field, filterable, base.def);
+        if (typeof filter === 'string')
+            return filter;
+        filters.push(filter);
     }
-    return { kind: 'list', ...base.head, permission, filters, total: decl.paged?.total === true };
+    return {
+        kind: 'list',
+        ...base.head,
+        permission,
+        filters,
+        total: decl.paged?.total === true,
+        ...(parent ? { parent } : {}),
+        ...(viewFrom !== undefined ? { viewFrom } : {}),
+    };
+}
+/**
+ * The parent a check narrows to, for a page of its children or a child created under it (#2157).
+ * The input's id must fill the LINK column `<parent>_id` — a filter or a value on any other column
+ * passes the check on one row and reads or writes another.
+ */
+function parentTarget(name, def, permission, entities, verb) {
+    const parent = permission.entity;
+    if (!(def.parents ?? []).includes(parent))
+        return `its check narrows to '${parent}', which is not a parent of '${name}'`;
+    const idFrom = permission.idFrom;
+    const column = snakeCaseField(idFrom);
+    const link = `${snakeCaseField(parent)}_id`;
+    if (column !== link) {
+        return `the parent's id '${idFrom}' ${verb} column '${column}', which is not the link to '${parent}' ('${link}')`;
+    }
+    const base = derivableEntity(parent, entities);
+    if (typeof base === 'string')
+        return base;
+    return { entity: parent, table: base.head.table, primaryKey: base.head.primaryKey, idFrom, column };
+}
+/** The input field a derived page of an archivable entity reads its view from (#119). */
+const VIEW_FIELD = 'view';
+/** The views `ctx.page` serves; the bin is its own read (`trashed`). */
+const PAGE_VIEWS = entityStateName.exclude(['trashed']).options;
+/** Why `view` cannot be passed to `ctx.page` as it arrives, or `null`. */
+function viewIssue(schema, filterable) {
+    if (filterable.has(VIEW_FIELD)) {
+        return `'${VIEW_FIELD}' is both the archive view and a declared \`filterable\` column, so the input means two things`;
+    }
+    if (inputDefaultIssue(schema) !== null)
+        return `input field '${VIEW_FIELD}' has a default`;
+    const base = baseDefOf(schema);
+    const values = base?.type === 'enum' ? Object.values(base.entries ?? {}).map(String).sort() : [];
+    if (values.join() !== [...PAGE_VIEWS].sort().join()) {
+        return `input field '${VIEW_FIELD}' is not \`z.enum(['active', 'archived'])\`, the views a page serves`;
+    }
+    return null;
 }
 /** The clauses a derived write shares: narrowed to the row it writes, announcing it, by that row's id. */
 function writeTarget(decl, entities) {
@@ -714,29 +751,64 @@ function updatePlan(decl, entities) {
     if (optional.length === 0)
         return 'its input has no field to write';
     const columnShape = base.def.fields.shape;
+    const stamps = stampsOf(name, base.def);
     const fields = [];
     for (const field of optional) {
-        const column = snakeCaseField(field);
-        const columnSchema = columnShape[column];
-        if (columnSchema === undefined)
-            return `body field '${field}' is not a column of '${name}'`;
-        if (column === base.head.primaryKey)
-            return `body field '${field}' would rewrite the row's id`;
-        const fieldSchema = decl.input?.shape[field];
-        const kind = baseDefOf(columnSchema)?.type;
-        if (kind === 'enum') {
-            return `column '${column}' is an enum — a change of state is a lifecycle edge with its own operation`;
-        }
-        if (!kind || !DERIVED_WRITE_KINDS.has(kind))
-            return `column '${column}' is not a string or number column`;
-        if (baseDefOf(fieldSchema)?.type !== kind)
-            return `body field '${field}' is not the same type as column '${column}'`;
+        const target = writableColumn(decl, field, name, base.head.primaryKey, columnShape, stamps, UPDATE_WORDS);
+        if (typeof target === 'string')
+            return target;
+        const { column, columnSchema, fieldSchema } = target;
         if (acceptsNull(fieldSchema) && !acceptsNull(columnSchema)) {
             return `body field '${field}' accepts null, and column '${column}' cannot be cleared`;
         }
         fields.push({ field, column });
     }
-    return { kind: 'update', ...base.head, permission: target.permission, idFrom, fields, emit: emitOf(decl) };
+    return {
+        kind: 'update',
+        ...base.head,
+        permission: target.permission,
+        idFrom,
+        fields,
+        emit: emitOf(decl),
+    };
+}
+const UPDATE_WORDS = {
+    field: 'body field',
+    onId: "would rewrite the row's id",
+    onEnum: 'a change of state is a lifecycle edge with its own operation',
+};
+const CREATE_WORDS = {
+    field: 'input field',
+    onId: "would set the row's id, which a create mints",
+    onEnum: "a row's first state is its lifecycle's, and authored",
+};
+/**
+ * The column one input field of a derived write fills, by its snake_case name — or the clause it
+ * fails: no such column, the id, a stamp, an enum, a kind the write cannot bind as it arrives, or
+ * a field of another type. Whether it may be empty is the caller's rule.
+ */
+function writableColumn(decl, field, name, primaryKey, columnShape, stamps, words) {
+    const column = snakeCaseField(field);
+    const columnSchema = columnShape[column];
+    if (columnSchema === undefined)
+        return `${words.field} '${field}' is not a column of '${name}'`;
+    if (column === primaryKey)
+        return `${words.field} '${field}' ${words.onId}`;
+    if (stamps[column] !== undefined)
+        return `${words.field} '${field}' writes '${column}', which is stamped`;
+    const fieldSchema = decl.input?.shape[field];
+    const kind = baseDefOf(columnSchema)?.type;
+    if (kind === 'enum')
+        return `column '${column}' is an enum — ${words.onEnum}`;
+    if (!kind || !DERIVED_WRITE_KINDS.has(kind))
+        return `column '${column}' is not a string or number column`;
+    if (baseDefOf(fieldSchema)?.type !== kind)
+        return `${words.field} '${field}' is not the same type as column '${column}'`;
+    return { column, columnSchema, fieldSchema };
+}
+/** The declared stamps, in declared order. */
+function stampList(stamps) {
+    return Object.entries(stamps).map(([column, kind]) => ({ column, kind }));
 }
 function deletePlan(decl, entities) {
     if (decl.http?.method !== 'DELETE')
@@ -759,11 +831,200 @@ function deletePlan(decl, entities) {
     }
     return { kind: 'delete', ...base.head, permission: target.permission, idFrom, emit: emitOf(decl) };
 }
+/** A column a row may leave empty — what a derived create writes when no source names it. */
+const columnMayBeNull = (schema) => acceptsNull(schema) || isOptionalSchema(schema);
+function createPlan(decl, entities) {
+    if (decl.http?.method !== 'POST')
+        return 'it is not served as POST, the method that says it adds a row';
+    if (decl.paged !== undefined)
+        return 'it is paged';
+    if (decl.concurrency !== undefined)
+        return 'it declares `concurrency`, and a row that does not exist yet has no version';
+    const name = decl.emits?.entity;
+    if (typeof name !== 'string')
+        return 'it emits nothing, and a create announces the row it adds';
+    const base = derivableEntity(name, entities);
+    if (typeof base === 'string')
+        return base;
+    const { primaryKey } = base.head;
+    if (decl.output !== base.def.fields)
+        return `its output is not '${name}'s own \`fields\``;
+    if (decl.emits?.entityIdFrom !== primaryKey) {
+        return `its event takes its subject from '${String(decl.emits?.entityIdFrom)}', not the row's id '${primaryKey}'`;
+    }
+    const columnShape = base.def.fields.shape;
+    if (baseDefOf(columnShape[primaryKey])?.type !== 'string') {
+        return `'${name}'s id '${primaryKey}' is not a string column, so a minted id cannot fill it`;
+    }
+    const permission = plainPermission(decl.permission);
+    if (typeof permission === 'string')
+        return permission;
+    const { required, optional } = inputFields(decl);
+    let parent;
+    if (permission.entity !== undefined) {
+        const target = parentTarget(name, base.def, permission, entities, 'fills');
+        if (typeof target === 'string')
+            return target;
+        if (!required.includes(target.idFrom))
+            return `the parent's id '${target.idFrom}' is not a required input`;
+        if (baseDefOf(decl.input?.shape[target.idFrom])?.type !== baseDefOf(columnShape[target.column])?.type) {
+            return `input field '${target.idFrom}' is not the same type as link column '${target.column}'`;
+        }
+        parent = target;
+    }
+    const stamps = stampsOf(name, base.def);
+    // Every input field fills the column of its name — an input the row does not hold is one the
+    // handler does something else with.
+    const values = [];
+    for (const field of [...required, ...optional]) {
+        if (field === parent?.idFrom)
+            continue;
+        if (snakeCaseField(field) === parent?.column)
+            return `input field '${field}' writes the link column '${parent.column}'`;
+        const target = writableColumn(decl, field, name, primaryKey, columnShape, stamps, CREATE_WORDS);
+        if (typeof target === 'string')
+            return target;
+        const { column, columnSchema, fieldSchema } = target;
+        if ((optional.includes(field) || acceptsNull(fieldSchema)) && !columnMayBeNull(columnSchema)) {
+            return `input field '${field}' may be absent or null, and column '${column}' cannot be empty`;
+        }
+        values.push({ field, column });
+    }
+    const filled = new Set([primaryKey, ...(parent ? [parent.column] : []), ...Object.keys(stamps), ...values.map((v) => v.column)]);
+    for (const column of Object.keys(columnShape)) {
+        if (!filled.has(column) && !columnMayBeNull(columnShape[column])) {
+            return `column '${column}' is filled by nothing the model names — no input, stamp or parent link — and cannot be empty`;
+        }
+    }
+    const key = [...(base.def.key ?? [])];
+    const fromInput = new Set([...(parent ? [parent.column] : []), ...values.map((v) => v.column)]);
+    for (const column of key) {
+        if (!fromInput.has(column))
+            return `its natural key column '${column}' is not filled from the input, so no existing row can be matched by it`;
+    }
+    // A replay answers the row already holding the key. The check passed on the parent the caller
+    // named, so the key must pin that parent too, or the lookup answers another parent's row.
+    if (parent && key.length > 0 && !key.includes(parent.column)) {
+        return `its natural key does not include the link to '${parent.entity}' ('${parent.column}'), so a replay could answer another ${parent.entity}'s row`;
+    }
+    // A replay would also answer a row the kernel hides (#119, K-45): a binned one to a caller who
+    // may not see the bin, or an archived one the active view leaves out — and skipping hidden rows
+    // only moves the clash to the insert. What re-creating one means is the vertical's to decide.
+    const hides = [base.def.trash ? '`trash`' : null, base.def.archive ? '`archive`' : null].filter(Boolean);
+    if (key.length > 0 && hides.length > 0) {
+        return `'${name}' declares ${hides.join(' and ')} and a natural key, so a replay could answer a row the kernel hides — whether re-creating one restores it, unarchives it or refuses is the vertical's call, so its handler is written by hand`;
+    }
+    return {
+        kind: 'create',
+        ...base.head,
+        permission,
+        ...(parent ? { parent } : {}),
+        values,
+        stamps: stampList(stamps),
+        key,
+        emit: emitOf(decl),
+    };
+}
+/** The derived kinds that are one kernel move (#119, K-45), and which declaration gates each. */
+const MOVE_GATE = {
+    archive: 'archive',
+    unarchive: 'archive',
+    trash: 'trash',
+    restore: 'trash',
+};
+/**
+ * One kernel move: a POST of the id alone, narrowed to that row under the key the entity declares
+ * for it, answering `entityStateOutput` and declaring no event, since the kernel emits the move.
+ */
+function movePlan(kind) {
+    return (decl, entities) => {
+        if (decl.http?.method !== 'POST')
+            return 'it is not served as POST, the method a move of state is';
+        if (decl.paged !== undefined)
+            return 'it is paged';
+        if (decl.emits !== undefined)
+            return 'it declares `emits`, and the kernel announces the move itself';
+        if (decl.output !== entityStateOutput)
+            return 'its output is not `entityStateOutput`';
+        const permission = plainPermission(decl.permission);
+        if (typeof permission === 'string')
+            return permission;
+        if (permission.entity === undefined)
+            return 'its check is scope-wide, and a move is checked on the row it moves';
+        const name = permission.entity;
+        const base = derivableEntity(name, entities);
+        if (typeof base === 'string')
+            return base;
+        const gate = MOVE_GATE[kind];
+        const declared = base.def[gate]?.permission;
+        if (declared === undefined)
+            return `'${name}' declares no \`${gate}\``;
+        if (permission.key !== declared) {
+            return `its check is '${permission.key}', not the key '${name}' declares for its ${gate}, '${declared}'`;
+        }
+        const idFrom = permission.idFrom;
+        const { required, optional } = inputFields(decl);
+        if (required.length !== 1 || required[0] !== idFrom || optional.length !== 0)
+            return `its input is not the id '${idFrom}' alone`;
+        if (kind === 'restore' && decl.trashed !== 'admits') {
+            return "it does not declare `trashed: 'admits'`, and a restore is the move that reaches a binned row";
+        }
+        return { kind, ...base.head, permission: { key: declared, entity: name, idFrom }, idFrom };
+    };
+}
+/** The bin: `ctx.pageTrashed` over an entity that declares `trash`, which checks its key per row. */
+function trashedPlan(decl, entities) {
+    const over = decl.paged?.over;
+    if (over === undefined)
+        return 'it is not a kernel-composed page (`paged.over`)';
+    if (decl.emits !== undefined)
+        return 'it emits, and a read announces nothing';
+    if (decl.http?.method !== 'GET')
+        return 'it is not served as GET, the method that says it only reads';
+    if (decl.paged?.total !== undefined)
+        return 'it asks for a total, and a page of the bin carries none';
+    const name = over.entity;
+    if (decl.output !== entities[name]?.fields)
+        return `its output is not '${name}'s own \`fields\``;
+    const base = derivableEntity(name, entities);
+    if (typeof base === 'string')
+        return base;
+    const key = base.def.trash?.permission;
+    if (key === undefined)
+        return `'${name}' declares no \`trash\``;
+    // `ctx.pageTrashed` checks the trash key on every row: a leading check on top would deny the
+    // person whose key is narrowed to the rows they binned, and say nothing the walk does not.
+    if (decl.permission !== undefined)
+        return 'it declares a leading check, and the bin is checked row by row';
+    // `unchecked` says the operation checks nothing, which a bin walked under its key is not.
+    const narrows = decl.narrows;
+    if (narrows?.unchecked !== undefined || narrows?.checks?.length !== 1 || narrows.checks[0] !== key) {
+        return `it does not declare \`narrows\` checking exactly '${key}', the key the bin is walked under`;
+    }
+    const filterable = new Set(over.filterable ?? []);
+    const filters = [];
+    const { required, optional } = inputFields(decl);
+    if (required.length !== 0)
+        return `input field '${required[0]}' is required, and a page of the bin takes filters only`;
+    for (const field of optional) {
+        const filter = optionalFilterOf(decl, field, filterable, base.def);
+        if (typeof filter === 'string')
+            return filter;
+        filters.push(filter);
+    }
+    return { kind: 'trashed', ...base.head, permission: { key }, filters };
+}
 const PLANNERS = {
     get: getPlan,
     list: listPlan,
     update: updatePlan,
     delete: deletePlan,
+    create: createPlan,
+    archive: movePlan('archive'),
+    unarchive: movePlan('unarchive'),
+    trash: movePlan('trash'),
+    restore: movePlan('restore'),
+    trashed: trashedPlan,
 };
 /** The plan for one shape, or the clause the declaration fails — the shared clauses first. */
 function planFor(kind, decl, entities) {
@@ -772,9 +1033,10 @@ function planFor(kind, decl, entities) {
 /**
  * The shape the platform could derive this operation's handler as, read off its declaration and
  * the module's entities alone — `undefined` when it matches none of `DerivedKind`. Pure: this
- * classifies, and `defineOperations` is what refuses. At most one shape matches: a `get` is
- * served as GET and not paged, a `list` is paged, an `update` is a PATCH that emits, a `delete`
- * is a DELETE answering `{ id, deleted }`.
+ * classifies, and `defineOperations` is what refuses. The first shape that matches is answered:
+ * a `get` is served as GET and not paged, a `list` is paged, an `update` is a PATCH that emits, a
+ * `delete` is a DELETE answering `{ id, deleted }`, a `create` is a POST that emits. The moves are
+ * the exception (`derivedKindsOf`).
  */
 export function derivationOf(decl, entities) {
     for (const kind of DERIVED_KINDS) {
@@ -784,6 +1046,13 @@ export function derivationOf(decl, entities) {
     }
     return undefined;
 }
+/**
+ * Every shape a declaration matches. One, except for a move (#119): archive and unarchive declare
+ * the same shape, so a hand-written one is named as both and `derive` says which it is.
+ */
+function derivedKindsOf(decl, entities) {
+    return DERIVED_KINDS.filter((kind) => typeof planFor(kind, decl, entities) !== 'string');
+}
 /**
  * A handler the platform could write is either written by it or excused, by name (#1773).
  *
@@ -829,10 +1098,13 @@ function assertHandlersDeclared(operations, entities) {
         }
         if (authored !== undefined)
             continue;
-        throw new Error(`model: '${name}' is derivable from the model as \`${plan.kind}\` over '${plan.entity}', and declares neither ` +
+        const kinds = derivedKindsOf(decl, entities);
+        const named = kinds.map((k) => `\`${k}\``).join(' or ');
+        const derives = kinds.map((k) => `\`derive: '${k}'\``).join(' or ');
+        throw new Error(`model: '${name}' is derivable from the model as ${named} over '${plan.entity}', and declares neither ` +
             '`derive` nor `authored`.\n' +
             `  A hand-written ${plan.kind} restates its declaration, and each restatement drifts (#1773).\n` +
-            `  Remedy: declare \`derive: '${plan.kind}'\` and delete its handler, or declare ` +
+            `  Remedy: declare ${derives} and delete its handler, or declare ` +
             `\`authored: '<why the derived ${plan.kind} is wrong here>'\`.`);
     }
 }
@@ -1504,4 +1776,21 @@ export function defineEngineRoutes(operations) {
         return out;
     };
 }
+/**
+ * Declare an app's hand-handled routes (#2170).
+ *
+ * ```ts
+ * export const routes = defineRoutes({
+ *   'dashboard/list-findings': {
+ *     summary: "This team's findings, most recently seen first",
+ *     input: z.object({ status: findingStatus.optional() }),
+ *     output: z.object({ available: z.boolean(), entries: z.array(findingEntry) }),
+ *     http: { method: 'GET', path: '/findings' },
+ *   },
+ * });
+ * ```
+ */
+export function defineRoutes(routes) {
+    return routes;
+}
 //# sourceMappingURL=operations.js.map