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

package/dist/shared/definedValues.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Definition rows read, and values judged by them (definedFields.ts says what
+ * a definition is). Pure, and shared: the server judges a stored row with
+ * `definedBreaks` (server/app/appValidation.ts) and the record page and New
+ * form, loaded on demand, draw and convert with the same words, so the two
+ * cannot disagree about what "a number" or "one of the choices" is.
+ *
+ * Apart from definedFields.ts because a module a first-page file imports is
+ * in the first page whole: the query language and the App's declaration read
+ * that one, and none of this is needed before a defined field is drawn.
+ */
+import type { TableMeta } from './schema.js';
+import { type DefinedField } from './definedFields.js';
+/** The definitions table's columns to read: the needed, the optional it has, and `per`. */
+export declare function definitionColumns(from: Pick<TableMeta, 'columns'>, per?: string): string[];
+/**
+ * The condition that picks a record's definitions, as the structured filter
+ * every read takes: those whose `per` is the record's, and those with none.
+ * Without `per`, every row.
+ */
+export declare function definitionFilter(per: string | undefined, value: unknown): {
+    groups: ({
+        column: string;
+        op: '=';
+        value: string | number | boolean;
+    } | {
+        column: string;
+        op: 'isNull';
+    })[][];
+} | undefined;
+/**
+ * Definition rows as fields, in their order: by `position`, then key. A row
+ * that cannot be read is left out. Where a scoped row and an unscoped one
+ * share a key, the scoped one (it says more about this record) wins.
+ */
+export declare function readDefinitions(rows: readonly Readonly<Record<string, unknown>>[], per?: string): DefinedField[];
+/** The column's object: as PostgreSQL returns it, or JSON text as SQLite holds it. Undefined where it is not an object. */
+export declare function definedObject(raw: unknown): Record<string, unknown> | undefined;
+/** What a value fails: a required one missing, a value of the wrong kind, a choice outside the list, or a key no definition names. */
+type DefinedBreak = 'required' | 'number' | 'date' | 'datetime' | 'bool' | 'choice' | 'text' | 'unknown';
+/**
+ * Every break in an object against its fields, by key. `extras` also refuses
+ * a key no field names — said when the column itself was written, so a key a
+ * removed definition left behind never blocks an edit of something else.
+ */
+export declare function definedBreaks(fields: readonly DefinedField[], object: Readonly<Record<string, unknown>>, options: {
+    extras: boolean;
+}): {
+    key: string;
+    reason: DefinedBreak;
+}[];
+/** What the server says of a break: a fixed sentence, never a value, a label or rule text. */
+export declare const DEFINED_REASONS: Readonly<Record<DefinedBreak, string>>;
+/**
+ * A field's value from what a form control holds — text for a box, true or
+ * false for a switch, a list for a checklist. Undefined is empty: the key is
+ * left out of the object. A box that does not read as its type is kept as
+ * typed, for the server to refuse by name.
+ */
+export declare function definedFromInput(field: DefinedField, input: unknown): unknown;
+/** The object with one field's value set from its control: an empty value removes the key. */
+export declare function withDefined(object: Readonly<Record<string, unknown>>, field: DefinedField, input: unknown): Record<string, unknown>;
+export {};

package/dist/shared/definedValues.js

