@async/db 0.2.0

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

@@ -0,0 +1,9 @@
+type CliConfig = {
+    server?: {
+        host?: string;
+        port?: string | number;
+    };
+    [key: string]: unknown;
+};
+export declare function runServe(config: CliConfig, args: string[]): Promise<never | void>;
+export {};

package/dist/cli/commands/serve.js

@@ -0,0 +1,18 @@
+import { startDbServer } from '../../server.js';
+import { isHelpRequested, valueAfter } from '../args.js';
+import { printServeHelp } from '../output.js';
+export async function runServe(config, args) {
+    if (isHelpRequested(args)) {
+        printServeHelp();
+        return;
+    }
+    const host = valueAfter(args, '--host') ?? config.server.host;
+    const port = valueAfter(args, '--port') ?? config.server.port;
+    const { url } = await startDbServer({
+        ...config,
+        host,
+        port,
+    });
+    console.log(`db server listening at ${url}`);
+    return new Promise(() => { });
+}

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

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

package/dist/cli/commands/sync.js

@@ -0,0 +1,11 @@
+import { syncDb } from '../../sync.js';
+import { printDiagnostic } from '../output.js';
+export async function runSync(config) {
+    const result = await syncDb(config);
+    for (const diagnostic of result.diagnostics) {
+        printDiagnostic(diagnostic);
+    }
+    for (const line of result.logs) {
+        console.log(line);
+    }
+}

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

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

package/dist/cli/commands/types.js

@@ -0,0 +1,37 @@
+import { watch } from 'node:fs';
+import path from 'node:path';
+import { loadProjectSchema } from '../../schema.js';
+import { generateTypes } from '../../types.js';
+import { isHelpRequested, valueAfter } from '../args.js';
+import { printDiagnostic, printTypesHelp } from '../output.js';
+export async function runTypes(config, args) {
+    if (isHelpRequested(args)) {
+        printTypesHelp();
+        return;
+    }
+    if (args.includes('--watch')) {
+        await runTypesOnce(config, args);
+        console.log(`Watching ${path.relative(config.cwd, config.sourceDir) || '.'}`);
+        watch(config.sourceDir, { recursive: true }, async () => {
+            try {
+                await runTypesOnce(config, args);
+            }
+            catch (error) {
+                console.error(error.message);
+            }
+        });
+        return new Promise(() => { });
+    }
+    await runTypesOnce(config, args);
+}
+async function runTypesOnce(config, args) {
+    const outFile = valueAfter(args, '--out');
+    const project = await loadProjectSchema(config);
+    const result = await generateTypes(config, { project, outFile });
+    for (const diagnostic of result.diagnostics) {
+        printDiagnostic(diagnostic);
+    }
+    for (const filePath of result.outFiles) {
+        console.log(`Generated ${path.relative(config.cwd, filePath)}`);
+    }
+}

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

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

package/dist/cli/commands/viewer.js

