@adecore/database 0.0.1 → 0.16.0-beta.0

package/src/table/references.ts

@@ -0,0 +1,38 @@
+import { wholeValueOf } from '../grid/focused-value.ts';
+import type { Shown } from '../grid/display.ts';
+import type { Engine, ForeignKeyInfo, ValueKind } from '../protocol/index.ts';
+import { matchCondition, type ColumnMatch } from '../sql.ts';
+
+/* Where a foreign key points for one row: the referenced table and the condition that picks the row out. */
+export interface Reference {
+    readonly schema: string;
+    readonly table: string;
+    readonly where: string;
+}
+
+/* The foreign key a column is part of; the first one when a column sits in several. */
+export const foreignKeyOf = (foreignKeys: readonly ForeignKeyInfo[], column: string): ForeignKeyInfo | undefined =>
+    foreignKeys.find((key) => key.columns.includes(column));
+
+/*
+ * The row a foreign key points to, from the cells of the referencing row. `null` when any column of
+ * the key is NULL (it references nothing), is only a preview, or is not among the columns.
+ */
+export const referenceOf = (
+    engine: Engine,
+    key: ForeignKeyInfo,
+    columns: readonly { readonly name: string; readonly kind: ValueKind }[],
+    cells: readonly Shown[]
+): Reference | null => {
+    const matches: ColumnMatch[] = [];
+    for (const [position, name] of key.columns.entries()) {
+        const referenced = key.referencedColumns[position];
+        const index = columns.findIndex((column) => column.name === name);
+        const value = index < 0 ? undefined : wholeValueOf(cells[index] ?? null);
+        if (referenced === undefined || value === undefined || value === null) {
+            return null;
+        }
+        matches.push({ column: referenced, value, kind: columns[index]!.kind });
+    }
+    return matches.length === 0 ? null : { schema: key.referencedSchema, table: key.referencedTable, where: matchCondition(engine, matches) };
+};

package/src/table/useLoaded.ts

@@ -0,0 +1,58 @@
+import { useEffect, useRef, useState } from 'react';
+import { messageOf } from '@adecore/ui';
+
+export interface Loaded<T> {
+    /* The last value that arrived; stays while the next one loads, so a page does not vanish under a reload. */
+    value: T | null;
+    loading: boolean;
+    error: string | null;
+    reload(): void;
+}
+
+interface State<T> {
+    key: string;
+    version: number;
+    value: T | null;
+    error: string | null;
+}
+
+/*
+ * Runs `load` when `key` changes or `reload` is called, and aborts the run that is still going.
+ * `key` has to name everything `load` reads, since `load` itself is a new function on every render.
+ * A value belongs to the hook's owner, which is remounted for a different subject, so it outlives a key change.
+ */
+export function useLoaded<T>(load: (signal: AbortSignal) => Promise<T>, key: string): Loaded<T> {
+    const loader = useRef(load);
+    const [version, setVersion] = useState(0);
+    // Loading is not a state of its own: it is that the last answer is not for this key and this version.
+    const [state, setState] = useState<State<T>>({ key: '', version: -1, value: null, error: null });
+
+    useEffect(() => {
+        loader.current = load;
+    });
+
+    useEffect(() => {
+        const controller = new AbortController();
+        loader.current(controller.signal).then(
+            (value) => {
+                if (!controller.signal.aborted) {
+                    setState({ key, version, value, error: null });
+                }
+            },
+            (error: unknown) => {
+                if (!controller.signal.aborted) {
+                    setState((now) => ({ key, version, value: now.value, error: messageOf(error) }));
+                }
+            }
+        );
+        return () => controller.abort();
+    }, [key, version]);
+
+    const answered = state.key === key && state.version === version;
+    return {
+        value: state.value,
+        loading: !answered,
+        error: answered ? state.error : null,
+        reload: () => setVersion((now) => now + 1)
+    };
+}

package/src/table/useStoredLayout.ts

