@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/shared/refusal.js

@@ -0,0 +1,144 @@
+/*
+ * The error a request earns when the tool will not carry it out. Shared
+ * because the row-scope and scope-catalog rules refuse requests as well as
+ * the adapters, and every caller tells a refusal from a failure by this one
+ * class.
+ */
+/**
+ * A request an adapter will not carry out.
+ *
+ * Distinct from a database failure, and the distinction is the whole point:
+ * "that is not the whole primary key" and "the database is down" are both
+ * exceptions, and a server that cannot tell them apart answers both with a
+ * 500. The first is something the caller can fix by asking differently.
+ *
+ * Ordinary adapter guards run before a statement. Private scoped transactions
+ * also use this for stored-image checks: those failures poison the transaction
+ * and require rollback. The error class alone never proves a write outcome.
+ */
+export class Refusal extends Error {
+    /** The column names the message quotes, so a surface that calls them something else (an App's captions) can say them its way. Never values. */
+    columns;
+    /** `cause`: a database failure that kept the check from being made. The
+     * request is still refused — the boundary does not move — but an owner that
+     * answers a caller can tell "refused" from "could not answer". */
+    constructor(message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'Refusal';
+        if (options.columns?.length)
+            this.columns = [...new Set(options.columns)];
+    }
+}
+/* Why a refusal happened, kept for the trusted owner that has to diagnose it.
+   A caller hears one fixed sentence and must: a driver's error text names
+   columns, values and internal tables, and a clash on a hidden unique column
+   says a row exists. But the sentence alone, with the real error swallowed,
+   has cost App authors whole days — an UPDATE the database refused, a startup
+   that could not say which store, a row policy that "could not be loaded". So
+   the cause is recorded on the refusal and kept off `cause`, which would
+   travel with the error everywhere it is inspected or serialized:
+   symbol-keyed and non-enumerable, so `'cause' in error` stays false and JSON
+   ignores it. One mechanism for every refusal, tenant, command and row policy
+   alike; registered, so a second copy of this module in a mixed deployment
+   reads the same key. */
+const CAUSE = Symbol.for('mistri.refusalCause');
+/** Record why a refusal happened on the refusal itself, for the trusted reader
+ * only. Every opaque refusal takes its reason this way — a tenant denial, a
+ * row policy that did not load, a command the database would not take — so
+ * the one reader below can say it to the operator. A string is a sentence for
+ * that operator, written here and naming the rule, table or column. */
+export function recordRefusalCause(error, cause) {
+    if (cause !== undefined && !Object.hasOwn(error, CAUSE)) {
+        Object.defineProperty(error, CAUSE, { value: typeof cause === 'string' ? new Error(cause) : cause, enumerable: false });
+    }
+    return error;
+}
+/** The recorded reason behind a refusal, for a trusted diagnostic only. */
+export const refusalCause = (error) => error !== null && typeof error === 'object' && CAUSE in error ? error[CAUSE] : undefined;
+/**
+ * What the operator is told about a refusal: each reason under it, outermost
+ * first — a recorded cause before `cause`, since the recorded one is the
+ * refusal's own — as messages, never objects, because a driver error's object
+ * can carry connection detail a console should not. Repeats are said once:
+ * a refusal rethrown as the same sentence is one reason, not two.
+ */
+export function refusalReasons(error) {
+    const reasons = [];
+    const seen = new Set([error]);
+    const outer = error instanceof Error ? error.message : undefined;
+    for (let because = refusalCause(error) ?? error?.cause, depth = 0; because instanceof Error && !seen.has(because) && depth < 8; depth++) {
+        seen.add(because);
+        if (because.message && because.message !== outer && !reasons.includes(because.message))
+            reasons.push(because.message);
+        because = refusalCause(because) ?? because.cause;
+    }
+    return reasons;
+}
+/**
+ * The refusal's one line for a startup headline: the fixed sentence, then the
+ * reason behind it. The `because:` lines under it carry the whole chain, but a
+ * reader (or a log that keeps one line) stopped at "could not be loaded or is
+ * invalid" and went to bisect the module; the headline now says the cause.
+ */
+export function refusalHeadline(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const [cause] = refusalReasons(error);
+    return cause ? `${message} Cause: ${cause}` : message;
+}
+/** The `because:` lines under a refusalHeadline: the chain past the cause the headline says already, which
+    printed again beneath it read as two reasons. */
+export const refusalReasonsBelow = (error) => refusalReasons(error).slice(1);
+/**
+ * A startup failure as the operator's terminal says it: the headline, then
+ * each further reason on a `because:` line. Every startup print goes through
+ * this, so a refusal that recorded why (a tenant denial's `"fonts" is not a
+ * key this takes`) is never said as its fixed sentence alone. The terminal of
+ * the person who started the server only: never an HTTP answer.
+ */
+export function startupReport(error) {
+    return [
+        refusalHeadline(error),
+        ...refusalReasonsBelow(error).map((reason) => `  because: ${reason}`),
+        ...faultFrames(error).map((frame) => `  ${frame}`),
+    ].join('\n');
+}
+/* A TypeError, a ReferenceError or a RangeError is a fault in the code that read the App, not a refusal of what its
+   author wrote: its sentence ("Cannot read properties of undefined (reading 'realm')") names nothing to go and fix,
+   and was printed with its stack swallowed (a field report). Its first frames are said beneath it, the file and line
+   a fix starts from. A refusal, however deep, is said as its sentences alone. */
+const FAULTS = new Set(['TypeError', 'ReferenceError', 'RangeError']);
+/** Where an unexpected fault in `error` (or the chain under it) happened: its first stack frames, or none for a refusal.
+    Read by name, not `instanceof`: an App module's errors are another realm's. */
+export function faultFrames(error, most = 6) {
+    const seen = new Set();
+    for (let at = error, depth = 0; at !== null && typeof at === 'object' && !seen.has(at) && depth < 8; depth++) {
+        seen.add(at);
+        const { name, stack } = at;
+        if (typeof name === 'string' && FAULTS.has(name) && typeof stack === 'string')
+            return stack
+                .split('\n')
+                .filter((line) => /^\s+at /.test(line))
+                .slice(0, most)
+                .map((line) => line.trim());
+        at = refusalCause(at) ?? at.cause;
+    }
+    return [];
+}
+/* What a refused request's own caller may be told about why: a sentence
+   naming only what the request itself named (the table, the column, the
+   command) and the kind of rule that refused it — the role's grant, the row
+   policy, the database computing a column. Never a row it cannot see, a
+   value, a physical name or a driver's words: those stay recorded for the
+   operator (recordRefusalCause). Set where the refusal is decided, by the code
+   that knows which rule it was, and said in place of the fixed sentence at
+   the one place a request's failure becomes its answer (field report TR7:
+   "not available to this account" with the cause only on the terminal). */
+const SAID = Symbol.for('mistri.refusalSaid');
+/** Record the sentence this refusal's caller is told: see above. The first one recorded stands. */
+export function sayRefusal(error, sentence) {
+    if (sentence && !Object.hasOwn(error, SAID))
+        Object.defineProperty(error, SAID, { value: sentence, enumerable: false });
+    return error;
+}
+/** The sentence a refusal's caller may read about why, if the code that refused said one. */
+export const refusalSaid = (error) => error !== null && typeof error === 'object' && SAID in error ? String(error[SAID]) : undefined;

