@async/db 0.2.0

package/dist/features/http/registry.js

@@ -0,0 +1,86 @@
+import { handleGraphqlRequest } from '../../graphql/http.js';
+import { sendJson } from '../../rest/handler.js';
+export function defaultHttpFeatureRegistry() {
+    return createHttpFeatureRegistry([
+        runtimeLogHttpFeature(),
+        graphqlDisabledHttpFeature(),
+        graphqlHttpFeature(),
+    ]);
+}
+export function createHttpFeatureRegistry(features) {
+    return {
+        matches(context, options = {}) {
+            return features.some((feature) => featureInPhase(feature, options.phase) && feature.match(context));
+        },
+        async handle(context, options = {}) {
+            for (const feature of features) {
+                if (featureInPhase(feature, options.phase) && feature.match(context)) {
+                    await feature.handle(context);
+                    return true;
+                }
+            }
+            return false;
+        },
+    };
+}
+function runtimeLogHttpFeature() {
+    return {
+        name: 'runtime-log',
+        phase: 'preMock',
+        match({ request, url, routes }) {
+            return request.method === 'GET' && url.pathname === routes.logPath;
+        },
+        async handle({ request, response, db }) {
+            subscribeRuntimeLog(request, response, db);
+        },
+    };
+}
+function graphqlHttpFeature() {
+    return {
+        name: 'graphql',
+        phase: 'postMock',
+        match({ db, url, routes }) {
+            return db.config.graphql?.enabled !== false && url.pathname === routes.graphqlPath;
+        },
+        async handle({ db, request, response }) {
+            await handleGraphqlRequest(db, request, response);
+        },
+    };
+}
+function graphqlDisabledHttpFeature() {
+    return {
+        name: 'graphql-disabled',
+        phase: 'preMock',
+        match({ db, url, routes }) {
+            return db.config.graphql?.enabled === false && url.pathname === routes.graphqlPath;
+        },
+        async handle({ response, routes }) {
+            sendJson(response, 404, {
+                error: {
+                    code: 'GRAPHQL_DISABLED',
+                    message: 'GraphQL endpoint is disabled.',
+                    hint: 'Set graphql.enabled to true in db.config.mjs to enable the GraphQL endpoint.',
+                    details: {
+                        graphqlEnabled: false,
+                        path: routes.graphqlPath,
+                    },
+                },
+            });
+        },
+    };
+}
+function featureInPhase(feature, phase) {
+    return !phase || (feature.phase ?? 'postMock') === phase;
+}
+function subscribeRuntimeLog(request, response, db) {
+    response.writeHead(200, {
+        'content-type': 'text/event-stream; charset=utf-8',
+        'cache-control': 'no-cache, no-transform',
+        connection: 'keep-alive',
+    });
+    response.write(': connected\n\n');
+    const unsubscribe = db.events.subscribe((event) => {
+        response.write(`event: db-log\ndata: ${JSON.stringify(event)}\n\n`);
+    });
+    request.on('close', unsubscribe);
+}

package/dist/features/operations/index.d.ts

@@ -0,0 +1,49 @@
+import { type OperationTemplate, type RegisteredOperation } from '../../shared/operations.js';
+type OperationConfig = {
+    cwd?: string;
+    operations?: {
+        sourceDir?: string;
+        outFile?: string | null;
+        refsOutFile?: string | null;
+    };
+};
+type BuildOperationOptions = {
+    outFile?: string | null;
+    refsOutFile?: string | null;
+    generatedAt?: string;
+    operations?: OperationTemplate[];
+    write?: boolean;
+    createDirectory?: boolean;
+};
+type OperationRef = {
+    name: string;
+    ref: string;
+};
+type OperationManifest = {
+    version: 1;
+    kind: 'db.operations';
+    generatedAt: string;
+    operations: Record<string, RegisteredOperation>;
+};
+type OperationRefsManifest = {
+    version: 1;
+    kind: 'db.operationRefs';
+    generatedAt: string;
+    operations: Record<string, OperationRef>;
+};
+type OperationContract = {
+    version: 1;
+    kind: 'db.operationContract';
+    operations: Record<string, OperationRef>;
+};
+export declare function hashOperation(input: OperationTemplate): string;
+export declare function buildOperationManifest(config: OperationConfig, options?: BuildOperationOptions): Promise<{
+    manifest: OperationManifest;
+    refs: OperationRefsManifest;
+    outFiles: string[];
+    refsOutFiles: string[];
+}>;
+export declare function buildOperationRegistry(config: OperationConfig, options?: BuildOperationOptions): Promise<Record<string, RegisteredOperation>>;
+export declare function operationClientContract(refs: Partial<OperationRefsManifest> | null | undefined): OperationContract;
+export declare function loadOperationSources(config: OperationConfig, options?: BuildOperationOptions): Promise<OperationTemplate[]>;
+export {};

