shutro-erp 0.2.0 → 0.3.0

package/dist/import/run.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The import itself (RFC 0014 §5.1–§5.5): rows of cells become records of a model through the ORM, as the user.
+ *
+ * - Records are created, updated or both (`mode`), matched on a key column: the record id, an external id, or a
+ *   field the model keeps unique (a code, an email).
+ * - A row whose own columns are empty continues the record above: its `lines.*` cells add a line (§5.2). Lines of an
+ *   updated record replace its lines, so a file exported with its lines re-imports to the same records.
+ * - A dry run does all of it — conversions, relation matches, creates and writes, computes, sequences, constraints,
+ *   record rules — in a savepoint that is rolled back. A commit is all-or-nothing, or with `onError: 'skip'` keeps
+ *   the records without errors.
+ * - A commit returns what undo needs (§5.5): the created ids, the previous values of updated records and their lines,
+ *   and each record's `updatedAt` after the import, to tell records changed since.
+ *
+ * Errors name their row (as numbered in the file), column and cell.
+ */
+import { type ApiModel } from '../server/index.js';
+import { type Env } from '../server/orm.js';
+import { type Cell, type CellError, type ConvertOptions } from './convert.js';
+import type { ColumnMapping } from './mapping.js';
+import { type Match, type MatchTarget } from './match.js';
+/** The record id as a key column (`#42` or `42`, as an export writes it). */
+export declare const ID_KEY = "id";
+/** An external id as a key column (`legacy.partner_42`; a bare `partner_42` is `__import__.partner_42`). */
+export declare const EXTERNAL_ID_KEY = "externalId";
+/** The module part of external ids an import gives (Shutro `env.setExternalId`). */
+export declare const IMPORT_MODULE = "__import__";
+export interface ImportOptions extends ConvertOptions {
+    /** `create` (default), `update` existing records only, or `upsert`. */
+    readonly mode?: 'create' | 'update' | 'upsert';
+    /** The key column's field: `id`, `externalId`, or a unique field. Needed to update. */
+    readonly key?: string;
+    /** `stop` (default): any error keeps nothing. `skip`: records with errors are left out, the others kept. */
+    readonly onError?: 'stop' | 'skip';
+    /** The file's first row holds the headers (default true). */
+    readonly headerRow?: boolean;
+}
+export type RowErrorCode = CellError['code'] | 'not-found' | 'ambiguous' | 'missing-required' | 'missing-key' | 'no-match' | 'exists' | 'duplicate-key' | 'rejected';
+/** One error, where the user can find it: the row of the file (1-based) and the column, when known. */
+export interface RowError {
+    readonly row: number;
+    readonly column: number | null;
+    readonly field: string | null;
+    readonly code: RowErrorCode;
+    readonly message: string;
+}
+/** What undo needs (RFC 0014 §5.5). JSON: stored with the session. */
+export interface UndoData {
+    readonly created: readonly number[];
+    readonly updated: readonly {
+        readonly id: number;
+        /** The previous values of the fields the import wrote (as `read()` gives them). */
+        readonly before: Readonly<Record<string, unknown>>;
+        /** The previous lines of the one2many fields the import replaced. */
+        readonly lines: Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>;
+    }[];
+    /** `updatedAt` of each touched record after the import (ISO). */
+    readonly stamps: Readonly<Record<string, string>>;
+}
+export interface ImportResult {
+    /** Records read (a record and its continuation rows count once). */
+    readonly rows: number;
+    /** Records created and updated; empty after a dry run or a commit that stopped on errors. */
+    readonly created: readonly number[];
+    readonly updated: readonly number[];
+    /** What a dry run would create and update. */
+    readonly wouldCreate: number;
+    readonly wouldUpdate: number;
+    /** Records left out for their errors (`onError: 'skip'`). */
+    readonly skipped: number;
+    /** The file rows of the records left out (their continuation rows included). */
+    readonly rejectedRows: readonly number[];
+    readonly errors: readonly RowError[];
+    /** How each relation text was matched (by external id, key, name), by field path, for the user to check. */
+    readonly matches: Readonly<Record<string, Readonly<Record<string, Match>>>>;
+    /** Set when the import was kept. */
+    readonly undo: UndoData | null;
+}
+/** A field the user can fill by import: of the model, a line field (`lines.product`), or a key column. */
+export interface ImportField {
+    /** The path: `name`, `lines.product`, `id`, `externalId`. */
+    readonly key: string;
+    readonly kind: string;
+    readonly label: string;
+    readonly required: boolean;
+    readonly options: readonly (readonly [string, string])[] | null;
+    readonly target: MatchTarget | null;
+    /** The one2many field a line field belongs to, else null. */
+    readonly line: string | null;
+    /** The field key in its own model (`product` for `lines.product`). */
+    readonly sub: string;
+    /** Usable as the key column: the id, an external id, or a field the model keeps unique. */
+    readonly keyable: boolean;
+}
+/** Records written per savepoint (and per progress report). */
+export declare const WRITE_BATCH = 1000;
+/** The full external id of a key cell. */
+export declare const externalIdOf: (text: string) => string;
+/**
+ * Imports `table` (cells by row) into `model` with `columns`. With `dryRun`, nothing is kept. Runs in the caller's
+ * transaction, in savepoints of its own.
+ */
+export declare function runImport(env: Env, model: ApiModel, fields: ReadonlyMap<string, ImportField>, table: readonly (readonly Cell[])[], columns: readonly ColumnMapping[], options: ImportOptions & {
+    readonly dryRun: boolean;
+    /** Called before the writes and after each batch: records written so far, of how many. */
+    readonly onProgress?: (done: number, total: number) => Promise<void>;
+}): Promise<ImportResult>;
+export interface UndoResult {
+    readonly deleted: number;
+    readonly restored: number;
+    /** Records changed since the import: left as they are. */
+    readonly changed: readonly number[];
+}
+/**
+ * Undoes an import (RFC 0014 §5.5), as the user: deletes the records it created and restores the values it changed,
+ * for the records nobody changed since (their `updatedAt` is still the import's). The others are listed.
+ */
+export declare function undoImport(env: Env, model: ApiModel, fields: ReadonlyMap<string, ImportField>, undo: UndoData): Promise<UndoResult>;
+/** What `importFields` needs to know about the models. */
+export interface ImportModels {
+    readonly models: ReadonlyMap<string, ApiModel>;
+    /** How records of a model are found from text (its name field, its unique char fields). */
+    targets(model: string): MatchTarget | null;
+    /** The many2one a one2many's lines point back with. */
+    inverseOf(model: string, field: string): string | null;
+}
+/**
+ * The fields of `model` the user may fill by import, by path: its own, the key columns (`id`, `externalId`), and
+ * the fields of the lines of each one2many the user may write and whose lines they may create (without the link
+ * back to the record).
+ */
+export declare function importFields(env: Env, model: ApiModel, catalog: ImportModels): Map<string, ImportField>;