package/dist/shared/relatedCreate.d.ts

@@ -0,0 +1,30 @@
+import { type DatabaseSchema } from './schema.js';
+import type { RelatedCreate } from '../../schema/model.js';
+export declare function parseRelatedCreate(raw: unknown, at: string): RelatedCreate<string>;
+/** Whether a create says more than its label, so it cannot be written as the label alone. */
+export declare function createSaysMore(create: RelatedCreate<string>): boolean;
+/** Bind only a direct FK to the whole parent PK, never inferred query equalities.
+ * `filter` is the related list's own query; the values it pins fill the new row
+ * as defaults do, never as bindings. */
+export declare function relatedCreatePlan(schema: DatabaseSchema, baseId: string, fromId: string, path: string, create: RelatedCreate<string>, list?: {
+    filter?: string;
+}): {
+    error: string;
+    show?: undefined;
+    bindings?: undefined;
+    otherParents?: undefined;
+    defaults?: undefined;
+    fill?: undefined;
+} | {
+    error?: undefined;
+    show: string[];
+    bindings: {
+        column: string;
+        parent: string;
+    }[];
+    otherParents: string[];
+    defaults: {
+        [x: string]: string | number | boolean | import("@mistriwork/engine/schema/model.js").AutoValue<"me" | "now" | "today"> | null;
+    };
+    fill: Record<string, string>;
+};

package/dist/shared/relatedCreate.js