package/dist/features/operations/index.js

@@ -0,0 +1,199 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { dbError } from '../../errors.js';
+import { parseJsonc } from '../../jsonc.js';
+import { resolveFrom, writeText } from '../../fs-utils.js';
+import { canonicalOperation, normalizeOperationTemplate, stableStringify, } from '../../shared/operations.js';
+import { operationMapFromEntries } from './maps.js';
+export function hashOperation(input) {
+    return `sha256:${createHash('sha256').update(stableStringify(canonicalOperation(input))).digest('hex')}`;
+}
+export async function buildOperationManifest(config, options = {}) {
+    const operations = await loadOperationSources(config, {
+        ...options,
+        createDirectory: true,
+    });
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const registryEntries = buildRegistryEntries(operations);
+    const registry = operationMapFromEntries(registryEntries);
+    const refs = {
+        version: 1,
+        kind: 'db.operationRefs',
+        generatedAt,
+        operations: operationMapFromEntries(registryEntries.map(([ref, operation]) => [
+            operation.name ?? ref,
+            {
+                name: operation.name ?? ref,
+                ref: operation.ref,
+            },
+        ])),
+    };
+    const manifest = {
+        version: 1,
+        kind: 'db.operations',
+        generatedAt,
+        operations: registry,
+    };
+    const outFiles = [];
+    const refsOutFiles = [];
+    const shouldWrite = options.write !== false;
+    const outFile = outputPath(config, optionValue(options, 'outFile', config.operations?.outFile));
+    const refsOutFile = outputPath(config, optionValue(options, 'refsOutFile', config.operations?.refsOutFile));
+    if (shouldWrite && outFile) {
+        await writeText(outFile, `${JSON.stringify(manifest, null, 2)}\n`);
+        outFiles.push(outFile);
+    }
+    if (shouldWrite && refsOutFile) {
+        await writeText(refsOutFile, `${JSON.stringify(refs, null, 2)}\n`);
+        refsOutFiles.push(refsOutFile);
+    }
+    return {
+        manifest,
+        refs,
+        outFiles,
+        refsOutFiles,
+    };
+}
+export async function buildOperationRegistry(config, options = {}) {
+    const operations = await loadOperationSources(config, options);
+    return operationMapFromEntries(buildRegistryEntries(operations));
+}
+export function operationClientContract(refs) {
+    return {
+        version: 1,
+        kind: 'db.operationContract',
+        operations: operationMapFromEntries(Object.entries(refs?.operations ?? {})
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([name, operationRef]) => [
+            name,
+            {
+                name: operationRef?.name ?? name,
+                ref: operationRef?.ref,
+            },
+        ])),
+    };
+}
+function buildRegistryEntries(operations) {
+    const seenNames = new Map();
+    const seenRefs = new Map();
+    return operations.map((operation, index) => {
+        const normalized = normalizeOperationTemplate(operation);
+        const ref = normalized.ref ?? hashOperation(normalized);
+        const name = normalized.name ?? ref;
+        const previousName = seenNames.get(name);
+        if (previousName) {
+            throw duplicateOperationName(name, previousName, { index, ref });
+        }
+        const previousRef = seenRefs.get(ref);
+        if (previousRef) {
+            throw duplicateOperationRef(ref, previousRef, { index, name });
+        }
+        seenNames.set(name, { index, ref });
+        seenRefs.set(ref, { index, name });
+        return [ref, {
+                ...normalized,
+                name,
+                ref,
+            }];
+    });
+}
+function duplicateOperationName(name, previous, current) {
+    return dbError('OPERATION_DUPLICATE_NAME', `Registered operation name "${name}" is used more than once.`, {
+        status: 400,
+        hint: 'Give each registered operation a unique name so generated client refs map to one callable operation.',
+        details: {
+            name,
+            firstIndex: previous.index,
+            duplicateIndex: current.index,
+            firstRef: previous.ref,
+            duplicateRef: current.ref,
+        },
+    });
+}
+function duplicateOperationRef(ref, previous, current) {
+    return dbError('OPERATION_DUPLICATE_REF', `Registered operation ref "${ref}" is used more than once.`, {
+        status: 400,
+        hint: 'Give each registered operation a unique ref so generated client refs map to one callable operation.',
+        details: {
+            ref,
+            firstIndex: previous.index,
+            duplicateIndex: current.index,
+            firstName: previous.name,
+            duplicateName: current.name,
+        },
+    });
+}
+export async function loadOperationSources(config, options = {}) {
+    if (Array.isArray(options.operations)) {
+        return options.operations;
+    }
+    const sourceDir = config.operations?.sourceDir;
+    if (!sourceDir) {
+        return [];
+    }
+    if (options.createDirectory === true) {
+        try {
+            await mkdir(sourceDir, { recursive: true });
+        }
+        catch {
+            return [];
+        }
+    }
+    let files = [];
+    try {
+        files = await listOperationFiles(sourceDir);
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') {
+            return [];
+        }
+        throw error;
+    }
+    const operations = [];
+    for (const filePath of files) {
+        const text = await readFile(filePath, 'utf8');
+        const extension = path.extname(filePath);
+        if (extension === '.json' || extension === '.jsonc') {
+            const parsed = parseJsonc(text, filePath);
+            operations.push(...(Array.isArray(parsed) ? parsed : [parsed]));
+            continue;
+        }
+        const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        const template = lines.find((line) => !line.startsWith('#'));
+        if (template) {
+            operations.push({
+                name: operationNameFromFile(filePath),
+                ...normalizeOperationTemplate(template),
+            });
+        }
+    }
+    return operations;
+}
+async function listOperationFiles(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const filePath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...await listOperationFiles(filePath));
+        }
+        else if (/\.(jsonc?|rest|txt)$/i.test(entry.name)) {
+            files.push(filePath);
+        }
+    }
+    return files.sort();
+}
+function operationNameFromFile(filePath) {
+    const basename = path.basename(filePath).replace(/\.(jsonc?|rest|txt)$/i, '');
+    return basename.replace(/(^|[-_])([a-z0-9])/gi, (_match, _separator, char) => char.toUpperCase());
+}
+function optionValue(options, key, fallback) {
+    return Object.hasOwn(options, key) && options[key] !== undefined ? options[key] : fallback;
+}
+function outputPath(config, value) {
+    if (!value) {
+        return null;
+    }
+    return resolveFrom(config.cwd, String(value));
+}

