@async/db 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,64 @@
+import { createIndexedDbCacheStorage } from './client-cache.js';
+import { type OperationTemplate, type OperationVariables } from './shared/operations.js';
+export { createIndexedDbCacheStorage };
+type ClientBatchingOptions = boolean | {
+    enabled?: boolean;
+    delayMs?: number;
+    dedupe?: boolean | 'reads' | 'all';
+};
+type ClientRequestOptions = {
+    batch?: boolean;
+    cache?: unknown;
+};
+type ClientOptions = {
+    baseUrl?: string;
+    apiBase?: string;
+    restBasePath?: string;
+    graphqlPath?: string;
+    restBatchPath?: string;
+    manifestPath?: string;
+    batching?: ClientBatchingOptions;
+    cache?: unknown;
+};
+type GraphqlRequest = {
+    query: string;
+    variables?: OperationVariables;
+    operationName?: string | null;
+    [key: string]: unknown;
+};
+type RestRequestInput = {
+    method?: string;
+    path?: string;
+    body?: unknown;
+    [key: string]: unknown;
+};
+type RestRequest = {
+    method: string;
+    path: string;
+    body?: unknown;
+};
+type RestResponse = {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+};
+export declare function createDbClient(options?: ClientOptions): {
+    cache: unknown;
+    graphql: {
+        (query: string | GraphqlRequest, variables?: OperationVariables, requestOptions?: ClientRequestOptions): Promise<unknown>;
+        batch: (requests: GraphqlRequest[]) => Promise<unknown[]>;
+        request: /*elided*/ any;
+    };
+    operation: (template: OperationTemplate, variables?: OperationVariables, requestOptions?: ClientRequestOptions) => Promise<unknown>;
+    query: (template: OperationTemplate, variables?: OperationVariables, requestOptions?: ClientRequestOptions) => Promise<unknown>;
+    rest: {
+        (method: string | RestRequestInput, path?: string, body?: unknown, requestOptions?: ClientRequestOptions): Promise<RestResponse>;
+        batch: (requests: RestRequest[]) => Promise<RestResponse[]>;
+        request: /*elided*/ any;
+        get(path: any, requestOptions: any): Promise<RestResponse>;
+        post(path: any, body: any, requestOptions: any): Promise<RestResponse>;
+        patch(path: any, body: any, requestOptions: any): Promise<RestResponse>;
+        put(path: any, body: any, requestOptions: any): Promise<RestResponse>;
+        delete(path: any, requestOptions: any): Promise<RestResponse>;
+    };
+};

package/dist/client.js