@@ -0,0 +1,162 @@
+import { authoredValue } from './autoValues.js';
+import { autoKey, isRequired } from './form.js';
+import { findTable, primaryKey } from './schema.js';
+import { hopName } from './view.js';
+import { parseQuery } from './query.js';
+const CREATE_KEYS = ['label', 'show', 'defaults', 'prefill'];
+/** Columns filled from the page's record, at most. */
+const MAX_FILL = 8;
+const COLUMN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// A tenant host hands its pages over as captured, null-prototype copies (evidence.ts), and those are plain too.
+const isPlain = (value) => !!value && typeof value === 'object' && !Array.isArray(value) && [null, Object.prototype].includes(Object.getPrototypeOf(value));
+export function parseRelatedCreate(raw, at) {
+    if (typeof raw === 'string')
+        raw = { label: raw };
+    if (!isPlain(raw))
+        throw new Error(`${at}: create must be an object.`);
+    const value = raw;
+    if (Object.keys(value).some((key) => !CREATE_KEYS.includes(key)))
+        throw new Error(`${at}: create accepts label, show, defaults and prefill.`);
+    if (typeof value.label !== 'string' || !value.label.trim())
+        throw new Error(`${at}: create needs a label.`);
+    if (value.show !== undefined && (!Array.isArray(value.show) || value.show.some((c) => typeof c !== 'string' || !c.trim())))
+        throw new Error(`${at}: create.show must contain column names.`);
+    let defaults;
+    if (value.defaults !== undefined) {
+        if (!isPlain(value.defaults))
+            throw new Error(`${at}: create.defaults is an object of column → value.`);
+        defaults = {};
+        for (const [column, authored] of Object.entries(value.defaults)) {
+            if (!COLUMN.test(column))
+                throw new Error(`${at}: create.defaults "${column}" is not a column name.`);
+            const v = authoredValue(authored, `${at}: create.defaults "${column}"`);
+            if (!(v === null || typeof v === 'string' || typeof v === 'boolean' || (typeof v === 'number' && Number.isFinite(v)))) {
+                throw new Error(`${at}: create.defaults "${column}" is a text, number, true/false, null, today, now or me.`);
+            }
+            defaults[column] = v;
+        }
+    }
+    let prefill;
+    if (value.prefill !== undefined) {
+        const pairs = isPlain(value.prefill) ? Object.entries(value.prefill) : [];
+        if (!pairs.length ||
+            pairs.length > MAX_FILL ||
+            pairs.some(([child, parent]) => !COLUMN.test(child) || typeof parent !== 'string' || !COLUMN.test(parent))) {
+            throw new Error(`${at}: create.prefill maps one to ${MAX_FILL} of the new row's columns to the record's: { patient_id: 'patient_id' }.`);
+        }
+        prefill = Object.fromEntries(pairs);
+    }
+    return {
+        label: value.label.trim(),
+        ...(value.show === undefined ? {} : { show: value.show.map((c) => c.trim()) }),
+        ...(defaults ? { defaults } : {}),
+        ...(prefill ? { prefill } : {}),
+    };
+}
+/** Whether a create says more than its label, so it cannot be written as the label alone. */
+export function createSaysMore(create) {
+    return create.show !== undefined || create.defaults !== undefined || create.prefill !== undefined;
+}
+/**
+ * What a filtered related list's query pins: its equalities (`status = open`,
+ * `kind in (visit)`), read by the query language's own parser over the child
+ * table. A row added from the list starts with them, so it is listed where it
+ * was added. An `or`, a range or a path pins nothing.
+ */
+function filterEqualities(schema, from, filter) {
+    if (!filter?.trim())
+        return {};
+    const parsed = parseQuery(`${from.id} ${filter}`, { schema });
+    const groups = parsed.query?.filter.groups;
+    if (parsed.errors.length || !groups || groups.length !== 1)
+        return {};
+    const pinned = {};
+    for (const condition of groups[0]) {
+        if (condition.column.includes('.') || !from.columns.some((c) => c.name === condition.column))
+            continue;
+        const value = condition.op === '='
+            ? condition.value
+            : condition.op === 'in' && Array.isArray(condition.value) && condition.value.length === 1
+                ? condition.value[0]
+                : undefined;
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+            pinned[condition.column] = value;
+    }
+    return pinned;
+}
+/** Bind only a direct FK to the whole parent PK, never inferred query equalities.
+ * `filter` is the related list's own query; the values it pins fill the new row
+ * as defaults do, never as bindings. */
+export function relatedCreatePlan(schema, baseId, fromId, path, create, list = {}) {
+    const base = findTable(schema, baseId);
+    const from = findTable(schema, fromId);
+    const candidates = schema.foreignKeys.filter((fk) => fk.from.table === fromId);
+    const fk = candidates.find((fk) => fk.name === path) ?? candidates.find((fk) => hopName(fk) === path);
+    /* A wrong `whose` is the usual mistake, so it is named for what it is —
+       not a column, or a column that points elsewhere — with the references
+       that would do, rather than as a rule about primary keys. */
+    if (base && from && !fk && !path.includes('.')) {
+        const toBase = candidates.filter((ref) => ref.to.table === baseId).map((ref) => `"${hopName(ref)}"`);
+        const could = toBase.length
+            ? ` Its references to ${base.name}: ${toBase.join(', ')}.`
+            : ` ${from.name} has no reference to ${base.name}.`;
+        return {
+            error: from.columns.some((c) => c.name === path)
+                ? `"${path}" is a column of ${from.name}, but not a reference to ${base.name}.${could}`
+                : `"${path}" is not a column of ${from.name}.${could}`,
+        };
+    }
+    if (base && fk && fk.to.table !== baseId) {
+        return {
+            error: `"${path}" refers to ${findTable(schema, fk.to.table)?.name ?? fk.to.table}, not to ${base.name}, so a row added here would not belong to this record.`,
+        };
+    }
+    if (!base ||
+        !from ||
+        from.isView ||
+        !fk ||
+        fk.to.columns.length !== primaryKey(base).length ||
+        !primaryKey(base).every((c) => fk.to.columns.includes(c))) {
+        return { error: 'Related creation needs a direct reference to the complete parent primary key.' };
+    }
+    const show = create.show ?? from.columns.map((c) => c.name);
+    if (show.some((name) => !from.columns.some((c) => c.name === name)))
+        return { error: 'Related creation names an unknown form column.' };
+    const unknownDefault = Object.keys(create.defaults ?? {}).find((name) => !from.columns.some((c) => c.name === name));
+    if (unknownDefault)
+        return { error: `Related creation defaults "${unknownDefault}", which is not a column of ${from.name}.` };
+    /* A filled column comes from the record: the child's column, the record's column. */
+    const fill = { ...(create.prefill ?? {}) };
+    for (const [child, parent] of Object.entries(fill)) {
+        if (!from.columns.some((c) => c.name === child))
+            return { error: `Related creation fills "${child}", which is not a column of ${from.name}.` };
+        if (!base.columns.some((c) => c.name === parent))
+            return { error: `Related creation fills "${child}" from "${parent}", which is not a column of ${base.name}.` };
+        if (fk.from.columns.includes(child))
+            return { error: `Related creation fills "${child}", the reference to ${base.name} it already binds.` };
+    }
+    const pinned = filterEqualities(schema, from, list.filter);
+    const given = new Set([...Object.keys(create.defaults ?? {}), ...Object.keys(fill), ...Object.keys(pinned)]);
+    const assigned = autoKey(from);
+    const hiddenRequired = from.columns.filter((c) => isRequired(c, assigned) && !show.includes(c.name) && !fk.from.columns.includes(c.name) && !given.has(c.name));
+    if (hiddenRequired.length)
+        return { error: `Related creation must show required columns: ${hiddenRequired.map((c) => c.name).join(', ')}.` };
+    /* A required reference to another record (a work order's bike, added from its mechanic): the record cannot say it,
+       so a New the list offers on its own would ask a whole other choice; one the author writes still may. */
+    const otherParents = schema.foreignKeys
+        .filter((ref) => ref !== fk && ref.from.table === fromId)
+        .flatMap((ref) => ref.from.columns)
+        .filter((name, index, all) => all.indexOf(name) === index && !fk.from.columns.includes(name) && !given.has(name))
+        .filter((name) => {
+        const column = from.columns.find((c) => c.name === name);
+        return column !== undefined && isRequired(column, assigned);
+    });
+    return {
+        show: show.filter((c) => !fk.from.columns.includes(c)),
+        bindings: fk.from.columns.map((column, i) => ({ column, parent: fk.to.columns[i] })),
+        otherParents,
+        // The list's own equalities win: a row added here is listed here.
+        defaults: { ...(create.defaults ?? {}), ...pinned },
+        fill,
+    };
+}