@async/db 0.2.0

package/dist/features/doctor/index.js

@@ -0,0 +1,177 @@
+import { loadProjectSchema } from '../../schema.js';
+import { resourceConfigValue } from '../../names.js';
+import { duplicateIdFindings, mixedIdTypeFindings } from './duplicate-ids.js';
+import { inconsistentFieldTypeFindings } from './field-consistency.js';
+import { operationStrictModeFindings } from '../operations/readiness.js';
+import { relationSuggestionFindings } from './relations.js';
+import { schemaGuidanceFindings } from './schema-guidance.js';
+const BUILTIN_STORES = ['json', 'memory', 'sourceFile', 'static'];
+const LARGE_JSON_STORE_RECORD_COUNT = 1000;
+export async function runDbDoctor(config) {
+    const project = await loadProjectSchema(config);
+    const inferredProject = await loadProjectSchema({
+        ...config,
+        schema: {
+            ...config.schema,
+            source: 'data',
+        },
+    });
+    const findings = [
+        ...project.diagnostics.map((diagnostic) => diagnosticToFinding(diagnostic, 'schema')),
+        ...doctorResourceFindings(project.resources, config),
+        ...schemaGuidanceFindings(project, inferredProject),
+        ...await operationStrictModeFindings(config),
+    ];
+    return {
+        summary: summarizeFindings(findings),
+        findings,
+    };
+}
+function diagnosticToFinding(diagnostic, source) {
+    return {
+        ...diagnostic,
+        source: diagnostic.source ?? source,
+        severity: diagnostic.severity ?? 'warn',
+        hint: diagnostic.hint ?? '',
+        details: diagnostic.details ?? {},
+    };
+}
+function doctorResourceFindings(resources, config) {
+    const collections = resources.filter((resource) => (resource.kind === 'collection'
+        && Array.isArray(resource.seed)
+        && resource.seed.every((record) => isRecord(record))));
+    return [
+        ...storeConfigFindings(resources, config),
+        ...jsonProductionFindings(resources, config),
+        ...collections.flatMap((resource) => [
+            ...duplicateIdFindings(resource),
+            ...mixedIdTypeFindings(resource),
+            ...inconsistentFieldTypeFindings(resource),
+        ]),
+        ...relationSuggestionFindings(collections),
+    ];
+}
+function jsonProductionFindings(resources, config) {
+    if (config.doctor?.production !== true) {
+        return [];
+    }
+    return resources.flatMap((resource) => {
+        const findings = [];
+        const resourceConfig = resourceConfigValue(config.resources, resource.name);
+        const storeName = resourceConfig?.store ?? config.stores?.default ?? 'json';
+        const driver = resolveStoreDriver(storeName, config);
+        if (driver !== 'json') {
+            return findings;
+        }
+        findings.push({
+            code: 'DOCTOR_JSON_PRODUCTION_REVIEW',
+            severity: 'info',
+            source: 'doctor',
+            resource: resource.name,
+            message: `Resource "${resource.name}" uses the JSON store in production mode.`,
+            hint: 'Keep JSON-backed production resources small, low-write, single-writer, and backed up; move high-write, multi-writer, transactional, or compliance-heavy data to SQLite, Postgres, or another app-owned store.',
+            details: {
+                resource: resource.name,
+                store: driver,
+                kind: resource.kind,
+                production: true,
+            },
+        });
+        if (!resource.schemaPath) {
+            findings.push({
+                code: 'DOCTOR_JSON_PRODUCTION_SCHEMA_RECOMMENDED',
+                severity: 'warn',
+                source: 'doctor',
+                resource: resource.name,
+                message: `Production JSON resource "${resource.name}" does not have an explicit schema file.`,
+                hint: `Add db/${resource.name}.schema.jsonc or a root db.schema.js entry so production writes validate against a reviewed contract.`,
+                details: {
+                    resource: resource.name,
+                    store: driver,
+                    kind: resource.kind,
+                    production: true,
+                },
+            });
+        }
+        return findings;
+    });
+}
+function storeConfigFindings(resources, config) {
+    return resources.flatMap((resource) => {
+        const findings = [];
+        const resourceConfig = resourceConfigValue(config.resources, resource.name);
+        const storeName = resourceConfig?.store ?? config.stores?.default ?? 'json';
+        const availableStores = configuredStoreNames(config);
+        if (!availableStores.includes(storeName) && config.stores?.[storeName] === undefined) {
+            findings.push({
+                code: 'DOCTOR_STORE_NOT_FOUND',
+                severity: 'error',
+                source: 'doctor',
+                resource: resource.name,
+                message: `Resource "${resource.name}" is configured with missing store "${storeName}".`,
+                hint: `Configure stores.${storeName}, choose stores.default, or use one of: ${availableStores.join(', ')}.`,
+                details: {
+                    resource: resource.name,
+                    store: storeName,
+                    availableStores,
+                },
+            });
+            return findings;
+        }
+        const driver = resolveStoreDriver(storeName, config);
+        if (resource.kind === 'collection'
+            && driver === 'json'
+            && Array.isArray(resource.seed)
+            && resource.seed.length > LARGE_JSON_STORE_RECORD_COUNT
+            && !hasIndexMetadata(resourceConfig)) {
+            findings.push({
+                code: 'DOCTOR_LARGE_JSON_STORE_WITHOUT_INDEXES',
+                severity: 'warn',
+                source: 'doctor',
+                resource: resource.name,
+                message: `Resource "${resource.name}" has ${resource.seed.length} records in the JSON store without index metadata.`,
+                hint: `Add resources.${resource.name}.indexes for dashboard or range-query fields, or bind the resource to a store better suited for large collections.`,
+                details: {
+                    resource: resource.name,
+                    store: driver,
+                    recordCount: resource.seed.length,
+                },
+            });
+        }
+        return findings;
+    });
+}
+function configuredStoreNames(config) {
+    return [
+        ...new Set([
+            ...BUILTIN_STORES,
+            ...Object.keys(config.stores ?? {}).filter((name) => name !== 'default'),
+        ]),
+    ];
+}
+function resolveStoreDriver(storeName, config) {
+    const configured = config.stores?.[storeName] ?? storeName;
+    if (typeof configured === 'string') {
+        return configured;
+    }
+    if (configured && typeof configured === 'object' && 'driver' in configured) {
+        return configured.driver;
+    }
+    return storeName;
+}
+function hasIndexMetadata(resourceConfig) {
+    return Array.isArray(resourceConfig?.indexes) && resourceConfig.indexes.length > 0;
+}
+function summarizeFindings(findings) {
+    return findings.reduce((summary, finding) => {
+        summary[finding.severity] = (summary[finding.severity] ?? 0) + 1;
+        return summary;
+    }, {
+        error: 0,
+        warn: 0,
+        info: 0,
+    });
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/features/doctor/relations.d.ts

@@ -0,0 +1,22 @@
+type DoctorRelation = {
+    sourceField: string;
+};
+type DoctorResource = {
+    name: string;
+    idField: string;
+    fields?: Record<string, unknown>;
+    relations?: DoctorRelation[];
+    seed: Array<Record<string, unknown>>;
+};
+type DoctorFinding = {
+    code: string;
+    severity: 'warn' | 'info';
+    source: 'doctor';
+    resource: string;
+    field: string;
+    message: string;
+    hint: string;
+    details: Record<string, unknown>;
+};
+export declare function relationSuggestionFindings(collections: DoctorResource[]): DoctorFinding[];
+export {};

package/dist/features/doctor/relations.js

@@ -0,0 +1,90 @@
+export function relationSuggestionFindings(collections) {
+    const findings = [];
+    for (const source of collections) {
+        const explicitRelationFields = new Set((source.relations ?? []).map((relation) => relation.sourceField));
+        for (const fieldName of Object.keys(source.fields ?? {})) {
+            if (fieldName === source.idField || explicitRelationFields.has(fieldName) || !fieldName.endsWith('Id')) {
+                continue;
+            }
+            const relationName = fieldName.slice(0, -2);
+            const target = collections.find((candidate) => candidate.name !== source.name && relationNameMatchesResource(relationName, candidate.name));
+            if (!target) {
+                continue;
+            }
+            const sourceValues = source.seed
+                .map((record) => record?.[fieldName])
+                .filter((value) => !isEmpty(value));
+            if (sourceValues.length === 0) {
+                continue;
+            }
+            const targetValues = new Set(target.seed
+                .map((record) => record?.[target.idField])
+                .filter((value) => !isEmpty(value))
+                .map((value) => String(value)));
+            const matchingValues = sourceValues
+                .filter((value) => targetValues.has(String(value)));
+            const missingValues = [...new Set(sourceValues
+                    .filter((value) => !targetValues.has(String(value)))
+                    .map((value) => String(value)))];
+            const matchingCount = matchingValues.length;
+            if (matchingCount === 0) {
+                continue;
+            }
+            const suggestedRelation = {
+                name: relationName,
+                to: target.name,
+                toField: target.idField,
+                cardinality: 'one',
+            };
+            if (missingValues.length > 0) {
+                findings.push({
+                    code: 'DOCTOR_RELATION_MISSING_TARGET_VALUES',
+                    severity: 'warn',
+                    source: 'doctor',
+                    resource: source.name,
+                    field: fieldName,
+                    message: `${source.name}.${fieldName} looks related to ${target.name}.${target.idField}, but ${missingValues.length} value(s) are missing from ${target.name}.`,
+                    hint: `Add matching ${target.name} records, fix ${source.name}.${fieldName}, or ignore this if the field is not a relation.`,
+                    details: {
+                        suggestedRelation,
+                        missingValues,
+                        matchingCount,
+                    },
+                });
+                continue;
+            }
+            findings.push({
+                code: 'DOCTOR_RELATION_SUGGESTION',
+                severity: 'info',
+                source: 'doctor',
+                resource: source.name,
+                field: fieldName,
+                message: `Possible relation detected: ${source.name}.${fieldName} -> ${target.name}.${target.idField}.`,
+                hint: `Add relation metadata to ${source.name}.schema.json to enable ?expand=${relationName}.`,
+                details: {
+                    suggestedRelation,
+                    matchingCount,
+                },
+            });
+        }
+    }
+    return findings;
+}
+function relationNameMatchesResource(relationName, resourceName) {
+    const normalizedRelation = relationName.toLowerCase();
+    return resourceNameVariants(resourceName).has(normalizedRelation);
+}
+function resourceNameVariants(resourceName) {
+    const normalized = resourceName.toLowerCase();
+    const variants = new Set([normalized]);
+    if (normalized.endsWith('ies') && normalized.length > 3) {
+        variants.add(`${normalized.slice(0, -3)}y`);
+    }
+    if (normalized.endsWith('s') && normalized.length > 1) {
+        variants.add(normalized.slice(0, -1));
+    }
+    return variants;
+}
+function isEmpty(value) {
+    return value === undefined || value === null || value === '';
+}

package/dist/features/doctor/schema-guidance.d.ts

@@ -0,0 +1,35 @@
+type SchemaField = {
+    type?: string;
+    required?: boolean;
+    nullable?: boolean;
+    values?: unknown[];
+    items?: SchemaField;
+    fields?: Record<string, SchemaField>;
+    [key: string]: unknown;
+};
+type SchemaResource = {
+    name: string;
+    kind: string;
+    idField?: string;
+    schemaPath?: string | null;
+    dataPath?: string | null;
+    typeSource?: string;
+    description?: string;
+    fields?: Record<string, SchemaField>;
+    seed?: unknown;
+};
+type SchemaProject = {
+    resources: SchemaResource[];
+};
+type DoctorFinding = {
+    code: string;
+    severity: 'info';
+    source: 'doctor';
+    resource: string;
+    field?: string;
+    message: string;
+    hint: string;
+    details: Record<string, unknown>;
+};
+export declare function schemaGuidanceFindings(project: SchemaProject, inferredProject: SchemaProject): DoctorFinding[];
+export {};

package/dist/features/doctor/schema-guidance.js

@@ -0,0 +1,184 @@
+export function schemaGuidanceFindings(project, inferredProject) {
+    return [
+        ...schemaRecommendedFindings(project.resources),
+        ...schemaMatchesInferenceFindings(project.resources, inferredProject.resources),
+    ];
+}
+function schemaRecommendedFindings(resources) {
+    const findings = [];
+    const seen = new Set();
+    for (const resource of resources) {
+        if (resource.schemaPath || resource.typeSource !== 'data') {
+            continue;
+        }
+        for (const fieldPath of ambiguousPolymorphicArrayPaths(resource.seed, resource.kind)) {
+            const key = `${resource.name}:${fieldPath}`;
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            findings.push({
+                code: 'DOCTOR_SCHEMA_RECOMMENDED',
+                severity: 'info',
+                source: 'doctor',
+                resource: resource.name,
+                field: fieldPath,
+                message: `${resource.name}.${fieldPath} has polymorphic array data that db cannot infer confidently.`,
+                hint: `Run async-db schema infer ${resource.name} --out db/${resource.name}.schema.jsonc to lock the current inferred shape into an explicit schema.`,
+                details: {
+                    resource: resource.name,
+                    field: fieldPath,
+                },
+            });
+        }
+    }
+    return findings;
+}
+function schemaMatchesInferenceFindings(resources, inferredResources) {
+    const inferredByName = new Map(inferredResources.map((resource) => [resource.name, resource]));
+    const findings = [];
+    for (const resource of resources) {
+        if (!resource.schemaPath || !resource.dataPath || hasNonInferableContractValue(resource)) {
+            continue;
+        }
+        const inferred = inferredByName.get(resource.name);
+        if (!inferred) {
+            continue;
+        }
+        if (JSON.stringify(comparableResource(resource)) !== JSON.stringify(comparableResource(inferred))) {
+            continue;
+        }
+        findings.push({
+            code: 'DOCTOR_SCHEMA_MATCHES_INFERENCE',
+            severity: 'info',
+            source: 'doctor',
+            resource: resource.name,
+            message: `${resource.name} schema matches inferred data and may be removable.`,
+            hint: 'Keep the schema if you want it as an explicit contract; otherwise the data fixture can infer the same local shape.',
+            details: {
+                resource: resource.name,
+            },
+        });
+    }
+    return findings;
+}
+function ambiguousPolymorphicArrayPaths(seed, kind) {
+    const roots = kind === 'collection' && Array.isArray(seed)
+        ? seed
+        : [seed];
+    const paths = [];
+    for (const root of roots) {
+        collectAmbiguousArrayPaths(root, '', paths);
+    }
+    return paths;
+}
+function collectAmbiguousArrayPaths(value, path, paths) {
+    if (Array.isArray(value)) {
+        if (isAmbiguousPolymorphicArray(value) && path) {
+            paths.push(path);
+            return;
+        }
+        for (const item of value) {
+            collectAmbiguousArrayPaths(item, path, paths);
+        }
+        return;
+    }
+    if (!isPlainRecord(value)) {
+        return;
+    }
+    for (const [fieldName, childValue] of Object.entries(value)) {
+        collectAmbiguousArrayPaths(childValue, path ? `${path}.${fieldName}` : fieldName, paths);
+    }
+}
+function isAmbiguousPolymorphicArray(value) {
+    const records = value.filter((item) => item !== null && item !== undefined && isPlainRecord(item));
+    if (records.length < 2 || records.length !== value.filter((item) => item !== null && item !== undefined).length) {
+        return false;
+    }
+    const signatures = new Set(records.map((record) => Object.keys(record).sort().join('|')));
+    return signatures.size > 1 && !hasStableDiscriminator(records);
+}
+function hasStableDiscriminator(records) {
+    return ['type', 'kind', 'blockType'].some((fieldName) => {
+        const values = records.map((record) => record[fieldName]);
+        return values.every((value) => typeof value === 'string' && value !== '')
+            && new Set(values).size >= 2;
+    });
+}
+function hasNonInferableContractValue(resource) {
+    if (resource.description) {
+        return true;
+    }
+    return Object.values(resource.fields ?? {}).some((field) => fieldHasNonInferableContractValue(field));
+}
+function fieldHasNonInferableContractValue(field) {
+    for (const property of [
+        'description',
+        'default',
+        'unique',
+        'relation',
+        'min',
+        'max',
+        'minLength',
+        'maxLength',
+        'pattern',
+        'additionalProperties',
+        'variants',
+    ]) {
+        if (property in field) {
+            return true;
+        }
+    }
+    if (field.type === 'array') {
+        return fieldHasNonInferableContractValue(field.items ?? { type: 'unknown' });
+    }
+    if (field.type === 'object') {
+        return Object.values(field.fields ?? {}).some((childField) => fieldHasNonInferableContractValue(childField));
+    }
+    return false;
+}
+function comparableResource(resource) {
+    const comparable = {
+        kind: resource.kind,
+        fields: comparableFieldMap(resource.fields ?? {}),
+    };
+    if (resource.kind === 'collection') {
+        comparable.idField = resource.idField;
+    }
+    return sortObject(comparable);
+}
+function comparableFieldMap(fields) {
+    return Object.fromEntries(Object.entries(fields)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([fieldName, field]) => [fieldName, comparableField(field)]));
+}
+function comparableField(field) {
+    const comparable = {
+        type: field.type ?? 'unknown',
+        required: Boolean(field.required),
+    };
+    if ('nullable' in field) {
+        comparable.nullable = Boolean(field.nullable);
+    }
+    if (field.type === 'enum') {
+        comparable.values = [...(field.values ?? [])];
+    }
+    if (field.type === 'array') {
+        comparable.items = comparableField(field.items ?? { type: 'unknown' });
+    }
+    if (field.type === 'object') {
+        comparable.fields = comparableFieldMap(field.fields ?? {});
+    }
+    return sortObject(comparable);
+}
+function sortObject(value) {
+    if (!isPlainRecord(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, childValue]) => [key, sortObject(childValue)]));
+}
+function isPlainRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/features/generate/registry.d.ts