package/dist/features/operations/maps.d.ts

@@ -0,0 +1 @@
+export declare function operationMapFromEntries<T = unknown>(entries?: Iterable<readonly [PropertyKey, T]>): Record<string, T>;

package/dist/features/operations/maps.js

@@ -0,0 +1,10 @@
+export function operationMapFromEntries(entries = []) {
+    // Operation names and refs are developer-controlled contract keys. Keep maps
+    // null-prototype so "__proto__" and "constructor" stay data keys instead of
+    // resolving inherited Object.prototype members during dynamic lookup.
+    const map = Object.create(null);
+    for (const [key, value] of entries) {
+        map[String(key)] = value;
+    }
+    return map;
+}

package/dist/features/operations/readiness.d.ts

@@ -0,0 +1,30 @@
+export declare const OPERATIONS_STRICT_MODE_CODE = "OPERATIONS_STRICT_MODE_WITHOUT_OPERATIONS";
+type OperationConfig = {
+    server?: {
+        expose?: {
+            rest?: string;
+        };
+    };
+    operations?: {
+        enabled?: boolean;
+        acceptRefs?: string;
+        registry?: Record<string, unknown>;
+        outFile?: string | null;
+        sourceDir?: string;
+        resolveRef?: unknown;
+    };
+    [key: string]: unknown;
+};
+type OperationDiagnostic = {
+    code: string;
+    severity: 'error' | 'info';
+    source: 'doctor';
+    message: string;
+    hint: string;
+    details: Record<string, unknown>;
+};
+export declare function operationStrictModeFindings(config: OperationConfig, options?: {
+    includeGuidance?: boolean;
+}): Promise<OperationDiagnostic[]>;
+export declare function assertOperationStrictModeReady(config: OperationConfig): Promise<void>;
+export {};

package/dist/features/operations/readiness.js

