@async/db 0.2.0

package/db.config.example.mjs

@@ -0,0 +1,128 @@
+// @ts-check
+import { defineConfig } from '@async/db/config';
+
+export default defineConfig({
+  // Fixture source folder. Defaults to './db'.
+  dbDir: './db',
+
+  // Generated output locations. Most committed outputs are opt-in.
+  outputs: {
+    stateDir: './.db',
+    types: './.db/types/index.ts',
+    committedTypes: null,
+    schemaManifest: null,
+    viewerManifest: null,
+    operationRegistry: null,
+    operationRefs: null,
+    honoStarterDir: './db-api',
+  },
+
+  // Optional visitor hook for changing or omitting generated manifest fields.
+  schemaManifest: {
+    customizeField({ defaultManifest }) {
+      return defaultManifest;
+    },
+  },
+
+  // Optional custom source readers. Built-in readers handle JSON, JSONC, CSV,
+  // .schema.json, .schema.jsonc, and .schema.mjs. Custom readers run first.
+  sources: {
+    writePolicy: 'preserve',
+    readers: [],
+  },
+
+  // Runtime stores. The default json store writes app edits to
+  // .db/state/<resource>.json while keeping source fixtures unchanged.
+  // Bind a resource to sourceFile only when supported writebacks should update
+  // a plain .json source fixture. Optional database stores such as
+  // @async/db/postgres, @async/db/kv, and @async/db/redis accept injected
+  // clients so the core package stays dependency-light.
+  stores: {
+    default: 'json',
+    // postgres: postgresStore({ client: pgPool }),
+    // redis: redisStore({ client: redisClient, prefix: 'my-app:' }),
+  },
+
+  resources: {
+    // users: { store: 'sourceFile' },
+    // activityEvents: {
+    //   store: 'json',
+    //   indexes: [
+    //     { fields: ['observedAt'] },
+    //     { fields: ['domain', 'observedAt'] },
+    //   ],
+    // },
+  },
+
+  // Generated TypeScript type behavior. Paths live under `outputs`.
+  types: {
+    enabled: true,
+    useReadonly: false,
+    emitComments: true,
+  },
+
+  // Default local development behavior is permissive: unknown schema-backed
+  // fields warn. Use 'error' when you want schema drift to fail sync/writes.
+  schema: {
+    unknownFields: 'warn',
+  },
+
+  // Optional schema-only mock records. Leave off when real fixture data exists.
+  seed: {
+    generateFromSchema: false,
+    generatedCount: 5,
+  },
+
+  // Local server settings.
+  server: {
+    // Dev-tool route base for the viewer, schema, batch, import, events, and log.
+    // Defaults to '/__db'.
+    apiBase: '/__db',
+    // App-facing REST data route alias. Defaults to '/db'; set false to only
+    // use scoped REST under /__db/rest and standalone root REST routes.
+    dataPath: '/db',
+    host: '127.0.0.1',
+    port: 7331,
+    maxBodyBytes: 1048576,
+    // Opt-in request tracing. When enabled, traces are written to /__db/log,
+    // concise console lines are printed, and responses get a request id header.
+    // Trace metadata includes query keys only, never request bodies, response
+    // bodies, cookie headers, authorization headers, or query values.
+    trace: {
+      enabled: false,
+      slowMs: 100,
+      console: true,
+      events: true,
+      header: 'x-async-db-request-id',
+    },
+    // Optional custom data viewer links shown in discovery and manifest output.
+    viewerLinks: [
+      // { label: 'My Viewer', href: 'http://127.0.0.1:5173/db' },
+    ],
+  },
+
+  // REST and manifest response formats. Built-ins are json, html, and md.
+  // Object entries can register media types for Accept negotiation and can
+  // render both resource routes and /__db/manifest.<extension>.
+  rest: {
+    formats: {
+      default: 'json',
+      // yaml: {
+      //   mediaTypes: ['application/yaml', 'text/yaml'],
+      //   contentType: 'application/yaml; charset=utf-8',
+      //   render({ data }) {
+      //     return stringifyYaml(data);
+      //   },
+      // },
+    },
+  },
+
+  // Local latency is on by default so loading states are visible. Use 0 to
+  // disable delay, 50 for a fixed 50ms delay, or [50, 300] for a range.
+  // Random errors are off by default.
+  mock: {
+    delay: [30, 100],
+    errors: null,
+  },
+
+});