@@ -0,0 +1,14 @@
+type GeneratorConfig = Record<string, unknown>;
+type Generator = {
+    name: string;
+    usage: string;
+    run: (config: GeneratorConfig, args: string[]) => Promise<unknown>;
+};
+type GeneratorRegistry = {
+    names: () => string[];
+    get: (name: string) => Generator | undefined;
+    usage: () => string;
+};
+export declare function defaultGeneratorRegistry(): GeneratorRegistry;
+export declare function createGeneratorRegistry(generators: Generator[]): GeneratorRegistry;
+export {};

package/dist/features/generate/registry.js

@@ -0,0 +1,37 @@
+import { generateHonoStarter } from '../../generate/hono.js';
+import { valueAfter } from '../../cli/args.js';
+export function defaultGeneratorRegistry() {
+    return createGeneratorRegistry([
+        honoGenerator(),
+    ]);
+}
+export function createGeneratorRegistry(generators) {
+    const byName = new Map(generators.map((generator) => [generator.name, generator]));
+    return {
+        names() {
+            return [...byName.keys()];
+        },
+        get(name) {
+            return byName.get(name);
+        },
+        usage() {
+            return generators.map((generator) => generator.usage).join('\n');
+        },
+    };
+}
+function honoGenerator() {
+    return {
+        name: 'hono',
+        usage: 'async-db generate hono [--out <dir>] [--api <rest|graphql|rest,graphql|none>] [--db sqlite] [--app <standalone|module>] [--seed fixtures] [--allow-warnings]',
+        async run(config, args) {
+            return generateHonoStarter(config, {
+                outDir: valueAfter(args, '--out'),
+                api: valueAfter(args, '--api'),
+                db: valueAfter(args, '--db'),
+                app: valueAfter(args, '--app'),
+                seed: valueAfter(args, '--seed'),
+                allowWarnings: args.includes('--allow-warnings') ? true : undefined,
+            });
+        },
+    };
+}