@@ -0,0 +1,53 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { DatabaseStorage } from '../actions.ts';
+import { EMPTY_LAYOUT, parseStoredLayout, serializeLayout, type StoredLayout } from './layout-store.ts';
+
+/* How long a change waits for the next before it is written, so a drag of a column edge is one write. */
+export const STORE_DELAY_MS = 500;
+
+export interface StoredLayoutHandle {
+    /* What was stored when the view mounted, or `null` when nothing usable was. */
+    readonly stored: StoredLayout | null;
+    /* Merges a change into what is remembered and writes it after a pause. Does nothing without storage. */
+    remember(change: Partial<StoredLayout>): void;
+}
+
+/*
+ * The layout of one table's view in the app's storage. It is read once, on mount, and written back
+ * in the background: the last change is still written when the view unmounts.
+ */
+export function useStoredLayout(storage: DatabaseStorage | undefined, key: string): StoredLayoutHandle {
+    const [stored] = useState(() => (storage === undefined ? null : parseStoredLayout(storage.get(key))));
+    const latest = useRef<StoredLayout>(stored ?? EMPTY_LAYOUT);
+    const dirty = useRef(false);
+    const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+    const target = useRef({ storage, key });
+
+    useEffect(() => {
+        target.current = { storage, key };
+    });
+
+    const write = useCallback((): void => {
+        clearTimeout(timer.current);
+        timer.current = undefined;
+        if (dirty.current) {
+            dirty.current = false;
+            target.current.storage?.set(target.current.key, serializeLayout(latest.current));
+        }
+    }, []);
+
+    useEffect(() => write, [write]);
+
+    return {
+        stored,
+        remember: (change) => {
+            if (storage === undefined) {
+                return;
+            }
+            latest.current = { ...latest.current, ...change };
+            dirty.current = true;
+            clearTimeout(timer.current);
+            timer.current = setTimeout(write, STORE_DELAY_MS);
+        }
+    };
+}

package/src/table/useTableTransfer.ts

