@adminiumjs/manifest 0.3.0 → 0.3.2

package/dist/add-ons.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `addOns` — the add-ons an app needs, and the ones it works better with.
+ *
+ * ```json
+ * "addOns": {
+ *   "requires": [{ "key": "invoices", "range": ">=1.1.0",
+ *                  "reason": { "en-US": "Proposals, invoices and receipts are made by this add-on." } }],
+ *   "suggests": [{ "key": "holiday-calendars", "range": ">=1.1.0", "checked": true,
+ *                  "reason": { "en-US": "Marks public holidays as days off." } }],
+ *   "features": [{ "id": "capacity-holidays", "label": { "en-US": "Holidays in Capacity" },
+ *                  "requires": ["holiday-calendars"] }]
+ * }
+ * ```
+ *
+ * Installing the app installs (or connects) every add-on it `requires`,
+ * before its own tables; one that is missing and cannot be had refuses the
+ * install before anything is written, and an add-on an installed app
+ * requires cannot be removed. A `suggests` entry is offered with the app,
+ * ticked when `checked`. A `feature` names what stops working without its
+ * add-ons, so a page may say `"feature": "<id>"` and stay hidden until they
+ * are there.
+ *
+ * Every `range` is a semver range over the add-on's version (`>=1.1.0`,
+ * `^1.1.0`); the reasons and labels are in every language the app speaks,
+ * US English always among them.
+ */
+import { z } from 'zod';
+import { type ReferenceIssue } from './refs.js';
+export declare const addOnsSchema: z.ZodObject<{
+    requires: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        range: z.ZodString;
+        reason: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>>>;
+    suggests: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        range: z.ZodString;
+        reason: z.ZodRecord<z.ZodString, z.ZodString>;
+        checked: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    features: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodRecord<z.ZodString, z.ZodString>;
+        requires: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type AddOnNeeds = z.infer<typeof addOnsSchema>;
+/** The add-ons an app names at all: required first, then suggested. */
+export declare function namedAddOns(needs: AddOnNeeds | undefined): {
+    key: string;
+    need: 'requires' | 'suggests';
+}[];
+/** Whether the app requires this add-on (so it is always there when the app runs). */
+export declare function requiresAddOn(needs: AddOnNeeds | undefined, key: string): boolean;
+/** Everything wrong with an app's `addOns` and the pages that name a feature. */
+export declare function addOnNeedsIssues(m: {
+    key: string;
+    addOns?: AddOnNeeds | undefined;
+    pages?: readonly {
+        feature?: string | undefined;
+    }[] | undefined;
+}): ReferenceIssue[];
+//# sourceMappingURL=add-ons.d.ts.map

package/dist/add-ons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-ons.d.ts","sourceRoot":"","sources":["../src/add-ons.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAa9D,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;kBAkBd,CAAC;AACZ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAEtD,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;CAAE,EAAE,CAK3G;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjF;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAChC,KAAK,CAAC,EAAE,SAAS;QAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,EAAE,GAAG,SAAS,CAAC;CACjE,GAAG,cAAc,EAAE,CA6BnB"}

package/dist/add-ons.js

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * `addOns` — the add-ons an app needs, and the ones it works better with.
+ *
+ * ```json
+ * "addOns": {
+ *   "requires": [{ "key": "invoices", "range": ">=1.1.0",
+ *                  "reason": { "en-US": "Proposals, invoices and receipts are made by this add-on." } }],
+ *   "suggests": [{ "key": "holiday-calendars", "range": ">=1.1.0", "checked": true,
+ *                  "reason": { "en-US": "Marks public holidays as days off." } }],
+ *   "features": [{ "id": "capacity-holidays", "label": { "en-US": "Holidays in Capacity" },
+ *                  "requires": ["holiday-calendars"] }]
+ * }
+ * ```
+ *
+ * Installing the app installs (or connects) every add-on it `requires`,
+ * before its own tables; one that is missing and cannot be had refuses the
+ * install before anything is written, and an add-on an installed app
+ * requires cannot be removed. A `suggests` entry is offered with the app,
+ * ticked when `checked`. A `feature` names what stops working without its
+ * add-ons, so a page may say `"feature": "<id>"` and stay hidden until they
+ * are there.
+ *
+ * Every `range` is a semver range over the add-on's version (`>=1.1.0`,
+ * `^1.1.0`); the reasons and labels are in every language the app speaks,
+ * US English always among them.
+ */
+import { z } from 'zod';
+import { labelsSchema } from './refs.js';
+import { parseSemverRange } from './semver.js';
+const addOnKeySchema = z.string().regex(/^[a-z][a-z0-9-]{1,79}$/, 'an add-on key');
+const rangeSchema = z
+    .string()
+    .min(1)
+    .max(120)
+    .refine((range) => parseSemverRange(range) !== null, { message: 'a semver range such as ">=1.1.0" or "^1.1.0"' });
+const needSchema = z.object({ key: addOnKeySchema, range: rangeSchema, reason: labelsSchema }).strict();
+export const addOnsSchema = z
+    .object({
+    requires: z.array(needSchema).min(1).max(8).optional(),
+    suggests: z.array(needSchema.extend({ checked: z.boolean().optional() }).strict()).min(1).max(8).optional(),
+    features: z
+        .array(z
+        .object({
+        id: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/, 'a feature id is kebab-case'),
+        label: labelsSchema,
+        requires: z.array(addOnKeySchema).min(1).max(4),
+    })
+        .strict())
+        .min(1)
+        .max(16)
+        .optional(),
+})
+    .strict();
+/** The add-ons an app names at all: required first, then suggested. */
+export function namedAddOns(needs) {
+    return [
+        ...(needs?.requires ?? []).map((n) => ({ key: n.key, need: 'requires' })),
+        ...(needs?.suggests ?? []).map((n) => ({ key: n.key, need: 'suggests' })),
+    ];
+}
+/** Whether the app requires this add-on (so it is always there when the app runs). */
+export function requiresAddOn(needs, key) {
+    return (needs?.requires ?? []).some((n) => n.key === key);
+}
+/** Everything wrong with an app's `addOns` and the pages that name a feature. */
+export function addOnNeedsIssues(m) {
+    const out = [];
+    const needs = m.addOns;
+    const seen = new Map();
+    for (const list of ['requires', 'suggests']) {
+        (needs?.[list] ?? []).forEach((need, i) => {
+            const at = ['addOns', list, i, 'key'];
+            if (need.key === m.key)
+                out.push({ path: at, message: 'an app does not need itself' });
+            const earlier = seen.get(need.key);
+            if (earlier !== undefined)
+                out.push({ path: at, message: `"${need.key}" is already named in ${earlier}` });
+            seen.set(need.key, list);
+        });
+    }
+    const features = new Set();
+    (needs?.features ?? []).forEach((feature, f) => {
+        if (features.has(feature.id))
+            out.push({ path: ['addOns', 'features', f, 'id'], message: `"${feature.id}" is declared twice` });
+        features.add(feature.id);
+        feature.requires.forEach((key, k) => {
+            if (!seen.has(key)) {
+                out.push({ path: ['addOns', 'features', f, 'requires', k], message: `"${key}" is neither required nor suggested by the app` });
+            }
+        });
+    });
+    (m.pages ?? []).forEach((page, p) => {
+        if (page.feature !== undefined && !features.has(page.feature)) {
+            out.push({ path: ['pages', p, 'feature'], message: `"${page.feature}" is not one of the app's addOns.features` });
+        }
+    });
+    return out;
+}
+//# sourceMappingURL=add-ons.js.map

