@async/db 0.2.0

package/dist/features/storage/source.d.ts

@@ -0,0 +1,37 @@
+import { type SourceMetadata } from './source-metadata.js';
+type RuntimeConfig = {
+    cwd: string;
+    [key: string]: unknown;
+};
+type RuntimeResource = {
+    name: string;
+    dataPath?: string | null;
+    dataFormat?: string | null;
+    [key: string]: unknown;
+};
+type ResourceWriteOperation<T> = () => T | Promise<T>;
+export declare const sourceRuntimeCapabilities: {
+    writable: boolean;
+    persistence: string;
+    atomicity: string;
+    liveEvents: boolean;
+    staticExport: boolean;
+    production: boolean;
+};
+export declare function createSourceRuntimeAdapter(config: RuntimeConfig): {
+    name: string;
+    capabilities: {
+        writable: boolean;
+        persistence: string;
+        atomicity: string;
+        liveEvents: boolean;
+        staticExport: boolean;
+        production: boolean;
+    };
+    hydrate(resources: RuntimeResource[]): Promise<void>;
+    readResource(resource: RuntimeResource, fallback: unknown): Promise<unknown>;
+    writeResource(resource: RuntimeResource, value: unknown): Promise<boolean>;
+    withResourceWrite<T>(resource: RuntimeResource, operation: ResourceWriteOperation<T>): Promise<T>;
+};
+export declare function writeSourceMetadata(config: RuntimeConfig, resources: RuntimeResource[], sourceMetadata: SourceMetadata): Promise<void>;
+export {};

package/dist/features/storage/source.js

@@ -0,0 +1,60 @@
+import { dbError } from '../../errors.js';
+import { applyDefaultsToSeed } from '../sync/defaults.js';
+import { seedForRuntimeState } from '../sync/synthetic-seed.js';
+import { atomicWriteJson, readJsonState, withJsonStateWrite } from './json.js';
+import { updateSourceMetadataResource } from './source-metadata.js';
+export const sourceRuntimeCapabilities = {
+    writable: true,
+    persistence: 'source-file',
+    atomicity: 'resource',
+    liveEvents: true,
+    staticExport: false,
+    production: false,
+};
+export function createSourceRuntimeAdapter(config) {
+    const fallbacks = new Map();
+    return {
+        name: 'sourceFile',
+        capabilities: sourceRuntimeCapabilities,
+        async hydrate(resources) {
+            for (const resource of resources) {
+                assertWritableSource(resource);
+                fallbacks.set(resource.name, structuredClone(applyDefaultsToSeed(seedForRuntimeState(resource, config), resource, config)));
+            }
+        },
+        readResource(resource, fallback) {
+            assertWritableSource(resource);
+            return readJsonState(resource.dataPath, fallbacks.has(resource.name) ? structuredClone(fallbacks.get(resource.name)) : fallback);
+        },
+        writeResource(resource, value) {
+            assertWritableSource(resource);
+            return atomicWriteJson(resource.dataPath, value);
+        },
+        withResourceWrite(resource, operation) {
+            assertWritableSource(resource);
+            return withJsonStateWrite(resource.dataPath, operation);
+        },
+    };
+}
+export async function writeSourceMetadata(config, resources, sourceMetadata) {
+    for (const resource of resources) {
+        updateSourceMetadata(sourceMetadata, config, resource);
+    }
+}
+function assertWritableSource(resource) {
+    if (resource.dataPath && resource.dataFormat === 'json') {
+        return;
+    }
+    throw dbError('STORE_SOURCE_NOT_WRITABLE', `Resource "${resource.name}" cannot use the sourceFile store because it is not backed by a plain JSON data file.`, {
+        status: 400,
+        hint: 'Use store "sourceFile" only for resources loaded from db/*.json data files.',
+        details: {
+            resource: resource.name,
+            dataFormat: resource.dataFormat,
+            dataPath: resource.dataPath,
+        },
+    });
+}
+function updateSourceMetadata(sourceMetadata, config, resource) {
+    updateSourceMetadataResource(sourceMetadata, config, resource);
+}

package/dist/features/storage/static.d.ts