@@ -0,0 +1,184 @@
+import { DEFINED_KEY, DEFINED_TYPES, NEEDED, OPTIONAL } from './definedFields.js';
+/** The definitions table's columns to read: the needed, the optional it has, and `per`. */
+export function definitionColumns(from, per) {
+    const has = (name) => from.columns.some((column) => column.name === name);
+    return [...NEEDED, ...OPTIONAL.filter(has), ...(per && has(per) ? [per] : [])];
+}
+/**
+ * The condition that picks a record's definitions, as the structured filter
+ * every read takes: those whose `per` is the record's, and those with none.
+ * Without `per`, every row.
+ */
+export function definitionFilter(per, value) {
+    if (!per)
+        return undefined;
+    const scoped = typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+    return {
+        groups: [...(scoped && value !== '' ? [[{ column: per, op: '=', value }]] : []), [{ column: per, op: 'isNull' }]],
+    };
+}
+const yes = (value) => value === true || value === 1 || value === '1' || value === 'true' || value === 't';
+/**
+ * Definition rows as fields, in their order: by `position`, then key. A row
+ * that cannot be read is left out. Where a scoped row and an unscoped one
+ * share a key, the scoped one (it says more about this record) wins.
+ */
+export function readDefinitions(rows, per) {
+    const read = rows.flatMap((row) => {
+        const key = typeof row.key === 'string' ? row.key.trim() : '';
+        const type = typeof row.type === 'string' ? row.type.trim() : undefined;
+        if (!DEFINED_KEY.test(key) || !type || !DEFINED_TYPES.includes(type))
+            return [];
+        const label = typeof row.label === 'string' && row.label.trim() ? row.label.trim() : key;
+        const options = typeof row.options === 'string'
+            ? [
+                ...new Set(row.options
+                    .split(/\r?\n/)
+                    .map((line) => line.trim())
+                    .filter(Boolean)),
+            ]
+            : [];
+        const position = typeof row.position === 'number' ? row.position : Number(row.position);
+        const field = {
+            key,
+            label,
+            type,
+            options,
+            required: yes(row.required),
+            position: Number.isFinite(position) && row.position !== null && row.position !== '' ? position : Number.MAX_SAFE_INTEGER,
+            scoped: Boolean(per) && row[per] !== null && row[per] !== undefined && row[per] !== '',
+        };
+        if (typeof row.help === 'string' && row.help.trim())
+            field.help = row.help.trim();
+        return [field];
+    });
+    const byKey = new Map();
+    for (const field of read) {
+        const kept = byKey.get(field.key);
+        if (!kept || (field.scoped && !kept.scoped))
+            byKey.set(field.key, field);
+    }
+    return [...byKey.values()]
+        .sort((a, b) => a.position - b.position || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+        .map(({ position: _position, scoped: _scoped, ...field }) => field);
+}
+/** The column's object: as PostgreSQL returns it, or JSON text as SQLite holds it. Undefined where it is not an object. */
+export function definedObject(raw) {
+    if (raw === null || raw === undefined || raw === '')
+        return {};
+    let value = raw;
+    if (typeof raw === 'string') {
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const DATETIME = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,6})?)?(?:Z|[+-]\d{2}:?\d{2})?$/;
+/** The most characters one text value holds: a field, not a document. */
+const TEXT_MOST = 10000;
+const realDate = (text) => {
+    const date = new Date(`${text.slice(0, 10)}T00:00:00Z`);
+    return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === text.slice(0, 10);
+};
+/** Whether a value is empty: absent, null, an empty string or an empty list. */
+const definedEmpty = (value) => value === undefined || value === null || (typeof value === 'string' && !value.trim()) || (Array.isArray(value) && !value.length);
+/** What one field's value breaks, or undefined. */
+function definedBreak(field, value) {
+    if (definedEmpty(value))
+        return field.required ? 'required' : undefined;
+    switch (field.type) {
+        case 'number':
+        case 'money':
+            return typeof value === 'number' && Number.isFinite(value) ? undefined : 'number';
+        case 'bool':
+            return typeof value === 'boolean' ? undefined : 'bool';
+        case 'date':
+            return typeof value === 'string' && DATE.test(value) && realDate(value) ? undefined : 'date';
+        case 'datetime':
+            return typeof value === 'string' && DATETIME.test(value) && realDate(value) ? undefined : 'datetime';
+        case 'choice':
+            return typeof value === 'string' && field.options.includes(value) ? undefined : 'choice';
+        case 'choices':
+            return Array.isArray(value) &&
+                value.every((item) => typeof item === 'string' && field.options.includes(item)) &&
+                new Set(value).size === value.length
+                ? undefined
+                : 'choice';
+        default:
+            return typeof value === 'string' && value.length <= TEXT_MOST ? undefined : 'text';
+    }
+}
+/**
+ * Every break in an object against its fields, by key. `extras` also refuses
+ * a key no field names — said when the column itself was written, so a key a
+ * removed definition left behind never blocks an edit of something else.
+ */
+export function definedBreaks(fields, object, options) {
+    const breaks = fields.flatMap((field) => {
+        const reason = definedBreak(field, object[field.key]);
+        return reason ? [{ key: field.key, reason }] : [];
+    });
+    if (options.extras) {
+        const known = new Set(fields.map((field) => field.key));
+        for (const key of Object.keys(object))
+            if (!known.has(key))
+                breaks.push({ key, reason: 'unknown' });
+    }
+    return breaks;
+}
+/** What the server says of a break: a fixed sentence, never a value, a label or rule text. */
+export const DEFINED_REASONS = Object.freeze({
+    required: 'This field is required.',
+    number: 'Enter a number.',
+    date: 'Enter a date.',
+    datetime: 'Enter a date and time.',
+    bool: 'Choose yes or no.',
+    choice: 'Choose from the list.',
+    text: 'Enter text, at most 10,000 characters.',
+    unknown: 'This is not one of the fields this record has.',
+});
+/**
+ * A field's value from what a form control holds — text for a box, true or
+ * false for a switch, a list for a checklist. Undefined is empty: the key is
+ * left out of the object. A box that does not read as its type is kept as
+ * typed, for the server to refuse by name.
+ */
+export function definedFromInput(field, input) {
+    if (definedEmpty(input))
+        return undefined;
+    // A list, or a box's text with one choice per comma.
+    if (field.type === 'choices') {
+        const chosen = (Array.isArray(input) ? input.map(String) : String(input).split(',')).map((item) => item.trim()).filter(Boolean);
+        return chosen.length ? [...new Set(chosen)] : undefined;
+    }
+    // A switch, or a yes/no list's `1` and `0` (the platform's flag controls).
+    if (field.type === 'bool')
+        return typeof input === 'boolean'
+            ? input
+            : input === 'true' || input === '1'
+                ? true
+                : input === 'false' || input === '0'
+                    ? false
+                    : String(input);
+    const text = String(input).trim();
+    if (field.type === 'number' || field.type === 'money') {
+        const n = Number(text.replace(/[,\s$]/g, ''));
+        return Number.isFinite(n) ? n : text;
+    }
+    return field.type === 'textarea' ? String(input) : text;
+}
+/** The object with one field's value set from its control: an empty value removes the key. */
+export function withDefined(object, field, input) {
+    const next = { ...object };
+    const value = definedFromInput(field, input);
+    if (value === undefined)
+        delete next[field.key];
+    else
+        next[field.key] = value;
+    return next;
+}