package/dist/features/http/registry.d.ts

@@ -0,0 +1,46 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+type HttpFeaturePhase = 'preMock' | 'postMock' | string;
+type RuntimeEventSource = {
+    subscribe: (subscriber: (event: unknown) => void) => () => void;
+};
+type HttpFeatureDb = {
+    config: {
+        graphql?: {
+            enabled?: boolean;
+        };
+        server?: {
+            maxBodyBytes?: number;
+        };
+    };
+    resources: Map<string, unknown>;
+    events: RuntimeEventSource;
+    [key: string]: unknown;
+};
+type HttpRoutes = {
+    logPath: string;
+    graphqlPath: string;
+    [key: string]: unknown;
+};
+type HttpFeatureContext = {
+    db: HttpFeatureDb;
+    request: IncomingMessage;
+    response: ServerResponse;
+    url: URL;
+    routes: HttpRoutes;
+};
+type HttpFeature = {
+    name: string;
+    phase?: HttpFeaturePhase;
+    match: (context: HttpFeatureContext) => boolean;
+    handle: (context: HttpFeatureContext) => void | Promise<void>;
+};
+type HttpFeatureOptions = {
+    phase?: HttpFeaturePhase;
+};
+type HttpFeatureRegistry = {
+    matches: (context: HttpFeatureContext, options?: HttpFeatureOptions) => boolean;
+    handle: (context: HttpFeatureContext, options?: HttpFeatureOptions) => Promise<boolean>;
+};
+export declare function defaultHttpFeatureRegistry(): HttpFeatureRegistry;
+export declare function createHttpFeatureRegistry(features: HttpFeature[]): HttpFeatureRegistry;
+export {};