@adecore/database 0.0.1 → 0.16.0-beta.0

package/src/client/client.ts

@@ -0,0 +1,324 @@
+import type { ConnectionConfig, DatabaseMethod, DatabaseParams, DatabaseRequest, DatabaseResult, ServerInfo } from '../protocol/index.ts';
+import {
+    DatabaseRequestError,
+    type Connection,
+    type DatabaseClient,
+    type DatabaseSession,
+    type DatabaseTransport,
+    type ExecuteOptions,
+    type RequestOptions,
+    type SchemaChange
+} from './types.ts';
+
+export interface DatabaseClientOptions {
+    /* Makes the id of a request. `crypto.randomUUID()` when left out. */
+    readonly createId?: () => string;
+}
+
+interface Opened {
+    readonly session: string;
+    readonly server: ServerInfo;
+}
+
+const cancelledError = (): DatabaseRequestError => new DatabaseRequestError('cancelled', 'The request was cancelled.');
+
+const isUnknownSession = (error: unknown): boolean => 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: string): boolean => 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: unknown, right: unknown): boolean => {
+    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 as Record<string, unknown>)[key] !== undefined);
+    const rightKeys = Object.keys(right).filter((key) => (right as Record<string, unknown>)[key] !== undefined);
+
+    return (
+        leftKeys.length === rightKeys.length &&
+        leftKeys.every((key) => isEqual((left as Record<string, unknown>)[key], (right as Record<string, unknown>)[key]))
+    );
+};
+
+/* Rejects with `cancelled` as soon as the signal aborts, without waiting for the promise. */
+const raceAbort = <T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> => {
+    if (signal === undefined) {
+        return promise;
+    }
+
+    if (signal.aborted) {
+        promise.catch(() => {});
+        return Promise.reject(cancelledError());
+    }
+
+    return new Promise<T>((resolve, reject) => {
+        const onAbort = (): void => reject(cancelledError());
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+};
+
+export const createDatabaseClient = (transport: DatabaseTransport, options: DatabaseClientOptions = {}): DatabaseClient => {
+    const createId = options.createId ?? (() => crypto.randomUUID());
+    const live = new Map<string, Map<string, ReturnType<typeof createSession>>>();
+    const schemaListeners = new Set<(change: SchemaChange) => void>();
+
+    const notifySchemaChange = (change: SchemaChange): void => {
+        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 <M extends DatabaseMethod>(method: M, params: DatabaseParams<M>, signal?: AbortSignal): Promise<DatabaseResult<M>> => {
+        if (signal?.aborted) {
+            throw cancelledError();
+        }
+
+        const id = createId();
+        const request = { id, method, params } as DatabaseRequest;
+
+        return new Promise<DatabaseResult<M>>((resolve, reject) => {
+            const onAbort = (): void => {
+                const cancel = { id: createId(), method: 'cancel', params: { request: id } } as DatabaseRequest;
+                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 as {
+                            ok: boolean;
+                            result?: unknown;
+                            error?: { code: never; message: string; sqlState?: string; change?: number };
+                        };
+
+                        if (ok) {
+                            resolve(result as DatabaseResult<M>);
+                        } else {
+                            reject(new DatabaseRequestError(error!.code, error!.message, error!.sqlState, error!.change));
+                        }
+                    },
+                    (error: unknown) => reject(new DatabaseRequestError('helper-unavailable', error instanceof Error ? error.message : String(error)))
+                )
+                .finally(() => signal?.removeEventListener('abort', onAbort));
+        });
+    };
+
+    const createSession = (initial: Connection, channel: string) => {
+        let connection = initial;
+        let opened: Opened | null = null;
+        let opening: Promise<Opened> | null = null;
+
+        /* A session that was closed and is used again is findable again, so `disconnect` and `dispose` reach it. */
+        const track = (): void => {
+            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 = (): Promise<Opened> => {
+            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 <M extends DatabaseMethod>(
+            method: M,
+            build: (session: string) => DatabaseParams<M>,
+            requestOptions: RequestOptions | undefined,
+            retry: boolean
+        ): Promise<DatabaseResult<M>> => {
+            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 (): Promise<void> => {
+            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: DatabaseSession = {
+            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: string) => (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?: 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): void {
+                connection = next;
+            }
+        };
+        return created;
+    };
+
+    return {
+        test(config: ConnectionConfig, requestOptions?: 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/src/client/index.ts

@@ -0,0 +1,18 @@
+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/src/client/types.ts

@@ -0,0 +1,161 @@
+import type {
+    ConnectionConfig,
+    DatabaseErrorCode,
+    DockerContainer,
+    ExportSource,
+    FileFormat,
+    DatabaseRequest,
+    DatabaseResponse,
+    RowChange,
+    RowKey,
+    RowsResult,
+    SchemaInfo,
+    ServerInfo,
+    StatementResult,
+    TableInfo,
+    TableStructure,
+    Value
+} from '../protocol/index.ts';
+
+/* How the page reaches the host: the app carries the request over its own channel and hands back what the host answered. */
+export type DatabaseTransport = (request: DatabaseRequest) => Promise<DatabaseResponse>;
+
+/* A connection a person saved, as the manager lists it and the app stores it. */
+export interface Connection {
+    /* Stable across edits, so the client keeps one session per connection. */
+    readonly id: string;
+    readonly name: string;
+    readonly config: ConnectionConfig;
+}
+
+/* A table or a view in a connection. */
+export interface TableRef {
+    readonly connectionId: string;
+    readonly schema: string;
+    readonly table: string;
+}
+
+export interface RequestOptions {
+    /* Aborting sends a `cancel` for the request, which then rejects with code `cancelled`. */
+    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;
+}
+
+/*
+ * One open connection. It opens on its first request, and opens again when the host lost it (a helper
+ * that exited); a read is then sent once more, a write or an `execute` fails with `unknown-session`,
+ * since nobody can tell whether it ran.
+ */
+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>;
+    /* Resolves whether a transaction is open after the action. */
+    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)[];
+}
+
+/* What changed in the shape of a database, so a tree or a structure view that shows it loads it again. */
+export interface SchemaChange {
+    readonly connectionId: string;
+    /* `undefined` when the statement did not say which schema, which reloads every schema of the connection. */
+    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[])[] }>;
+    /*
+     * Tells every listener the shape of a database changed. The client calls it itself after an `execute`
+     * that ran `CREATE`, `ALTER`, `DROP`, `RENAME` or `TRUNCATE`; a view that changes the shape another way calls it too.
+     */
+    notifySchemaChange(change: SchemaChange): void;
+    /* Returns the function that stops listening. */
+    onSchemaChange(listener: (change: SchemaChange) => void): () => void;
+    /*
+     * The session of this connection on a channel, the same object on every call. Each channel is its own
+     * session on the host, so a transaction on one does not reach the others. A connection whose config
+     * changed gets a new one, and the old one closes.
+     */
+    session(connection: Connection, channel?: string): DatabaseSession;
+    /* Closes every channel of the connection. */
+    disconnect(connectionId: string): Promise<void>;
+    dispose(): Promise<void>;
+}
+
+/* A request that failed, with the code of the protocol. */
+export class DatabaseRequestError extends Error {
+    readonly code: DatabaseErrorCode;
+    readonly sqlState: string | undefined;
+    readonly change: number | undefined;
+
+    constructor(code: DatabaseErrorCode, message: string, sqlState?: string, change?: number) {
+        super(message);
+        this.name = 'DatabaseRequestError';
+        this.code = code;
+        this.sqlState = sqlState;
+        this.change = change;
+    }
+}

package/src/client-context.ts

@@ -0,0 +1,35 @@
+import { createContext, use } 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 DatabaseContextValue {
+    readonly client: DatabaseClient;
+    readonly onAction: ((action: DatabaseAction) => void) | undefined;
+    readonly storage: DatabaseStorage | undefined;
+    readonly files: DatabaseFiles | undefined;
+    readonly numberNotation: NumberNotation;
+}
+
+export const DatabaseContext = createContext<DatabaseContextValue | null>(null);
+
+const useDatabaseContext = (): DatabaseContextValue => {
+    const value = use(DatabaseContext);
+    if (value === null) {
+        throw new Error('A database view needs a DatabaseProvider above it.');
+    }
+    return value;
+};
+
+export const useDatabaseClient = (): DatabaseClient => 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 = (): ((action: DatabaseAction) => void) | undefined => useDatabaseContext().onAction;
+
+export const useDatabaseStorage = (): DatabaseStorage | undefined => useDatabaseContext().storage;
+
+/* The app's file dialogs; export and import stay hidden without them. */
+export const useDatabaseFiles = (): DatabaseFiles | undefined => 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 = (): NumberNotation => use(DatabaseContext)?.numberNotation ?? 'database';