@async/db 0.2.0

package/dist/shared/operations.js

@@ -0,0 +1,302 @@
+import { dbError } from './errors.js';
+const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+export function normalizeOperationTemplate(input) {
+    if (typeof input === 'string') {
+        return normalizeStringOperation(input);
+    }
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        throw dbError('OPERATION_INVALID_TEMPLATE', 'Registered operation must be a REST or GraphQL template.', {
+            hint: 'Use "/users/{id}.json?select=id,name", { method: "GET", path: "/users/{id}.json", query: { select: "id,name" } }, or { query: "{ users { id } }" }.',
+        });
+    }
+    const template = input;
+    if (template.ref && !template.path && !template.query) {
+        return {
+            name: stringValue(template.name),
+            ref: String(template.ref),
+        };
+    }
+    if (template.kind === 'graphql' || isGraphqlTemplateObject(template)) {
+        return normalizeGraphqlOperation(template);
+    }
+    const method = normalizeMethod(template.method ?? 'GET');
+    const operationPath = normalizePath(template.path ?? '/');
+    const query = normalizeQuery(template.query);
+    const normalized = {
+        method,
+        path: operationPath,
+    };
+    if (template.name) {
+        normalized.name = String(template.name);
+    }
+    if (template.ref) {
+        normalized.ref = String(template.ref);
+    }
+    if (query && Object.keys(query).length > 0) {
+        normalized.query = query;
+    }
+    if ('body' in template) {
+        normalized.body = template.body;
+    }
+    if (template.variables && typeof template.variables === 'object' && !Array.isArray(template.variables)) {
+        normalized.variables = stableObject(template.variables);
+    }
+    return normalized;
+}
+export function canonicalOperation(input) {
+    const operation = normalizeOperationTemplate(input);
+    if (operation.kind === 'graphql') {
+        const canonical = {
+            kind: 'graphql',
+            query: String(operation.query ?? ''),
+        };
+        if (operation.operationName) {
+            canonical.operationName = operation.operationName;
+        }
+        if (operation.variables) {
+            canonical.variables = stableObject(operation.variables);
+        }
+        return canonical;
+    }
+    const canonical = {
+        method: operation.method,
+        path: operation.path,
+    };
+    if (operation.query) {
+        canonical.query = typeof operation.query === 'string'
+            ? operation.query
+            : stableObject(operation.query);
+    }
+    if ('body' in operation) {
+        canonical.body = operation.body;
+    }
+    return canonical;
+}
+export function operationRequest(input, variables = {}) {
+    const operation = normalizeOperationTemplate(input);
+    if (operation.ref && !operation.path && operation.kind !== 'graphql') {
+        return {
+            ref: operation.ref,
+        };
+    }
+    if (operation.kind === 'graphql') {
+        return graphqlOperationRequest(operation, variables);
+    }
+    const placeholders = placeholdersForOperation(operation);
+    const provided = Object.keys(variables ?? {});
+    const missing = [...placeholders].filter((name) => !(name in (variables ?? {})));
+    const extra = provided.filter((name) => !placeholders.has(name));
+    if (missing.length > 0) {
+        throw dbError('OPERATION_VARIABLE_MISSING', `Operation is missing variable "${missing[0]}".`, {
+            status: 400,
+            hint: `Pass variables for: ${[...placeholders].join(', ')}.`,
+            details: { missing, expectedVariables: [...placeholders] },
+        });
+    }
+    if (extra.length > 0) {
+        throw dbError('OPERATION_VARIABLE_UNKNOWN', `Operation received unknown variable "${extra[0]}".`, {
+            status: 400,
+            hint: `Only pass variables used by this operation: ${[...placeholders].join(', ')}.`,
+            details: { extra, expectedVariables: [...placeholders] },
+        });
+    }
+    const operationPath = substitutePath(String(operation.path ?? '/'), variables);
+    const query = substituteValue(operation.query ?? {}, variables);
+    const body = 'body' in operation ? substituteValue(operation.body, variables) : undefined;
+    return {
+        method: operation.method,
+        path: pathWithQuery(operationPath, query),
+        body,
+    };
+}
+export function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function normalizeStringOperation(input) {
+    const trimmed = input.trim();
+    const [maybeMethod, ...rest] = trimmed.split(/\s+/);
+    const hasMethod = HTTP_METHODS.has(maybeMethod.toUpperCase());
+    const method = hasMethod ? maybeMethod.toUpperCase() : 'GET';
+    const target = hasMethod ? rest.join(' ') : trimmed;
+    const url = new URL(target, 'http://db.local');
+    const query = Object.fromEntries([...url.searchParams.entries()].sort(([left], [right]) => left.localeCompare(right)));
+    const normalized = {
+        method,
+        path: normalizePath(decodeURIComponent(url.pathname)),
+    };
+    if (Object.keys(query).length > 0) {
+        normalized.query = query;
+    }
+    return normalized;
+}
+function normalizeGraphqlOperation(input) {
+    if (typeof input.query !== 'string' || input.query.trim() === '') {
+        throw dbError('OPERATION_INVALID_GRAPHQL_QUERY', 'GraphQL operation query must be a non-empty string.', {
+            status: 400,
+            hint: 'Use { query: "query GetUser { users { id } }" }.',
+        });
+    }
+    const normalized = {
+        kind: 'graphql',
+        query: input.query,
+    };
+    if (input.name) {
+        normalized.name = String(input.name);
+    }
+    if (input.ref) {
+        normalized.ref = String(input.ref);
+    }
+    if (input.operationName !== undefined && input.operationName !== null) {
+        normalized.operationName = String(input.operationName);
+    }
+    if (input.variables !== undefined) {
+        if (!input.variables || typeof input.variables !== 'object' || Array.isArray(input.variables)) {
+            throw dbError('OPERATION_INVALID_GRAPHQL_VARIABLES', 'GraphQL operation variables must be an object.', {
+                status: 400,
+                hint: 'Use variables such as { id: "{id}" }.',
+            });
+        }
+        normalized.variables = stableObject(input.variables);
+    }
+    return normalized;
+}
+function isGraphqlTemplateObject(input) {
+    return !input.path && typeof input.query === 'string' && !input.method && !('body' in input);
+}
+function graphqlOperationRequest(operation, variables = {}) {
+    const placeholders = new Set();
+    if (operation.variables) {
+        collectPlaceholders(operation.variables, placeholders);
+    }
+    const provided = Object.keys(variables ?? {});
+    const missing = [...placeholders].filter((name) => !(name in (variables ?? {})));
+    const extra = operation.variables
+        ? provided.filter((name) => placeholders.size > 0 && !placeholders.has(name))
+        : [];
+    if (missing.length > 0) {
+        throw dbError('OPERATION_VARIABLE_MISSING', `Operation is missing variable "${missing[0]}".`, {
+            status: 400,
+            hint: `Pass variables for: ${[...placeholders].join(', ')}.`,
+            details: { missing, expectedVariables: [...placeholders] },
+        });
+    }
+    if (extra.length > 0) {
+        throw dbError('OPERATION_VARIABLE_UNKNOWN', `Operation received unknown variable "${extra[0]}".`, {
+            status: 400,
+            hint: `Only pass variables used by this operation: ${[...placeholders].join(', ')}.`,
+            details: { extra, expectedVariables: [...placeholders] },
+        });
+    }
+    return {
+        kind: 'graphql',
+        query: String(operation.query ?? ''),
+        variables: operation.variables ? substituteValue(operation.variables, variables) : (variables ?? {}),
+        operationName: operation.operationName ?? null,
+    };
+}
+function normalizeMethod(value) {
+    const method = String(value ?? 'GET').toUpperCase();
+    if (!HTTP_METHODS.has(method)) {
+        throw dbError('OPERATION_UNSUPPORTED_METHOD', `Operation method "${method}" is not supported.`, {
+            status: 400,
+            hint: 'Use GET, POST, PUT, PATCH, or DELETE.',
+            details: { method },
+        });
+    }
+    return method;
+}
+function normalizePath(value) {
+    const path = String(value ?? '/');
+    return path.startsWith('/') ? path : `/${path}`;
+}
+function normalizeQuery(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === 'string') {
+        return Object.fromEntries([...new URLSearchParams(value).entries()].sort(([left], [right]) => left.localeCompare(right)));
+    }
+    if (typeof value === 'object' && !Array.isArray(value)) {
+        return stableObject(value);
+    }
+    throw dbError('OPERATION_INVALID_QUERY', 'Operation query must be an object or query string.', {
+        status: 400,
+        hint: 'Use { select: "id,name" } or "select=id,name".',
+    });
+}
+function stableObject(value) {
+    return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)));
+}
+function placeholdersForOperation(operation) {
+    const names = new Set();
+    collectPlaceholders(operation.path, names);
+    collectPlaceholders(operation.query, names);
+    collectPlaceholders(operation.body, names);
+    return names;
+}
+function collectPlaceholders(value, names) {
+    if (typeof value === 'string') {
+        for (const match of value.matchAll(/\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g)) {
+            names.add(match[1] ?? match[2]);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            collectPlaceholders(item, names);
+        }
+        return;
+    }
+    if (value && typeof value === 'object') {
+        for (const item of Object.values(value)) {
+            collectPlaceholders(item, names);
+        }
+    }
+}
+function substitutePath(path, variables) {
+    return path.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => encodeURIComponent(String(variables[name])));
+}
+function substituteValue(value, variables) {
+    if (typeof value === 'string') {
+        const exactVariable = value.match(/^\$([A-Za-z_][A-Za-z0-9_]*)$/) ?? value.match(/^\{([A-Za-z_][A-Za-z0-9_]*)\}$/);
+        if (exactVariable) {
+            return variables[exactVariable[1]];
+        }
+        return value
+            .replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => String(variables[name]))
+            .replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, name) => String(variables[name]));
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => substituteValue(item, variables));
+    }
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, substituteValue(item, variables)]));
+    }
+    return value;
+}
+function pathWithQuery(path, query) {
+    const entries = Object.entries(query ?? {}).filter(([, value]) => value !== undefined);
+    if (entries.length === 0) {
+        return path;
+    }
+    const params = new URLSearchParams();
+    for (const [key, value] of entries) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                params.append(key, String(item));
+            }
+            continue;
+        }
+        params.set(key, String(value));
+    }
+    return `${path}?${params.toString().replaceAll('%2C', ',')}`;
+}
+function stringValue(value) {
+    return value === undefined || value === null ? undefined : String(value);
+}