package/dist/shared/displayDefaults.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The conventions an App applies without being told: how a column is drawn
+ * when its name, type or vocabulary says what it holds. A `price` is money, a
+ * `due_on` is said from today, an `email` is a link, a CHECK vocabulary of
+ * plain words wears tones by what the words mean, a machine's states wear
+ * tones by where they stand, a person's name has an initials disc. The
+ * scaffold used to write each of these out; now the platform infers them at
+ * runtime, `mistri check --defaults` prints every one per resource, and a
+ * rule the App writes that only restates one is a `restated` warning.
+ *
+ * What the App writes wins, concern by concern: a declared `format` (or a
+ * unit, a bar) replaces the inferred figure, a declared `tone` or `colors` the
+ * inferred tones, declared `values` the inferred words, a declared avatar or
+ * mark the inferred disc. An empty rule (`display: { value: {} }`) keeps the
+ * column exactly as stored.
+ *
+ * Pure over one table's catalog entry, so the server's payload, `check` and
+ * the scaffold read one rule.
+ */
+import { type ColumnMeta, type DatabaseSchema, type TableMeta } from './schema.js';
+import type { AppDisplayRule } from './servedApp.js';
+import { type DisplayTone } from './model.js';
+/** A machine as the conventions read it: its column, its states in order and its verbs. An App's machine
+    (appMachine.ts) says more; this is the part a tone or a stamp is read from. */
+interface DisplayMachine {
+    column: string;
+    since?: string;
+    states: readonly {
+        name: string;
+        final?: boolean;
+    }[];
+    edges: readonly {
+        verb: string;
+        from: string;
+        to: readonly string[];
+        fixed?: {
+            set: Record<string, unknown>;
+        };
+    }[];
+}
+/** What the conventions read of an App's declared resources: their captions, record label, display rules,
+    machine and New form defaults. The App's own definition (appModel.ts) holds them, among much else. */
+interface DeclaredResources {
+    resources?: Readonly<Record<string, {
+        labels?: Record<string, string>;
+        recordLabel?: string | false;
+        display?: Record<string, AppDisplayRule>;
+        machine?: DisplayMachine;
+        form?: {
+            defaults?: unknown;
+        };
+    }>>;
+    ui?: unknown;
+}
+export declare const MONEY: RegExp;
+export declare const UNITS: Array<[RegExp, string]>;
+/** Tones for a short vocabulary, or nothing: a map that colours nothing says nothing. */
+export declare function vocabularyTones(allowed: readonly string[]): Record<string, DisplayTone> | undefined;
+/**
+ * A machine's tones, where the App gives none: a final state is neutral (it is
+ * over, however it ended); the open state furthest along that hands the record
+ * to a final one (`ready` before `collected`) is good, the work done; a state
+ * whose word says it waits (`waiting_parts`, `on_hold`) warns, one whose word
+ * says it went wrong is bad, and the rest are neutral or, by their word, info.
+ */
+export declare function machineTones(machine: Pick<DisplayMachine, 'states' | 'edges'>): Record<string, DisplayTone>;
+/** A figure that is money: named like money on a number column, or typed as money. */
+export declare function isMoneyColumn(column: ColumnMeta): boolean;
+/** One inferred rule and the reason it is inferred, in words `check --defaults` prints. */
+interface InferredRule {
+    rule: AppDisplayRule;
+    why: string;
+    /** False where the browser already reads the convention off the name (a year, an email's link): the rule is
+        printed and a restatement warned, but nothing is served, so the two readings cannot drift. */
+    served?: false;
+}
+/** What the conventions are read with: the table's machine, the catalog its rollups reach, and the rules the App
+    declares on any table (a figure made of money is counted as that money is). */
+interface InferOptions {
+    machine?: DisplayMachine;
+    schema?: DatabaseSchema;
+    declared?: (table: TableMeta) => Readonly<Record<string, AppDisplayRule>> | undefined;
+}
+/** The App's declared display rules looked up by table, as `InferOptions.declared` reads them. */
+export declare function declaredDisplayOf(app: DeclaredResources, schema: DatabaseSchema): (table: TableMeta) => Readonly<Record<string, AppDisplayRule>> | undefined;
+/**
+ * Every rule the conventions give one table's columns, keyed by column. A
+ * reference, a key and a column whose type says nothing are left alone.
+ */
+export declare function inferredDisplay(table: TableMeta, opts?: InferOptions): Record<string, InferredRule>;
+/** Rows that are people, by the table's head noun. */
+export declare function isPeople(table: Pick<TableMeta, 'name'>): boolean;
+/**
+ * A resource's display rules as they are drawn: each column's declared rule
+ * over the conventions it leaves standing, and a rule for every column the
+ * conventions dress that the App did not mention. `served` keeps only what the
+ * server sends (the browser reads a year and a link off the name itself).
+ */
+export declare function effectiveDisplay(declared: Readonly<Record<string, AppDisplayRule>> | undefined, table: TableMeta, opts?: InferOptions & {
+    served?: boolean;
+}): Record<string, AppDisplayRule>;
+/** A declared rule, or part of one, that says what the platform would: a deletion. */
+export interface RestatedRule {
+    resource: string;
+    /** The keys from the anchor written in the source down to the object holding `keys`: `['display', 'price']`,
+        `['defaults']`, `['set']`, `['labels']`, `['display', 'kind', 'values']`; empty for the resource's own key. */
+    at: string[];
+    /** The keys there to delete. */
+    keys: string[];
+    /** The object at `at` as the App declares it: what the source must say there for the deletion to be made. */
+    held?: Record<string, unknown>;
+    /** The whole rule or holder goes: nothing else is left in it. */
+    whole: boolean;
+    /** The warning: what is restated, where, and why the platform says it already. */
+    warning: string;
+}
+/**
+ * Every declared value the platform derives, so deleting it changes nothing:
+ * a display rule or concern of one the conventions give, a caption the screens
+ * say anyway, a record label that is the label column, a `number` format beside
+ * a unit, the App's own currency, a word a vocabulary says by itself, a form
+ * default that is the schema's DEFAULT, a verb's stamp its state writes on
+ * entry. `check` warns on each (`restated`) and `check --design --fix` deletes
+ * exactly these, so the two never disagree.
+ */
+export declare function restatedDefaults(app: DeclaredResources, schema: DatabaseSchema): RestatedRule[];
+/** What `check --defaults` prints: each declared resource's inferred rules, and whether the App's own rule wins. */
+export declare function inferredReport(app: DeclaredResources, schema: DatabaseSchema): Array<{
+    resource: string;
+    column: string;
+    rule: AppDisplayRule;
+    why: string;
+    overridden: boolean;
+}>;
+export {};