@navette-js/panels 1.0.0-beta.3 → 1.0.0-beta.5

package/lib/import-export.d.ts

@@ -0,0 +1,185 @@
+import { Action } from '@navette-js/actions';
+type StoredFile = {
+    owner: string;
+    name: string;
+    type: string;
+    content: Buffer;
+    expires: number;
+};
+/**
+ * Files offered for download to one user (exports, failed import rows), kept in memory for a limited time. They are lost
+ * when the process restarts and are not shared between processes.
+ */
+export declare class DownloadStore {
+    private files;
+    private readonly ttl;
+    private readonly maxFiles;
+    constructor(options?: {
+        ttl?: number;
+        maxFiles?: number;
+    });
+    /** Stores a file for a user and returns its token (part of the download URL). */
+    put(owner: string | number, name: string, type: string, content: string | Buffer): string;
+    /** The file of a token, only for the user who created it. */
+    get(token: string, owner: string | number): StoredFile | null;
+}
+/**
+ * A CSV cell. Text starting with `=`, `+`, `-`, `@`, a tab or a carriage return is prefixed with `'`, so that spreadsheet
+ * software does not run it as a formula (CSV injection).
+ */
+export declare function csvCell(value: unknown): string;
+export declare const csvLine: (cells: unknown[]) => string;
+/** Parses CSV text (quoted cells, doubled quotes, line breaks inside quotes). */
+export declare function parseCsv(text: string, maxRows?: number): string[][];
+/** Column of an export: its header and the value written for each record. */
+export declare class ExportColumn {
+    readonly name: string;
+    private _label;
+    private _state;
+    private _format;
+    private _enabledByDefault;
+    constructor(name: string);
+    static make(name: string): ExportColumn;
+    label(label: string | null): this;
+    getLabel(): string;
+    /** Value from the record, instead of the attribute with the column's name (dots read relationships: `author.name`). */
+    state(resolver: ((record: any) => unknown) | null): this;
+    formatStateUsing(format: ((state: unknown, record: any) => unknown) | null): this;
+    /** `false`: unchecked in the export modal. */
+    enabledByDefault(condition?: boolean): this;
+    isEnabledByDefault(): boolean;
+    getValue(record: any): unknown;
+}
+/** Describes an export: its columns, and optionally the query and the notification. */
+export declare abstract class Exporter {
+    static getColumns(): ExportColumn[];
+    /** Changes the query of the exported records (e.g. eager loading). */
+    static modifyQuery(_query: any): void;
+    /** Body of the "Export completed" notification. */
+    static getCompletedNotificationBody(count: number): string;
+    /** File name, without extension. */
+    static getFileName(_count: number): string;
+}
+export type ExportActionInstance = Action & {
+    exporter(exporter: typeof Exporter): ExportActionInstance;
+    /** Refuses exports of more rows (10,000 by default, 100,000 at most). */
+    maxRows(count: number): ExportActionInstance;
+    /** `false`: no column selection, every column is exported (the modal only confirms). */
+    columnMapping(condition: boolean): ExportActionInstance;
+    /** Files offered for download: `['csv', 'xlsx']` (both by default). */
+    formats(formats: ('csv' | 'xlsx')[]): ExportActionInstance;
+    /** Builds the files after the response, in the background; the download links arrive in the bell. */
+    queued(condition?: boolean): ExportActionInstance;
+};
+/** Exports the records of the table (with its filters, search and sort) to a CSV file. */
+export declare class ExportAction {
+    static make(name?: string): ExportActionInstance;
+}
+/** Exports the selected records to a CSV file. */
+export declare class ExportBulkAction {
+    static make(name?: string): ExportActionInstance;
+}
+type ImportRule = string | ((value: unknown, row: Record<string, unknown>) => string | null);
+/** Column of an import: the file column it is read from, its validation and how the value is cast. */
+export declare class ImportColumn {
+    readonly name: string;
+    private _label;
+    private _guesses;
+    private _required;
+    private _rules;
+    private _cast;
+    private _example;
+    private _fill;
+    constructor(name: string);
+    static make(name: string): ImportColumn;
+    label(label: string | null): this;
+    getLabel(): string;
+    /** Other file headers that map to this column (compared case-insensitively). */
+    guess(headers: string[]): this;
+    /** The file must contain this column. */
+    requiredMapping(condition?: boolean): this;
+    isMappingRequired(): boolean;
+    /** `required`, `email`, `numeric`, `integer`, `boolean`, `min:n`, `max:n`, `in:a,b`, or a function returning an error message. */
+    rules(rules: ImportRule[]): this;
+    /** Converts the text of the cell before it is saved. */
+    castStateUsing(cast: ((value: string | null) => unknown) | null): this;
+    numeric(): this;
+    boolean(): this;
+    /** Value written in the example file. */
+    example(value: string | null): this;
+    getExample(): string;
+    /** Writes the value into the record yourself, instead of the attribute with the column's name. */
+    fillRecordUsing(fill: ((record: Record<string, unknown>, value: unknown) => void) | null): this;
+    matches(header: string): boolean;
+    validate(value: string | null, row: Record<string, unknown>): string | null;
+    cast(value: string | null): unknown;
+    fill(record: Record<string, unknown>, value: unknown): void;
+}
+/** Describes an import: its columns, how a row finds or creates its record, and hooks. */
+export declare abstract class Importer {
+    static getColumns(): ImportColumn[];
+    /**
+     * Existing record a row updates, or `null` to create one (the default). For example, find a product by its SKU with the
+     * data adapter. Only return records the user may change.
+     */
+    static resolveRecord(_data: Record<string, unknown>, _ctx: {
+        livewire: any;
+    }): Promise<any | null>;
+    /** Runs before a record is saved; `data` may be changed. */
+    static beforeSave(_data: Record<string, unknown>, _record: any | null): Promise<void>;
+    static afterSave(_record: any): Promise<void>;
+    static getCompletedNotificationBody(imported: number, failed: number): string;
+}
+export type ImportActionInstance = Action & {
+    importer(importer: typeof Importer): ImportActionInstance;
+    /** Refuses files with more rows (1,000 by default, 10,000 at most; 100,000 for a queued import). */
+    maxRows(count: number): ImportActionInstance;
+    /** Largest accepted file, in kilobytes (5,120 by default). */
+    maxFileSize(kilobytes: number): ImportActionInstance;
+    /** `false`: no column selection after the upload; file headers are matched to the columns automatically. */
+    columnMapping(condition: boolean): ImportActionInstance;
+    /** Runs after the response, in the background: the user is told it started, then notified in the bell when it ends. */
+    queued(condition?: boolean): ImportActionInstance;
+};
+/** Rows of an uploaded CSV or XLSX file (detected from its content, never its name), up to `limit` rows. */
+export declare function readSpreadsheet(path: string, limit: number): string[][];
+export type BackgroundTask = () => Promise<void>;
+/**
+ * Runs queued imports and exports. By default, one at a time in this process, after the response. Plug your own queue (BullMQ,
+ * a worker…) with a function receiving each task.
+ */
+export declare const useBackgroundRunner: (runner: (task: BackgroundTask) => void) => void;
+export declare const runInBackground: (task: BackgroundTask) => void;
+/** Where runs of imports and exports are recorded (see `knexImportExportHistory()`). */
+export interface ImportExportHistory {
+    startImport(data: {
+        userId: string | number;
+        importer: string;
+        fileName: string;
+        totalRows: number;
+    }): Promise<string | number>;
+    finishImport(id: string | number, data: {
+        processedRows: number;
+        successfulRows: number;
+    }): Promise<void>;
+    recordFailedImportRow(importId: string | number, row: Record<string, unknown>, error: string): Promise<void>;
+    startExport(data: {
+        userId: string | number;
+        exporter: string;
+        fileName: string;
+        totalRows: number;
+    }): Promise<string | number>;
+    finishExport(id: string | number, data: {
+        successfulRows: number;
+    }): Promise<void>;
+}
+type Query = (table: string) => any;
+/** History in `imports`, `exports` and `failed_import_rows` tables (create them with `importExportSchema()`). */
+export declare function knexImportExportHistory(db: Query): ImportExportHistory;
+/** Creates the history tables when missing (call it from a migration). */
+export declare function importExportSchema(knex: any): Promise<void>;
+/** Imports the rows of a CSV or XLSX file: each row is validated, then creates or updates a record through the data adapter. */
+export declare class ImportAction {
+    static make(name?: string): ImportActionInstance;
+}
+export {};