@@ -0,0 +1,29 @@
+import path from 'node:path';
+import { dbError } from '../../errors.js';
+import { loadProjectSchema } from '../../schema.js';
+import { generateViewerManifest } from '../../viewer-manifest.js';
+import { isHelpRequested, valueAfter } from '../args.js';
+import { printViewerHelp } from '../output.js';
+export async function runViewer(config, args) {
+    if (isHelpRequested(args)) {
+        printViewerHelp();
+        return;
+    }
+    if (args[0] !== 'manifest') {
+        throw dbError('VIEWER_UNKNOWN_COMMAND', `Unknown viewer command "${args[0] ?? ''}".`, {
+            hint: 'Use async-db viewer manifest [--out <file>].',
+        });
+    }
+    const project = await loadProjectSchema(config);
+    const result = await generateViewerManifest(config, {
+        project,
+        outFile: valueAfter(args, '--out'),
+    });
+    if (result.outFiles.length === 0) {
+        console.log(result.content);
+        return;
+    }
+    for (const filePath of result.outFiles) {
+        console.log(`Generated ${path.relative(config.cwd, filePath)}`);
+    }
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export declare function main(args?: string[]): Promise<void>;
+export declare function runCli(args?: string[]): void;

package/dist/cli/index.js

@@ -0,0 +1,108 @@
+import { loadConfig } from '../config.js';
+import { defaultGeneratorRegistry } from '../features/generate/registry.js';
+import { isHelpRequested, parseGlobalOptions } from './args.js';
+import { runCreate } from './commands/create.js';
+import { runDoctor } from './commands/doctor.js';
+import { runGenerate } from './commands/generate.js';
+import { runSchema } from './commands/schema.js';
+import { runServe } from './commands/serve.js';
+import { runSync } from './commands/sync.js';
+import { runTypes } from './commands/types.js';
+import { runViewer } from './commands/viewer.js';
+import { runOperations } from './commands/operations.js';
+import { printDiagnostic, printDoctorHelp, printGenerateHelp, printHelp, printOperationsHelp, printSchemaHelp, printServeHelp, printTypesHelp, printViewerHelp } from './output.js';
+export async function main(args = process.argv.slice(2)) {
+    const command = args[0] ?? 'help';
+    if (command === 'help' || command === '--help' || command === '-h') {
+        printHelp();
+        return;
+    }
+    if (command === '--version' || command === '-v') {
+        console.log('0.1.0');
+        return;
+    }
+    if (printSubcommandHelp(command, args.slice(1))) {
+        return;
+    }
+    const config = await loadConfig(parseGlobalOptions(args));
+    switch (command) {
+        case 'sync':
+            await runSync(config);
+            break;
+        case 'types':
+            await runTypes(config, args.slice(1));
+            break;
+        case 'schema':
+            await runSchema(config, args.slice(1));
+            break;
+        case 'doctor':
+        case 'check':
+            await runDoctor(config, args.slice(1));
+            break;
+        case 'create':
+            await runCreate(config, args.slice(1));
+            break;
+        case 'serve':
+            await runServe(config, args.slice(1));
+            break;
+        case 'viewer':
+            await runViewer(config, args.slice(1));
+            break;
+        case 'operations':
+            await runOperations(config, args.slice(1));
+            break;
+        case 'generate':
+            await runGenerate(config, args.slice(1));
+            break;
+        default:
+            throw new Error(`Unknown command "${command}". Run "async-db help".`);
+    }
+}
+function printSubcommandHelp(command, args) {
+    if (!isHelpRequested(args)) {
+        return false;
+    }
+    switch (command) {
+        case 'types':
+            printTypesHelp();
+            return true;
+        case 'schema':
+            printSchemaHelp();
+            return true;
+        case 'doctor':
+        case 'check':
+            printDoctorHelp();
+            return true;
+        case 'serve':
+            printServeHelp();
+            return true;
+        case 'viewer':
+            printViewerHelp();
+            return true;
+        case 'operations':
+            printOperationsHelp();
+            return true;
+        case 'generate':
+            printGenerateHelp(generateHelpUsage(args));
+            return true;
+        default:
+            return false;
+    }
+}
+function generateHelpUsage(args) {
+    const registry = defaultGeneratorRegistry();
+    const target = args.find((arg) => !arg.startsWith('-'));
+    return registry.get(target)?.usage ?? registry.usage();
+}
+export function runCli(args = process.argv.slice(2)) {
+    main(args).catch((error) => {
+        const cliError = error;
+        if (cliError.diagnostics) {
+            for (const diagnostic of cliError.diagnostics) {
+                printDiagnostic(diagnostic);
+            }
+        }
+        console.error(cliError.message);
+        process.exitCode = 1;
+    });
+}

package/dist/cli/output.d.ts

@@ -0,0 +1,25 @@
+type CliDiagnostic = {
+    severity?: string;
+    message: string;
+    [key: string]: unknown;
+};
+type DoctorFinding = {
+    severity: string;
+    code: string;
+    message: string;
+    hint?: string;
+};
+type DoctorResult = {
+    findings: DoctorFinding[];
+};
+export declare function printDiagnostic(diagnostic: CliDiagnostic): void;
+export declare function printDoctorResult(result: DoctorResult): void;
+export declare function printHelp(): void;
+export declare function printOperationsHelp(): void;
+export declare function printTypesHelp(): void;
+export declare function printSchemaHelp(): void;
+export declare function printDoctorHelp(): void;
+export declare function printViewerHelp(): void;
+export declare function printServeHelp(): void;
+export declare function printGenerateHelp(usage: string): void;
+export {};

package/dist/cli/output.js

@@ -0,0 +1,149 @@
+export function printDiagnostic(diagnostic) {
+    const prefix = diagnostic.severity === 'error' ? 'error' : 'warn';
+    console.error(`${prefix}: ${diagnostic.message}`);
+}
+export function printDoctorResult(result) {
+    if (result.findings.length === 0) {
+        console.log('async-db doctor found no issues');
+        return;
+    }
+    console.log(`async-db doctor found ${result.findings.length} finding${result.findings.length === 1 ? '' : 's'}`);
+    for (const finding of result.findings) {
+        console.log(`${finding.severity}: ${finding.code}: ${finding.message}`);
+        if (finding.hint) {
+            console.log(`  hint: ${finding.hint}`);
+        }
+    }
+}
+export function printHelp() {
+    console.log(`async-db
+
+Usage:
+  async-db sync
+  async-db types [--watch] [--out <file>]
+  async-db schema [resource]
+  async-db schema infer [resource] [--out <file>]
+  async-db schema unbundle [resource] [--schema-out <file>] [--seed-out <file>] [--empty-seed] [--force]
+  async-db schema unbundle --all [--schema-dir <dir>] [--force]
+  async-db schema bundle [resource] [--out <file>] [--force]
+  async-db schema bundle --all [--out <file>] [--force]
+  async-db schema manifest [--out <file>]
+  async-db schema validate
+  async-db operations build [--out <file>] [--refs-out <file>]
+  async-db operations contract [--out <file>] [--check]
+  async-db viewer manifest [--out <file>]
+  async-db doctor [--strict] [--json] [--production]
+  async-db check [--strict] [--json] [--production]
+  async-db create <collection> <json>
+  async-db serve [--host <host>] [--port <port>]
+  async-db generate hono [--out <dir>] [--api <targets>] [--app <shape>]
+
+Options:
+  --cwd <dir>       Project directory
+  --config <file>   Config file path
+`);
+}
+export function printOperationsHelp() {
+    console.log(`async-db operations
+
+Usage:
+  async-db operations build [--out <file>] [--refs-out <file>]
+  async-db operations contract [--out <file>] [--check]
+
+Options:
+  --out <file>      Build: write the full server registry. Contract: write or check the client contract
+  --refs-out <file> Build only: write client-safe operation refs
+  --check           Contract only: fail if the generated client contract differs from --out or outputs.operationRefs
+  --cwd <dir>       Project directory
+  --config <file>   Config file path
+`);
+}
+export function printTypesHelp() {
+    console.log(`async-db types
+
+Usage:
+  async-db types [--watch] [--out <file>]
+
+Options:
+  --watch        Regenerate types when fixture sources change
+  --out <file>   Write generated types to this path
+  --cwd <dir>     Project directory
+  --config <file> Config file path
+`);
+}
+export function printSchemaHelp() {
+    console.log(`async-db schema
+
+Usage:
+  async-db schema [resource]
+  async-db schema infer [resource] [--out <file>]
+  async-db schema unbundle [resource] [--schema-out <file>] [--seed-out <file>] [--empty-seed] [--force]
+  async-db schema unbundle --all [--schema-dir <dir>] [--force]
+  async-db schema bundle [resource] [--out <file>] [--force]
+  async-db schema bundle --all [--out <file>] [--force]
+  async-db schema manifest [--out <file>]
+  async-db schema validate
+
+Options:
+  --out <file>        Write schema manifest, inferred schema, or bundled schema output to this path
+  --schema-out <file> Write unbundled schema output to this path
+  --seed-out <file>   Write unbundled seed output to this path
+  --schema-dir <dir>  Write aggregate unbundled schema files under this directory
+  --empty-seed        Write an empty seed fixture when unbundling schema-only resources
+  --force             Allow overwriting outputs or writing bundle output inside db/
+  --all               Skip the interactive target prompt and use all schemas
+  --cwd <dir>     Project directory
+  --config <file> Config file path
+`);
+}
+export function printDoctorHelp() {
+    console.log(`async-db doctor
+
+Usage:
+  async-db doctor [--strict] [--json] [--production]
+  async-db check [--strict] [--json] [--production]
+
+Options:
+  --strict       Exit with an error when warnings are present
+  --json         Print machine-readable findings
+  --production   Include production-readiness guidance for JSON-backed resources
+  --cwd <dir>     Project directory
+  --config <file> Config file path
+`);
+}
+export function printViewerHelp() {
+    console.log(`async-db viewer
+
+Usage:
+  async-db viewer manifest [--out <file>]
+
+Options:
+  --out <file>   Write generated viewer manifest output to this path
+  --cwd <dir>     Project directory
+  --config <file> Config file path
+`);
+}
+export function printServeHelp() {
+    console.log(`async-db serve
+
+Usage:
+  async-db serve [--host <host>] [--port <port>]
+
+Options:
+  --host <host>  Host to bind, defaulting to configured server.host
+  --port <port>  Port to bind, defaulting to configured server.port
+  --cwd <dir>     Project directory
+  --config <file> Config file path
+`);
+}
+export function printGenerateHelp(usage) {
+    console.log(`async-db generate
+
+Usage:
+  ${usage}
+
+Options:
+  --cwd <dir>     Project directory
+  --config <file> Config file path
+`);
+}

package/dist/cli/schema-prompt.d.ts

@@ -0,0 +1,20 @@
+import type { Readable, Writable } from 'node:stream';
+type SchemaPromptTarget = {
+    all?: boolean;
+    resourceName?: string;
+};
+type SchemaPromptOptions = {
+    command: string;
+    resources: string[];
+    input?: Readable & {
+        isTTY?: boolean;
+    };
+    output?: Writable & {
+        isTTY?: boolean;
+    };
+    isInteractive?: boolean;
+    ask?: (prompt: string) => Promise<string | undefined> | string | undefined;
+    write?: (text: string) => unknown;
+};
+export declare function promptForSchemaTarget(options: SchemaPromptOptions): Promise<SchemaPromptTarget | undefined>;
+export {};

package/dist/cli/schema-prompt.js

@@ -0,0 +1,66 @@
+import { createInterface } from 'node:readline/promises';
+export async function promptForSchemaTarget(options) {
+    const { command, resources, input = process.stdin, output = process.stdout, isInteractive = Boolean(input.isTTY && output.isTTY), ask, write = (text) => output.write(text), } = options;
+    if (!isInteractive) {
+        return undefined;
+    }
+    const choices = [
+        { label: 'All schemas', value: { all: true } },
+        ...resources.map((resourceName) => ({
+            label: resourceName,
+            value: { resourceName },
+        })),
+    ];
+    const prompt = createPrompt({ ask, input, output });
+    try {
+        write(`Select schema ${command} target:\n`);
+        for (const [index, choice] of choices.entries()) {
+            write(`  ${index + 1}. ${choice.label}\n`);
+        }
+        write('  q. Cancel\n');
+        while (true) {
+            const answer = await prompt.question('Choice: ');
+            const normalized = String(answer ?? '').trim().toLowerCase();
+            if (normalized === '' || normalized === 'q' || normalized === 'quit' || normalized === 'cancel') {
+                return undefined;
+            }
+            if (normalized === 'all') {
+                return { all: true };
+            }
+            const number = Number(normalized);
+            if (Number.isInteger(number) && number >= 1 && number <= choices.length) {
+                return choices[number - 1].value;
+            }
+            const resource = resources.find((resourceName) => resourceName.toLowerCase() === normalized);
+            if (resource) {
+                return { resourceName: resource };
+            }
+            write(`Invalid selection "${answer}". Choose 1-${choices.length}, "all", a resource name, or "q".\n`);
+        }
+    }
+    finally {
+        prompt.close();
+    }
+}
+function createPrompt({ ask, input, output }) {
+    if (ask) {
+        return {
+            question: ask,
+            close() { },
+        };
+    }
+    const rl = createInterface({ input, output });
+    return {
+        async question(prompt) {
+            try {
+                return await rl.question(prompt);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        close() {
+            rl.close();
+        },
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from './cli/index.js';
+runCli(process.argv.slice(2));

package/dist/client-cache.d.ts

@@ -0,0 +1,105 @@
+type CacheWritePolicy = 'merge-and-invalidate' | 'invalidate' | 'refetch' | string;
+type CacheEventPolicy = 'invalidate' | 'refetch' | false | string;
+type CacheManifest = Record<string, unknown> & {
+    generatedAt?: string;
+    collections?: Record<string, unknown>;
+    documents?: Record<string, unknown>;
+    api?: {
+        log?: string;
+        events?: string;
+        [key: string]: unknown;
+    };
+};
+type ClientCacheStorageContext = {
+    baseNamespace: string;
+    manifestFingerprint: string | null;
+    namespace: string;
+};
+type ClientCacheStorage = {
+    load?(context: ClientCacheStorageContext): unknown | Promise<unknown>;
+    save?(snapshot: ClientCacheSnapshot, context: ClientCacheStorageContext): unknown | Promise<unknown>;
+    clear?(context: ClientCacheStorageContext): unknown | Promise<unknown>;
+};
+type ClientCacheSnapshot = {
+    namespace?: string;
+    manifestFingerprint?: string | null;
+    manifest?: unknown;
+    queries?: unknown[];
+    resources?: Record<string, unknown>;
+    entities?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+type ClientCacheConfigInput = {
+    enabled?: boolean;
+    readPolicy?: string;
+    writePolicy?: CacheWritePolicy;
+    eventPolicy?: CacheEventPolicy;
+    manifest?: CacheManifest | null;
+    storage?: ClientCacheStorage | 'memory' | null;
+};
+type ClientCacheFactoryOptions = {
+    cache?: boolean | ClientCacheConfigInput | null;
+    cacheNamespace?: unknown;
+    fetchManifest?: () => unknown | Promise<unknown>;
+    createEventSource?: (path: string) => CacheEventSource | null | undefined;
+    restBasePath?: string;
+};
+type CacheEventSource = {
+    addEventListener?: (type: string, listener: (event: CacheEvent) => void) => unknown;
+    on?: (type: string, listener: (event: CacheEvent) => void) => unknown;
+};
+type CacheEvent = {
+    data?: string;
+    [key: string]: unknown;
+};
+type RestCacheRequest = Record<string, unknown> & {
+    method?: string;
+    path?: string;
+};
+type RestCacheResult = Record<string, unknown> & {
+    status?: number;
+    body?: unknown;
+};
+type GraphqlCacheRequest = Record<string, unknown> & {
+    query?: string;
+    variables?: unknown;
+    operationName?: string;
+};
+type GraphqlCacheResult = Record<string, unknown> & {
+    data?: unknown;
+    errors?: unknown[];
+};
+type CacheRequestOptions = {
+    cache?: false | string | {
+        readPolicy?: string;
+        [key: string]: unknown;
+    };
+};
+type PublicClientCacheApi = {
+    enabled: boolean;
+    clear(): void;
+    invalidate(resourceName?: string | null): void;
+    snapshot(): ClientCacheSnapshot;
+    watch(request: unknown, callback: (event: {
+        data: unknown;
+        stale: boolean;
+        source: 'cache';
+    }) => unknown): () => void;
+};
+type ClientCacheController = {
+    enabled: boolean;
+    publicApi: PublicClientCacheApi;
+    executeRestRead(request: RestCacheRequest, network: () => RestCacheResult | Promise<RestCacheResult>, requestOptions?: CacheRequestOptions): Promise<RestCacheResult | null>;
+    executeGraphqlRead(request: GraphqlCacheRequest, network: () => GraphqlCacheResult | Promise<GraphqlCacheResult>, requestOptions?: CacheRequestOptions): Promise<GraphqlCacheResult | null>;
+    recordRestWrite(request: RestCacheRequest, result: RestCacheResult): void;
+    recordGraphqlWrite(result: GraphqlCacheResult): void;
+};
+type IndexedDbCacheStorageOptions = {
+    name?: string;
+    storeName?: string;
+    key?: string;
+    indexedDB?: IDBFactory;
+};
+export declare function createClientCache(options?: ClientCacheFactoryOptions): ClientCacheController;
+export declare function createIndexedDbCacheStorage(options?: IndexedDbCacheStorageOptions): ClientCacheStorage;
+export {};