@async/db 0.2.0

package/dist/features/schema/standard-schema.d.ts

@@ -0,0 +1,57 @@
+export type StandardSchemaV1 = {
+    '~standard': {
+        version: 1;
+        vendor?: string;
+        validate: (...args: unknown[]) => unknown;
+        jsonSchema?: {
+            output?: (options?: Record<string, unknown>) => unknown;
+        };
+        [key: string]: unknown;
+    };
+};
+export type SchemaFieldDefinition = {
+    type: string;
+    required?: boolean;
+    nullable?: boolean;
+    description?: string;
+    default?: unknown;
+    values?: unknown[];
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    items?: SchemaFieldDefinition;
+    fields?: Record<string, SchemaFieldDefinition>;
+    additionalProperties?: boolean;
+    metadataOnly?: boolean;
+    [key: string]: unknown;
+};
+export type SchemaDiagnostic = {
+    code: string;
+    severity: 'error' | 'warn' | 'info';
+    resource?: string;
+    field?: string;
+    message: string;
+    hint?: string;
+    details?: Record<string, unknown>;
+};
+type StandardSchemaIssue = {
+    message?: string;
+    path?: readonly unknown[];
+    [key: string]: unknown;
+};
+type SchemaResource = {
+    name: string;
+};
+export declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+export declare function standardSchemaVendor(schema: StandardSchemaV1 | null | undefined): string;
+export declare function standardJsonSchemaFields(schema: StandardSchemaV1 | null | undefined, resourceName: string): {
+    fields: Record<string, SchemaFieldDefinition>;
+    authoritative: boolean;
+    diagnostics: SchemaDiagnostic[];
+};
+export declare function mergeStandardSchemaFields(inferredFields: Record<string, SchemaFieldDefinition> | null | undefined, overlayFields: Record<string, SchemaFieldDefinition> | null | undefined): Record<string, SchemaFieldDefinition>;
+export declare function standardSchemaIssueDiagnostics(schema: StandardSchemaV1, issues: readonly StandardSchemaIssue[] | null | undefined, resource: SchemaResource): SchemaDiagnostic[];
+export declare function isPromiseLike(value: unknown): value is PromiseLike<unknown>;
+export {};

package/dist/features/schema/standard-schema.js

