@async/db 0.2.0

package/dist/features/schema/fields.js

@@ -0,0 +1,296 @@
+export function normalizeField(field, fieldName = '') {
+    if (!isPlainRecord(field)) {
+        return inferFieldFromValue(field, fieldName, { required: false });
+    }
+    const normalized = {
+        type: (field.type ?? 'unknown'),
+    };
+    if ('nullable' in field) {
+        normalized.nullable = Boolean(field.nullable);
+    }
+    if ('required' in field) {
+        normalized.required = Boolean(field.required);
+    }
+    if ('computed' in field) {
+        normalized.computed = Boolean(field.computed);
+    }
+    if ('readOnly' in field) {
+        normalized.readOnly = Boolean(field.readOnly);
+    }
+    if (normalized.computed) {
+        normalized.readOnly = true;
+        normalized.required = false;
+    }
+    if ('description' in field) {
+        normalized.description = String(field.description);
+    }
+    if ('default' in field) {
+        normalized.default = field.default;
+    }
+    if ('unique' in field) {
+        normalized.unique = Boolean(field.unique);
+    }
+    for (const constraintName of ['min', 'max', 'minLength', 'maxLength', 'pattern']) {
+        if (constraintName in field) {
+            normalized[constraintName] = field[constraintName];
+        }
+    }
+    if (isPlainRecord(field.relation)) {
+        normalized.relation = normalizeRelation(field.relation, fieldName);
+    }
+    if (field.type === 'enum') {
+        normalized.values = Array.isArray(field.values) ? [...field.values] : [];
+    }
+    if (field.type === 'array') {
+        normalized.items = normalizeField(field.items ?? { type: 'unknown' }, `${fieldName}Item`);
+    }
+    if (field.type === 'object' && 'additionalProperties' in field) {
+        normalized.additionalProperties = Boolean(field.additionalProperties);
+    }
+    if (field.type === 'object' && 'discriminator' in field) {
+        normalized.discriminator = String(field.discriminator);
+    }
+    if (field.type === 'object' && isPlainRecord(field.fields)) {
+        normalized.fields = Object.fromEntries(Object.entries(field.fields).map(([childName, childField]) => [childName, normalizeField(childField, childName)]));
+    }
+    if (field.type === 'object' && isPlainRecord(field.variants)) {
+        normalized.variants = Object.fromEntries(Object.entries(field.variants).map(([variantName, variant]) => [variantName, normalizeVariant(variantName, variant, normalized.discriminator)]));
+    }
+    return normalized;
+}
+export function inferFieldsFromData(value, kind = 'collection') {
+    if (kind === 'collection') {
+        const records = Array.isArray(value) ? value : [];
+        const names = new Set();
+        for (const record of records) {
+            if (isPlainRecord(record)) {
+                for (const key of Object.keys(record)) {
+                    names.add(key);
+                }
+            }
+        }
+        return Object.fromEntries([...names].sort().map((fieldName) => {
+            const samples = records.map((record) => isPlainRecord(record) ? record[fieldName] : undefined);
+            const present = samples.filter((sample) => sample !== undefined && sample !== null);
+            const required = records.length > 0 && present.length === records.length;
+            return [fieldName, inferFieldFromSamples(present, fieldName, { required })];
+        }));
+    }
+    if (!isPlainRecord(value)) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([fieldName, sample]) => [fieldName, inferFieldFromValue(sample, fieldName, { required: false })]));
+}
+export function inferFieldFromSamples(samples, fieldName, options = {}) {
+    if (samples.length === 0) {
+        return { type: 'unknown', required: Boolean(options.required) };
+    }
+    if (options.inferVariants === true) {
+        const variantField = inferDiscriminatedObjectField(samples, options.required);
+        if (variantField) {
+            return variantField;
+        }
+    }
+    const inferred = samples.map((sample) => inferFieldFromValue(sample, fieldName, options));
+    return mergeInferredFields(inferred, options.required);
+}
+export function inferFieldFromValue(value, fieldName, options = {}) {
+    const required = Boolean(options.required);
+    if (value === null || value === undefined) {
+        return { type: 'unknown', required: false };
+    }
+    if (Array.isArray(value)) {
+        return {
+            type: 'array',
+            required,
+            items: inferFieldFromSamples(value.filter((item) => item !== null && item !== undefined), `${fieldName}Item`, {
+                required: false,
+                inferVariants: true,
+            }),
+        };
+    }
+    if (isPlainRecord(value)) {
+        return {
+            type: 'object',
+            required,
+            fields: inferFieldsFromData(value, 'document'),
+        };
+    }
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return { type: typeof value, required };
+    }
+    return { type: 'unknown', required };
+}
+function mergeInferredFields(fields, required) {
+    if (fields.length === 0) {
+        return { type: 'unknown', required: Boolean(required) };
+    }
+    const types = new Set(fields.map((field) => field.type));
+    if (types.size > 1) {
+        return { type: 'unknown', required: Boolean(required) };
+    }
+    const [first] = fields;
+    if (first.type === 'object') {
+        if (fields.every((field) => field.type === 'object' && field.variants && field.discriminator === first.discriminator)) {
+            return mergeVariantObjectFields(fields, required);
+        }
+        const names = new Set();
+        for (const field of fields) {
+            for (const childName of Object.keys(field.fields ?? {})) {
+                names.add(childName);
+            }
+        }
+        return {
+            type: 'object',
+            required: Boolean(required),
+            fields: Object.fromEntries([...names].sort().map((childName) => {
+                const childSamples = fields.map((field) => field.fields?.[childName]).filter(Boolean);
+                return [childName, mergeInferredFields(childSamples, childSamples.every((field) => field.required))];
+            })),
+        };
+    }
+    if (first.type === 'array') {
+        return {
+            type: 'array',
+            required: Boolean(required),
+            items: mergeInferredFields(fields.map((field) => field.items).filter(Boolean), false),
+        };
+    }
+    return {
+        ...first,
+        required: Boolean(required),
+    };
+}
+function mergeVariantObjectFields(fields, required) {
+    const discriminator = fields[0].discriminator;
+    const variantNames = new Set();
+    for (const field of fields) {
+        for (const variantName of Object.keys(field.variants ?? {})) {
+            variantNames.add(variantName);
+        }
+    }
+    return {
+        type: 'object',
+        required: Boolean(required),
+        discriminator,
+        variants: Object.fromEntries([...variantNames].map((variantName) => [
+            variantName,
+            mergeVariantDefinitions(fields.map((field) => field.variants?.[variantName]).filter(Boolean), discriminator, variantName),
+        ])),
+    };
+}
+function mergeVariantDefinitions(variants, discriminator, variantName) {
+    const fieldNames = new Set();
+    for (const variant of variants) {
+        for (const fieldName of Object.keys(variant.fields ?? {})) {
+            fieldNames.add(fieldName);
+        }
+    }
+    const fields = Object.fromEntries([...fieldNames].sort().map((fieldName) => {
+        const childFields = variants.map((variant) => variant.fields?.[fieldName]).filter(Boolean);
+        const required = childFields.length === variants.length && childFields.every((field) => field.required);
+        return [fieldName, mergeInferredFields(childFields, required)];
+    }));
+    fields[discriminator] = {
+        type: 'enum',
+        values: [variantName],
+        required: true,
+    };
+    return { fields };
+}
+function normalizeVariant(variantName, variant, discriminator) {
+    const raw = isPlainRecord(variant)
+        ? variant
+        : {};
+    const rawFields = isPlainRecord(raw.fields)
+        ? raw.fields
+        : {};
+    const normalized = {
+        fields: Object.fromEntries(Object.entries(rawFields).map(([fieldName, field]) => [fieldName, normalizeField(field, fieldName)])),
+    };
+    if ('additionalProperties' in raw) {
+        normalized.additionalProperties = Boolean(raw.additionalProperties);
+    }
+    if (discriminator && !(discriminator in normalized.fields)) {
+        normalized.fields = {
+            [discriminator]: {
+                type: 'enum',
+                values: [variantName],
+                required: true,
+            },
+            ...normalized.fields,
+        };
+    }
+    return normalized;
+}
+function inferDiscriminatedObjectField(samples, required) {
+    const records = samples.filter((sample) => sample !== null && sample !== undefined);
+    if (records.length === 0 || records.some((sample) => !isPlainRecord(sample))) {
+        return null;
+    }
+    const objectRecords = records;
+    for (const discriminator of ['type', 'kind', 'blockType']) {
+        const groups = groupByDiscriminator(objectRecords, discriminator);
+        if (!groups) {
+            continue;
+        }
+        const signatures = new Set([...groups.values()].map((group) => objectSignature(group[0], discriminator)));
+        if (signatures.size < 2) {
+            continue;
+        }
+        return {
+            type: 'object',
+            required: Boolean(required),
+            discriminator,
+            variants: Object.fromEntries([...groups.entries()].map(([variantName, group]) => {
+                const fields = inferFieldsFromData(group, 'collection');
+                fields[discriminator] = {
+                    type: 'enum',
+                    values: [variantName],
+                    required: true,
+                };
+                return [variantName, {
+                        fields,
+                    }];
+            })),
+        };
+    }
+    return null;
+}
+function groupByDiscriminator(records, discriminator) {
+    const groups = new Map();
+    for (const record of records) {
+        const value = record[discriminator];
+        if (typeof value !== 'string' || value === '') {
+            return null;
+        }
+        if (!groups.has(value)) {
+            groups.set(value, []);
+        }
+        groups.get(value).push(record);
+    }
+    return groups.size >= 2 ? groups : null;
+}
+function objectSignature(record, discriminator) {
+    return Object.keys(record)
+        .filter((fieldName) => fieldName !== discriminator)
+        .sort()
+        .join('|');
+}
+function normalizeRelation(relation, fieldName) {
+    return {
+        name: String(relation.name ?? relationNameFromField(fieldName)),
+        to: relation.to === undefined ? undefined : String(relation.to),
+        toField: String(relation.toField ?? 'id'),
+        cardinality: relation.cardinality === 'many' ? 'many' : 'one',
+    };
+}
+function isPlainRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function relationNameFromField(fieldName) {
+    const withoutId = String(fieldName).replace(/Id$/i, '');
+    return withoutId || String(fieldName);
+}