package/dist/sqlite.d.ts

@@ -0,0 +1,24 @@
+import type { DbOptions, Db } from './index.d.ts';
+
+export type SqliteDbOptions = DbOptions & {
+  file?: string;
+  storage?: {
+    kind?: 'sqlite';
+    file?: string;
+  };
+};
+
+export function openSqliteDb(options?: SqliteDbOptions): Promise<Db>;
+export function sqliteStore(options?: { file?: string }): unknown;
+export const sqliteStoreCapabilities: {
+  writable: true;
+  persistence: 'local-sqlite';
+  atomicity: 'resource';
+  liveEvents: true;
+  staticExport: false;
+  production: 'small-local';
+};
+export function migrateSqliteDb(database: unknown, resources: unknown[]): void;
+export class SqliteDb {}
+export class SqliteDbCollection {}
+export class SqliteDbDocument {}

package/dist/sqlite.js

@@ -0,0 +1 @@
+export { migrateSqliteDb, openSqliteDb, sqliteStore, sqliteStoreCapabilities, SqliteDb, SqliteDbCollection, SqliteDbDocument, } from './integrations/sqlite.js';

package/dist/state.d.ts

@@ -0,0 +1 @@
+export { readJsonState, statePathForResource, withJsonStateWrite, writeJsonState } from './features/runtime/state.js';

