@vertesia/common 1.5.0-dev.20260807.073259Z → 1.5.0-dev.20260901.005903Z

package/src/view-configuration-validation.ts

@@ -1,74 +0,0 @@
-import Ajv, { type ErrorObject } from 'ajv';
-import type { ViewExperienceConfiguration } from './views.js';
-import {
-    PersistedViewExperienceConfigurationJsonSchema,
-    ViewExperienceConfigurationJsonSchema,
-} from './views-schema.js';
-import { type ViewValidationIssue, validateViewExperienceSemantics } from './views-validation.js';
-
-export type ViewConfigurationValidationMode = 'draft' | 'persisted';
-
-const ajv = new Ajv.default({ allErrors: true, strict: false });
-const validateDraftStructure = ajv.compile(ViewExperienceConfigurationJsonSchema);
-const validatePersistedStructure = ajv.compile(PersistedViewExperienceConfigurationJsonSchema);
-
-function jsonPointerPath(instancePath: string): string {
-    if (instancePath === '') return 'configuration';
-    return instancePath
-        .slice(1)
-        .split('/')
-        .map((segment) => segment.replaceAll('~1', '/').replaceAll('~0', '~'))
-        .reduce((path, segment) => {
-            if (/^\d+$/.test(segment)) return `${path}[${segment}]`;
-            return path.length === 0 ? segment : `${path}.${segment}`;
-        }, '');
-}
-
-function errorPath(error: ErrorObject): string {
-    const base = jsonPointerPath(error.instancePath);
-    if (error.keyword === 'required' && 'missingProperty' in error.params) {
-        const missingProperty = String(error.params.missingProperty);
-        return base === 'configuration' ? missingProperty : `${base}.${missingProperty}`;
-    }
-    if (error.keyword === 'additionalProperties' && 'additionalProperty' in error.params) {
-        const additionalProperty = String(error.params.additionalProperty);
-        return base === 'configuration' ? additionalProperty : `${base}.${additionalProperty}`;
-    }
-    return base;
-}
-
-function structuralIssues(value: unknown, mode: ViewConfigurationValidationMode): ViewValidationIssue[] {
-    const validateStructure = mode === 'persisted' ? validatePersistedStructure : validateDraftStructure;
-    if (validateStructure(value)) return [];
-    const issues = (validateStructure.errors ?? []).map((error: ErrorObject) => ({
-        path: errorPath(error),
-        message: error.message ?? 'is invalid',
-    }));
-    return [...new Map(issues.map((issue) => [`${issue.path}\u0000${issue.message}`, issue])).values()];
-}
-
-/**
- * Validate both the canonical JSON structure and semantic cross-reference rules.
- *
- * Persisted mode adds the documentation requirement structurally. Blank
- * descriptions pass the shape check and are rejected by semantic validation,
- * while structure-first short-circuiting prevents duplicate errors.
- */
-export function validateViewConfiguration(
-    value: unknown,
-    mode: ViewConfigurationValidationMode = 'draft',
-): ViewValidationIssue[] {
-    const issues = structuralIssues(value, mode);
-    if (issues.length > 0) return issues;
-    return validateViewExperienceSemantics(value as ViewExperienceConfiguration, mode);
-}
-
-/** @deprecated Use validateViewConfiguration(value, 'draft'). */
-export function validateViewExperienceConfiguration(value: unknown): ViewValidationIssue[] {
-    return validateViewConfiguration(value, 'draft');
-}
-
-/** @deprecated Use validateViewConfiguration(value, 'persisted'). */
-export function validatePersistedViewExperienceConfiguration(value: unknown): ViewValidationIssue[] {
-    return validateViewConfiguration(value, 'persisted');
-}

package/src/view-query-validation.test.ts

@@ -1,21 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { validateSupportedViewQuery } from './view-query-validation.js';
-
-function deeplyNestedFilter(depth: number): unknown {
-    let query: unknown = { term: { status: 'active' } };
-    for (let index = 0; index < depth; index++) {
-        query = { bool: { filter: query } };
-    }
-    return query;
-}
-
-describe('View query validation', () => {
-    it('rejects deeply nested queries without overflowing the call stack', () => {
-        expect(() => validateSupportedViewQuery(deeplyNestedFilter(6_000))).not.toThrow();
-        expect(validateSupportedViewQuery(deeplyNestedFilter(6_000))).toContainEqual(
-            expect.objectContaining({
-                message: 'exceeds the maximum of 100 query clauses',
-            }),
-        );
-    });
-});

package/src/view-query-validation.ts