package/dist/cli/args.d.ts

@@ -0,0 +1,8 @@
+type GlobalOptions = {
+    cwd: string;
+    configPath?: string;
+};
+export declare function parseGlobalOptions(args: string[]): GlobalOptions;
+export declare function valueAfter(args: string[], flag: string): string | undefined;
+export declare function isHelpRequested(args: string[]): boolean;
+export {};

package/dist/cli/args.js

@@ -0,0 +1,16 @@
+export function parseGlobalOptions(args) {
+    return {
+        cwd: valueAfter(args, '--cwd') ?? process.cwd(),
+        configPath: valueAfter(args, '--config'),
+    };
+}
+export function valueAfter(args, flag) {
+    const index = args.indexOf(flag);
+    if (index === -1) {
+        return undefined;
+    }
+    return args[index + 1];
+}
+export function isHelpRequested(args) {
+    return args.includes('--help') || args.includes('-h');
+}

package/dist/cli/commands/create.d.ts

@@ -0,0 +1,3 @@
+type CliConfig = Record<string, unknown>;
+export declare function runCreate(config: CliConfig, args: string[]): Promise<void>;
+export {};

package/dist/cli/commands/create.js

@@ -0,0 +1,13 @@
+import { openDb } from '../../db.js';
+export async function runCreate(config, args) {
+    const [collectionName, json] = args;
+    if (!collectionName || !json) {
+        throw new Error('Usage: async-db create <collection> <json>');
+    }
+    const db = await openDb({
+        ...config,
+        syncOnOpen: true,
+    });
+    const record = await db.collection(collectionName).create(JSON.parse(json));
+    console.log(JSON.stringify(record, null, 2));
+}

package/dist/cli/commands/doctor.d.ts

@@ -0,0 +1,3 @@
+type CliConfig = Record<string, unknown>;
+export declare function runDoctor(config: CliConfig, args: string[]): Promise<void>;
+export {};

package/dist/cli/commands/doctor.js

@@ -0,0 +1,31 @@
+import { runDbDoctor } from '../../doctor.js';
+import { isHelpRequested } from '../args.js';
+import { printDoctorHelp, printDoctorResult } from '../output.js';
+export async function runDoctor(config, args) {
+    if (isHelpRequested(args)) {
+        printDoctorHelp();
+        return;
+    }
+    const result = await runDbDoctor(doctorConfig(config, args));
+    if (args.includes('--json')) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        printDoctorResult(result);
+    }
+    if (result.summary.error > 0 || (args.includes('--strict') && result.summary.warn > 0)) {
+        process.exitCode = 1;
+    }
+}
+function doctorConfig(config, args) {
+    if (!args.includes('--production')) {
+        return config;
+    }
+    return {
+        ...config,
+        doctor: {
+            ...(config.doctor && typeof config.doctor === 'object' ? config.doctor : {}),
+            production: true,
+        },
+    };
+}

package/dist/cli/commands/generate.d.ts

@@ -0,0 +1,6 @@
+type CliConfig = {
+    cwd?: string;
+    [key: string]: unknown;
+};
+export declare function runGenerate(config: CliConfig, args: string[]): Promise<void>;
+export {};