package/dist/features/schema/generated.d.ts

@@ -0,0 +1,29 @@
+import { type SchemaDiagnostic, type SchemaResource } from './metadata.js';
+type GeneratedSchemaResource = {
+    kind?: string;
+    typeName: string;
+    routePath: string;
+    idField?: string;
+    description?: unknown;
+    fields?: unknown;
+    relations?: unknown;
+    seed?: unknown;
+    source: {
+        typeSource?: unknown;
+        dataPath?: unknown;
+        dataFormat?: unknown;
+        dataHash?: unknown;
+        schemaPath?: unknown;
+        generatedIds?: unknown;
+    };
+};
+export declare function makeGeneratedSchema(resources: SchemaResource[], diagnostics?: SchemaDiagnostic[]): {
+    diagnostics: SchemaDiagnostic[];
+    version: number;
+    generatedAt: string;
+    resources: {
+        [k: string]: GeneratedSchemaResource;
+    };
+    relations: unknown[];
+};
+export {};

package/dist/features/schema/generated.js

@@ -0,0 +1,32 @@
+import { defaultGeneratedSchemaMetadataContributors, generatedSchemaMetadata, } from './metadata.js';
+export function makeGeneratedSchema(resources, diagnostics = []) {
+    const metadata = generatedSchemaMetadata(resources, diagnostics, defaultGeneratedSchemaMetadataContributors());
+    return {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        resources: Object.fromEntries(resources.map((resource) => [resource.name, serializeResource(resource)])),
+        relations: resources.flatMap((resource) => resource.relations ?? []),
+        ...metadata,
+        diagnostics,
+    };
+}
+function serializeResource(resource) {
+    return {
+        kind: resource.kind,
+        typeName: resource.typeName,
+        routePath: resource.routePath,
+        idField: resource.kind === 'collection' ? resource.idField : undefined,
+        description: resource.description,
+        fields: Object.keys(resource.fields ?? {}).length > 0 ? resource.fields : undefined,
+        relations: resource.relations,
+        seed: resource.seed,
+        source: {
+            typeSource: resource.typeSource,
+            dataPath: resource.dataPath,
+            dataFormat: resource.dataFormat,
+            dataHash: resource.dataHash,
+            schemaPath: resource.schemaPath,
+            generatedIds: resource.generatedIds,
+        },
+    };
+}

