@async/db 0.2.0

package/dist/features/schema/api.js

@@ -0,0 +1,460 @@
+import { loadConfig } from '../../config.js';
+import { dbError, listChoices } from '../../errors.js';
+import { resolveResource } from '../../names.js';
+import { loadProjectSchema } from './project.js';
+import { callFieldResolver, valueFromResolveManyResult } from './resolvers.js';
+import { isPromiseLike, standardSchemaIssueDiagnostics } from './standard-schema.js';
+import { validateRecordAgainstResource } from './validation.js';
+export async function loadDbSchema(options = {}) {
+    const rawOptions = typeof options === 'string'
+        ? { from: options }
+        : { ...options };
+    const load = (rawOptions.load ?? 'schema');
+    const config = await loadConfig({
+        ...rawOptions,
+        load,
+    });
+    const project = await loadProjectSchema(config, {
+        load: config.schemaLoadMode ?? load,
+    });
+    return createDbSchema(project, config);
+}
+export function createDbSchema(project, config) {
+    const resources = new Map(project.resources.map((resource) => [resource.name, resource]));
+    return {
+        kind: 'DbSchema',
+        config,
+        loadMode: project.loadMode,
+        locator: project.locator,
+        rootSchema: project.rootSchema,
+        resources,
+        diagnostics: project.diagnostics,
+        schema: project.schema,
+        resource(name) {
+            return requireSchemaResource(resources, name);
+        },
+        resourceNames() {
+            return [...resources.keys()];
+        },
+        validator(name, options = {}) {
+            return createSchemaValidator(requireSchemaResource(resources, name), config, options);
+        },
+        resolver(selector, options = {}) {
+            const { resourceName, fieldName } = parseResolverSelector(selector);
+            const resource = requireSchemaResource(resources, resourceName);
+            if (fieldName) {
+                return createSchemaFieldResolver(resource, fieldName, config, options);
+            }
+            return createSchemaResourceResolverMap(resource, config, options);
+        },
+        validate(name, value, options = {}) {
+            return this.validator(name, options).validate(value);
+        },
+        assert(name, value, options = {}) {
+            return this.validator(name, options).assert(value);
+        },
+        validateAsync(name, value, options = {}) {
+            return this.validator(name, options).validateAsync(value);
+        },
+        assertAsync(name, value, options = {}) {
+            return this.validator(name, options).assertAsync(value);
+        },
+        toJSON() {
+            return project.schema;
+        },
+    };
+}
+export function createSchemaResourceResolverMap(resource, config, options = {}) {
+    const resolvers = {};
+    for (const fieldName of Object.keys(resource.resolvers?.fields ?? {})) {
+        resolvers[fieldName] = createSchemaFieldResolver(resource, fieldName, config, options);
+    }
+    return resolvers;
+}
+export function createSchemaFieldResolver(resource, fieldName, config, options = {}) {
+    const resolver = resource.resolvers?.fields?.[fieldName];
+    if (!resolver) {
+        throw dbError('DB_SCHEMA_RESOLVER_NOT_FOUND', `Resource "${resource.name}" does not define a resolver for field "${fieldName}".`, {
+            status: 404,
+            hint: `Use one of: ${listChoices(Object.keys(resource.resolvers?.fields ?? {}))}.`,
+            details: {
+                resource: resource.name,
+                field: fieldName,
+                availableFields: Object.keys(resource.resolvers?.fields ?? {}),
+            },
+        });
+    }
+    const resolve = (async (args = {}) => {
+        if (typeof resolver.resolve === 'function') {
+            return callFieldResolver(resolver.resolve, normalizeResolverArgs(args), resolverCallOptions(resource, fieldName, config, options, args));
+        }
+        if (typeof resolver.resolveMany === 'function') {
+            const normalizedArgs = normalizeResolverArgs(args);
+            const record = normalizedArgs.record ?? normalizedArgs.value ?? {};
+            const manyArgs = {
+                ...normalizedArgs,
+                records: [record],
+            };
+            const values = await callFieldResolver(resolver.resolveMany, manyArgs, resolverCallOptions(resource, fieldName, config, options, {
+                ...spreadableRecord(args),
+                records: manyArgs.records,
+            }));
+            return valueFromResolveManyResult(values, resource, record, 0);
+        }
+        return undefined;
+    });
+    if (typeof resolver.resolve === 'function') {
+        resolve.resolve = resolve;
+    }
+    if (typeof resolver.resolveMany === 'function') {
+        resolve.resolveMany = async (args = {}) => {
+            const normalizedArgs = normalizeResolveManyArgs(args);
+            return callFieldResolver(resolver.resolveMany, normalizedArgs, resolverCallOptions(resource, fieldName, config, options, {
+                ...spreadableRecord(args),
+                records: normalizedArgs.records,
+            }));
+        };
+    }
+    return resolve;
+}
+export function createSchemaValidator(resource, config, options = {}) {
+    const mode = normalizeValidationMode(options.mode);
+    const unknownFields = normalizeValidatorUnknownFields(options.unknownFields);
+    function validate(value, validateOptions = {}) {
+        const result = validateInternal(value, validateOptions);
+        if (isPromiseLike(result)) {
+            throw asyncValidatorRequiredError(resource);
+        }
+        return result;
+    }
+    async function validateAsync(value, validateOptions = {}) {
+        return validateInternal(value, validateOptions, { allowAsync: true });
+    }
+    function validateInternal(value, validateOptions = {}, internalOptions = {}) {
+        const activeMode = normalizeValidationMode(validateOptions.mode ?? mode);
+        const activeUnknownFields = normalizeValidatorUnknownFields(validateOptions.unknownFields ?? unknownFields);
+        const source = validateOptions.source ?? options.source ?? `${resource.name} ${activeMode} input`;
+        const input = cloneInput(value);
+        const withDefaults = applyValidationDefaults(input, resource, {
+            mode: activeMode,
+            applyDefaults: validateOptions.applyDefaults ?? options.applyDefaults,
+        });
+        const standardResult = validateWithStandardSchema(resource, withDefaults);
+        if (isPromiseLike(standardResult)) {
+            if (!internalOptions.allowAsync) {
+                throw asyncValidatorRequiredError(resource);
+            }
+            return standardResult.then((resolvedStandardResult) => finishValidation(resolvedStandardResult, {
+                activeMode,
+                activeUnknownFields,
+                source,
+            }));
+        }
+        return finishValidation(standardResult, {
+            activeMode,
+            activeUnknownFields,
+            source,
+        });
+    }
+    function finishValidation(standardResult, context) {
+        const { activeMode, activeUnknownFields, source } = context;
+        const standardValue = standardResult.value;
+        const sanitized = activeUnknownFields === 'strip'
+            ? stripUnknownResourceFields(standardValue, resource)
+            : standardValue;
+        const validationConfig = {
+            ...config,
+            schema: {
+                ...config.schema,
+                unknownFields: activeUnknownFields === 'strip' || resource.fieldsAuthoritative === false
+                    ? 'allow'
+                    : activeUnknownFields,
+            },
+        };
+        const validationResource = validationResourceForMode(resource, sanitized, activeMode);
+        const diagnostics = [
+            ...standardResult.diagnostics,
+            ...validateRecordAgainstResource(sanitized, validationResource, validationConfig, {
+                source,
+                requireFields: activeMode !== 'patch',
+            }),
+        ];
+        const errors = diagnostics.filter((diagnostic) => diagnostic.severity === 'error');
+        return {
+            ok: errors.length === 0,
+            value: sanitized,
+            diagnostics,
+            errors,
+            resource: resource.name,
+            mode: activeMode,
+        };
+    }
+    return {
+        resource: resource.name,
+        mode,
+        unknownFields,
+        validate,
+        validateAsync,
+        assert(value, assertOptions = {}) {
+            const result = validate(value, assertOptions);
+            if (result.ok) {
+                return result.value;
+            }
+            throw dbError('DB_SCHEMA_VALIDATION_FAILED', `${resource.name} input does not match its schema: ${result.errors[0].message}`, {
+                status: 400,
+                hint: 'Update the input to match the schema field types, required fields, enum values, constraints, and read-only field rules.',
+                details: {
+                    resource: resource.name,
+                    mode: result.mode,
+                    diagnostics: result.diagnostics,
+                },
+            });
+        },
+        async assertAsync(value, assertOptions = {}) {
+            const result = await validateAsync(value, assertOptions);
+            if (result.ok) {
+                return result.value;
+            }
+            throw dbError('DB_SCHEMA_VALIDATION_FAILED', `${resource.name} input does not match its schema: ${result.errors[0].message}`, {
+                status: 400,
+                hint: 'Update the input to match the schema field types, required fields, enum values, constraints, and read-only field rules.',
+                details: {
+                    resource: resource.name,
+                    mode: result.mode,
+                    diagnostics: result.diagnostics,
+                },
+            });
+        },
+    };
+}
+function validateWithStandardSchema(resource, value) {
+    const standardSchema = resource.validators?.standard;
+    const validate = standardSchema?.['~standard']?.validate;
+    if (typeof validate !== 'function') {
+        return {
+            value,
+            diagnostics: [],
+        };
+    }
+    const result = validate(value);
+    if (isPromiseLike(result)) {
+        return result.then((resolved) => standardSchemaValidationResult(standardSchema, resource, value, resolved));
+    }
+    return standardSchemaValidationResult(standardSchema, resource, value, result);
+}
+function standardSchemaValidationResult(standardSchema, resource, inputValue, result) {
+    const issues = Array.isArray(result?.issues) ? result.issues : [];
+    return {
+        value: Object.prototype.hasOwnProperty.call(result ?? {}, 'value') ? result.value : inputValue,
+        diagnostics: standardSchemaIssueDiagnostics(standardSchema, issues, resource),
+    };
+}
+function asyncValidatorRequiredError(resource) {
+    return dbError('DB_SCHEMA_ASYNC_VALIDATOR_REQUIRED', `${resource.name} uses an async Standard Schema validator, but this helper is synchronous.`, {
+        status: 400,
+        hint: 'Use validateAsync(...) or assertAsync(...) for resources backed by async Standard Schema validators.',
+        details: {
+            resource: resource.name,
+        },
+    });
+}
+function parseResolverSelector(selector) {
+    const value = String(selector ?? '');
+    const [resourceName, ...fieldParts] = value.split('.');
+    const fieldName = fieldParts.join('.');
+    if (!resourceName) {
+        throw dbError('DB_SCHEMA_RESOLVER_SELECTOR_INVALID', `Invalid schema resolver selector ${JSON.stringify(selector)}.`, {
+            status: 400,
+            hint: 'Use "resourceName" for a resolver map or "resourceName.fieldName" for one field resolver.',
+            details: {
+                selector,
+            },
+        });
+    }
+    return {
+        resourceName,
+        fieldName: fieldName || null,
+    };
+}
+function resolverCallOptions(resource, fieldName, config, options, args) {
+    const normalizedArgs = normalizeResolverArgs(args);
+    return {
+        db: options.db,
+        config,
+        resource,
+        fieldName,
+        cache: options.cache ?? new Map(),
+        context: options.context,
+        services: options.services ?? config.services,
+        value: options.value ?? normalizedArgs.record ?? normalizedArgs.records ?? normalizedArgs.value,
+    };
+}
+function normalizeResolverArgs(args) {
+    if (args === undefined || args === null) {
+        return {};
+    }
+    if (Array.isArray(args)) {
+        return { records: args };
+    }
+    if (typeof args === 'object') {
+        return args;
+    }
+    return { value: args };
+}
+function normalizeResolveManyArgs(args) {
+    const normalizedArgs = normalizeResolverArgs(args);
+    if (Array.isArray(normalizedArgs.records)) {
+        return normalizedArgs;
+    }
+    return {
+        ...normalizedArgs,
+        records: [],
+    };
+}
+function spreadableRecord(value) {
+    if (value === null || value === undefined) {
+        return {};
+    }
+    return Object(value);
+}
+function requireSchemaResource(resources, name) {
+    const { resource, candidates } = resolveResource(resources, name);
+    if (resource) {
+        return resource;
+    }
+    throw dbError('DB_UNKNOWN_RESOURCE', `Unknown schema resource "${name}".`, {
+        status: 404,
+        hint: `Use one of: ${listChoices([...resources.keys()])}.`,
+        details: {
+            resource: name,
+            requestedResource: name,
+            normalizedCandidates: candidates,
+            availableResources: [...resources.keys()],
+        },
+    });
+}
+function normalizeValidationMode(value = 'create') {
+    if (value === 'create' || value === 'replace' || value === 'patch') {
+        return value;
+    }
+    throw dbError('DB_SCHEMA_VALIDATOR_MODE_INVALID', `Invalid schema validator mode ${JSON.stringify(value)}.`, {
+        status: 400,
+        hint: 'Use "create", "replace", or "patch".',
+        details: {
+            value,
+            allowed: ['create', 'replace', 'patch'],
+        },
+    });
+}
+function normalizeValidatorUnknownFields(value = 'error') {
+    if (value === 'ignore') {
+        return 'allow';
+    }
+    if (value === 'allow' || value === 'warn' || value === 'error' || value === 'strip') {
+        return value;
+    }
+    throw dbError('DB_SCHEMA_VALIDATOR_UNKNOWN_FIELDS_INVALID', `Invalid schema validator unknownFields setting ${JSON.stringify(value)}.`, {
+        status: 400,
+        hint: 'Use "error", "strip", "allow", "warn", or "ignore".',
+        details: {
+            value,
+            allowed: ['error', 'strip', 'allow', 'warn', 'ignore'],
+        },
+    });
+}
+function validationResourceForMode(resource, value, mode) {
+    if (mode !== 'create' || resource.kind !== 'collection' || !isPlainRecord(value)) {
+        return resource;
+    }
+    const idField = resource.idField ?? 'id';
+    if (value[idField] !== undefined || !resource.fields?.[idField]?.required) {
+        return resource;
+    }
+    return {
+        ...resource,
+        fields: {
+            ...resource.fields,
+            [idField]: {
+                ...resource.fields[idField],
+                required: false,
+            },
+        },
+    };
+}
+function applyValidationDefaults(value, resource, options) {
+    if (options.mode !== 'create' || options.applyDefaults === false || !isPlainRecord(value)) {
+        return value;
+    }
+    const next = { ...value };
+    for (const [fieldName, field] of Object.entries(resource.fields ?? {})) {
+        if (next[fieldName] !== undefined || !Object.prototype.hasOwnProperty.call(field, 'default')) {
+            continue;
+        }
+        if (field.readOnly || field.computed) {
+            continue;
+        }
+        next[fieldName] = structuredClone(field.default);
+    }
+    return next;
+}
+function stripUnknownResourceFields(value, resource) {
+    if (resource.fieldsAuthoritative === false) {
+        return value;
+    }
+    return stripUnknownFields(value, resource.fields ?? {});
+}
+function stripUnknownFields(value, fields) {
+    if (!isPlainRecord(value)) {
+        return value;
+    }
+    const next = {};
+    for (const [fieldName, fieldValue] of Object.entries(value)) {
+        const field = fields[fieldName];
+        if (!field) {
+            continue;
+        }
+        if (field.type === 'object') {
+            next[fieldName] = stripUnknownObjectValue(fieldValue, field);
+        }
+        else if (field.type === 'array' && field.items?.type === 'object' && Array.isArray(fieldValue)) {
+            next[fieldName] = fieldValue.map((item) => stripUnknownObjectValue(item, field.items));
+        }
+        else {
+            next[fieldName] = fieldValue;
+        }
+    }
+    return next;
+}
+function stripUnknownObjectValue(value, field) {
+    if (field.additionalProperties === true || !isPlainRecord(value)) {
+        return value;
+    }
+    return stripUnknownFields(value, fieldsForObjectValue(value, field));
+}
+function fieldsForObjectValue(value, field) {
+    if (!field.discriminator || !field.variants) {
+        return field.fields ?? {};
+    }
+    const discriminatorValue = value?.[field.discriminator];
+    const variant = field.variants[String(discriminatorValue)];
+    if (!variant) {
+        return field.fields ?? {};
+    }
+    return {
+        [field.discriminator]: {
+            type: 'enum',
+            values: [String(discriminatorValue)],
+            required: true,
+        },
+        ...(variant.fields ?? {}),
+    };
+}
+function cloneInput(value) {
+    if (!isPlainRecord(value)) {
+        return value;
+    }
+    return structuredClone(value);
+}
+function isPlainRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

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