package/dist/cli/commands/generate.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import { defaultGeneratorRegistry } from '../../features/generate/registry.js';
+import { isHelpRequested } from '../args.js';
+import { printGenerateHelp } from '../output.js';
+export async function runGenerate(config, args) {
+    const target = args[0];
+    const registry = defaultGeneratorRegistry();
+    if (isHelpRequested(args) && (!target || target.startsWith('-'))) {
+        printGenerateHelp(registry.usage());
+        return;
+    }
+    const generator = registry.get(target);
+    if (!generator) {
+        throw new Error(`Usage: ${registry.usage()}`);
+    }
+    if (isHelpRequested(args.slice(1))) {
+        printGenerateHelp(generator.usage);
+        return;
+    }
+    const result = await generator.run(config, args.slice(1));
+    for (const filePath of result.files) {
+        console.log(`Generated ${path.relative(config.cwd, filePath)}`);
+    }
+}

package/dist/cli/commands/operations.d.ts

@@ -0,0 +1,12 @@
+type CliConfig = {
+    cwd?: string;
+    outputs?: {
+        operationRefs?: string | null;
+    };
+    operations?: {
+        refsOutFile?: string | null;
+    };
+    [key: string]: unknown;
+};
+export declare function runOperations(config: CliConfig, args: string[]): Promise<void>;
+export {};

package/dist/cli/commands/operations.js

@@ -0,0 +1,61 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { buildOperationManifest, operationClientContract } from '../../operations.js';
+import { resolveFrom, writeText } from '../../fs-utils.js';
+import { valueAfter } from '../args.js';
+export async function runOperations(config, args) {
+    if (args[0] === 'contract') {
+        await runOperationContract(config, args);
+        return;
+    }
+    if (args[0] !== 'build') {
+        throw new Error('Unknown operations command. Use async-db operations build or async-db operations contract.');
+    }
+    const result = await buildOperationManifest(config, {
+        outFile: valueAfter(args, '--out'),
+        refsOutFile: valueAfter(args, '--refs-out'),
+    });
+    if (result.outFiles.length === 0 && result.refsOutFiles.length === 0) {
+        console.log(JSON.stringify(result.manifest, null, 2));
+        return;
+    }
+    for (const filePath of [...result.outFiles, ...result.refsOutFiles]) {
+        console.log(`Generated ${path.relative(config.cwd, filePath)}`);
+    }
+}
+async function runOperationContract(config, args) {
+    const result = await buildOperationManifest(config, {
+        write: false,
+    });
+    const contract = operationClientContract(result.refs);
+    const content = contractContent(contract);
+    const check = args.includes('--check');
+    const target = contractTarget(config, args, { check });
+    if (check) {
+        if (!target) {
+            throw new Error('Operation contract check needs --out <file> or outputs.operationRefs in db.config.mjs.');
+        }
+        const expected = operationClientContract(JSON.parse(await readFile(target, 'utf8')));
+        const expectedContent = contractContent(expected);
+        if (expectedContent !== content) {
+            const relative = path.relative(config.cwd, target);
+            throw new Error(`Operation client contract changed for ${relative}. Review the exposed operation names and refs, then regenerate or approve the committed contract.`);
+        }
+        console.log(`Operation client contract matches ${path.relative(config.cwd, target)}`);
+        return;
+    }
+    if (target) {
+        await writeText(target, content);
+        console.log(`Generated ${path.relative(config.cwd, target)}`);
+        return;
+    }
+    console.log(content.trimEnd());
+}
+function contractTarget(config, args, options = {}) {
+    const explicitTarget = valueAfter(args, '--out');
+    const target = explicitTarget ?? (options.check ? config.outputs?.operationRefs ?? config.operations?.refsOutFile : null);
+    return target ? resolveFrom(config.cwd, target) : null;
+}
+function contractContent(contract) {
+    return `${JSON.stringify(contract, null, 2)}\n`;
+}

package/dist/cli/commands/schema.d.ts

@@ -0,0 +1,11 @@
+type CliConfig = {
+    cwd?: string;
+    sourceDir?: string;
+    schema?: {
+        standardSchema?: boolean;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+};
+export declare function runSchema(config: CliConfig, args: string[]): Promise<void>;
+export {};