@@ -0,0 +1,228 @@
+import { readFile } from 'node:fs/promises';
+import { normalizeOperationTemplate } from '../../shared/operations.js';
+import { buildOperationRegistry } from './index.js';
+export const OPERATIONS_STRICT_MODE_CODE = 'OPERATIONS_STRICT_MODE_WITHOUT_OPERATIONS';
+const ACCEPT_REFS_RECOMMENDATION_CODE = 'OPERATIONS_STRICT_MODE_ACCEPT_REFS_RECOMMENDED';
+export async function operationStrictModeFindings(config, options = {}) {
+    if (config.server?.expose?.rest !== 'registered-only') {
+        return [];
+    }
+    const includeGuidance = options.includeGuidance !== false;
+    const readiness = await operationStrictModeReadiness(config);
+    if (!readiness.ready) {
+        return [operationStrictModeDiagnostic(readiness)];
+    }
+    if (includeGuidance && (config.operations?.acceptRefs ?? 'both') !== 'ref') {
+        return [operationAcceptRefsRecommendation(config)];
+    }
+    return [];
+}
+export async function assertOperationStrictModeReady(config) {
+    const findings = await operationStrictModeFindings(config, {
+        includeGuidance: false,
+    });
+    const errors = findings.filter((finding) => finding.severity === 'error');
+    if (errors.length === 0) {
+        return;
+    }
+    const error = new Error(errors.map((finding) => finding.message).join('\n'));
+    error.code = errors[0].code;
+    error.hint = errors[0].hint;
+    error.details = errors[0].details;
+    error.diagnostics = errors;
+    throw error;
+}
+async function operationStrictModeReadiness(config) {
+    const operations = config.operations ?? {};
+    const details = {
+        restExposure: 'registered-only',
+        operationsEnabled: operations.enabled === true,
+        registry: inlineRegistryDetails(operations),
+        outFile: operations.outFile ? { configured: true, path: String(operations.outFile) } : { configured: false },
+        resolveRef: { configured: typeof operations.resolveRef === 'function' },
+        sourceDir: operations.sourceDir ? { configured: true, path: String(operations.sourceDir) } : { configured: false },
+    };
+    if (operations.enabled !== true) {
+        return {
+            ready: false,
+            reason: 'disabled',
+            details,
+        };
+    }
+    if (details.registry.count > 0) {
+        return {
+            ready: true,
+            source: 'registry',
+            details,
+        };
+    }
+    if (operations.outFile) {
+        const registryFile = await inspectOperationRegistryFile(operations.outFile);
+        details.outFile = {
+            ...details.outFile,
+            ...registryFile.details,
+        };
+        return registryFile.ready
+            ? {
+                ready: true,
+                source: 'outFile',
+                details,
+            }
+            : {
+                ready: false,
+                reason: registryFile.reason,
+                details,
+            };
+    }
+    if (typeof operations.resolveRef === 'function') {
+        return {
+            ready: true,
+            source: 'resolveRef',
+            details,
+        };
+    }
+    if (operations.sourceDir) {
+        const sourceDir = await inspectOperationSourceDir(config);
+        details.sourceDir = {
+            ...details.sourceDir,
+            ...sourceDir.details,
+        };
+        if (sourceDir.ready) {
+            return {
+                ready: true,
+                source: 'sourceDir',
+                details,
+            };
+        }
+        if (sourceDir.reason !== 'source-empty') {
+            return {
+                ready: false,
+                reason: sourceDir.reason,
+                details,
+            };
+        }
+    }
+    return {
+        ready: false,
+        reason: 'no-source',
+        details,
+    };
+}
+function inlineRegistryDetails(operations = {}) {
+    const count = operations.registry && typeof operations.registry === 'object'
+        ? Object.keys(operations.registry).length
+        : 0;
+    return {
+        configured: count > 0,
+        count,
+    };
+}
+async function inspectOperationRegistryFile(outFile) {
+    try {
+        const manifest = JSON.parse(await readFile(outFile, 'utf8'));
+        const entries = Object.entries(manifest.operations ?? {});
+        for (const [, operation] of entries) {
+            normalizeOperationTemplate(operation);
+        }
+        if (entries.length === 0) {
+            return {
+                ready: false,
+                reason: 'registry-empty',
+                details: {
+                    reason: 'empty',
+                    count: 0,
+                },
+            };
+        }
+        return {
+            ready: true,
+            details: {
+                count: entries.length,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            ready: false,
+            reason: 'registry-load-failed',
+            details: {
+                reason: operationRegistryLoadReason(error),
+                error: error.message,
+            },
+        };
+    }
+}
+async function inspectOperationSourceDir(config) {
+    try {
+        const registry = await buildOperationRegistry(config, {
+            createDirectory: false,
+        });
+        const count = Object.keys(registry).length;
+        return count > 0
+            ? {
+                ready: true,
+                details: {
+                    count,
+                },
+            }
+            : {
+                ready: false,
+                reason: 'source-empty',
+                details: {
+                    reason: 'empty',
+                    count: 0,
+                },
+            };
+    }
+    catch (error) {
+        return {
+            ready: false,
+            reason: 'source-load-failed',
+            details: {
+                reason: operationRegistryLoadReason(error),
+                error: error.message,
+            },
+        };
+    }
+}
+function operationStrictModeDiagnostic(readiness) {
+    return {
+        code: OPERATIONS_STRICT_MODE_CODE,
+        severity: 'error',
+        source: 'doctor',
+        message: strictModeMessage(readiness.reason),
+        hint: 'Set operations.enabled: true and provide outputs.operationRegistry, operations.registry, operations.resolveRef, or operation source files; or use server.expose.rest: "open" for local REST routes.',
+        details: {
+            ...readiness.details,
+            reason: readiness.reason,
+        },
+    };
+}
+function strictModeMessage(reason) {
+    if (reason === 'disabled') {
+        return 'server.expose.rest: "registered-only" requires registered operations to be enabled.';
+    }
+    return 'server.expose.rest: "registered-only" requires registered operations to be enabled and resolvable.';
+}
+function operationAcceptRefsRecommendation(config) {
+    return {
+        code: ACCEPT_REFS_RECOMMENDATION_CODE,
+        severity: 'info',
+        source: 'doctor',
+        message: 'Operation-only REST exposure is easiest to review when public clients use operations.acceptRefs: "ref".',
+        hint: 'Set operations.acceptRefs: "ref" for public operation-only APIs, or keep the current value for readable local/internal refs.',
+        details: {
+            acceptRefs: config.operations?.acceptRefs ?? 'both',
+            restExposure: 'registered-only',
+        },
+    };
+}
+function operationRegistryLoadReason(error) {
+    if ('code' in error && error.code === 'ENOENT') {
+        return 'missing';
+    }
+    if (error instanceof SyntaxError) {
+        return 'invalid-json';
+    }
+    return 'read-failed';
+}

package/dist/features/operations/runtime.d.ts

@@ -0,0 +1,57 @@
+import { type OperationTemplate, type OperationVariables, type RegisteredOperation } from '../../shared/operations.js';
+type OperationAcceptRefs = 'ref' | 'name' | 'both';
+type OperationRegistry = Record<string, OperationTemplate>;
+type OperationRefContext = {
+    ref: string;
+    decodedRef: string;
+    acceptRefs: OperationAcceptRefs;
+    registry: Record<string, RegisteredOperation>;
+    operation: RegisteredOperation | null;
+};
+type OperationOptions = {
+    enabled?: boolean;
+    acceptRefs?: OperationAcceptRefs | 'hash';
+    registry?: OperationRegistry;
+    outFile?: string | null;
+    sourceDir?: string;
+    resolveRef?: (ref: string, context: Omit<OperationRefContext, 'operation'>) => OperationTemplate | null | undefined | Promise<OperationTemplate | null | undefined>;
+    validateRef?: (context: OperationRefContext) => boolean | null | undefined | OperationTemplate | Promise<boolean | null | undefined | OperationTemplate>;
+};
+type DbLike = {
+    config: {
+        cwd?: string;
+        graphql?: {
+            enabled?: boolean;
+        };
+        operations?: OperationOptions;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+};
+type CreateHandlerOptions = OperationOptions | {
+    operations?: boolean | 'auto' | OperationOptions;
+};
+type ExecutionOptions = {
+    routes?: Record<string, unknown>;
+    trace?: unknown;
+};
+type OperationExecutionResult = {
+    kind: 'rest' | 'graphql';
+    status: number;
+    headers: Record<string, unknown>;
+    body: unknown;
+    rawBody?: string;
+};
+export declare function createDbOperationHandler(db: DbLike, options?: CreateHandlerOptions): {
+    enabled: boolean;
+    options: OperationOptions & {
+        enabled: boolean;
+        acceptRefs: OperationAcceptRefs;
+    };
+    resolve(ref: string): Promise<RegisteredOperation | null>;
+    execute(ref: string, variables?: OperationVariables, executionOptions?: ExecutionOptions): Promise<OperationExecutionResult>;
+    executeRequest(ref: string, body?: {
+        variables?: OperationVariables;
+    } | null, executionOptions?: ExecutionOptions): Promise<any>;
+};
+export {};