@@ -0,0 +1,86 @@
+export type SchemaFieldDefinition = {
+    type: string;
+    fields?: Record<string, SchemaFieldDefinition>;
+    items?: SchemaFieldDefinition;
+    metadataOnly?: boolean;
+    computed?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    nullable?: boolean;
+    resolve?: ComputedResolveFunction;
+    resolveMany?: ComputedResolveManyFunction;
+    [key: string]: unknown;
+};
+export type SchemaResourceDefinition = {
+    kind?: 'collection' | 'document';
+    fields?: Record<string, SchemaFieldDefinition>;
+    validator?: unknown;
+    [key: string]: unknown;
+};
+type FieldOptions = Omit<SchemaFieldDefinition, 'type'> & {
+    type?: string;
+};
+type ComputedResolveFunction = (...args: unknown[]) => unknown;
+type ComputedResolveManyFunction = (...args: unknown[]) => unknown;
+type ComputedResolver = {
+    resolve?: ComputedResolveFunction;
+    resolveMany?: ComputedResolveManyFunction;
+};
+type FilesOptions = {
+    read?: string;
+};
+export declare function collection(definition: SchemaResourceDefinition | unknown, options?: SchemaResourceDefinition | undefined): {
+    kind: "collection" | "document";
+    validator: import("./standard-schema.js").StandardSchemaV1;
+    fields?: Record<string, SchemaFieldDefinition>;
+} | {
+    kind: "collection" | "document";
+};
+export declare function document(definition: SchemaResourceDefinition | unknown, options?: SchemaResourceDefinition | undefined): {
+    kind: "collection" | "document";
+    validator: import("./standard-schema.js").StandardSchemaV1;
+    fields?: Record<string, SchemaFieldDefinition>;
+} | {
+    kind: "collection" | "document";
+};
+export declare function files(patterns: string | readonly string[], options?: FilesOptions): {
+    kind: string;
+    patterns: any[];
+    read: string;
+};
+export declare const field: {
+    string(options?: FieldOptions): SchemaFieldDefinition;
+    datetime(options?: FieldOptions): SchemaFieldDefinition;
+    number(options?: FieldOptions): SchemaFieldDefinition;
+    boolean(options?: FieldOptions): SchemaFieldDefinition;
+    enum(values: readonly (string | number | boolean)[], options?: FieldOptions): SchemaFieldDefinition;
+    object(fieldsOrOptions?: Record<string, SchemaFieldDefinition> | FieldOptions, maybeOptions?: FieldOptions): SchemaFieldDefinition;
+    array(items?: SchemaFieldDefinition, options?: FieldOptions): SchemaFieldDefinition;
+    json(options?: FieldOptions): SchemaFieldDefinition;
+    meta(options?: FieldOptions): SchemaFieldDefinition;
+    nullable(definition: SchemaFieldDefinition, options?: FieldOptions): {
+        nullable: boolean;
+        type: string;
+        fields?: Record<string, SchemaFieldDefinition>;
+        items?: SchemaFieldDefinition;
+        metadataOnly?: boolean;
+        computed?: boolean;
+        readOnly?: boolean;
+        required?: boolean;
+        resolve?: ComputedResolveFunction;
+        resolveMany?: ComputedResolveManyFunction;
+    };
+    computed(definition: SchemaFieldDefinition, resolver?: ComputedResolveFunction | ComputedResolver): {
+        computed: boolean;
+        readOnly: boolean;
+        required: boolean;
+        resolve: ComputedResolveFunction;
+        resolveMany: ComputedResolveManyFunction;
+        type: string;
+        fields?: Record<string, SchemaFieldDefinition>;
+        items?: SchemaFieldDefinition;
+        metadataOnly?: boolean;
+        nullable?: boolean;
+    };
+};
+export {};