package/dist/features/schema/locator.d.ts

@@ -0,0 +1,16 @@
+export type SchemaLoadMode = 'schema' | 'data' | 'runtime';
+export type SchemaLocator = {
+    cwd: string;
+    sourceDir: string;
+    mode: 'project' | 'source-dir' | 'root-schema' | 'schema-file';
+    file: string | null;
+    baseDir: string;
+    resourceName: string | null;
+};
+type ResolveSchemaLocatorOptions = {
+    cwd?: string;
+    from?: string | null;
+};
+export declare function resolveSchemaLocator(options?: ResolveSchemaLocatorOptions | string): Promise<SchemaLocator>;
+export declare function normalizeSchemaLoadMode(value?: unknown): SchemaLoadMode;
+export {};

package/dist/features/schema/locator.js

@@ -0,0 +1,135 @@
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+const SCHEMA_FILE_RE = /(?:^|[/\\])(?:db\.schema\.(?:mjs|js)|[^/\\]+\.schema\.(?:json|jsonc|mjs|js))$/;
+export async function resolveSchemaLocator(options = {}) {
+    const input = typeof options === 'string' ? { from: options } : options ?? {};
+    const baseCwd = path.resolve(input.cwd ?? process.cwd());
+    const from = input.from === undefined || input.from === null || input.from === ''
+        ? null
+        : path.resolve(baseCwd, String(input.from));
+    if (!from) {
+        return projectLocator(baseCwd);
+    }
+    let stats;
+    try {
+        stats = await stat(from);
+    }
+    catch (error) {
+        const fsError = error;
+        if (fsError.code === 'ENOENT') {
+            throw schemaLocatorError('DB_SCHEMA_LOCATOR_NOT_FOUND', `Schema locator path does not exist: ${path.relative(baseCwd, from) || from}`, {
+                hint: 'Pass from: "." for a project root, from: "./db" for a fixture folder, or from: "./db.schema.mjs" / "./db.schema.js" / "./db/users.schema.mjs" for a schema file.',
+                details: {
+                    from: input.from,
+                    path: from,
+                },
+            });
+        }
+        throw error;
+    }
+    if (stats.isDirectory()) {
+        return directoryLocator(from, baseCwd);
+    }
+    if (stats.isFile()) {
+        return fileLocator(from, baseCwd);
+    }
+    throw schemaLocatorError('DB_SCHEMA_LOCATOR_UNSUPPORTED', `Schema locator must be a file or directory: ${path.relative(baseCwd, from) || from}`, {
+        hint: 'Use a project root, a db folder, db.schema.mjs, db.schema.js, or a .schema.json/.schema.jsonc/.schema.mjs/.schema.js file.',
+        details: {
+            from: input.from,
+            path: from,
+        },
+    });
+}
+export function normalizeSchemaLoadMode(value = 'data') {
+    if (value === undefined || value === null || value === '') {
+        return 'data';
+    }
+    if (value === 'schema' || value === 'data' || value === 'runtime') {
+        return value;
+    }
+    throw schemaLocatorError('DB_SCHEMA_LOAD_MODE_INVALID', `Unsupported schema load mode "${value}".`, {
+        hint: 'Use load: "schema", load: "data", or load: "runtime".',
+        details: {
+            load: value,
+            allowed: ['schema', 'data', 'runtime'],
+        },
+    });
+}
+function projectLocator(cwd) {
+    return {
+        cwd,
+        sourceDir: path.join(cwd, 'db'),
+        mode: 'project',
+        file: null,
+        baseDir: cwd,
+        resourceName: null,
+    };
+}
+function directoryLocator(directory, fallbackCwd) {
+    const basename = path.basename(directory);
+    const cwd = basename === 'db' ? path.dirname(directory) : directory;
+    return {
+        cwd: path.resolve(cwd || fallbackCwd),
+        sourceDir: basename === 'db' ? directory : path.join(directory, 'db'),
+        mode: basename === 'db' ? 'source-dir' : 'project',
+        file: null,
+        baseDir: directory,
+        resourceName: null,
+    };
+}
+function fileLocator(file, fallbackCwd) {
+    const normalized = file.split(path.sep).join('/');
+    if (!SCHEMA_FILE_RE.test(normalized)) {
+        throw schemaLocatorError('DB_SCHEMA_LOCATOR_UNSUPPORTED', `Unsupported schema locator file: ${path.basename(file)}`, {
+            hint: 'Use db.schema.mjs, db.schema.js, or a .schema.json/.schema.jsonc/.schema.mjs/.schema.js file.',
+            details: {
+                path: file,
+            },
+        });
+    }
+    if (path.basename(file) === 'db.schema.mjs' || path.basename(file) === 'db.schema.js') {
+        const cwd = path.dirname(file);
+        return {
+            cwd,
+            sourceDir: path.join(cwd, 'db'),
+            mode: 'root-schema',
+            file,
+            baseDir: cwd,
+            resourceName: null,
+        };
+    }
+    const sourceDir = inferSourceDirForSchemaFile(file);
+    const cwd = path.basename(sourceDir) === 'db' ? path.dirname(sourceDir) : fallbackCwd;
+    return {
+        cwd,
+        sourceDir,
+        mode: 'schema-file',
+        file,
+        baseDir: path.dirname(file),
+        resourceName: resourceNameForSchemaFile(file, sourceDir),
+    };
+}
+function inferSourceDirForSchemaFile(file) {
+    const segments = file.split(path.sep);
+    const dbIndex = segments.lastIndexOf('db');
+    if (dbIndex >= 0) {
+        return segments.slice(0, dbIndex + 1).join(path.sep) || path.sep;
+    }
+    return path.dirname(file);
+}
+function resourceNameForSchemaFile(file, sourceDir) {
+    const relative = path.relative(sourceDir, file).split(path.sep).join('/');
+    if (relative.endsWith('/index.schema.mjs') || relative.endsWith('/index.schema.js')) {
+        return path.basename(path.dirname(file));
+    }
+    return path.basename(relative).replace(/\.schema\.(?:json|jsonc|mjs|js)$/i, '');
+}
+function schemaLocatorError(code, message, options = {}) {
+    const error = new Error(message);
+    return Object.assign(error, {
+        code,
+        hint: options.hint,
+        details: options.details ?? {},
+    });
+}

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