@@ -0,0 +1,29 @@
+type RuntimeConfig = Record<string, unknown>;
+type RuntimeResource = {
+    name: string;
+    [key: string]: unknown;
+};
+export declare const staticRuntimeCapabilities: {
+    writable: boolean;
+    persistence: string;
+    atomicity: string;
+    liveEvents: boolean;
+    staticExport: boolean;
+    production: boolean;
+};
+export declare function createStaticRuntimeAdapter(config: RuntimeConfig): {
+    name: string;
+    capabilities: {
+        writable: boolean;
+        persistence: string;
+        atomicity: string;
+        liveEvents: boolean;
+        staticExport: boolean;
+        production: boolean;
+    };
+    hydrate(resources: RuntimeResource[]): Promise<void>;
+    readResource(resource: RuntimeResource, fallback: unknown): Promise<unknown>;
+    writeResource(resource: RuntimeResource): Promise<never>;
+    withResourceWrite(resource: RuntimeResource): Promise<never>;
+};
+export {};

package/dist/features/storage/static.js

@@ -0,0 +1,42 @@
+import { dbError } from '../../errors.js';
+import { applyDefaultsToSeed } from '../sync/defaults.js';
+import { seedForRuntimeState } from '../sync/synthetic-seed.js';
+export const staticRuntimeCapabilities = {
+    writable: false,
+    persistence: 'static',
+    atomicity: 'none',
+    liveEvents: false,
+    staticExport: true,
+    production: true,
+};
+export function createStaticRuntimeAdapter(config) {
+    const values = new Map();
+    return {
+        name: 'static',
+        capabilities: staticRuntimeCapabilities,
+        async hydrate(resources) {
+            for (const resource of resources) {
+                values.set(resource.name, structuredClone(applyDefaultsToSeed(seedForRuntimeState(resource, config), resource, config)));
+            }
+        },
+        async readResource(resource, fallback) {
+            return values.has(resource.name) ? structuredClone(values.get(resource.name)) : structuredClone(fallback);
+        },
+        async writeResource(resource) {
+            throw readOnlyResourceError(resource);
+        },
+        async withResourceWrite(resource) {
+            throw readOnlyResourceError(resource);
+        },
+    };
+}
+function readOnlyResourceError(resource) {
+    return dbError('STORE_RESOURCE_READ_ONLY', `Resource "${resource.name}" is configured with a read-only store.`, {
+        status: 405,
+        hint: 'Use a writable store such as "json" or remove the static store strategy for this resource.',
+        details: {
+            resource: resource.name,
+            store: 'static',
+        },
+    });
+}

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

@@ -0,0 +1,21 @@
+type SyncConfig = {
+    defaults?: {
+        applyOnSafeMigration?: boolean;
+    };
+    [key: string]: unknown;
+};
+type FieldDefinition = {
+    default?: unknown;
+    [key: string]: unknown;
+};
+type SyncResource = {
+    name?: string;
+    kind?: string;
+    idField?: string;
+    fields?: Record<string, FieldDefinition>;
+    [key: string]: unknown;
+};
+type RuntimeRecord = Record<string, unknown>;
+export declare function applyDefaultsToSeed(seed: unknown, resource: SyncResource, config: SyncConfig): unknown;
+export declare function applyDefaultsToRecord<T>(record: T, resource: SyncResource): T | RuntimeRecord;
+export {};

package/dist/features/sync/defaults.js

@@ -0,0 +1,21 @@
+export function applyDefaultsToSeed(seed, resource, config) {
+    if (config.defaults?.applyOnSafeMigration === false) {
+        return seed;
+    }
+    if (resource.kind === 'collection') {
+        return Array.isArray(seed) ? seed.map((record) => applyDefaultsToRecord(record, resource)) : [];
+    }
+    return applyDefaultsToRecord(seed, resource);
+}
+export function applyDefaultsToRecord(record, resource) {
+    if (!record || typeof record !== 'object' || Array.isArray(record)) {
+        return record;
+    }
+    const next = { ...record };
+    for (const [fieldName, field] of Object.entries(resource.fields ?? {})) {
+        if (next[fieldName] === undefined && 'default' in field) {
+            next[fieldName] = structuredClone(field.default);
+        }
+    }
+    return next;
+}

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