package/dist/features/schema/builders.js

@@ -0,0 +1,110 @@
+import { isStandardSchema } from './standard-schema.js';
+export function collection(definition, options = undefined) {
+    return resourceDefinition('collection', definition, options);
+}
+export function document(definition, options = undefined) {
+    return resourceDefinition('document', definition, options);
+}
+export function files(patterns, options = {}) {
+    return {
+        kind: 'files',
+        patterns: Array.isArray(patterns) ? [...patterns] : [patterns],
+        read: options.read ?? 'frontmatter',
+    };
+}
+function makeField(type, extras = {}) {
+    return {
+        type,
+        ...extras,
+    };
+}
+export const field = {
+    string(options = {}) {
+        return makeField('string', options);
+    },
+    datetime(options = {}) {
+        return makeField('datetime', options);
+    },
+    number(options = {}) {
+        return makeField('number', options);
+    },
+    boolean(options = {}) {
+        return makeField('boolean', options);
+    },
+    enum(values, options = {}) {
+        return makeField('enum', {
+            values,
+            ...options,
+        });
+    },
+    object(fieldsOrOptions = {}, maybeOptions = {}) {
+        if (isRecord(fieldsOrOptions) && fieldsOrOptions.fields) {
+            return makeField('object', fieldsOrOptions);
+        }
+        if (isFieldMap(fieldsOrOptions)) {
+            return makeField('object', {
+                fields: fieldsOrOptions,
+                ...maybeOptions,
+            });
+        }
+        return makeField('object', fieldsOrOptions);
+    },
+    array(items = { type: 'unknown' }, options = {}) {
+        return makeField('array', {
+            items,
+            ...options,
+        });
+    },
+    json(options = {}) {
+        return makeField('unknown', options);
+    },
+    meta(options = {}) {
+        const { type = 'unknown', ...metadata } = options;
+        return makeField(type, {
+            ...metadata,
+            metadataOnly: true,
+        });
+    },
+    nullable(definition, options = {}) {
+        return {
+            ...definition,
+            ...options,
+            nullable: true,
+        };
+    },
+    computed(definition, resolver = {}) {
+        const normalizedResolver = typeof resolver === 'function'
+            ? { resolve: resolver }
+            : resolver;
+        return {
+            ...definition,
+            computed: true,
+            readOnly: true,
+            required: false,
+            resolve: normalizedResolver?.resolve,
+            resolveMany: normalizedResolver?.resolveMany,
+        };
+    },
+};
+function resourceDefinition(kind, definition, options) {
+    if (isStandardSchema(definition)) {
+        return {
+            ...(options ?? {}),
+            kind,
+            validator: definition,
+        };
+    }
+    return {
+        ...(isRecord(definition) ? definition : {}),
+        kind,
+    };
+}
+function isFieldMap(value) {
+    if (!value || Array.isArray(value) || typeof value !== 'object') {
+        return false;
+    }
+    return Object.values(value).some((entry) => entry && typeof entry === 'object' && 'type' in entry);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}

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