@@ -1,319 +0,0 @@
-import {
-    ELASTICSEARCH_FIELD_PATH_PATTERN as FIELD_PATTERN,
-    isViewValidationRecord as isRecord,
-    SERVER_CONTROLLED_VIEW_FIELD_ROOTS,
-} from './view-validation-helpers.js';
-import type { ViewElasticsearchQuery } from './views.js';
-
-export interface ViewQueryValidationIssue {
-    path: string;
-    message: string;
-}
-
-export interface ViewQueryValidationOptions {
-    allowedFields?: ReadonlySet<string>;
-    allowedOperators?: ReadonlyMap<string, ReadonlySet<string>>;
-}
-
-const ALLOWED_QUERY_TYPES = new Set([
-    'bool',
-    'match',
-    'multi_match',
-    'simple_query_string',
-    'term',
-    'terms',
-    'range',
-    'exists',
-    'ids',
-    'prefix',
-    'match_all',
-]);
-const MAX_QUERY_CLAUSES = 100;
-const FORBIDDEN_FIELD_ROOTS = new Set<string>(SERVER_CONTROLLED_VIEW_FIELD_ROOTS);
-
-function addFieldIssue(
-    issues: ViewQueryValidationIssue[],
-    field: unknown,
-    path: string,
-    options: ViewQueryValidationOptions,
-): void {
-    if (typeof field !== 'string' || !FIELD_PATTERN.test(field)) {
-        issues.push({ path, message: 'must be a dot-separated field name' });
-        return;
-    }
-    if (FORBIDDEN_FIELD_ROOTS.has(field.split('.')[0])) {
-        issues.push({ path, message: `field '${field}' is server-controlled` });
-        return;
-    }
-    if (options.allowedFields && !options.allowedFields.has(field)) {
-        issues.push({ path, message: `field '${field}' is not available to this View` });
-    }
-}
-
-function addOperatorIssue(
-    issues: ViewQueryValidationIssue[],
-    field: string,
-    operator: string,
-    path: string,
-    options: ViewQueryValidationOptions,
-): void {
-    const allowed = options.allowedOperators?.get(field);
-    if (allowed && !allowed.has(operator)) {
-        issues.push({
-            path,
-            message: `operator '${operator}' is not available for field '${field}'`,
-        });
-    }
-}
-
-function validateSingleFieldClause(
-    issues: ViewQueryValidationIssue[],
-    value: unknown,
-    path: string,
-    validateValue: (fieldValue: unknown, valuePath: string, field: string) => void,
-    options: ViewQueryValidationOptions,
-): void {
-    if (!isRecord(value)) {
-        issues.push({ path, message: 'must be an object keyed by field name' });
-        return;
-    }
-    const entries = Object.entries(value);
-    if (entries.length !== 1) {
-        issues.push({ path, message: 'must reference exactly one field' });
-        return;
-    }
-    const [field, fieldValue] = entries[0];
-    addFieldIssue(issues, field, `${path}.${field}`, options);
-    validateValue(fieldValue, `${path}.${field}`, field);
-}
-
-function validateQueryNode(
-    issues: ViewQueryValidationIssue[],
-    value: unknown,
-    path: string,
-    state: { clauses: number },
-    options: ViewQueryValidationOptions,
-): void {
-    state.clauses++;
-    if (state.clauses > MAX_QUERY_CLAUSES) {
-        issues.push({ path, message: `exceeds the maximum of ${MAX_QUERY_CLAUSES} query clauses` });
-        return;
-    }
-    if (!isRecord(value)) {
-        issues.push({ path, message: 'must be an Elasticsearch query object' });
-        return;
-    }
-    const entries = Object.entries(value);
-    if (entries.length !== 1) {
-        issues.push({ path, message: 'must contain exactly one query clause' });
-        return;
-    }
-    const [type, body] = entries[0];
-    if (!ALLOWED_QUERY_TYPES.has(type)) {
-        issues.push({ path: `${path}.${type}`, message: `query type '${type}' is not supported` });
-        return;
-    }
-
-    if (type === 'match_all') {
-        if (!isRecord(body)) {
-            issues.push({ path: `${path}.match_all`, message: 'must be an object' });
-        }
-        return;
-    }
-    if (type === 'bool') {
-        if (!isRecord(body)) {
-            issues.push({ path: `${path}.bool`, message: 'must be an object' });
-            return;
-        }
-        const allowed = new Set(['must', 'filter', 'should', 'must_not', 'minimum_should_match']);
-        for (const key of Object.keys(body)) {
-            if (!allowed.has(key)) {
-                issues.push({ path: `${path}.bool.${key}`, message: 'is not supported' });
-            }
-        }
-        for (const key of ['must', 'filter', 'should', 'must_not'] as const) {
-            const child = body[key];
-            if (child === undefined) continue;
-            const children = Array.isArray(child) ? child : [child];
-            if (children.length > 50) {
-                issues.push({ path: `${path}.bool.${key}`, message: 'must contain at most 50 clauses' });
-            }
-            children.forEach((item, index) => {
-                validateQueryNode(issues, item, `${path}.bool.${key}[${index}]`, state, options);
-            });
-        }
-        const minimumShouldMatch = body.minimum_should_match;
-        if (
-            minimumShouldMatch !== undefined &&
-            typeof minimumShouldMatch !== 'number' &&
-            typeof minimumShouldMatch !== 'string'
-        ) {
-            issues.push({ path: `${path}.bool.minimum_should_match`, message: 'must be a number or string' });
-        }
-        return;
-    }
-    if (type === 'exists') {
-        if (!isRecord(body)) {
-            issues.push({ path: `${path}.exists`, message: 'must be an object' });
-        } else {
-            addFieldIssue(issues, body.field, `${path}.exists.field`, options);
-            if (typeof body.field === 'string') {
-                addOperatorIssue(issues, body.field, 'exists', `${path}.exists.field`, options);
-            }
-        }
-        return;
-    }
-    if (type === 'ids') {
-        if (!isRecord(body) || !Array.isArray(body.values) || body.values.length > 1_000) {
-            issues.push({ path: `${path}.ids.values`, message: 'must be an array containing at most 1000 IDs' });
-        } else if (body.values.some((id) => typeof id !== 'string')) {
-            issues.push({ path: `${path}.ids.values`, message: 'must contain only strings' });
-        }
-        return;
-    }
-    if (type === 'multi_match' || type === 'simple_query_string') {
-        if (!isRecord(body) || typeof body.query !== 'string') {
-            issues.push({ path: `${path}.${type}.query`, message: 'must be a string' });
-            return;
-        }
-        if (!Array.isArray(body.fields) || body.fields.length === 0 || body.fields.length > 20) {
-            issues.push({ path: `${path}.${type}.fields`, message: 'must contain between 1 and 20 fields' });
-        } else {
-            body.fields.forEach((rawField, index) => {
-                const field = typeof rawField === 'string' ? rawField.split('^')[0] : rawField;
-                addFieldIssue(issues, field, `${path}.${type}.fields[${index}]`, options);
-                if (typeof field === 'string') {
-                    addOperatorIssue(issues, field, type, `${path}.${type}.fields[${index}]`, options);
-                }
-            });
-        }
-        return;
-    }
-
-    if (isRecord(body)) {
-        const fieldEntries = Object.entries(body);
-        if (fieldEntries.length === 1) {
-            addOperatorIssue(issues, fieldEntries[0][0], type, `${path}.${type}.${fieldEntries[0][0]}`, options);
-        }
-    }
-    validateSingleFieldClause(
-        issues,
-        body,
-        `${path}.${type}`,
-        (fieldValue, valuePath, field) => {
-            if (type === 'terms') {
-                if (!Array.isArray(fieldValue) || fieldValue.length > 1_000) {
-                    issues.push({ path: valuePath, message: 'must be an array containing at most 1000 values' });
-                }
-                return;
-            }
-            if (type === 'range') {
-                if (!isRecord(fieldValue)) {
-                    issues.push({ path: valuePath, message: 'must be a range object' });
-                    return;
-                }
-                const allowed = new Set(['gt', 'gte', 'lt', 'lte']);
-                if (Object.keys(fieldValue).length === 0 || Object.keys(fieldValue).some((key) => !allowed.has(key))) {
-                    issues.push({ path: valuePath, message: 'supports only gt, gte, lt, and lte' });
-                }
-                return;
-            }
-            if (type === 'prefix') {
-                if (field !== 'location') {
-                    issues.push({ path: valuePath, message: 'prefix queries are supported only for location' });
-                }
-                const prefix = isRecord(fieldValue) ? fieldValue.value : fieldValue;
-                if (typeof prefix !== 'string' || !prefix.startsWith('/') || !prefix.endsWith('/')) {
-                    issues.push({ path: valuePath, message: 'must be a boundary-aware absolute location prefix' });
-                }
-                return;
-            }
-            if (type === 'match') {
-                const query = isRecord(fieldValue) ? fieldValue.query : fieldValue;
-                if (typeof query !== 'string') {
-                    issues.push({ path: valuePath, message: 'must contain a string query' });
-                }
-                return;
-            }
-            if (type === 'term' && isRecord(fieldValue)) {
-                const allowed = new Set(['value', 'boost', 'case_insensitive']);
-                if (!('value' in fieldValue) || Object.keys(fieldValue).some((key) => !allowed.has(key))) {
-                    issues.push({
-                        path: valuePath,
-                        message: 'supports only value, boost, and case_insensitive options',
-                    });
-                    return;
-                }
-                if (isRecord(fieldValue.value) || Array.isArray(fieldValue.value)) {
-                    issues.push({ path: `${valuePath}.value`, message: 'must be a scalar value' });
-                }
-                if (fieldValue.boost !== undefined && typeof fieldValue.boost !== 'number') {
-                    issues.push({ path: `${valuePath}.boost`, message: 'must be a number' });
-                }
-                if (fieldValue.case_insensitive !== undefined && typeof fieldValue.case_insensitive !== 'boolean') {
-                    issues.push({ path: `${valuePath}.case_insensitive`, message: 'must be a boolean' });
-                }
-                return;
-            }
-            if (isRecord(fieldValue) || Array.isArray(fieldValue)) {
-                issues.push({ path: valuePath, message: 'must be a scalar value' });
-            }
-        },
-        options,
-    );
-}
-
-function normalizeViewQueryNode(value: unknown, state: { clauses: number }): unknown {
-    state.clauses++;
-    if (state.clauses > MAX_QUERY_CLAUSES) return value;
-    if (!isRecord(value)) return value;
-    const entries = Object.entries(value);
-    if (entries.length !== 1) return value;
-    const [type, body] = entries[0];
-    if (type === 'bool' && isRecord(body)) {
-        const normalizedBody: Record<string, unknown> = { ...body };
-        for (const key of ['must', 'filter', 'should', 'must_not'] as const) {
-            const child = body[key];
-            if (Array.isArray(child)) {
-                normalizedBody[key] = child.map((item) => normalizeViewQueryNode(item, state));
-            } else if (child !== undefined) {
-                normalizedBody[key] = normalizeViewQueryNode(child, state);
-            }
-        }
-        return { bool: normalizedBody };
-    }
-    if (type !== 'term' || !isRecord(body)) return value;
-    const fieldEntries = Object.entries(body);
-    if (fieldEntries.length !== 1) return value;
-    const [field, fieldValue] = fieldEntries[0];
-    if (!isRecord(fieldValue) || Object.keys(fieldValue).length !== 1 || !('value' in fieldValue)) return value;
-    return { term: { [field]: fieldValue.value } };
-}
-
-export function normalizeViewQuery(value: unknown): unknown {
-    return normalizeViewQueryNode(value, { clauses: 0 });
-}
-
-export function validateSupportedViewQuery(
-    value: unknown,
-    path = 'query',
-    options: ViewQueryValidationOptions = {},
-): ViewQueryValidationIssue[] {
-    const issues: ViewQueryValidationIssue[] = [];
-    validateQueryNode(issues, normalizeViewQuery(value), path, { clauses: 0 }, options);
-    return issues;
-}
-
-export function asSupportedViewQuery(
-    value: unknown,
-    path = 'query',
-    options: ViewQueryValidationOptions = {},
-): ViewElasticsearchQuery {
-    const normalized = normalizeViewQuery(value);
-    const issues: ViewQueryValidationIssue[] = [];
-    validateQueryNode(issues, normalized, path, { clauses: 0 }, options);
-    if (issues.length > 0) {
-        throw new Error(issues.map((issue) => `${issue.path} ${issue.message}`).join('; '));
-    }
-    return normalized as ViewElasticsearchQuery;
-}