package/dist/add-ons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-ons.js","sourceRoot":"","sources":["../src/add-ons.ts"],"names":[],"mappings":"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"}

package/dist/documents.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Document profiles an app ships: which of its columns make a printed
+ * document (an invoice, a receipt, a statement), drawn by an add-on that
+ * renders documents.
+ *
+ * ```json
+ * "documents": [{
+ *   "kind": "receipt", "addOn": "invoices", "table": "sales",
+ *   "name": { "en-US": "Till receipt" },
+ *   "mapping": {
+ *     "number": { "column": "number" },
+ *     "customerName": { "via": "customer_id", "column": "name" },
+ *     "lines": { "collection": { "table": "sale_lines", "via": "sale_id", "orderBy": "position",
+ *                                "columns": { "description": "name", "qty": "qty", "amount": "amount" } } }
+ *   }
+ * }]
+ * ```
+ *
+ * A slot reads a column of the row, a column of a row a foreign key points at
+ * (`via`), or a list of child rows in order. A list may leave rows out by
+ * their own columns, the way a statement's sources do: `where` keeps only the
+ * rows whose column holds one of its values, and `unless` drops a row whose
+ * column is true or set (a voided line: `"unless": "voided"`). The slots
+ * themselves are the add-on's words; Adminium checks the columns here and the
+ * slots against the add-on when the profile is made at install. A profile is
+ * the app's: made with real table names when the app is installed, removed
+ * with it.
+ *
+ * A statement is a document over one row (a client) and a period: it lists
+ * the documents and payments that point at that row, so it names them
+ * instead of one child list.
+ */
+import { z } from 'zod';
+import { type ReferenceIssue, type TableIndex } from './refs.js';
+export declare const slotMappingSchema: z.ZodUnion<readonly [z.ZodObject<{
+    column: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    via: z.ZodString;
+    column: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    collection: z.ZodObject<{
+        table: z.ZodString;
+        via: z.ZodString;
+        orderBy: z.ZodOptional<z.ZodString>;
+        columns: z.ZodRecord<z.ZodString, z.ZodString>;
+        where: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        }, z.core.$strict>>;
+        unless: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>]>;
+export type SlotMapping = z.infer<typeof slotMappingSchema>;
+export declare const appDocumentSchema: z.ZodObject<{
+    kind: z.ZodString;
+    addOn: z.ZodString;
+    table: z.ZodString;
+    name: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+    mapping: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        column: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        via: z.ZodString;
+        column: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        collection: z.ZodObject<{
+            table: z.ZodString;
+            via: z.ZodString;
+            orderBy: z.ZodOptional<z.ZodString>;
+            columns: z.ZodRecord<z.ZodString, z.ZodString>;
+            where: z.ZodOptional<z.ZodObject<{
+                column: z.ZodString;
+                in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            }, z.core.$strict>>;
+            unless: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>]>>;
+    statement: z.ZodOptional<z.ZodObject<{
+        documents: z.ZodObject<{
+            table: z.ZodString;
+            via: z.ZodString;
+            date: z.ZodString;
+            amount: z.ZodString;
+            number: z.ZodOptional<z.ZodString>;
+            where: z.ZodOptional<z.ZodObject<{
+                column: z.ZodString;
+                in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            }, z.core.$strict>>;
+            unless: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        payments: z.ZodObject<{
+            table: z.ZodString;
+            via: z.ZodString;
+            date: z.ZodString;
+            amount: z.ZodString;
+            number: z.ZodOptional<z.ZodString>;
+            where: z.ZodOptional<z.ZodObject<{
+                column: z.ZodString;
+                in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            }, z.core.$strict>>;
+            unless: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    feature: z.ZodOptional<z.ZodString>;
+    requestValues: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type AppDocument = z.infer<typeof appDocumentSchema>;
+/** Every column a mapping names, against the manifest's tables. */
+export declare function mappingIssues(table: string, mapping: Readonly<Record<string, SlotMapping>>, index: TableIndex, at: (...rest: (string | number)[]) => (string | number)[]): ReferenceIssue[];
+/** Everything wrong with an app's `documents` against its tables and add-on needs. */
+export declare function appDocumentIssues(documents: readonly AppDocument[], ctx: {
+    index: TableIndex;
+    addOns: ReadonlySet<string>;
+    features: ReadonlySet<string>;
+}): ReferenceIssue[];
+//# sourceMappingURL=documents.d.ts.map

package/dist/documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../src/documents.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAA2B,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAO1F,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;oBAmB5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAgB5D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAkBnB,CAAC;AACZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,mEAAmE;AACnE,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,EAC9C,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GACxD,cAAc,EAAE,CA2BlB;AAED,sFAAsF;AACtF,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,GAAG,EAAE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAAE,GACrF,cAAc,EAAE,CAqClB"}

package/dist/documents.js

@@ -0,0 +1,171 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Document profiles an app ships: which of its columns make a printed
+ * document (an invoice, a receipt, a statement), drawn by an add-on that
+ * renders documents.
+ *
+ * ```json
+ * "documents": [{
+ *   "kind": "receipt", "addOn": "invoices", "table": "sales",
+ *   "name": { "en-US": "Till receipt" },
+ *   "mapping": {
+ *     "number": { "column": "number" },
+ *     "customerName": { "via": "customer_id", "column": "name" },
+ *     "lines": { "collection": { "table": "sale_lines", "via": "sale_id", "orderBy": "position",
+ *                                "columns": { "description": "name", "qty": "qty", "amount": "amount" } } }
+ *   }
+ * }]
+ * ```
+ *
+ * A slot reads a column of the row, a column of a row a foreign key points at
+ * (`via`), or a list of child rows in order. A list may leave rows out by
+ * their own columns, the way a statement's sources do: `where` keeps only the
+ * rows whose column holds one of its values, and `unless` drops a row whose
+ * column is true or set (a voided line: `"unless": "voided"`). The slots
+ * themselves are the add-on's words; Adminium checks the columns here and the
+ * slots against the add-on when the profile is made at install. A profile is
+ * the app's: made with real table names when the app is installed, removed
+ * with it.
+ *
+ * A statement is a document over one row (a client) and a period: it lists
+ * the documents and payments that point at that row, so it names them
+ * instead of one child list.
+ */
+import { z } from 'zod';
+import { refSchema, textOrLabels } from './refs.js';
+const slotId = z.string().regex(/^[A-Za-z][A-Za-z0-9_]*$/, 'a slot id');
+/** Only rows whose column holds one of the values (sent invoices, not drafts). */
+const whereSchema = z.object({ column: refSchema, in: z.array(z.union([z.string(), z.number(), z.boolean()])).min(1).max(16) }).strict();
+export const slotMappingSchema = z.union([
+    z.object({ column: refSchema }).strict(),
+    z.object({ via: refSchema, column: refSchema }).strict(),
+    z
+        .object({
+        collection: z
+            .object({
+            table: refSchema,
+            via: refSchema,
+            orderBy: refSchema.optional(),
+            columns: z.record(slotId, refSchema),
+            /** Only the child rows whose column holds one of the values. */
+            where: whereSchema.optional(),
+            /** A child row whose column is true (or set) is left out: a voided line. */
+            unless: refSchema.optional(),
+        })
+            .strict(),
+    })
+        .strict(),
+]);
+/** The rows a statement lists for its one row, and the columns it reads of them. */
+const statementSourceSchema = z
+    .object({
+    table: refSchema,
+    via: refSchema,
+    date: refSchema,
+    amount: refSchema,
+    number: refSchema.optional(),
+    where: whereSchema.optional(),
+    /** A row whose column is true (or set) is left out: a voided payment. */
+    unless: refSchema.optional(),
+})
+    .strict();
+export const appDocumentSchema = z
+    .object({
+    kind: z.string().regex(/^[a-z][a-z0-9-]*$/, 'a document kind'),
+    addOn: z.string().regex(/^[a-z][a-z0-9-]{1,79}$/, 'an add-on key'),
+    table: refSchema,
+    name: textOrLabels,
+    mapping: z.record(slotId, slotMappingSchema),
+    statement: z.object({ documents: statementSourceSchema, payments: statementSourceSchema }).strict().optional(),
+    /** The feature this document belongs to (see `addOns.features`). */
+    feature: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/).optional(),
+    /**
+     * The slots the app's own screen may fill when it asks for the document
+     * (a label sheet's `count`), and no others: a slot nothing maps, with no
+     * default, holding a number or a text. Anything a request sends for a slot
+     * not listed here is refused.
+     */
+    requestValues: z.array(slotId).min(1).max(8).optional(),
+})
+    .strict();
+/** Every column a mapping names, against the manifest's tables. */
+export function mappingIssues(table, mapping, index, at) {
+    const out = [];
+    for (const [slot, source] of Object.entries(mapping)) {
+        const here = (...rest) => at('mapping', slot, ...rest);
+        if ('collection' in source) {
+            const c = source.collection;
+            if (index.table(c.table) === undefined) {
+                out.push({ path: here('collection', 'table'), message: `"${c.table}" is not a table of this manifest` });
+                continue;
+            }
+            const via = index.column(c.table, c.via);
+            if (via?.type !== 'fk' || via.references !== table)
+                out.push({ path: here('collection', 'via'), message: `"${c.table}.${c.via}" does not point at "${table}"` });
+            for (const ref of [...Object.values(c.columns), ...[c.orderBy, c.where?.column, c.unless].filter((r) => r !== undefined)]) {
+                if (!index.has(c.table, ref))
+                    out.push({ path: here('collection'), message: `"${c.table}" has no column "${ref}"` });
+            }
+        }
+        else if ('via' in source) {
+            const via = index.column(table, source.via);
+            if (via?.type !== 'fk' || via.references === undefined) {
+                out.push({ path: here('via'), message: `"${source.via}" is not a foreign key of "${table}"` });
+            }
+            else if (!index.has(via.references, source.column)) {
+                out.push({ path: here('column'), message: `"${via.references}" has no column "${source.column}"` });
+            }
+        }
+        else if (!index.has(table, source.column)) {
+            out.push({ path: here('column'), message: `"${table}" has no column "${source.column}"` });
+        }
+    }
+    return out;
+}
+/** Everything wrong with an app's `documents` against its tables and add-on needs. */
+export function appDocumentIssues(documents, ctx) {
+    const out = [];
+    const kinds = new Set();
+    documents.forEach((doc, d) => {
+        const at = (...rest) => ['documents', d, ...rest];
+        const key = `${doc.table}|${doc.kind}`;
+        if (kinds.has(key))
+            out.push({ path: at('kind'), message: `"${doc.table}" already has a "${doc.kind}" document` });
+        kinds.add(key);
+        if (!ctx.addOns.has(doc.addOn))
+            out.push({ path: at('addOn'), message: `"${doc.addOn}" is neither required nor suggested by the app` });
+        if (doc.feature !== undefined && !ctx.features.has(doc.feature))
+            out.push({ path: at('feature'), message: `"${doc.feature}" is not one of the app's addOns.features` });
+        if (ctx.index.table(doc.table) === undefined) {
+            out.push({ path: at('table'), message: `"${doc.table}" is not a table of this app` });
+            return;
+        }
+        out.push(...mappingIssues(doc.table, doc.mapping, ctx.index, at));
+        (doc.requestValues ?? []).forEach((slot, n) => {
+            if (doc.requestValues.indexOf(slot) !== n)
+                out.push({ path: at('requestValues', n), message: `"${slot}" is listed twice` });
+            // A mapped slot prints the row; a value sent for it would print something the row does not say.
+            else if (doc.mapping[slot] !== undefined)
+                out.push({ path: at('requestValues', n), message: `"${slot}" is mapped, so a request may not fill it` });
+        });
+        if (doc.statement !== undefined) {
+            for (const part of ['documents', 'payments']) {
+                const s = doc.statement[part];
+                const here = (...rest) => at('statement', part, ...rest);
+                if (ctx.index.table(s.table) === undefined) {
+                    out.push({ path: here('table'), message: `"${s.table}" is not a table of this app` });
+                    continue;
+                }
+                const via = ctx.index.column(s.table, s.via);
+                if (via?.type !== 'fk' || via.references !== doc.table)
+                    out.push({ path: here('via'), message: `"${s.table}.${s.via}" does not point at "${doc.table}"` });
+                for (const ref of [s.date, s.amount, s.number, s.unless, s.where?.column]) {
+                    if (ref !== undefined && !ctx.index.has(s.table, ref))
+                        out.push({ path: here(), message: `"${s.table}" has no column "${ref}"` });
+                }
+            }
+        }
+    });
+    return out;
+}
+//# sourceMappingURL=documents.js.map

package/dist/documents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.js","sourceRoot":"","sources":["../src/documents.ts"],"names":[],"mappings":"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"}

package/dist/formula.d.ts

@@ -0,0 +1,124 @@
+/**
+ * `rules.formula` — a column Adminium works out from the other columns of the
+ * same row, on every write: a line's amount, a document's tax and total.
+ *
+ * ```json
+ * { "ref": "amount", "type": "decimal", "scale": "currency",
+ *   "rules": { "formula": { "max": [0, { "sub": [{ "mul": ["qty", "rate"] }, { "coalesce": ["discount", 0] }] }] } } }
+ * ```
+ *
+ * The grammar is small on purpose: numbers, the row's own columns, the four
+ * operations, `min`, `max`, `round`, `coalesce` and one `if`. Anything that
+ * reads another row is a `copy` or a `rollup`, which already know how to keep
+ * in step when that other row changes; a formula that could read across rows
+ * would need the same machinery again.
+ *
+ * THE ARITHMETIC IS EXACT. Every value becomes a fraction of two big
+ * integers, parsed from its decimal text (Postgres and MySQL hand a decimal
+ * back as `"12.5000"`, SQLite as the number `12.5`), and nothing goes through
+ * a float. Division stays exact; the result is rounded ONCE, half away from
+ * zero, to the column's scale. So `1 / 3 × 3` is exactly 1, and a total is the
+ * same on all three databases to the last minor unit.
+ *
+ * An empty column makes the result empty, unless `coalesce` says what to read
+ * instead: a draft line with no rate yet has no amount, not an amount of 0
+ * that looks like a price. Division by zero is empty too.
+ *
+ * Pure: a browser (an app's demo) evaluates the same formula the server does.
+ */
+import { z } from 'zod';
+import { type ColumnShape, type ReferenceIssue } from './refs.js';
+export type FormulaExpr = number | string | {
+    add: FormulaExpr[];
+} | {
+    sub: [FormulaExpr, FormulaExpr];
+} | {
+    mul: FormulaExpr[];
+} | {
+    div: [FormulaExpr, FormulaExpr];
+} | {
+    min: FormulaExpr[];
+} | {
+    max: FormulaExpr[];
+} | {
+    round: FormulaExpr | [FormulaExpr, number];
+} | {
+    coalesce: [FormulaExpr, FormulaExpr];
+} | {
+    if: [FormulaCondition, FormulaExpr, FormulaExpr];
+};
+export type FormulaCondition = {
+    eq: [string, string | number | boolean];
+} | {
+    neq: [string, string | number | boolean];
+} | {
+    gt: [FormulaExpr, FormulaExpr];
+} | {
+    gte: [FormulaExpr, FormulaExpr];
+} | {
+    lt: [FormulaExpr, FormulaExpr];
+} | {
+    lte: [FormulaExpr, FormulaExpr];
+} | {
+    isNull: string;
+} | {
+    and: FormulaCondition[];
+} | {
+    or: FormulaCondition[];
+};
+export declare const formulaExprSchema: z.ZodType<FormulaExpr>;
+export declare const formulaConditionSchema: z.ZodType<FormulaCondition>;
+/** How deep a formula may nest: deeper is a formula nobody can read back. */
+export declare const FORMULA_MAX_DEPTH = 8;
+/** Every column a formula reads, in the order it first names them. */
+export declare function formulaColumns(expr: FormulaExpr | FormulaCondition): string[];
+/**
+ * What is wrong with one column's formula against its table: a column it
+ * names that the table lacks, a column used in arithmetic that holds no
+ * number, a formula deeper than {@link FORMULA_MAX_DEPTH}, one that reads
+ * itself. Cycles across a table's formulas are {@link formulaCycle}'s.
+ */
+export declare function formulaIssues(expr: FormulaExpr, own: string, column: (ref: string) => ColumnShape | undefined): string[];
+/**
+ * The first cycle among a table's formula columns (`total` reads `tax`, which
+ * reads `total`), as the columns in order, or `null`. A cycle has no value to
+ * settle on, so it is refused before it is ever stored.
+ */
+export declare function formulaCycle(formulas: ReadonlyMap<string, FormulaExpr>): string[] | null;
+/**
+ * A table's formula columns in the order they can be worked out: each after
+ * every formula column it reads. Assumes no cycle (checked at validation).
+ */
+export declare function formulaOrder(formulas: ReadonlyMap<string, FormulaExpr>): string[];
+/** A fraction of two big integers; `d` is always positive. */
+interface Ratio {
+    n: bigint;
+    d: bigint;
+}
+/**
+ * A stored value as an exact fraction: the decimal text of a number (never a
+ * float product), a decimal string as a driver returns it, a bigint, or a
+ * boolean (1 / 0, as MySQL and SQLite store one). `null` for an empty value or
+ * text that is not a number.
+ */
+export declare function toRatio(value: unknown): Ratio | null;
+/** A fraction as decimal text with exactly `scale` places (`12.50`, `-3`, `0.125`). */
+export declare function ratioText(value: Ratio, scale: number): string;
+/**
+ * Work a formula out over a row, exactly: the result as decimal text at
+ * `scale` places, or `null` when an input it needs is empty or a divisor is
+ * zero. `row` holds the stored row with the new values over it.
+ */
+export declare function evaluateFormula(expr: FormulaExpr, row: Readonly<Record<string, unknown>>, scale: number): string | null;
+/** Whether a condition holds for the row; a comparison with an empty side does not. */
+export declare function holds(condition: FormulaCondition, row: Readonly<Record<string, unknown>>, scale: number): boolean;
+/** The decimals a currency is written with (ISO 4217): JPY 0, most 2, KWD 3. Unknown → 2. */
+export declare function currencyScale(code: string | null | undefined): number;
+/** For the checks in `schema.ts`: every issue of a table's formulas, cycles included. */
+export declare function tableFormulaIssues(columns: readonly (ColumnShape & {
+    rules?: {
+        formula?: FormulaExpr | undefined;
+    } | undefined;
+})[], at: (column: number, ...rest: (string | number)[]) => (string | number)[]): ReferenceIssue[];
+export {};
+//# sourceMappingURL=formula.d.ts.map

package/dist/formula.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formula.d.ts","sourceRoot":"","sources":["../src/formula.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAiB,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAKjF,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,MAAM,GACN;IAAE,GAAG,EAAE,WAAW,EAAE,CAAA;CAAE,GACtB;IAAE,GAAG,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAA;CAAE,GACnC;IAAE,GAAG,EAAE,WAAW,EAAE,CAAA;CAAE,GACtB;IAAE,GAAG,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAA;CAAE,GACnC;IAAE,GAAG,EAAE,WAAW,EAAE,CAAA;CAAE,GACtB;IAAE,GAAG,EAAE,WAAW,EAAE,CAAA;CAAE,GACtB;IAAE,KAAK,EAAE,WAAW,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,CAAA;CAAE,GAC9C;IAAE,QAAQ,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAA;CAAE,GACxC;IAAE,EAAE,EAAE,CAAC,gBAAgB,EAAE,WAAW,EAAE,WAAW,CAAC,CAAA;CAAE,CAAC;AAEzD,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;CAAE,GAC3C;IAAE,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;CAAE,GAC5C;IAAE,EAAE,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAA;CAAE,GAClC;IAAE,GAAG,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAA;CAAE,GACnC;IAAE,EAAE,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAA;CAAE,GAClC;IAAE,GAAG,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,GAAG,EAAE,gBAAgB,EAAE,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAC;AAI/B,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAgBpD,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAY9D,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,gBAAgB,GAAG,MAAM,EAAE,CAsB7E;AASD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,GAC/C,MAAM,EAAE,CAqBV;AAoBD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,MAAM,EAAE,GAAG,IAAI,CAuBxF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,MAAM,EAAE,CAWjF;AAID,8DAA8D;AAC9D,UAAU,KAAK;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAiBD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAuBpD;AAuBD,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAS7D;AAeD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGvH;AAqDD,uFAAuF;AACvF,wBAAgB,KAAK,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CA0BjH;AAED,6FAA6F;AAC7F,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAMrE;AAOD,yFAAyF;AACzF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG;IAAE,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;KAAE,GAAG,SAAS,CAAA;CAAE,CAAC,EAAE,EACjG,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GACxE,cAAc,EAAE,CAqBlB"}