@@ -0,0 +1,38 @@
+type FieldRelation = {
+    name: string;
+    to?: string;
+    toField: string;
+    cardinality: 'one' | 'many';
+};
+export type SchemaField = {
+    type?: string;
+    required?: boolean;
+    nullable?: boolean;
+    computed?: boolean;
+    readOnly?: boolean;
+    description?: string;
+    default?: unknown;
+    unique?: boolean;
+    relation?: FieldRelation;
+    values?: unknown[];
+    items?: SchemaField;
+    fields?: Record<string, SchemaField>;
+    variants?: Record<string, SchemaVariant>;
+    discriminator?: string;
+    additionalProperties?: boolean;
+    [key: string]: unknown;
+};
+type SchemaVariant = {
+    fields?: Record<string, SchemaField>;
+    additionalProperties?: boolean;
+    [key: string]: unknown;
+};
+type InferFieldOptions = {
+    required?: boolean;
+    inferVariants?: boolean;
+};
+export declare function normalizeField(field: unknown, fieldName?: string): SchemaField;
+export declare function inferFieldsFromData(value: unknown, kind?: string): Record<string, SchemaField>;
+export declare function inferFieldFromSamples(samples: unknown[], fieldName: string, options?: InferFieldOptions): SchemaField;
+export declare function inferFieldFromValue(value: unknown, fieldName: string, options?: InferFieldOptions): SchemaField;
+export {};