@adecore/database 0.0.1 → 0.16.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bas Milius
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,154 @@
 # @adecore/database
 
-A placeholder that reserves the name for trusted publishing. Install a later version.
+[![npm](https://img.shields.io/npm/v/@adecore/database)](https://www.npmjs.com/package/@adecore/database)
+[![Docs](https://img.shields.io/badge/docs-adecore.dev-blue)](https://adecore.dev/database/)
+
+Browse, query and edit SQLite and MySQL or MariaDB databases from a desktop app. React views draw the connections, a table tree, the rows of a table, its structure, a designer that creates and alters tables, a query console and a workbench that puts them together. A host in the app's backend and a native helper that talks to the servers do the work behind them.
+
+**[Documentation with a live demo of every view](https://adecore.dev/database/)**
+
+## Install
+
+```sh
+bun add @adecore/database
+```
+
+`@adecore/ui`, React 19, `react-dom`, `i18next` and `react-i18next` are peer dependencies; the app brings them. Only the page needs them. The host (`@adecore/database/host`) and the protocol (`@adecore/database/protocol`) import none of them.
+
+## Layers
+
+```
+page            views, createDatabaseClient(transport)
+  |
+app channel     ipcMain.handle, a utility process, a WebSocket (the app's own, with its own sender check)
+  |
+backend         createDatabaseHost, spawnHelper          (Bun or Node)
+  |
+helper          adecore-database                         (native binary, one JSON message per line)
+  |
+server          SQLite file, MySQL or MariaDB
+```
+
+The package does not carry the messages between the page and the backend. The app does, over a channel it already has and already guards.
+
+## Wire it up
+
+In the backend, create one host per app and hand every request that comes over the channel to it. Check the sender first, and name the owner of the request: a window, a socket. When the owner goes away, release it.
+
+```ts
+import { createDatabaseHost, spawnHelper } from '@adecore/database/host';
+
+const host = createDatabaseHost({
+    start: () => spawnHelper(helperPath),
+    // Optional: turn down connections the page may not open.
+    authorize: (connection) => connection.engine !== 'sqlite' || connection.path.startsWith(dataFolder),
+    // Optional: the files the page may export to and import from. Every file is refused without it.
+    authorizeFile: (path, access, owner) => isChosenInDialog(owner, access, path),
+    // Optional: whether the page may list Docker containers. Refused without it.
+    authorizeDiscovery: (kind, owner) => isTrusted(owner)
+});
+
+ipcMain.handle('database:request', (event, request) => {
+    if (!isTrustedSender(event)) {
+        throw new Error('Untrusted sender.');
+    }
+
+    return host.handle(request, String(event.sender.id));
+});
+
+app.on('web-contents-created', (_event, contents) => {
+    const owner = String(contents.id);
+    contents.once('destroyed', () => void host.release(owner));
+});
+```
+
+On the page, make a client over a transport that sends a request and returns the response, then mount `DatabaseProvider` inside `UIProvider`:
+
+```tsx
+import { createDatabaseClient, DatabaseProvider, TableView } from '@adecore/database';
+
+const client = createDatabaseClient((request) => window.database.request(request));
+
+createRoot(root).render(
+    <UIProvider i18n={i18next} formatSource={formatSource}>
+        <DatabaseProvider client={client}>
+            <TableView connection={connection} schema="main" table="customers" className="h-full" />
+        </DatabaseProvider>
+    </UIProvider>
+);
+```
+
+A `Connection` is `{ id, name, config }`. The app keeps the list, with the password in its own secure storage; the package stores nothing.
+
+`DatabaseProvider` also takes three optional hooks into the app. Without them the views leave out what they cannot do.
+
+```tsx
+<DatabaseProvider
+    client={client}
+    onAction={(action) => openInTab(action)}
+    storage={{ get: (key) => localStorage.getItem(key), set: (key, value) => (value === null ? localStorage.removeItem(key) : localStorage.setItem(key, value)) }}
+    files={{ save: (options) => window.app.saveFile(options), open: (options) => window.app.openFile(options) }}
+>
+```
+
+`onAction` receives a `DatabaseAction` when a view wants a table, a console or the designer opened, so the app decides where it goes. `storage` keeps layouts, console history and open tabs across a remount. `files` holds the app's save and open dialogs for export and import.
+
+Tell Tailwind to scan the package for its classes, next to the `@source` line of `@adecore/ui`. The path is relative to the CSS file:
+
+```css
+@import 'tailwindcss';
+@import '@adecore/ui/theme.css';
+
+@source "../node_modules/@adecore/ui/dist";
+@source "../node_modules/@adecore/database/dist";
+```
+
+The words live in the `database` namespace, in English and Dutch. `DatabaseProvider` adds them to the i18next instance of `UIProvider`.
+
+## The helper binary
+
+The helper is a Rust program that holds the database drivers, so a crashing driver cannot take the backend down. The install brings a prebuilt one: `@adecore/database` lists a package per platform as an optional dependency (`@adecore/database-darwin-arm64` for Apple silicon, `-linux-x64`, `-linux-arm64` and `-win32-x64`), and the package manager installs the one that fits the machine. `helperPath()` returns its path, or `null` when the platform has no package or optional dependencies were left out.
+
+```ts
+import { createDatabaseHost, helperPath, spawnHelper } from '@adecore/database/host';
+
+const path = helperPath();
+
+if (path === null) {
+    throw new Error('No prebuilt helper for this platform.');
+}
+
+const host = createDatabaseHost({ start: () => spawnHelper(path) });
+```
+
+The Linux binaries link against glibc 2.35 or newer. An app that wants its own build, for another platform or a patched helper, builds it with cargo from this folder and passes that path to `spawnHelper` instead:
+
+```sh
+cargo build --release --locked --manifest-path helper/Cargo.toml
+```
+
+The binary is `helper/target/release/adecore-database`.
+
+### In an Electron app
+
+A binary cannot run from inside an `app.asar` archive. `helperPath()` maps `app.asar` to `app.asar.unpacked`, so the app unpacks the platform packages. With electron-builder:
+
+```json
+{
+    "asarUnpack": ["node_modules/@adecore/database-*/**"]
+}
+```
+
+Or copy the binary into `extraResources` and pass that path to `spawnHelper`, without `helperPath()`. Either way the app's own code signing and notarization cover the binary, so sign the unpacked file with the rest of the app. An app packaged for one platform from another machine needs the package of the target platform installed there.
+
+## Views and testing
+
+`ConnectionManager` and `ConnectionForm` edit the saved connections: a SQLite file, or a MySQL or MariaDB server reached over TCP, a Unix socket, an SSH host or a Docker container. `DatabaseExplorer` is a tree of connections, schemas, tables and columns, with context menus. `TableView` pages through the rows of a table, filters and sorts them from one command field, and edits them. `StructureView` shows columns, indexes, foreign keys and the DDL. `TableDesigner` creates and alters a table and shows the SQL before it runs. `QueryConsole` runs SQL, with history, paging, transactions and export. `DatabaseWorkbench` is the explorer beside closable tabs for all of those.
+
+`@adecore/database/testing` has `fakeDatabaseTransport`, an in-memory server behind the same transport, for demos and for tests of an app.
+
+The documentation at https://adecore.dev/database/ has a page for each view, and guides for connections, files, security and the protocol.
+
+## License
+
+MIT

package/dist/DatabaseProvider.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from 'react';
+import type { DatabaseAction, DatabaseFiles, DatabaseStorage } from './actions.ts';
+import type { DatabaseClient } from './client/types.ts';
+import type { NumberNotation } from './grid/display.ts';
+export interface DatabaseProviderProps {
+    client: DatabaseClient;
+    onAction?(action: DatabaseAction): void;
+    storage?: DatabaseStorage;
+    files?: DatabaseFiles;
+    numberNotation?: NumberNotation;
+    children: ReactNode;
+}
+export declare function DatabaseProvider({ client, onAction, storage, files, numberNotation, children }: DatabaseProviderProps): import("react").JSX.Element;

package/dist/DatabaseProvider.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { DatabaseContext } from './client-context.js';
+import { addDatabaseResources } from './locales.js';
+/* Hands every view below it the client and the app's hooks, and adds the package's words to the i18next the app's `UIProvider` was given. Mount it inside that provider. */
+export function DatabaseProvider({ client, onAction, storage, files, numberNotation = 'database', children }) {
+    const { i18n } = useTranslation();
+    const [added, setAdded] = useState(null);
+    // In render, as `UIProvider` does, so the first view already reads its words.
+    if (added !== i18n) {
+        addDatabaseResources(i18n);
+        setAdded(i18n);
+    }
+    const value = useMemo(() => ({ client, onAction, storage, files, numberNotation }), [client, onAction, storage, files, numberNotation]);
+    return _jsx(DatabaseContext, { value: value, children: children });
+}

package/dist/actions.d.ts

@@ -0,0 +1,40 @@
+import type { TableRef } from './client/types.ts';
+export type DatabaseAction = {
+    readonly kind: 'open-table';
+    readonly ref: TableRef;
+    readonly view: 'data' | 'structure';
+    readonly where?: string;
+} | {
+    readonly kind: 'open-console';
+    readonly connectionId: string;
+    readonly schema?: string;
+    readonly sql?: string;
+} | {
+    readonly kind: 'new-table';
+    readonly connectionId: string;
+    readonly schema: string;
+} | {
+    readonly kind: 'edit-table';
+    readonly ref: TableRef;
+} | {
+    readonly kind: 'manage-connection';
+    readonly connectionId: string;
+};
+export interface ExplorerSelection {
+    readonly connectionId: string;
+    readonly schema?: string;
+    readonly table?: string;
+}
+export interface DatabaseStorage {
+    get(key: string): string | null;
+    set(key: string, value: string | null): void;
+}
+export interface DatabaseFiles {
+    save(options: {
+        readonly suggestedName: string;
+        readonly format: 'csv' | 'tsv' | 'json' | 'sql';
+    }): Promise<string | null>;
+    open(options: {
+        readonly formats: readonly ('csv' | 'tsv')[];
+    }): Promise<string | null>;
+}

package/dist/actions.js

@@ -0,0 +1 @@
+export {};

package/dist/client/client.d.ts

@@ -0,0 +1,5 @@
+import { type DatabaseClient, type DatabaseTransport } from './types.ts';
+export interface DatabaseClientOptions {
+    readonly createId?: () => string;
+}
+export declare const createDatabaseClient: (transport: DatabaseTransport, options?: DatabaseClientOptions) => DatabaseClient;

package/dist/client/client.js

@@ -0,0 +1,245 @@
+import { DatabaseRequestError } from './types.js';
+const cancelledError = () => new DatabaseRequestError('cancelled', 'The request was cancelled.');
+const isUnknownSession = (error) => error instanceof DatabaseRequestError && error.code === 'unknown-session';
+const LEADING_COMMENTS = /^(?:\s+|--[^\n]*(?:\n|$)|#[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)+/;
+const CHANGES_SHAPE = /^(?:create|alter|drop|rename|truncate)\b/i;
+const changesShape = (sql) => CHANGES_SHAPE.test(sql.replace(LEADING_COMMENTS, ''));
+/* Structural equality for the JSON a config is made of; a key set to `undefined` counts as absent. */
+const isEqual = (left, right) => {
+    if (left === right) {
+        return true;
+    }
+    if (typeof left !== 'object' || typeof right !== 'object' || left === null || right === null) {
+        return false;
+    }
+    const leftKeys = Object.keys(left).filter((key) => left[key] !== undefined);
+    const rightKeys = Object.keys(right).filter((key) => right[key] !== undefined);
+    return (leftKeys.length === rightKeys.length &&
+        leftKeys.every((key) => isEqual(left[key], right[key])));
+};
+/* Rejects with `cancelled` as soon as the signal aborts, without waiting for the promise. */
+const raceAbort = (promise, signal) => {
+    if (signal === undefined) {
+        return promise;
+    }
+    if (signal.aborted) {
+        promise.catch(() => { });
+        return Promise.reject(cancelledError());
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(cancelledError());
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+};
+export const createDatabaseClient = (transport, options = {}) => {
+    const createId = options.createId ?? (() => crypto.randomUUID());
+    const live = new Map();
+    const schemaListeners = new Set();
+    const notifySchemaChange = (change) => {
+        for (const listener of [...schemaListeners]) {
+            try {
+                listener(change);
+            }
+            catch (error) {
+                // One failing listener must neither hide the result of the statement nor keep the others from hearing it.
+                console.error('A schema change listener failed.', error);
+            }
+        }
+    };
+    const send = async (method, params, signal) => {
+        if (signal?.aborted) {
+            throw cancelledError();
+        }
+        const id = createId();
+        const request = { id, method, params };
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                const cancel = { id: createId(), method: 'cancel', params: { request: id } };
+                new Promise((done) => done(transport(cancel))).catch(() => { });
+                reject(cancelledError());
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            new Promise((done) => done(transport(request)))
+                .then((response) => {
+                const { ok, result, error } = response;
+                if (ok) {
+                    resolve(result);
+                }
+                else {
+                    reject(new DatabaseRequestError(error.code, error.message, error.sqlState, error.change));
+                }
+            }, (error) => reject(new DatabaseRequestError('helper-unavailable', error instanceof Error ? error.message : String(error))))
+                .finally(() => signal?.removeEventListener('abort', onAbort));
+        });
+    };
+    const createSession = (initial, channel) => {
+        let connection = initial;
+        let opened = null;
+        let opening = null;
+        /* A session that was closed and is used again is findable again, so `disconnect` and `dispose` reach it. */
+        const track = () => {
+            let channels = live.get(connection.id);
+            if (channels === undefined) {
+                channels = new Map();
+                live.set(connection.id, channels);
+            }
+            if (!channels.has(channel)) {
+                channels.set(channel, created);
+            }
+        };
+        const open = () => {
+            if (opened !== null) {
+                return Promise.resolve(opened);
+            }
+            track();
+            opening ??= send('open', { connection: connection.config })
+                .then((result) => (opened = result))
+                .finally(() => {
+                opening = null;
+            });
+            return opening;
+        };
+        /* Reads are safe to send twice, so they open again and retry once; a write is not, so it only drops the session. */
+        const request = async (method, build, requestOptions, retry) => {
+            const signal = requestOptions?.signal;
+            if (signal?.aborted) {
+                throw cancelledError();
+            }
+            const current = await raceAbort(open(), signal);
+            try {
+                return await send(method, build(current.session), signal);
+            }
+            catch (error) {
+                if (!isUnknownSession(error)) {
+                    throw error;
+                }
+                if (opened === current) {
+                    opened = null;
+                }
+                if (retry) {
+                    return request(method, build, requestOptions, false);
+                }
+                throw error;
+            }
+        };
+        const close = async () => {
+            const channels = live.get(connection.id);
+            if (channels?.get(channel) === created) {
+                channels.delete(channel);
+                if (channels.size === 0) {
+                    live.delete(connection.id);
+                }
+            }
+            const current = opened ?? (opening === null ? null : await opening.catch(() => null));
+            opened = null;
+            if (current !== null) {
+                await send('close', { session: current.session }).catch(() => { });
+            }
+        };
+        const session = {
+            get connection() {
+                return connection;
+            },
+            async server(requestOptions) {
+                return (await raceAbort(open(), requestOptions?.signal)).server;
+            },
+            async schemas(requestOptions) {
+                return (await request('schemas', (id) => ({ session: id }), requestOptions, true)).schemas;
+            },
+            async tables(schema, requestOptions) {
+                return (await request('tables', (id) => ({ session: id, schema }), requestOptions, true)).tables;
+            },
+            structure(schema, table, requestOptions) {
+                return request('structure', (id) => ({ session: id, schema, table }), requestOptions, true);
+            },
+            rows(schema, table, query, requestOptions) {
+                return request('rows', (id) => ({ session: id, schema, table, ...query }), requestOptions, true);
+            },
+            async count(schema, table, where, requestOptions) {
+                const params = (id) => (where === undefined ? { session: id, schema, table } : { session: id, schema, table, where });
+                return (await request('count', params, requestOptions, true)).count;
+            },
+            async cell(schema, table, key, column, requestOptions) {
+                return (await request('cell', (id) => ({ session: id, schema, table, key, column }), requestOptions, true)).value;
+            },
+            async apply(schema, table, changes, requestOptions) {
+                return (await request('apply', (id) => ({ session: id, schema, table, changes }), requestOptions, false)).affected;
+            },
+            async execute(sql, executeOptions) {
+                const { signal: _signal, ...rest } = executeOptions ?? {};
+                const result = await request('execute', (id) => ({ session: id, sql, ...rest }), executeOptions, false);
+                if (result.results.some((item) => item.kind !== 'error' && changesShape(item.sql))) {
+                    notifySchemaChange({ connectionId: connection.id, ...(rest.schema === undefined ? {} : { schema: rest.schema }) });
+                }
+                return result;
+            },
+            page(sql, query, requestOptions) {
+                return request('page', (id) => ({ session: id, sql, ...query }), requestOptions, true);
+            },
+            async transaction(action, requestOptions) {
+                return (await request('transaction', (id) => ({ session: id, action }), requestOptions, false)).active;
+            },
+            export(exportRequest, requestOptions) {
+                return request('export', (id) => ({ session: id, ...exportRequest }), requestOptions, false);
+            },
+            async import(schema, table, importRequest, requestOptions) {
+                return (await request('import', (id) => ({ session: id, schema, table, ...importRequest }), requestOptions, false)).rows;
+            },
+            close
+        };
+        const created = {
+            session,
+            close,
+            update(next) {
+                connection = next;
+            }
+        };
+        return created;
+    };
+    return {
+        test(config, requestOptions) {
+            return send('test', { connection: config }, requestOptions?.signal).then((result) => result.server);
+        },
+        async discover(kind, discoverOptions) {
+            const params = discoverOptions?.context === undefined ? { kind } : { kind, context: discoverOptions.context };
+            return (await send('discover', params, discoverOptions?.signal)).containers;
+        },
+        sample(path, format, header, requestOptions) {
+            return send('sample', { path, format, header }, requestOptions?.signal);
+        },
+        notifySchemaChange,
+        onSchemaChange(listener) {
+            schemaListeners.add(listener);
+            return () => {
+                schemaListeners.delete(listener);
+            };
+        },
+        session(connection, channel = '') {
+            let channels = live.get(connection.id);
+            const existing = channels?.get(channel);
+            if (existing !== undefined && isEqual(existing.session.connection.config, connection.config)) {
+                existing.update(connection);
+                return existing.session;
+            }
+            void existing?.close();
+            const created = createSession(connection, channel);
+            if (channels === undefined) {
+                channels = new Map();
+                live.set(connection.id, channels);
+            }
+            channels.set(channel, created);
+            return created.session;
+        },
+        async disconnect(connectionId) {
+            const existing = [...(live.get(connectionId)?.values() ?? [])];
+            live.delete(connectionId);
+            await Promise.all(existing.map((entry) => entry.close()));
+        },
+        async dispose() {
+            const all = [...live.values()].flatMap((channels) => [...channels.values()]);
+            live.clear();
+            await Promise.all(all.map((entry) => entry.close()));
+        }
+    };
+};

package/dist/client/index.d.ts

@@ -0,0 +1,2 @@
+export { createDatabaseClient, type DatabaseClientOptions } from './client.ts';
+export { DatabaseRequestError, type Connection, type DatabaseClient, type DatabaseSession, type DatabaseTransport, type ExecuteOptions, type ExecuteResult, type ExportRequest, type ExportResult, type ImportRequest, type PageQuery, type RequestOptions, type RowsQuery, type SchemaChange, type TableRef } from './types.ts';

package/dist/client/index.js

@@ -0,0 +1,2 @@
+export { createDatabaseClient } from './client.js';
+export { DatabaseRequestError } from './types.js';

package/dist/client/types.d.ts

@@ -0,0 +1,97 @@
+import type { ConnectionConfig, DatabaseErrorCode, DockerContainer, ExportSource, FileFormat, DatabaseRequest, DatabaseResponse, RowChange, RowKey, RowsResult, SchemaInfo, ServerInfo, StatementResult, TableInfo, TableStructure, Value } from '../protocol/index.ts';
+export type DatabaseTransport = (request: DatabaseRequest) => Promise<DatabaseResponse>;
+export interface Connection {
+    readonly id: string;
+    readonly name: string;
+    readonly config: ConnectionConfig;
+}
+export interface TableRef {
+    readonly connectionId: string;
+    readonly schema: string;
+    readonly table: string;
+}
+export interface RequestOptions {
+    readonly signal?: AbortSignal;
+}
+export interface RowsQuery {
+    readonly where?: string;
+    readonly orderBy?: string;
+    readonly offset: number;
+    readonly limit: number;
+    readonly cellLimit?: number;
+}
+export interface ExecuteOptions extends RequestOptions {
+    readonly schema?: string;
+    readonly limit?: number;
+    readonly cellLimit?: number;
+}
+export interface DatabaseSession {
+    readonly connection: Connection;
+    server(options?: RequestOptions): Promise<ServerInfo>;
+    schemas(options?: RequestOptions): Promise<readonly SchemaInfo[]>;
+    tables(schema: string, options?: RequestOptions): Promise<readonly TableInfo[]>;
+    structure(schema: string, table: string, options?: RequestOptions): Promise<TableStructure>;
+    rows(schema: string, table: string, query: RowsQuery, options?: RequestOptions): Promise<RowsResult>;
+    count(schema: string, table: string, where?: string, options?: RequestOptions): Promise<number>;
+    cell(schema: string, table: string, key: RowKey, column: string, options?: RequestOptions): Promise<Value>;
+    apply(schema: string, table: string, changes: readonly RowChange[], options?: RequestOptions): Promise<number>;
+    execute(sql: string, options?: ExecuteOptions): Promise<ExecuteResult>;
+    page(sql: string, query: PageQuery, options?: RequestOptions): Promise<RowsResult>;
+    transaction(action: 'begin' | 'commit' | 'rollback', options?: RequestOptions): Promise<boolean>;
+    export(request: ExportRequest, options?: RequestOptions): Promise<ExportResult>;
+    import(schema: string, table: string, request: ImportRequest, options?: RequestOptions): Promise<number>;
+    close(): Promise<void>;
+}
+export interface ExecuteResult {
+    readonly results: readonly StatementResult[];
+    readonly inTransaction: boolean;
+}
+export interface PageQuery {
+    readonly schema?: string;
+    readonly offset: number;
+    readonly limit: number;
+    readonly cellLimit?: number;
+}
+export interface ExportRequest {
+    readonly source: ExportSource;
+    readonly format: FileFormat;
+    readonly path: string;
+    readonly header?: boolean;
+    readonly tableName?: string;
+}
+export interface ExportResult {
+    readonly rows: number;
+    readonly bytes: number;
+    readonly elapsedMs: number;
+}
+export interface ImportRequest {
+    readonly path: string;
+    readonly format: 'csv' | 'tsv';
+    readonly header: boolean;
+    readonly columns: readonly (string | null)[];
+}
+export interface SchemaChange {
+    readonly connectionId: string;
+    readonly schema?: string;
+}
+export interface DatabaseClient {
+    test(config: ConnectionConfig, options?: RequestOptions): Promise<ServerInfo>;
+    discover(kind: 'docker', options?: RequestOptions & {
+        readonly context?: string;
+    }): Promise<readonly DockerContainer[]>;
+    sample(path: string, format: 'csv' | 'tsv', header: boolean, options?: RequestOptions): Promise<{
+        readonly columns: readonly string[];
+        readonly rows: readonly (readonly string[])[];
+    }>;
+    notifySchemaChange(change: SchemaChange): void;
+    onSchemaChange(listener: (change: SchemaChange) => void): () => void;
+    session(connection: Connection, channel?: string): DatabaseSession;
+    disconnect(connectionId: string): Promise<void>;
+    dispose(): Promise<void>;
+}
+export declare class DatabaseRequestError extends Error {
+    readonly code: DatabaseErrorCode;
+    readonly sqlState: string | undefined;
+    readonly change: number | undefined;
+    constructor(code: DatabaseErrorCode, message: string, sqlState?: string, change?: number);
+}

package/dist/client/types.js

@@ -0,0 +1,13 @@
+/* A request that failed, with the code of the protocol. */
+export class DatabaseRequestError extends Error {
+    code;
+    sqlState;
+    change;
+    constructor(code, message, sqlState, change) {
+        super(message);
+        this.name = 'DatabaseRequestError';
+        this.code = code;
+        this.sqlState = sqlState;
+        this.change = change;
+    }
+}

package/dist/client-context.d.ts

@@ -0,0 +1,16 @@
+import type { DatabaseAction, DatabaseFiles, DatabaseStorage } from './actions.ts';
+import type { DatabaseClient } from './client/types.ts';
+import type { NumberNotation } from './grid/display.ts';
+export interface DatabaseContextValue {
+    readonly client: DatabaseClient;
+    readonly onAction: ((action: DatabaseAction) => void) | undefined;
+    readonly storage: DatabaseStorage | undefined;
+    readonly files: DatabaseFiles | undefined;
+    readonly numberNotation: NumberNotation;
+}
+export declare const DatabaseContext: import("react").Context<DatabaseContextValue | null>;
+export declare const useDatabaseClient: () => DatabaseClient;
+export declare const useDatabaseAction: () => ((action: DatabaseAction) => void) | undefined;
+export declare const useDatabaseStorage: () => DatabaseStorage | undefined;
+export declare const useDatabaseFiles: () => DatabaseFiles | undefined;
+export declare const useNumberNotation: () => NumberNotation;

package/dist/client-context.js

@@ -0,0 +1,17 @@
+import { createContext, use } from 'react';
+export const DatabaseContext = createContext(null);
+const useDatabaseContext = () => {
+    const value = use(DatabaseContext);
+    if (value === null) {
+        throw new Error('A database view needs a DatabaseProvider above it.');
+    }
+    return value;
+};
+export const useDatabaseClient = () => useDatabaseContext().client;
+/* Hands an action to the app, or `undefined` when the app takes none, so a view can leave out what would go nowhere. */
+export const useDatabaseAction = () => useDatabaseContext().onAction;
+export const useDatabaseStorage = () => useDatabaseContext().storage;
+/* The app's file dialogs; export and import stay hidden without them. */
+export const useDatabaseFiles = () => useDatabaseContext().files;
+/* Read without the guard of the other hooks: a grid drawn on its own, such as in a test, writes numbers as the database does. */
+export const useNumberNotation = () => use(DatabaseContext)?.numberNotation ?? 'database';