@@ -0,0 +1,232 @@
+export function isStandardSchema(value) {
+    const standard = value?.['~standard'];
+    return Boolean(standard
+        && standard.version === 1
+        && typeof standard.validate === 'function');
+}
+export function standardSchemaVendor(schema) {
+    return String(schema?.['~standard']?.vendor ?? 'unknown');
+}
+export function standardJsonSchemaFields(schema, resourceName) {
+    const converter = schema?.['~standard']?.jsonSchema?.output;
+    if (typeof converter !== 'function') {
+        return {
+            fields: {},
+            authoritative: false,
+            diagnostics: [standardFieldsUnknownDiagnostic(resourceName, 'no-converter')],
+        };
+    }
+    let jsonSchema;
+    try {
+        jsonSchema = converter({ target: 'draft-07' });
+    }
+    catch (error) {
+        return {
+            fields: {},
+            authoritative: false,
+            diagnostics: [standardJsonSchemaDiagnostic(resourceName, error)],
+        };
+    }
+    const fields = fieldsFromJsonSchemaObject(jsonSchema);
+    if (!fields) {
+        return {
+            fields: {},
+            authoritative: false,
+            diagnostics: [standardFieldsUnknownDiagnostic(resourceName, 'unsupported-json-schema')],
+        };
+    }
+    return {
+        fields,
+        authoritative: true,
+        diagnostics: [],
+    };
+}
+export function mergeStandardSchemaFields(inferredFields, overlayFields) {
+    const inferred = inferredFields ?? {};
+    const overlay = overlayFields ?? {};
+    const names = new Set([...Object.keys(inferred), ...Object.keys(overlay)]);
+    return Object.fromEntries([...names].map((fieldName) => [
+        fieldName,
+        mergeStandardSchemaField(inferred[fieldName], overlay[fieldName]),
+    ]));
+}
+export function standardSchemaIssueDiagnostics(schema, issues, resource) {
+    const vendor = standardSchemaVendor(schema);
+    return [...(issues ?? [])].map((issue) => {
+        const path = normalizeStandardIssuePath(issue?.path);
+        const field = fieldPathFromStandardIssuePath(path);
+        return {
+            code: 'STANDARD_SCHEMA_VALIDATION_FAILED',
+            severity: 'error',
+            resource: resource.name,
+            field,
+            message: field
+                ? `${resource.name} field "${field}" failed Standard Schema validation: ${String(issue?.message ?? 'Invalid value')}`
+                : `${resource.name} record failed Standard Schema validation: ${String(issue?.message ?? 'Invalid value')}`,
+            hint: 'Update the input to satisfy the configured Standard Schema validator.',
+            details: {
+                vendor,
+                path,
+                message: String(issue?.message ?? 'Invalid value'),
+            },
+        };
+    });
+}
+export function isPromiseLike(value) {
+    return Boolean(value) && typeof value === 'object' && typeof value.then === 'function';
+}
+function mergeStandardSchemaField(inferredField, overlayField) {
+    if (!overlayField) {
+        return inferredField ?? { type: 'unknown' };
+    }
+    if (!inferredField) {
+        return overlayField;
+    }
+    const overlayType = overlayField.type;
+    const keepInferredType = overlayField.metadataOnly === true && (overlayType === undefined || overlayType === 'unknown');
+    const merged = {
+        ...inferredField,
+        ...overlayField,
+    };
+    if (keepInferredType) {
+        merged.type = inferredField.type;
+    }
+    return merged;
+}
+function fieldsFromJsonSchemaObject(schema) {
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+        return null;
+    }
+    const jsonSchema = schema;
+    if (jsonSchema.type !== 'object' || !jsonSchema.properties || typeof jsonSchema.properties !== 'object' || Array.isArray(jsonSchema.properties)) {
+        return null;
+    }
+    const required = new Set(Array.isArray(jsonSchema.required) ? jsonSchema.required.map(String) : []);
+    return Object.fromEntries(Object.entries(jsonSchema.properties).map(([fieldName, propertySchema]) => [
+        fieldName,
+        fieldFromJsonSchema(propertySchema, required.has(fieldName)),
+    ]));
+}
+function fieldFromJsonSchema(schema, required = false) {
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+        return {
+            type: 'unknown',
+            required,
+        };
+    }
+    const jsonSchema = schema;
+    const types = Array.isArray(jsonSchema.type) ? jsonSchema.type : [jsonSchema.type].filter(Boolean);
+    const nullable = types.includes('null');
+    const type = types.find((candidate) => candidate !== 'null') ?? (jsonSchema.enum ? 'enum' : 'unknown');
+    const field = {
+        type: asyncDbFieldType(type),
+        required,
+    };
+    if (nullable) {
+        field.nullable = true;
+    }
+    if (typeof jsonSchema.description === 'string') {
+        field.description = jsonSchema.description;
+    }
+    if ('default' in jsonSchema) {
+        field.default = jsonSchema.default;
+    }
+    if (Array.isArray(jsonSchema.enum)) {
+        field.type = 'enum';
+        field.values = [...jsonSchema.enum];
+    }
+    if (typeof jsonSchema.minimum === 'number' && Number.isFinite(jsonSchema.minimum)) {
+        field.min = jsonSchema.minimum;
+    }
+    if (typeof jsonSchema.maximum === 'number' && Number.isFinite(jsonSchema.maximum)) {
+        field.max = jsonSchema.maximum;
+    }
+    if (typeof jsonSchema.minLength === 'number' && Number.isFinite(jsonSchema.minLength)) {
+        field.minLength = jsonSchema.minLength;
+    }
+    if (typeof jsonSchema.maxLength === 'number' && Number.isFinite(jsonSchema.maxLength)) {
+        field.maxLength = jsonSchema.maxLength;
+    }
+    if (typeof jsonSchema.pattern === 'string') {
+        field.pattern = jsonSchema.pattern;
+    }
+    if (field.type === 'array') {
+        field.items = fieldFromJsonSchema(jsonSchema.items ?? {}, false);
+    }
+    if (field.type === 'object') {
+        const fields = fieldsFromJsonSchemaObject(jsonSchema);
+        if (fields) {
+            field.fields = fields;
+        }
+        if (jsonSchema.additionalProperties === true) {
+            field.additionalProperties = true;
+        }
+    }
+    return field;
+}
+function asyncDbFieldType(type) {
+    switch (type) {
+        case 'string':
+        case 'number':
+        case 'boolean':
+        case 'object':
+        case 'array':
+            return type;
+        case 'integer':
+            return 'number';
+        default:
+            return 'unknown';
+    }
+}
+function normalizeStandardIssuePath(path) {
+    if (!Array.isArray(path)) {
+        return [];
+    }
+    return path.map((segment) => {
+        if (segment && typeof segment === 'object' && 'key' in segment) {
+            return segment.key;
+        }
+        return segment;
+    });
+}
+function fieldPathFromStandardIssuePath(path) {
+    if (!path.length) {
+        return undefined;
+    }
+    let output = '';
+    for (const segment of path) {
+        if (typeof segment === 'number') {
+            output += `[${segment}]`;
+            continue;
+        }
+        const value = String(segment);
+        output += output ? `.${value}` : value;
+    }
+    return output;
+}
+function standardFieldsUnknownDiagnostic(resourceName, reason) {
+    return {
+        code: 'STANDARD_SCHEMA_FIELDS_UNKNOWN',
+        severity: 'warn',
+        resource: resourceName,
+        message: `${resourceName} uses a Standard Schema validator, but async-db could not infer field metadata from it.`,
+        hint: 'Add field.meta(...) overlays for generated types/manifests, or use a validator that exposes a Standard JSON Schema converter.',
+        details: {
+            reason,
+        },
+    };
+}
+function standardJsonSchemaDiagnostic(resourceName, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        code: 'STANDARD_SCHEMA_JSON_SCHEMA_FAILED',
+        severity: 'warn',
+        resource: resourceName,
+        message: `${resourceName} Standard JSON Schema conversion failed: ${message}`,
+        hint: 'Add field.meta(...) overlays for generated types/manifests, or update the validator JSON Schema converter.',
+        details: {
+            reason: 'converter-threw',
+            parserMessage: message,
+        },
+    };
+}

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