@@ -0,0 +1,91 @@
+import type { SchemaField } from './fields.js';
+type ResourceKind = 'collection' | 'document';
+type ManifestDiagnostic = {
+    code: string;
+    severity: 'error' | 'warn' | 'info';
+    resource?: string;
+    field?: string;
+    message: string;
+    hint?: string;
+    details?: Record<string, unknown>;
+};
+type SchemaResource = {
+    kind: ResourceKind;
+    name: string;
+    idField?: string;
+    description?: string;
+    fields?: Record<string, SchemaField>;
+    schemaPath?: string | null;
+    dataPath?: string | null;
+};
+type FieldUiManifest = Record<string, unknown> & {
+    label: string;
+    component: string;
+    readonly?: boolean;
+    optionsFrom?: string;
+};
+type FieldManifest = Record<string, unknown> & {
+    type: string;
+    required: boolean;
+    nullable: boolean;
+    items?: FieldManifest;
+    fields?: Record<string, unknown>;
+    variants?: Record<string, VariantManifest>;
+    ui?: FieldUiManifest;
+};
+type VariantManifest = Record<string, unknown> & {
+    fields: Record<string, unknown>;
+    additionalProperties?: boolean;
+};
+type ResourceManifest = Record<string, unknown> & {
+    kind: ResourceKind;
+    name: string;
+    fields: Record<string, unknown>;
+    description?: string;
+    idField?: string;
+};
+type SchemaManifest = {
+    version: 1;
+    collections: Record<string, unknown>;
+    documents: Record<string, unknown>;
+};
+type ResourceCustomizeContext = {
+    resource: SchemaResource;
+    resourceName: string;
+    file: string | null;
+    sourceFile: string | null;
+    defaultManifest: ResourceManifest;
+};
+type FieldCustomizeContext = {
+    field: SchemaField;
+    fieldName: string;
+    resource: SchemaResource;
+    resourceName: string;
+    path: string;
+    file: string | null;
+    sourceFile: string | null;
+    defaultManifest: FieldManifest;
+};
+type SchemaManifestConfig = {
+    cwd?: string;
+    schemaOutFile?: string | null;
+    schemaManifest?: {
+        customizeResource?: (context: ResourceCustomizeContext) => unknown;
+        customizeField?: (context: FieldCustomizeContext) => unknown;
+        [key: string]: unknown;
+    } | null;
+    [key: string]: unknown;
+};
+type GenerateSchemaManifestOptions = {
+    project?: unknown;
+    outFile?: string | null;
+};
+type GenerateSchemaManifestResult = {
+    manifest: SchemaManifest;
+    content: string;
+    outFiles: string[];
+    diagnostics: ManifestDiagnostic[];
+};
+export declare function generateSchemaManifest(config: SchemaManifestConfig, options?: GenerateSchemaManifestOptions): Promise<GenerateSchemaManifestResult>;
+export declare function renderSchemaManifest(resources: SchemaResource[], config?: SchemaManifestConfig): SchemaManifest;
+export {};