@@ -0,0 +1,187 @@
+import { useEffect, useRef, useState } from 'react';
+import { messageOf } from '@adecore/ui';
+import type { DatabaseFiles } from '../actions.ts';
+import { DatabaseRequestError, type DatabaseClient, type DatabaseSession } from '../client/types.ts';
+import type { FileFormat, TableStructure } from '../protocol/index.ts';
+import type { ImportSample } from './ImportDialog.tsx';
+import { formatOfPath, importableColumns, mapColumn, matchColumns, type ImportFormat } from './import-mapping.ts';
+
+/* What the strip over the table says about an export or an import. */
+export type TransferNotice =
+    | { readonly kind: 'exporting'; readonly format: FileFormat }
+    | { readonly kind: 'exported'; readonly rows: number }
+    | { readonly kind: 'imported'; readonly rows: number }
+    | { readonly kind: 'failed'; readonly message: string };
+
+/* The import a person is setting up. */
+export interface ImportDraft {
+    readonly path: string;
+    readonly format: ImportFormat;
+    readonly header: boolean;
+    /* `null` while a new sample is read. */
+    readonly sample: ImportSample | null;
+    readonly mapping: readonly (string | null)[];
+    readonly busy: boolean;
+    readonly error: string | null;
+}
+
+export interface TableTransferInput {
+    readonly client: DatabaseClient;
+    readonly session: DatabaseSession;
+    /* Without the app's file dialogs there is no export and no import. */
+    readonly files: DatabaseFiles | undefined;
+    readonly schema: string;
+    readonly table: string;
+    readonly structure: TableStructure | null;
+    /* The filters as applied, which an export respects. */
+    readonly where: string;
+    readonly orderBy: string;
+    /* Rows were added; the table reloads. */
+    readonly onImported: () => void;
+}
+
+export interface TableTransfer {
+    readonly notice: TransferNotice | null;
+    readonly importDraft: ImportDraft | null;
+    exportAs(format: FileFormat): void;
+    /* Stops the export that is running. */
+    cancelExport(): void;
+    dismiss(): void;
+    chooseImportFile(): void;
+    changeHeader(header: boolean): void;
+    changeMapping(fileColumn: number, tableColumn: string | null): void;
+    runImport(): void;
+    closeImport(): void;
+}
+
+/* Export of the table as filtered, and import of a file into it, with the state both need between the dialogs and the strip. */
+export function useTableTransfer({ client, session, files, schema, table, structure, where, orderBy, onImported }: TableTransferInput): TableTransfer {
+    const [notice, setNotice] = useState<TransferNotice | null>(null);
+    const [importDraft, setImportDraft] = useState<ImportDraft | null>(null);
+    const exporting = useRef<AbortController | null>(null);
+    const sampling = useRef<AbortController | null>(null);
+    const tableColumns = structure === null ? [] : importableColumns(structure.columns).map((column) => column.name);
+
+    useEffect(() => {
+        if (notice?.kind !== 'exported' && notice?.kind !== 'imported') {
+            return;
+        }
+        const timer = setTimeout(() => setNotice(null), 8000);
+        return () => clearTimeout(timer);
+    }, [notice]);
+
+    useEffect(() => () => sampling.current?.abort(), []);
+
+    const exportAs = (format: FileFormat): void => {
+        if (files === undefined || exporting.current !== null) {
+            return;
+        }
+        void (async () => {
+            const path = await files.save({ suggestedName: `${table}.${format}`, format });
+            if (path === null) {
+                return;
+            }
+            const controller = new AbortController();
+            exporting.current = controller;
+            setNotice({ kind: 'exporting', format });
+            try {
+                const result = await session.export(
+                    { source: { kind: 'table', schema, table, where: where || undefined, orderBy: orderBy || undefined }, format, path },
+                    { signal: controller.signal }
+                );
+                setNotice({ kind: 'exported', rows: result.rows });
+            } catch (error) {
+                const cancelled = controller.signal.aborted || (error instanceof DatabaseRequestError && error.code === 'cancelled');
+                setNotice(cancelled ? null : { kind: 'failed', message: messageOf(error) });
+            } finally {
+                exporting.current = null;
+            }
+        })();
+    };
+
+    const sample = async (path: string, format: ImportFormat, header: boolean): Promise<ImportSample> => {
+        sampling.current?.abort();
+        const controller = new AbortController();
+        sampling.current = controller;
+        return await client.sample(path, format, header, { signal: controller.signal });
+    };
+
+    const chooseImportFile = (): void => {
+        if (files === undefined || structure === null) {
+            return;
+        }
+        void (async () => {
+            const path = await files.open({ formats: ['csv', 'tsv'] });
+            if (path === null) {
+                return;
+            }
+            const format = formatOfPath(path);
+            try {
+                const read = await sample(path, format, true);
+                setImportDraft({ path, format, header: true, sample: read, mapping: matchColumns(read.columns, tableColumns, true), busy: false, error: null });
+            } catch (error) {
+                setNotice({ kind: 'failed', message: messageOf(error) });
+            }
+        })();
+    };
+
+    const changeHeader = (header: boolean): void => {
+        if (importDraft === null) {
+            return;
+        }
+        const { path, format } = importDraft;
+        setImportDraft({ ...importDraft, header, sample: null, error: null });
+        void (async () => {
+            try {
+                const read = await sample(path, format, header);
+                setImportDraft((now) =>
+                    now === null || now.path !== path ? now : { ...now, header, sample: read, mapping: matchColumns(read.columns, tableColumns, header) }
+                );
+            } catch (error) {
+                if (!(error instanceof DatabaseRequestError && error.code === 'cancelled')) {
+                    setImportDraft((now) => (now === null || now.path !== path ? now : { ...now, error: messageOf(error) }));
+                }
+            }
+        })();
+    };
+
+    const changeMapping = (fileColumn: number, tableColumn: string | null): void => {
+        setImportDraft((now) => (now === null ? now : { ...now, mapping: mapColumn(now.mapping, fileColumn, tableColumn) }));
+    };
+
+    const runImport = (): void => {
+        if (importDraft === null || importDraft.busy || importDraft.sample === null) {
+            return;
+        }
+        const { path, format, header, mapping } = importDraft;
+        setImportDraft({ ...importDraft, busy: true, error: null });
+        void (async () => {
+            try {
+                const rows = await session.import(schema, table, { path, format, header, columns: mapping });
+                setImportDraft(null);
+                setNotice({ kind: 'imported', rows });
+                onImported();
+            } catch (error) {
+                setImportDraft((now) => (now === null ? now : { ...now, busy: false, error: messageOf(error) }));
+            }
+        })();
+    };
+
+    const closeImport = (): void => {
+        sampling.current?.abort();
+        setImportDraft(null);
+    };
+
+    return {
+        notice,
+        importDraft,
+        exportAs,
+        cancelExport: () => exporting.current?.abort(),
+        dismiss: () => setNotice(null),
+        chooseImportFile,
+        changeHeader,
+        changeMapping,
+        runImport,
+        closeImport
+    };
+}