@graview/core 0.1.27 → 0.1.29

package/dist/import/mapping.js

@@ -0,0 +1,182 @@
+import { fieldOf } from "../document/field-spec.js";
+import { nameKey } from "../labels.js";
+import { article, fieldWords, humanizeField, labelOf, nounOf, pluralOf } from "../schema/define-node.js";
+import { edgeWords } from "../schema/value-words.js";
+/** A mapping that names something the kind has not got. Thrown before any row is read: it is the caller's to fix, not the sheet's. */
+export class ImportMappingError extends Error {
+    problems;
+    constructor(problems) {
+        super(problems.join(" "));
+        this.problems = problems;
+        this.name = "ImportMappingError";
+    }
+}
+const schemaOf = (from) => ("schema" in from && !("definitions" in from) ? from.schema : from);
+/** The relations declared toward `kind` by other kinds (and by itself), by name. */
+function incoming(schema, kind) {
+    const found = new Map();
+    for (const definition of schema.definitions) {
+        for (const [name, decl] of Object.entries(definition.edges)) {
+            if (decl.to !== "*" && !decl.to.includes(kind))
+                continue;
+            const list = found.get(name) ?? [];
+            list.push({ from: definition.kind, decl });
+            found.set(name, list);
+        }
+    }
+    return found;
+}
+/** The kind's field as an import reads it: its document spec, or a word when a document has no type for it. */
+export function fieldSpecFor(definition, field) {
+    const shape = definition.fields.shape ?? {};
+    if (!Object.hasOwn(shape, field))
+        return undefined;
+    const read = fieldOf(shape[field]);
+    const optional = shape[field].safeParse?.(undefined).success ?? false;
+    const spec = "spec" in read ? read.spec : { type: "string", ...(optional ? {} : { required: true }) };
+    return { spec, schema: shape[field] };
+}
+/** Reads a mapping against the kind's declaration; a target it has not got is an `ImportMappingError`. */
+export function readMapping(schema, kind, mapping, 
+/** The fields the importer's sight keeps from it (Roadmap f-field-sight): to the importer, fields the kind does not have. */
+kept) {
+    const definition = schema.tryDefinition(kind);
+    if (!definition)
+        throw new ImportMappingError([`This app has no kind called “${kind}”.`]);
+    const noun = nounOf(definition, kind);
+    const edges = definition.edges;
+    const toward = incoming(schema, kind);
+    const columns = [];
+    const problems = [];
+    for (const [column, target] of Object.entries(mapping)) {
+        if (target === null || target === undefined)
+            continue;
+        const name = typeof target === "string" ? target : "field" in target ? target.field : target.relation;
+        const wantsField = typeof target === "string" || "field" in target;
+        const direction = typeof target === "object" && target !== null && "relation" in target ? target.direction : undefined;
+        if (wantsField) {
+            const field = kept?.(name) ? undefined : fieldSpecFor(definition, name);
+            if (field) {
+                columns.push({ column, as: "field", field: name, ...field });
+                continue;
+            }
+            if (typeof target !== "string") {
+                problems.push(`The ${column} column goes to “${name}”, which ${withNoun(noun)} has no field called.`);
+                continue;
+            }
+        }
+        if (direction !== "in" && Object.hasOwn(edges, name)) {
+            const decl = edges[name];
+            columns.push({ column, as: "relation", relation: name, direction: "out", kinds: decl.to === "*" ? [...schema.kinds] : [...decl.to], one: decl.cardinality === "one" });
+            continue;
+        }
+        const far = direction === "out" ? undefined : toward.get(name);
+        if (far && far.length > 0) {
+            columns.push({ column, as: "relation", relation: name, direction: "in", kinds: [...new Set(far.map((one) => one.from))], one: far.some((one) => one.decl.cardinality === "one") });
+            continue;
+        }
+        problems.push(`The ${column} column goes to “${name}”, which is neither a field of ${withNoun(noun)} nor a relation it has.`);
+    }
+    if (problems.length > 0)
+        throw new ImportMappingError(problems);
+    return columns;
+}
+const withNoun = (noun) => `${article(noun)} ${noun}`;
+/** A header's words for comparing: case, accents, punctuation and a plural "s" aside. */
+function key(text) {
+    return nameKey(humanizeField(text))
+        .replace(/[^\p{L}\p{N} ]+/gu, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+const singular = (text) => text.replace(/(ies)$/, "y").replace(/(?<=[^s])s$/, "");
+/**
+ * A MAPPING PROPOSED FROM THE HEADER ROW (FR-177), for the seat or a
+ * builder to offer and a person to correct. A header matches a field by
+ * its name, its label or its name spoken ("Booked on" for `bookedOn`), a
+ * plural aside; a relation by its name, its words from either end, or the
+ * noun or plural of the kind at its far end ("Event" for a link to an
+ * event). A header that starts with the kind's own noun is read without it
+ * ("Vendor name" is the name). Each field or relation is matched once, by
+ * the first header that names it; what nothing answers to is `unmatched`.
+ */
+export function proposeMapping(declaration, kind, header) {
+    const schema = schemaOf(declaration);
+    const definition = schema.tryDefinition(kind);
+    if (!definition)
+        throw new ImportMappingError([`This app has no kind called “${kind}”.`]);
+    const noun = nounOf(definition, kind);
+    const shape = definition.fields.shape ?? {};
+    const candidates = [];
+    const add = (target, said, id, words) => {
+        const keys = new Set();
+        for (const word of words) {
+            if (!word)
+                continue;
+            keys.add(key(word));
+            keys.add(singular(key(word)));
+        }
+        candidates.push({ target, said, keys, id });
+    };
+    for (const field of Object.keys(shape)) {
+        const words = fieldWords(definition, field);
+        const extra = field === "label" || field === "name" || field === "title" ? ["name", "title", noun] : [];
+        add({ field }, `the field ${words}`, `field:${field}`, [field, words, ...extra]);
+    }
+    for (const [name, decl] of Object.entries(definition.edges)) {
+        const kinds = decl.to === "*" ? [] : decl.to;
+        const far = kinds.flatMap((one) => [one, nounOf(schema.tryDefinition(one), one), pluralOf(schema, one)]);
+        add({ relation: name }, `the relation “${edgeWords(schema, kind, name, "out")}”`, `out:${name}`, [name, decl.description, ...far]);
+    }
+    for (const [name, list] of incoming(schema, kind)) {
+        if (Object.hasOwn(definition.edges, name))
+            continue;
+        const far = list.flatMap(({ from }) => [from, nounOf(schema.tryDefinition(from), from), pluralOf(schema, from)]);
+        const inverse = list.map(({ from }) => edgeWords(schema, from, name, "in"));
+        add({ relation: name, direction: "in" }, `the relation “${inverse[0]}”`, `in:${name}`, [name, ...inverse, ...far]);
+    }
+    const used = new Set();
+    const mapping = {};
+    const columns = [];
+    const unmatched = [];
+    const nounKey = key(noun);
+    for (const column of header) {
+        const own = key(column);
+        const asked = [own, singular(own), ...(own.startsWith(`${nounKey} `) ? [own.slice(nounKey.length + 1), singular(own.slice(nounKey.length + 1))] : [])];
+        const found = asked.map((one) => candidates.find((candidate) => !used.has(candidate.id) && candidate.keys.has(one))).find((one) => one !== undefined);
+        if (!found) {
+            unmatched.push(column);
+            continue;
+        }
+        used.add(found.id);
+        mapping[column] = found.target;
+        columns.push({ column, target: found.target, said: found.said });
+    }
+    const missing = Object.keys(shape)
+        .filter((field) => !used.has(`field:${field}`))
+        .filter((field) => fieldSpecFor(definition, field)?.spec.required === true && definition.defaults?.[field] === undefined)
+        .map((field) => fieldWords(definition, field));
+    return { mapping, columns, unmatched, missing, ...matchFor(schema, definition, kind, columns) };
+}
+/** A field whose values name one record each: an email, a code, a key, a reference, an id of somebody else's. */
+const KEYISH = /^(e-?mail|code|sku|key|ref|reference|externalId|[a-z]+(Id|Code|Number|Ref))$/;
+const PROBE = "graview-import-probe";
+/** What `proposeMapping` suggests rows are matched by: a key column, else the column the name is read from. */
+function matchFor(schema, definition, kind, columns) {
+    const plural = pluralOf(schema, kind).toLowerCase();
+    const fieldColumns = columns.flatMap((one) => ("field" in one.target ? [{ column: one.column, field: one.target.field }] : []));
+    const keyed = fieldColumns.find(({ field }) => fieldSpecFor(definition, field)?.spec.type === "email" || KEYISH.test(field));
+    if (keyed)
+        return { match: { column: keyed.column, field: keyed.field }, matchSaid: `rows are matched to ${plural} by ${keyed.column}` };
+    // The column the kind's name is read from: a record is called what that cell says.
+    const naming = fieldColumns.find(({ field }) => {
+        try {
+            return labelOf(definition, { id: "", kind, [field]: PROBE }) === PROBE;
+        }
+        catch {
+            return false;
+        }
+    });
+    return naming ? { match: "label", matchSaid: `rows are matched to ${plural} by their name, under ${naming.column}` } : {};
+}
+//# sourceMappingURL=mapping.js.map

package/dist/import/mapping.js.map

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

package/dist/import/rows.d.ts

@@ -0,0 +1,116 @@
+import type { Violation } from "../invariants/types.js";
+import type { Author, Operation, Via } from "../ops/types.js";
+import type { Principal } from "../permissions/types.js";
+import type { AnySchema } from "../schema/schema.js";
+import { type PlannedChange, type Store } from "../store.js";
+import { type ImportMapping, type ImportMatch } from "./mapping.js";
+/**
+ * ROWS TO RECORDS (FR-177). A spreadsheet became an app only by a chat
+ * retyping it fifty records at a time; `importRows` takes the rows as they
+ * are — arrays under a header row, or records keyed by header — and a
+ * mapping from columns to the kind's fields and relations, reads each cell
+ * by its field's type, links a cell that names another kind's record by
+ * its label (an exact name, or the one label it starts, as acts take
+ * names), and lands every row that fits as ONE batch: undone as one,
+ * attributed to the importer, `via: "import"`. A row that does not fit is
+ * left out and said, in words, with every reason; the rest still land.
+ * Asked with `preview: true` (or as `previewImport`), it says all of that
+ * and keeps nothing.
+ */
+/** One row: cells in the header's order, or a record keyed by header. */
+export type ImportRow = readonly unknown[] | Readonly<Record<string, unknown>>;
+export interface ImportOptions {
+    /** Who is importing. The rows are judged by their policy and resolved by their sight, and the history names them. */
+    readonly by: Author | Principal;
+    /** Say what would happen, and keep nothing. */
+    readonly preview?: boolean;
+    /** The channel each op records. Defaults to `"import"`. */
+    readonly via?: Via;
+    /** What the batch was, in a sentence. Defaults to "Import 52 vendors". */
+    readonly intent?: string;
+    /** The batch the ops are kept under. Defaults to a fresh one. */
+    readonly batch?: string;
+    /** `3/4/2024` is the 4th of March, read day first; else the 3rd of April. */
+    readonly dayFirst?: boolean;
+    /**
+     * A HOST'S LAST WORD (as `ApplyOptions.admit`): asked with the import as
+     * planned before anything is kept, its ops as they would be appended;
+     * whatever it throws goes on up and nothing is kept.
+     */
+    readonly admit?: (planned: PlannedChange) => void;
+    /**
+     * HOW A ROW FINDS THE RECORD IT IS ALREADY: `"label"`, a record of the
+     * kind called what the row would call it; `{ column, field }`, one whose
+     * `field` holds what the row has under `column`. Found under the
+     * importer's sight among the live records, a row that finds one changes
+     * it — only the fields the row has, through the kind's edit act, so the
+     * policy is asked as a press on "Change" would be — and links what it
+     * names that the record is not yet linked to; one that finds none makes
+     * one. Unsaid, every row makes a record, as before.
+     */
+    readonly match?: ImportMatch;
+}
+/** A link a row makes: the relation, which way it runs, and the record at the far end. */
+export interface ImportLink {
+    readonly relation: string;
+    readonly direction: "out" | "in";
+    readonly id: string;
+    readonly label: string;
+}
+/** A field a row changes on the record it found: what it held, and what it will. */
+export interface ImportChange {
+    readonly field: string;
+    readonly from: unknown;
+    readonly to: unknown;
+}
+/** What became of one row. */
+export interface ImportRowOutcome {
+    /** The row as a spreadsheet numbers it: the header is row 1, the first record row 2. */
+    readonly row: number;
+    readonly made: boolean;
+    /**
+     * What the row does: `make` a record, `change` the one it found (its
+     * fields, or links it lacked), `leave` that one as it is, or is `refuse`d.
+     */
+    readonly action: "make" | "change" | "leave" | "refuse";
+    /** The fields a row that found its record changes on it, under `match`. */
+    readonly changes?: readonly ImportChange[];
+    /** The record it makes (or made), when it is not refused. */
+    readonly id?: string;
+    readonly label?: string;
+    readonly fields?: Readonly<Record<string, unknown>>;
+    readonly links: readonly ImportLink[];
+    /** Every reason it is refused, in words; empty for a row that is made. */
+    readonly refused: readonly string[];
+    /** The row's outcome in one sentence: "Row 4 would make Bloom & Co, linked to Smith wedding." */
+    readonly sentence: string;
+}
+export interface ImportResult {
+    readonly kind: string;
+    /** Whether anything was kept: false for a preview, and for an import with no row that fits. */
+    readonly kept: boolean;
+    readonly rows: readonly ImportRowOutcome[];
+    /** Rows made (or that would be). */
+    readonly made: number;
+    /** Rows that found their record and change it (or would), under `match`. */
+    readonly changed: number;
+    /** Rows that found their record and leave it as it is, under `match`. */
+    readonly unchanged: number;
+    /** Links those rows make. */
+    readonly linked: number;
+    /** Rows refused. */
+    readonly refused: number;
+    /** Header columns the mapping does not import. */
+    readonly ignored: readonly string[];
+    /** The totals, in a sentence. */
+    readonly sentence: string;
+    /** The batch it was kept under — what `store.undo` takes to take it back. */
+    readonly batch?: string;
+    readonly ops?: readonly Operation[];
+    /** Problems the import brought that were not there before it, once kept. */
+    readonly introduces?: readonly Violation[];
+}
+/** Says what a row would do: preview `importRows`. */
+export declare function previewImport<S extends AnySchema>(store: Store<S>, kind: string, rows: readonly ImportRow[], mapping: ImportMapping, options: Omit<ImportOptions, "preview">): ImportResult;
+export declare function importRows<S extends AnySchema>(store: Store<S>, kind: string, rows: readonly ImportRow[], mapping: ImportMapping, options: ImportOptions): ImportResult;
+//# sourceMappingURL=rows.d.ts.map

package/dist/import/rows.d.ts.map

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