@adminiumjs/manifest 0.3.0-rc.4 → 0.3.1

package/dist/documents.js

@@ -0,0 +1,148 @@
+// 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. 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');
+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),
+        })
+            .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(),
+    /** Only rows whose column holds one of the values (sent invoices, not drafts). */
+    where: z.object({ column: refSchema, in: z.array(z.union([z.string(), z.number(), z.boolean()])).min(1).max(16) }).strict().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(),
+})
+    .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 === undefined ? [] : [c.orderBy])]) {
+                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));
+        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":"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"}