package/dist/state.js

@@ -0,0 +1 @@
+export { readJsonState, statePathForResource, withJsonStateWrite, writeJsonState } from './features/runtime/state.js';

package/dist/sync.d.ts

@@ -0,0 +1 @@
+export { applyDefaultsToRecord, applyDefaultsToSeed, syncDb, } from './features/sync/index.js';

package/dist/sync.js

@@ -0,0 +1 @@
+export { applyDefaultsToRecord, applyDefaultsToSeed, syncDb, } from './features/sync/index.js';

package/dist/tracing.d.ts

@@ -0,0 +1,95 @@
+type TraceConfig = {
+    enabled?: boolean;
+    slowMs?: number;
+    console?: boolean;
+    events?: boolean;
+    header?: string;
+};
+type TraceSource = boolean | TraceConfig | null | undefined;
+type ResolvedTraceOptions = {
+    enabled: true;
+    slowMs: number;
+    console: boolean;
+    events: boolean;
+    header: string;
+};
+type TraceDetails = Record<string, unknown>;
+type TracePhase = TraceDetails & {
+    name: string;
+    durationMs: number;
+};
+type TraceError = {
+    code: string;
+    message: string;
+};
+type TraceEvent = TraceDetails & {
+    type: 'request-trace';
+    requestId: string;
+    timestamp: string;
+    method: string;
+    pathname: string;
+    queryKeys: string[];
+    route: string | null;
+    resource: string | null;
+    operation: string | null;
+    id: string | null;
+    status: number | null;
+    handled: boolean;
+    durationMs: number;
+    slow: boolean;
+    phases: TracePhase[];
+    error?: TraceError;
+};
+type TraceRequest = {
+    method?: string;
+    url?: string;
+};
+type TraceResponse = {
+    body?: unknown;
+    status?: number;
+    statusCode?: number;
+    setHeader?: (name: string, value: string) => unknown;
+    writeHead?: (status: number, ...args: unknown[]) => unknown;
+};
+type HonoHeaderContext = {
+    header?: (name: string, value: string) => unknown;
+};
+type DbWithTrace = {
+    config?: {
+        server?: {
+            trace?: TraceSource;
+        };
+    };
+    events?: {
+        emit?: (event: TraceEvent) => unknown;
+    };
+};
+type ErrorWithStatus = {
+    code?: unknown;
+    status?: unknown;
+};
+export declare function resolveTraceOptions(explicitTrace: TraceSource, configTrace?: TraceSource): ResolvedTraceOptions | null;
+export declare function createRequestTrace(db: DbWithTrace | null | undefined, request: TraceRequest, options?: {
+    trace?: TraceSource;
+}): RequestTrace | null;
+export declare class RequestTrace {
+    options: ResolvedTraceOptions;
+    start: number;
+    headerAttached: boolean;
+    event: TraceEvent;
+    constructor(options: ResolvedTraceOptions, request: TraceRequest, url: URL);
+    markHandled(response: TraceResponse): void;
+    setRoute(details?: TraceDetails): void;
+    addPhase(name: string, durationMs: number, details?: TraceDetails): void;
+    timeSync<Result>(name: string, fn: () => Result, details?: TraceDetails): Result;
+    time<Result>(name: string, fn: () => Result | Promise<Result>, details?: TraceDetails): Promise<Result>;
+    setError(error: ErrorWithStatus | null | undefined): void;
+    finish(db: DbWithTrace | null | undefined, response: TraceResponse): TraceEvent | null;
+    attachResponseHeader(response: TraceResponse | null | undefined): void;
+    attachHonoHeader(c: HonoHeaderContext | null | undefined): void;
+    captureSerializedError(response: TraceResponse | null | undefined): void;
+}
+export declare function responseStatus(response: TraceResponse | null | undefined): number | null;
+export declare function tracePhase<Result>(trace: RequestTrace | null | undefined, name: string, fn: () => Result | Promise<Result>, details?: TraceDetails): Result | Promise<Result>;
+export declare function tracePhaseSync<Result>(trace: RequestTrace | null | undefined, name: string, fn: () => Result, details?: TraceDetails): Result;
+export {};