package/src/view-validation-helpers.ts

@@ -1,28 +0,0 @@
-export const VIEW_CONFIGURATION_ID_PATTERN_SOURCE = '^[a-z][a-z0-9_-]*$';
-export const ELASTICSEARCH_FIELD_PATH_PATTERN_SOURCE = '^[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*$';
-
-export const VIEW_CONFIGURATION_ID_PATTERN = new RegExp(VIEW_CONFIGURATION_ID_PATTERN_SOURCE);
-export const ELASTICSEARCH_FIELD_PATH_PATTERN = new RegExp(ELASTICSEARCH_FIELD_PATH_PATTERN_SOURCE);
-
-/**
- * Elasticsearch roots owned by the server and unavailable to View-authored
- * queries or dynamic collection filters.
- */
-export const SERVER_CONTROLLED_VIEW_FIELD_ROOTS = [
-    'security',
-    'revision',
-    'is_deleted',
-    'embeddings_text',
-    'embeddings_image',
-    'embeddings_properties',
-    '_indexing_metadata',
-] as const;
-
-/** @deprecated Use ELASTICSEARCH_FIELD_PATH_PATTERN_SOURCE. */
-export const VIEW_FIELD_PATTERN_SOURCE = ELASTICSEARCH_FIELD_PATH_PATTERN_SOURCE;
-/** @deprecated Use ELASTICSEARCH_FIELD_PATH_PATTERN. */
-export const VIEW_FIELD_PATTERN = ELASTICSEARCH_FIELD_PATH_PATTERN;
-
-export function isViewValidationRecord(value: unknown): value is Record<string, unknown> {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}