@@ -0,0 +1,69 @@
+type DiagnosticSeverity = 'error' | 'warn';
+type SchemaDiagnostic = {
+    code: string;
+    severity: DiagnosticSeverity;
+    resource: string;
+    field?: string;
+    message: string;
+    hint?: string;
+    details?: Record<string, unknown>;
+};
+type ValidationConfig = {
+    schema?: {
+        unknownFields?: 'allow' | 'warn' | 'error' | string;
+    };
+    [key: string]: unknown;
+};
+type SchemaField = {
+    type?: string;
+    required?: boolean;
+    nullable?: boolean;
+    readOnly?: boolean;
+    values?: unknown[];
+    items?: SchemaField;
+    fields?: Record<string, SchemaField>;
+    variants?: Record<string, SchemaVariant>;
+    discriminator?: string;
+    additionalProperties?: boolean;
+    min?: unknown;
+    max?: unknown;
+    minLength?: unknown;
+    maxLength?: unknown;
+    pattern?: unknown;
+    unique?: boolean;
+    [key: string]: unknown;
+};
+type SchemaVariant = {
+    fields?: Record<string, SchemaField>;
+    additionalProperties?: boolean;
+};
+type SchemaResource = {
+    name: string;
+    kind?: string;
+    fields?: Record<string, SchemaField>;
+    seed?: unknown;
+    dataPath?: string | null;
+    schemaPath?: string | null;
+    [key: string]: unknown;
+};
+type ValidationOptions = {
+    source?: string;
+    requireFields?: boolean;
+};
+type ValidationContext = {
+    config: ValidationConfig;
+    fieldPath: string;
+    resource: SchemaResource;
+    requireFields?: boolean;
+    source?: string;
+};
+type UniqueDiagnosticOptions = {
+    source?: unknown;
+};
+export declare function assertRecordMatchesResource(record: unknown, resource: SchemaResource, config: ValidationConfig, options?: ValidationOptions): void;
+export declare function validateRecordAgainstResource(record: unknown, resource: SchemaResource, config: ValidationConfig, options?: ValidationOptions): SchemaDiagnostic[];
+export declare function validateValueAgainstField(value: unknown, field: SchemaField, context: ValidationContext): SchemaDiagnostic[];
+export declare function validateResourceSeed(resource: SchemaResource, config: ValidationConfig): SchemaDiagnostic[];
+export declare function validateUniqueCollectionFields(resource: SchemaResource, records?: unknown, options?: UniqueDiagnosticOptions): SchemaDiagnostic[];
+export declare function uniqueDuplicateDiagnostic(resource: SchemaResource, fieldName: string, value: unknown, firstIndex: number, duplicateIndex: number, options?: UniqueDiagnosticOptions): SchemaDiagnostic;
+export {};