@@ -0,0 +1,405 @@
+import { dbError } from './errors.js';
+import { createClientCache, createIndexedDbCacheStorage } from './client-cache.js';
+import { operationRequest } from './shared/operations.js';
+export { createIndexedDbCacheStorage };
+export function createDbClient(options = {}) {
+    rejectRemovedForkOption(options);
+    const baseUrl = options.baseUrl ?? '';
+    const apiBase = normalizeBasePath(options.apiBase ?? '/__db');
+    const restBasePath = options.restBasePath ?? '';
+    const graphqlPath = options.graphqlPath ?? '/graphql';
+    const restBatchPath = options.restBatchPath ?? `${apiBase}/batch`;
+    const manifestPath = options.manifestPath ?? `${apiBase}/manifest.json`;
+    const batching = normalizeBatching(options.batching);
+    const cache = createClientCache({
+        cache: options.cache,
+        cacheNamespace: {
+            baseUrl,
+            apiBase,
+            manifestPath,
+        },
+        restBasePath,
+        fetchManifest: () => getJson(resolveUrl(baseUrl, manifestPath)),
+        createEventSource(path) {
+            if (typeof EventSource !== 'function') {
+                return null;
+            }
+            return new EventSource(resolveUrl(baseUrl, path));
+        },
+    });
+    const graphqlQueue = createQueue((requests) => graphqlBatch(requests), batching, {
+        shouldDedupeRequest: isGraphqlDedupeSafe,
+    });
+    const restQueue = createQueue((requests) => restBatch(requests), batching, {
+        shouldDedupeRequest: isRestDedupeSafe,
+    });
+    async function graphql(query, variables, requestOptions = {}) {
+        const request = typeof query === 'string' ? { query, variables } : query;
+        if (cache.enabled && isGraphqlDedupeSafe(request)) {
+            return cache.executeGraphqlRead(request, () => graphqlDirect(request), requestOptions);
+        }
+        if (shouldBatch(requestOptions, batching)) {
+            const result = await graphqlQueue({ request });
+            cache.recordGraphqlWrite(result);
+            return result;
+        }
+        const result = await graphqlDirect(request);
+        cache.recordGraphqlWrite(result);
+        return result;
+    }
+    async function graphqlDirect(request) {
+        return postJson(resolveUrl(baseUrl, graphqlPath), request);
+    }
+    async function graphqlBatch(requests) {
+        return postJson(resolveUrl(baseUrl, graphqlPath), requests);
+    }
+    async function rest(method, path, body, requestOptions = {}) {
+        const request = normalizeRestRequest(method, path, body);
+        return executeRestRequest(request, requestOptions);
+    }
+    async function executeRestRequest(request, requestOptions = {}) {
+        if (cache.enabled && isRestDedupeSafe(request)) {
+            return cache.executeRestRead(request, () => restDirect(request), requestOptions);
+        }
+        if (shouldBatch(requestOptions, batching)) {
+            const result = await restQueue({ request });
+            cache.recordRestWrite(request, result);
+            return result;
+        }
+        const result = await restDirect(request);
+        cache.recordRestWrite(request, result);
+        return result;
+    }
+    async function restDirect(request) {
+        const init = {
+            method: request.method,
+            headers: {
+                'content-type': 'application/json',
+            },
+        };
+        if (!['GET', 'DELETE'].includes(request.method) && request.body !== undefined) {
+            init.body = JSON.stringify(request.body);
+        }
+        const response = await fetch(resolveUrl(baseUrl, joinPaths(restBasePath, request.path)), init);
+        return {
+            status: response.status,
+            headers: Object.fromEntries(response.headers.entries()),
+            body: await readResponseBody(response),
+        };
+    }
+    async function restBatch(requests) {
+        return postJson(resolveUrl(baseUrl, restBatchPath), requests.map(normalizeRestRequestObject));
+    }
+    async function operation(template, variables = {}, requestOptions = {}) {
+        const request = typeof template === 'string' && !isRestOperationString(template)
+            ? { ref: template }
+            : operationRequest(template, variables);
+        return executeOperationRequest(request, variables, requestOptions);
+    }
+    async function query(template, variables = {}, requestOptions = {}) {
+        const request = typeof template === 'string' && !isRestOperationString(template)
+            ? { ref: template }
+            : operationRequest(template, variables);
+        return executeOperationRequest(request, variables, requestOptions);
+    }
+    async function executeOperationRequest(request, variables, requestOptions) {
+        if (request.ref) {
+            return postJson(resolveUrl(baseUrl, `${apiBase}/operations/${encodeURIComponent(request.ref)}`), {
+                variables,
+            });
+        }
+        if (request.kind === 'graphql') {
+            return graphql({
+                query: request.query,
+                variables: request.variables,
+                operationName: request.operationName,
+            }, undefined, requestOptions);
+        }
+        return executeRestRequest(request, requestOptions).then((result) => result.body);
+    }
+    graphql.batch = graphqlBatch;
+    graphql.request = graphql;
+    rest.batch = restBatch;
+    rest.request = rest;
+    rest.get = (path, requestOptions) => rest('GET', path, undefined, requestOptions);
+    rest.post = (path, body, requestOptions) => rest('POST', path, body, requestOptions);
+    rest.patch = (path, body, requestOptions) => rest('PATCH', path, body, requestOptions);
+    rest.put = (path, body, requestOptions) => rest('PUT', path, body, requestOptions);
+    rest.delete = (path, requestOptions) => rest('DELETE', path, undefined, requestOptions);
+    return {
+        cache: cache.publicApi,
+        graphql,
+        operation,
+        query,
+        rest,
+    };
+}
+function rejectRemovedForkOption(options) {
+    const fork = options.fork;
+    if (fork !== undefined) {
+        throw dbError('CLIENT_FORK_OPTION_REMOVED', 'The HTTP client fork option was removed with fixture-folder fork routes.', {
+            hint: 'Use the package API runtime scope with db.forks.open(name) and tenant.branches.open(name), or pass explicit REST/GraphQL paths for an app-owned tenant route.',
+            details: {
+                fork,
+            },
+        });
+    }
+}
+function normalizeBatching(value) {
+    if (value === true) {
+        return {
+            enabled: true,
+            delayMs: 10,
+            dedupe: 'reads',
+        };
+    }
+    if (!value) {
+        return {
+            enabled: false,
+            delayMs: 10,
+            dedupe: 'reads',
+        };
+    }
+    return {
+        enabled: Boolean(value.enabled),
+        delayMs: Number(value.delayMs ?? 10),
+        dedupe: normalizeDedupeMode(value.dedupe),
+    };
+}
+function normalizeDedupeMode(value) {
+    if (value === false) {
+        return false;
+    }
+    if (value === 'all') {
+        return 'all';
+    }
+    return 'reads';
+}
+function shouldBatch(requestOptions, batching) {
+    if (requestOptions?.batch === false) {
+        return false;
+    }
+    if (requestOptions?.batch === true) {
+        return true;
+    }
+    return batching.enabled;
+}
+function isRestOperationString(value) {
+    const trimmed = String(value ?? '').trim();
+    if (trimmed.startsWith('/')) {
+        return true;
+    }
+    const methodMatch = trimmed.match(/^(GET|POST|PUT|PATCH|DELETE)\s+/i);
+    if (!methodMatch) {
+        return false;
+    }
+    return trimmed.slice(methodMatch[0].length).trimStart().startsWith('/');
+}
+function createQueue(flush, batching, options = {}) {
+    let pending = [];
+    let timer = null;
+    return (item) => new Promise((resolve, reject) => {
+        pending.push({
+            ...item,
+            resolve,
+            reject,
+        });
+        if (!timer) {
+            timer = setTimeout(async () => {
+                const items = pending;
+                pending = [];
+                timer = null;
+                try {
+                    const groups = batching.dedupe ? groupQueuedItems(items, (request) => shouldDedupeRequest(request, batching, options)) : items.map((queued) => ({
+                        request: queued.request,
+                        queued: [queued],
+                    }));
+                    const results = await flush(groups.map((group) => group.request));
+                    groups.forEach((group, index) => {
+                        for (const queued of group.queued) {
+                            queued.resolve(results[index]);
+                        }
+                    });
+                }
+                catch (error) {
+                    items.forEach((queued) => queued.reject(error));
+                }
+            }, batching.delayMs);
+        }
+    });
+}
+function shouldDedupeRequest(request, batching, options) {
+    if (batching.dedupe === 'all') {
+        return true;
+    }
+    if (batching.dedupe === 'reads') {
+        return options.shouldDedupeRequest?.(request) === true;
+    }
+    return false;
+}
+function groupQueuedItems(items, canDedupe) {
+    const groups = [];
+    let readSegment = new Map();
+    for (const item of items) {
+        if (!canDedupe(item.request)) {
+            groups.push({
+                request: item.request,
+                queued: [item],
+            });
+            readSegment = new Map();
+            continue;
+        }
+        const key = stableStringify(item.request);
+        const group = readSegment.get(key);
+        if (group) {
+            group.queued.push(item);
+        }
+        else {
+            const nextGroup = {
+                request: item.request,
+                queued: [item],
+            };
+            readSegment.set(key, nextGroup);
+            groups.push(nextGroup);
+        }
+    }
+    return groups;
+}
+function isGraphqlDedupeSafe(request) {
+    const query = String(request.query ?? '').trimStart();
+    return !/^(mutation|subscription)\b/.test(query);
+}
+function isRestDedupeSafe(request) {
+    return String(request.method ?? 'GET').toUpperCase() === 'GET';
+}
+async function postJson(url, body) {
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (error) {
+        throw dbError('CLIENT_FETCH_FAILED', `db client could not reach ${url}.`, {
+            hint: 'Make sure async-db serve is running and baseUrl points at the correct host and port.',
+            details: {
+                url,
+                cause: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+    const responseBody = await readResponseBody(response);
+    if (response.ok === false) {
+        throw dbError('CLIENT_HTTP_ERROR', `db client request to ${url} failed with HTTP ${response.status}.`, {
+            status: response.status,
+            hint: 'Inspect details.responseBody for the server error payload.',
+            details: {
+                url,
+                status: response.status,
+                responseBody,
+            },
+        });
+    }
+    return responseBody;
+}
+async function getJson(url) {
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                accept: 'application/json',
+            },
+        });
+    }
+    catch (error) {
+        throw dbError('CLIENT_FETCH_FAILED', `db client could not reach ${url}.`, {
+            hint: 'Make sure async-db serve is running and baseUrl points at the correct host and port.',
+            details: {
+                url,
+                cause: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+    const responseBody = await readResponseBody(response);
+    if (response.ok === false) {
+        throw dbError('CLIENT_HTTP_ERROR', `db client request to ${url} failed with HTTP ${response.status}.`, {
+            status: response.status,
+            hint: 'Inspect details.responseBody for the server error payload.',
+            details: {
+                url,
+                status: response.status,
+                responseBody,
+            },
+        });
+    }
+    return responseBody;
+}
+async function readResponseBody(response) {
+    const text = await response.text();
+    if (!text) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function normalizeRestRequest(method, path, body) {
+    if (typeof method === 'object' && method !== null) {
+        return normalizeRestRequestObject(method);
+    }
+    return normalizeRestRequestObject({
+        method: String(method),
+        path,
+        body,
+    });
+}
+function normalizeRestRequestObject(request) {
+    if (!request || typeof request !== 'object' || Array.isArray(request)) {
+        throw dbError('CLIENT_REST_INVALID_REQUEST', 'REST request must be an object or method/path arguments.', {
+            hint: 'Use client.rest("GET", "/users") or client.rest({ method: "GET", path: "/users" }).',
+        });
+    }
+    return {
+        method: String(request.method ?? 'GET').toUpperCase(),
+        path: request.path ?? '/',
+        body: request.body,
+    };
+}
+function resolveUrl(baseUrl, path) {
+    if (!baseUrl) {
+        return path;
+    }
+    return new URL(path, baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`).href;
+}
+function joinPaths(basePath, requestPath) {
+    if (!basePath) {
+        return requestPath;
+    }
+    const normalizedBase = `/${String(basePath).replace(/^\/+/, '').replace(/\/+$/, '')}`;
+    const normalizedPath = `/${String(requestPath ?? '/').replace(/^\/+/, '')}`;
+    return `${normalizedBase}${normalizedPath === '/' ? '' : normalizedPath}`;
+}
+function normalizeBasePath(value) {
+    const path = `/${String(value ?? '').replace(/^\/+/, '').replace(/\/+$/, '')}`;
+    return path === '/' ? '' : path;
+}
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    if (isRecord(value)) {
+        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/config-public.d.ts

@@ -0,0 +1 @@
+export { defineConfig, mergeManifest, parseFixturePath, resourceNameFromPath } from './features/config/public.js';

package/dist/config-public.js

@@ -0,0 +1 @@
+export { defineConfig, mergeManifest, parseFixturePath, resourceNameFromPath } from './features/config/public.js';

package/dist/config.d.ts

@@ -0,0 +1,54 @@
+import type { DbOptions } from './index.d.ts';
+
+export type {
+  DbSourceReader,
+  DbSourceReaderContext,
+  DbSourceReaderResult,
+  DbSourceReaderDataResult,
+  DbSourceReaderSchemaResult,
+  DbSourcesOptions,
+  DbCustomStore,
+  DbCustomStoreFactory,
+  DbStoreName,
+  DbStoreOptions,
+  DbStoresOptions,
+} from './index.d.ts';
+
+/**
+ * db project configuration.
+ *
+ * Use with `// @ts-check` in `db.config.mjs` for editor autocomplete:
+ *
+ * ```js
+ * import { defineConfig } from '@async/db/config';
+ *
+ * export default defineConfig({
+ *   dbDir: './db',
+ * });
+ * ```
+ */
+export type DbConfig = DbOptions;
+
+/**
+ * Type-only helper for authoring `db.config.mjs`.
+ *
+ * It returns the config unchanged at runtime and exists so JavaScript config
+ * files get autocomplete, literal value checking, and inline JSDoc.
+ */
+export function defineConfig<Config extends DbConfig>(config: Config): Config;
+
+/** Deep-merge JSON-serializable manifest patches without mutating inputs. */
+export function mergeManifest<Base, Patch>(base: Base, patch: Patch): Base & Patch;
+
+/** Derive a resource name from a fixture path using db naming strategies. */
+export function resourceNameFromPath(file: string, options?: { strategy?: 'basename' | 'folder-prefixed' | 'path' }): string;
+
+/** Parse a fixture path into folder, basename, filename, and extension metadata. */
+export function parseFixturePath(file: string): {
+  file: string;
+  folders: string[];
+  folder: string | null;
+  filename: string;
+  basename: string;
+  extension: string;
+};

package/dist/config.js

@@ -0,0 +1,2 @@
+export { DEFAULT_CONFIG } from './features/config/defaults.js';
+export { loadConfig, mergeDeep } from './features/config/load.js';

package/dist/csv.d.ts

@@ -0,0 +1 @@
+export { parseCsvRecords, parseCsvRows } from './shared/csv.js';

package/dist/csv.js

@@ -0,0 +1 @@
+export { parseCsvRecords, parseCsvRows } from './shared/csv.js';

package/dist/db.d.ts

@@ -0,0 +1,3 @@
+export { Db, openDb, stateFileForDebug } from './features/runtime/db.js';
+export { DbCollection } from './features/runtime/collection.js';
+export { DbDocument } from './features/runtime/document.js';

package/dist/db.js

@@ -0,0 +1,3 @@
+export { Db, openDb, stateFileForDebug } from './features/runtime/db.js';
+export { DbCollection } from './features/runtime/collection.js';
+export { DbDocument } from './features/runtime/document.js';

package/dist/doctor.d.ts

@@ -0,0 +1 @@
+export { runDbDoctor } from './features/doctor/index.js';

package/dist/doctor.js

@@ -0,0 +1 @@
+export { runDbDoctor } from './features/doctor/index.js';

package/dist/errors.d.ts

@@ -0,0 +1 @@
+export { describeValue, graphqlError, DbError, dbError, listChoices, serializeError, } from './shared/errors.js';

package/dist/errors.js

@@ -0,0 +1 @@
+export { describeValue, graphqlError, DbError, dbError, listChoices, serializeError, } from './shared/errors.js';

package/dist/features/config/defaults.d.ts

@@ -0,0 +1,98 @@
+type NullableOutput = string | null;
+type DefaultConfig = {
+    dbDir: string;
+    sourceDir: string;
+    stateDir: string;
+    outputs: {
+        stateDir: string;
+        types: string;
+        committedTypes: NullableOutput;
+        schemaManifest: NullableOutput;
+        viewerManifest: NullableOutput;
+        operationRegistry: NullableOutput;
+        operationRefs: NullableOutput;
+        honoStarterDir: string;
+    };
+    schemaOutFile: NullableOutput;
+    viewerManifestOutFile: NullableOutput;
+    schemaManifest: Record<string, unknown>;
+    sources: {
+        readers: unknown[];
+        writePolicy: 'preserve' | string;
+    };
+    stores: {
+        default: string;
+        json: {
+            driver: string;
+        };
+    };
+    types: {
+        enabled: boolean;
+        outFile: string;
+        commitOutFile: NullableOutput;
+        useReadonly: boolean;
+        emitComments: boolean;
+        exportRuntimeHelpers: boolean;
+    };
+    schema: {
+        source: 'auto' | string;
+        allowJsonc: boolean;
+        autoModulePackageJson: boolean;
+        standardSchema: boolean;
+        unknownFields: 'warn' | string;
+        additiveChanges: 'auto' | string;
+        destructiveChanges: 'manual' | string;
+        typeChanges: 'manual' | string;
+    };
+    defaults: {
+        applyOnCreate: boolean;
+        applyOnSafeMigration: boolean;
+    };
+    seed: {
+        generateFromSchema: boolean;
+        generatedCount: number;
+    };
+    collections: Record<string, unknown>;
+    resources: {
+        naming: 'basename' | string;
+    };
+    server: {
+        apiBase: string;
+        dataPath: string | false;
+        host: string;
+        port: number;
+        maxBodyBytes: number;
+        viewerLinks: unknown[];
+    };
+    rest: {
+        enabled: boolean;
+    };
+    graphql: {
+        enabled: boolean;
+        path: string;
+    };
+    operations: {
+        enabled: boolean;
+        sourceDir: string;
+        outFile: NullableOutput;
+        refsOutFile: NullableOutput;
+        acceptRefs: 'both' | string;
+        registry: Record<string, unknown>;
+    };
+    mock: {
+        delay: [number, number] | number | false;
+        errors: unknown;
+    };
+    generate: {
+        hono: {
+            outDir: string;
+            api: string[];
+            db: string;
+            app: string;
+            runtime: string;
+            seed: boolean;
+        };
+    };
+};
+export declare const DEFAULT_CONFIG: DefaultConfig;
+export {};