package/dist/tracing.js

@@ -0,0 +1,260 @@
+const DEFAULT_TRACE_HEADER = 'x-async-db-request-id';
+export function resolveTraceOptions(explicitTrace, configTrace) {
+    const source = explicitTrace === undefined ? configTrace : explicitTrace;
+    if (source === false || source === undefined || source === null) {
+        return null;
+    }
+    const options = source === true
+        ? {}
+        : typeof source === 'object'
+            ? source
+            : {};
+    if (options.enabled === false) {
+        return null;
+    }
+    return {
+        enabled: true,
+        slowMs: Math.max(0, Number(options.slowMs ?? 0)),
+        console: options.console !== false,
+        events: options.events !== false,
+        header: typeof options.header === 'string' && options.header.trim()
+            ? options.header.trim().toLowerCase()
+            : DEFAULT_TRACE_HEADER,
+    };
+}
+export function createRequestTrace(db, request, options = {}) {
+    const traceOptions = resolveTraceOptions(options.trace, db?.config?.server?.trace);
+    if (!traceOptions) {
+        return null;
+    }
+    const url = new URL(request.url ?? '/', 'http://db.local');
+    return new RequestTrace(traceOptions, request, url);
+}
+export class RequestTrace {
+    options;
+    start;
+    headerAttached;
+    event;
+    constructor(options, request, url) {
+        this.options = options;
+        this.start = now();
+        this.headerAttached = false;
+        this.event = {
+            type: 'request-trace',
+            requestId: requestId(),
+            timestamp: new Date().toISOString(),
+            method: String(request.method ?? 'GET').toUpperCase(),
+            pathname: url.pathname,
+            queryKeys: [...new Set([...url.searchParams.keys()])].sort(),
+            route: null,
+            resource: null,
+            operation: null,
+            id: null,
+            status: null,
+            handled: false,
+            durationMs: 0,
+            slow: false,
+            phases: [],
+        };
+    }
+    markHandled(response) {
+        this.event.handled = true;
+        this.attachResponseHeader(response);
+    }
+    setRoute(details = {}) {
+        for (const [key, value] of Object.entries(details)) {
+            if (value !== undefined && value !== null && value !== '') {
+                this.event[key] = value;
+            }
+        }
+    }
+    addPhase(name, durationMs, details = {}) {
+        const phase = {
+            name,
+            durationMs: roundMs(durationMs),
+        };
+        for (const [key, value] of Object.entries(details)) {
+            if (value !== undefined && value !== null) {
+                phase[key] = value;
+            }
+        }
+        this.event.phases.push(phase);
+    }
+    timeSync(name, fn, details = {}) {
+        const start = now();
+        try {
+            return fn();
+        }
+        finally {
+            this.addPhase(name, now() - start, details);
+        }
+    }
+    async time(name, fn, details = {}) {
+        const start = now();
+        try {
+            return await fn();
+        }
+        finally {
+            this.addPhase(name, now() - start, details);
+        }
+    }
+    setError(error) {
+        if (!error) {
+            return;
+        }
+        if (typeof error.status === 'number') {
+            this.event.status = error.status;
+        }
+        const code = error.code ? String(error.code) : 'ERROR';
+        this.event.error = {
+            code,
+            message: safeErrorMessage(code),
+        };
+    }
+    finish(db, response) {
+        if (!this.event.handled) {
+            return null;
+        }
+        const status = responseStatus(response);
+        if (status !== null) {
+            this.event.status = status;
+        }
+        this.captureSerializedError(response);
+        this.event.durationMs = roundMs(now() - this.start);
+        this.event.slow = this.event.durationMs >= this.options.slowMs;
+        const traceEvent = compactEvent(this.event);
+        if (this.options.events && typeof db?.events?.emit === 'function') {
+            db.events.emit(traceEvent);
+        }
+        if (this.options.console) {
+            writeConsoleTrace(traceEvent);
+        }
+        return traceEvent;
+    }
+    attachResponseHeader(response) {
+        if (this.headerAttached || !response || !this.options.header) {
+            return;
+        }
+        this.headerAttached = true;
+        if (typeof response.setHeader === 'function') {
+            response.setHeader(this.options.header, this.event.requestId);
+            return;
+        }
+        if (typeof response.writeHead !== 'function') {
+            return;
+        }
+        const originalWriteHead = response.writeHead.bind(response);
+        response.writeHead = (status, ...args) => {
+            return originalWriteHead(status, ...withHeader(args, this.options.header, this.event.requestId));
+        };
+    }
+    attachHonoHeader(c) {
+        if (!this.options.header || typeof c?.header !== 'function') {
+            return;
+        }
+        c.header(this.options.header, this.event.requestId);
+    }
+    captureSerializedError(response) {
+        if (this.event.error || typeof response?.body !== 'string' || response.body.trim() === '') {
+            return;
+        }
+        try {
+            const parsed = JSON.parse(response.body);
+            const error = parsed?.error;
+            if (error && typeof error === 'object') {
+                const code = error.code ? String(error.code) : 'ERROR';
+                this.event.error = {
+                    code,
+                    message: safeErrorMessage(code),
+                };
+            }
+        }
+        catch {
+            // Response bodies are not part of trace data; this only observes tests' serialized error envelope.
+        }
+    }
+}
+export function responseStatus(response) {
+    if (typeof response?.status === 'number') {
+        return response.status;
+    }
+    if (typeof response?.statusCode === 'number') {
+        return response.statusCode;
+    }
+    return null;
+}
+export function tracePhase(trace, name, fn, details) {
+    return trace ? trace.time(name, fn, details) : fn();
+}
+export function tracePhaseSync(trace, name, fn, details) {
+    return trace ? trace.timeSync(name, fn, details) : fn();
+}
+function withHeader(args, name, value) {
+    if (args.length === 0) {
+        return [{ [name]: value }];
+    }
+    if (typeof args[0] === 'string') {
+        return [
+            args[0],
+            {
+                ...headerObject(args[1]),
+                [name]: value,
+            },
+            ...args.slice(2),
+        ];
+    }
+    return [
+        {
+            ...headerObject(args[0]),
+            [name]: value,
+        },
+        ...args.slice(1),
+    ];
+}
+function compactEvent(event) {
+    const next = {};
+    for (const [key, value] of Object.entries(event)) {
+        if (value === null || value === undefined) {
+            continue;
+        }
+        if (Array.isArray(value) && value.length === 0) {
+            continue;
+        }
+        next[key] = value;
+    }
+    return next;
+}
+function writeConsoleTrace(event) {
+    const prefix = event.slow ? '[async-db:slow]' : '[async-db]';
+    const fields = [
+        event.route ? `route=${event.route}` : null,
+        event.resource ? `resource=${event.resource}` : null,
+        event.operation ? `op=${event.operation}` : null,
+        event.hook ? `hook=${event.hook}` : null,
+        event.shortCircuit ? 'shortCircuit=true' : null,
+        `requestId=${event.requestId}`,
+    ].filter(Boolean);
+    console.log(`${prefix} ${event.method} ${event.pathname} ${event.status ?? '-'} ${event.durationMs}ms ${fields.join(' ')}`);
+}
+function headerObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function safeErrorMessage(code) {
+    return code ? `Request failed (${code})` : 'Request failed';
+}
+function requestId() {
+    if (typeof globalThis.crypto?.randomUUID === 'function') {
+        return globalThis.crypto.randomUUID();
+    }
+    return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function now() {
+    return typeof globalThis.performance?.now === 'function'
+        ? globalThis.performance.now()
+        : Date.now();
+}
+function roundMs(value) {
+    return Math.round(Number(value) * 1000) / 1000;
+}