@@ -0,0 +1,35 @@
+export { applyDefaultsToRecord, applyDefaultsToSeed } from './defaults.js';
+type SyncConfig = {
+    cwd: string;
+    stateDir: string;
+    types?: {
+        enabled?: boolean;
+    };
+    schemaOutFile?: string | null;
+    viewerManifestOutFile?: string | null;
+    [key: string]: unknown;
+};
+type SyncDiagnostic = {
+    code?: string;
+    severity?: string;
+    message: string;
+    [key: string]: unknown;
+};
+type SyncResource = {
+    name: string;
+    schemaPath?: string | null;
+    dataPath?: string | null;
+    [key: string]: unknown;
+};
+type SyncProject = {
+    resources: SyncResource[];
+    diagnostics: SyncDiagnostic[];
+    schema?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+type SyncOptions = {
+    allowErrors?: boolean;
+};
+export declare function syncDb(config: SyncConfig, options?: SyncOptions): Promise<SyncProject & {
+    logs: string[];
+}>;

package/dist/features/sync/index.js

@@ -0,0 +1,85 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { loadProjectSchema, makeGeneratedSchema } from '../../schema.js';
+import { generateSchemaManifest } from '../../schema-manifest.js';
+import { generateTypes } from '../../types.js';
+import { generateViewerManifest } from '../../viewer-manifest.js';
+import { readJsonState, writeJsonState } from '../runtime/state.js';
+import { createRuntime } from '../storage/runtime.js';
+import { writeSourceMetadata } from '../storage/source.js';
+import { writeText } from '../../fs-utils.js';
+import { ensureRuntimeDirs } from './runtime-dirs.js';
+import { writeGeneratedIdsToSources } from './source-writes.js';
+export { applyDefaultsToRecord, applyDefaultsToSeed } from './defaults.js';
+export async function syncDb(config, options = {}) {
+    const project = await loadProjectSchema(config);
+    const logs = [];
+    const errors = project.diagnostics.filter((diagnostic) => diagnostic.severity === 'error');
+    const fatalErrors = errors.filter((diagnostic) => diagnostic.code === 'RESOURCE_ALIAS_COLLISION');
+    for (const resource of project.resources) {
+        logs.push(`Loaded ${path.relative(config.cwd, String(resource.schemaPath ?? resource.dataPath ?? ''))}`);
+    }
+    if (fatalErrors.length > 0 || (errors.length > 0 && options.allowErrors !== true)) {
+        const error = new Error(errors.map((diagnostic) => diagnostic.message).join('\n'));
+        error.diagnostics = project.diagnostics;
+        throw error;
+    }
+    await writeGeneratedIdsToSources(config, project.resources, logs);
+    await ensureRuntimeDirs(config);
+    const schemaOutFile = path.join(config.stateDir, 'schema.generated.json');
+    project.schema = await preserveGeneratedAt(schemaOutFile, makeGeneratedSchema(project.resources, project.diagnostics));
+    await writeText(schemaOutFile, `${JSON.stringify(project.schema, null, 2)}\n`);
+    logs.push(`Generated ${path.relative(config.cwd, schemaOutFile)}`);
+    if (config.types?.enabled !== false) {
+        const result = await generateTypes(config, { project });
+        for (const outFile of result.outFiles) {
+            logs.push(`Generated ${path.relative(config.cwd, String(outFile))}`);
+        }
+    }
+    if (config.schemaOutFile) {
+        const result = await generateSchemaManifest(config, { project });
+        for (const outFile of result.outFiles) {
+            logs.push(`Generated ${path.relative(config.cwd, String(outFile))}`);
+        }
+    }
+    if (config.viewerManifestOutFile) {
+        const result = await generateViewerManifest(config, { project });
+        for (const outFile of result.outFiles) {
+            logs.push(`Generated ${path.relative(config.cwd, String(outFile))}`);
+        }
+    }
+    const sourceMetadataPath = path.join(config.stateDir, 'state', '.sources.json');
+    const sourceMetadata = await readJsonState(sourceMetadataPath, { resources: {} });
+    sourceMetadata.resources ??= {};
+    const runtime = createRuntime(config, project.resources);
+    await runtime.hydrate();
+    await writeSourceMetadata(config, project.resources, sourceMetadata);
+    await writeJsonState(sourceMetadataPath, sourceMetadata);
+    logs.push('Synced runtime store');
+    return {
+        ...project,
+        logs,
+    };
+}
+async function preserveGeneratedAt(schemaOutFile, schema) {
+    let previous;
+    try {
+        previous = JSON.parse(await readFile(schemaOutFile, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT' || error instanceof SyntaxError) {
+            return schema;
+        }
+        throw error;
+    }
+    if (isObject(previous) && typeof previous.generatedAt === 'string' && sameGeneratedSchema(previous, schema)) {
+        schema.generatedAt = previous.generatedAt;
+    }
+    return schema;
+}
+function sameGeneratedSchema(left, right) {
+    return JSON.stringify({ ...left, generatedAt: null }) === JSON.stringify({ ...right, generatedAt: null });
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/features/sync/mirror-state.d.ts

@@ -0,0 +1,14 @@
+type SyncConfig = {
+    cwd: string;
+    stateDir: string;
+    [key: string]: unknown;
+};
+type SyncResource = {
+    name: string;
+    [key: string]: unknown;
+};
+type SourceMetadata = {
+    resources: Record<string, unknown>;
+};
+export declare function syncStateResource(config: SyncConfig, resource: SyncResource, sourceMetadata: SourceMetadata): Promise<void>;
+export {};

package/dist/features/sync/mirror-state.js

@@ -0,0 +1,4 @@
+import { syncJsonResourceState } from '../storage/json.js';
+export async function syncStateResource(config, resource, sourceMetadata) {
+    await syncJsonResourceState(config, resource, sourceMetadata);
+}

package/dist/features/sync/runtime-dirs.d.ts

@@ -0,0 +1,5 @@
+type RuntimeDirsConfig = {
+    stateDir: string;
+};
+export declare function ensureRuntimeDirs(config: RuntimeDirsConfig): Promise<void>;
+export {};

package/dist/features/sync/runtime-dirs.js

@@ -0,0 +1,9 @@
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+export async function ensureRuntimeDirs(config) {
+    await mkdir(config.stateDir, { recursive: true });
+    await mkdir(path.join(config.stateDir, 'state'), { recursive: true });
+    await mkdir(path.join(config.stateDir, 'wal'), { recursive: true });
+    await mkdir(path.join(config.stateDir, 'migrations'), { recursive: true });
+    await mkdir(path.join(config.stateDir, 'types'), { recursive: true });
+}

package/dist/features/sync/source-writes.d.ts

@@ -0,0 +1,15 @@
+type SyncConfig = {
+    cwd: string;
+    resources?: Record<string, unknown>;
+    stores?: Record<string, unknown>;
+};
+type SyncResource = {
+    name: string;
+    seed?: unknown;
+    generatedIds?: boolean;
+    dataFormat?: string;
+    dataPath?: string | null;
+    dataHash?: string;
+};
+export declare function writeGeneratedIdsToSources(config: SyncConfig, resources: SyncResource[], logs: string[]): Promise<void>;
+export {};

package/dist/features/sync/source-writes.js

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { writeText } from '../../fs-utils.js';
+import { resourceConfigValue } from '../../names.js';
+export async function writeGeneratedIdsToSources(config, resources, logs) {
+    for (const resource of resources) {
+        if (!usesSourceFileStore(config, resource) || !resource.generatedIds || resource.dataFormat !== 'json' || !resource.dataPath) {
+            continue;
+        }
+        const text = `${JSON.stringify(resource.seed, null, 2)}\n`;
+        await writeText(resource.dataPath, text);
+        resource.dataHash = createHash('sha256').update(text).digest('hex');
+        resource.generatedIds = false;
+        logs.push(`Updated ${path.relative(config.cwd, resource.dataPath)} with generated ids`);
+    }
+}
+function usesSourceFileStore(config, resource) {
+    const resourceConfig = storeRecord(resourceConfigValue(config.resources, resource.name));
+    const storeName = String(resourceConfig?.store ?? config.stores?.default ?? 'json');
+    const configured = config.stores?.[storeName] ?? storeName;
+    const configuredRecord = storeRecord(configured);
+    const driver = typeof configured === 'string' ? configured : configuredRecord?.driver ?? storeName;
+    return driver === 'sourceFile';
+}
+function storeRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}

package/dist/features/sync/synthetic-seed.d.ts

@@ -0,0 +1,26 @@
+type SyncConfig = {
+    seed?: {
+        generateFromSchema?: boolean;
+        generatedCount?: unknown;
+    };
+    [key: string]: unknown;
+};
+type FieldDefinition = {
+    type?: string;
+    default?: unknown;
+    values?: unknown[];
+    items?: FieldDefinition;
+    fields?: Record<string, FieldDefinition>;
+};
+type SyncResource = {
+    name?: string;
+    kind?: string;
+    idField?: string;
+    dataPath?: string | null;
+    schemaPath?: string | null;
+    seed?: unknown;
+    fields?: Record<string, FieldDefinition>;
+    [key: string]: unknown;
+};
+export declare function seedForRuntimeState(resource: SyncResource, config: SyncConfig): unknown;
+export {};

package/dist/features/sync/synthetic-seed.js

@@ -0,0 +1,83 @@
+export function seedForRuntimeState(resource, config) {
+    if (shouldGenerateSeedFromSchema(resource, config)) {
+        return generateSyntheticSeed(resource, syntheticSeedCount(config));
+    }
+    return resource.seed;
+}
+function shouldGenerateSeedFromSchema(resource, config) {
+    if (config.seed?.generateFromSchema !== true) {
+        return false;
+    }
+    if (resource.dataPath || !resource.schemaPath) {
+        return false;
+    }
+    if (resource.kind === 'collection') {
+        return Array.isArray(resource.seed) && resource.seed.length === 0;
+    }
+    return isPlainObject(resource.seed) && Object.keys(resource.seed).length === 0;
+}
+function syntheticSeedCount(config) {
+    const value = Number(config.seed?.generatedCount);
+    if (!Number.isFinite(value)) {
+        return 5;
+    }
+    return Math.max(0, Math.floor(value));
+}
+function generateSyntheticSeed(resource, count) {
+    if (resource.kind === 'collection') {
+        return Array.from({ length: count }, (_unused, index) => generateSyntheticRecord(resource, index));
+    }
+    return generateSyntheticRecord(resource, 0);
+}
+function generateSyntheticRecord(resource, index) {
+    const record = {};
+    for (const [fieldName, field] of Object.entries(resource.fields ?? {})) {
+        if (fieldName === resource.idField) {
+            record[fieldName] = String(index + 1);
+            continue;
+        }
+        const value = syntheticValue(field, fieldName, index);
+        if (value !== undefined) {
+            record[fieldName] = value;
+        }
+    }
+    return record;
+}
+function syntheticValue(field, fieldName, index) {
+    if (!field || typeof field !== 'object' || Array.isArray(field)) {
+        return null;
+    }
+    if ('default' in field) {
+        return structuredClone(field.default);
+    }
+    if (field.type === 'enum' && Array.isArray(field.values) && field.values.length > 0) {
+        return field.values[index % field.values.length];
+    }
+    switch (field.type) {
+        case 'string':
+            return `${fieldName}_${index + 1}`;
+        case 'datetime':
+            return new Date(Date.UTC(2020, 0, index + 1)).toISOString();
+        case 'number':
+            return index + 1;
+        case 'boolean':
+            return index % 2 === 0;
+        case 'array':
+            return field.items ? [syntheticValue(field.items, `${fieldName}Item`, index)].filter((item) => item !== undefined) : [];
+        case 'object': {
+            const objectValue = {};
+            for (const [childName, childField] of Object.entries(field.fields ?? {})) {
+                const childValue = syntheticValue(childField, childName, index);
+                if (childValue !== undefined) {
+                    objectValue[childName] = childValue;
+                }
+            }
+            return objectValue;
+        }
+        default:
+            return null;
+    }
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/features/viewer/manifest.d.ts

@@ -0,0 +1,148 @@
+type ViewerConfig = {
+    cwd?: string;
+    viewerManifestOutFile?: string | null;
+    rest?: {
+        enabled?: boolean;
+        formats?: Record<string, string | ((...args: unknown[]) => unknown) | Record<string, unknown> | null | undefined>;
+    };
+    graphql?: {
+        enabled?: boolean;
+        path?: string;
+    };
+    server?: {
+        apiBase?: string;
+        viewerLinks?: unknown[];
+    };
+    [key: string]: unknown;
+};
+type ViewerRoutes = {
+    apiBase?: string;
+    viewerPath?: string;
+    manifestPath?: string;
+    manifestJsonPath?: string;
+    manifestHtmlPath?: string;
+    manifestMarkdownPath?: string;
+    schemaPath?: string;
+    eventsPath?: string;
+    logPath?: string;
+    batchPath?: string;
+    importPath?: string;
+    graphqlPath?: string;
+    restBasePath?: string | null;
+    [key: string]: unknown;
+};
+type ViewerResource = {
+    name: string;
+    kind: 'collection' | 'document' | string;
+    typeName?: string;
+    routePath: string;
+    idField?: string;
+    relations?: unknown[];
+    [key: string]: unknown;
+};
+type GenerateViewerManifestOptions = {
+    project?: unknown;
+    outFile?: string;
+    generatedAt?: string;
+    routes?: ViewerRoutes;
+};
+type RenderViewerManifestOptions = {
+    generatedAt?: string;
+    routes?: ViewerRoutes;
+    diagnostics?: unknown[];
+};
+type ViewerLink = {
+    label: string;
+    href: string;
+    source: 'built-in' | 'custom';
+};
+export declare function generateViewerManifest(config: ViewerConfig, options?: GenerateViewerManifestOptions): Promise<{
+    manifest: {
+        version: number;
+        kind: string;
+        generatedAt: string;
+        api: {
+            viewer: string;
+            manifest: string;
+            manifestJson: string;
+            manifestHtml: string;
+            manifestMarkdown: string;
+            formats: Record<string, {
+                extension: string;
+                mediaTypes: string[];
+                contentType: string;
+                manifestPath: string;
+            }>;
+            viewers: ViewerLink[];
+            schema: string;
+            events: string;
+            log: string;
+            batch: string;
+            import: string;
+            graphql: string;
+            restBasePath: string;
+            resources: {
+                [k: string]: Record<string, unknown>;
+            };
+        };
+        capabilities: {
+            collections: boolean;
+            documents: boolean;
+            rest: boolean;
+            writes: boolean;
+            restBatch: boolean;
+            graphql: boolean;
+            csvImport: boolean;
+            liveEvents: boolean;
+        };
+        collections: Record<string, Record<string, unknown>>;
+        documents: Record<string, Record<string, unknown>>;
+        diagnostics: unknown[];
+    };
+    content: string;
+    outFiles: string[];
+    diagnostics: unknown[];
+}>;
+export declare function renderViewerManifest(resources: ViewerResource[], config?: ViewerConfig, options?: RenderViewerManifestOptions): {
+    version: number;
+    kind: string;
+    generatedAt: string;
+    api: {
+        viewer: string;
+        manifest: string;
+        manifestJson: string;
+        manifestHtml: string;
+        manifestMarkdown: string;
+        formats: Record<string, {
+            extension: string;
+            mediaTypes: string[];
+            contentType: string;
+            manifestPath: string;
+        }>;
+        viewers: ViewerLink[];
+        schema: string;
+        events: string;
+        log: string;
+        batch: string;
+        import: string;
+        graphql: string;
+        restBasePath: string;
+        resources: {
+            [k: string]: Record<string, unknown>;
+        };
+    };
+    capabilities: {
+        collections: boolean;
+        documents: boolean;
+        rest: boolean;
+        writes: boolean;
+        restBatch: boolean;
+        graphql: boolean;
+        csvImport: boolean;
+        liveEvents: boolean;
+    };
+    collections: Record<string, Record<string, unknown>>;
+    documents: Record<string, Record<string, unknown>>;
+    diagnostics: unknown[];
+};
+export {};