@hypequery/datasets 0.0.0-canary-20260520183507

package/dist/query-planner.js

@@ -0,0 +1,87 @@
+import { GRAIN_FUNCTIONS } from "./constants.js";
+export function resolveDimensionExpression(ds, dimensionName) {
+    const definition = ds.dimensions[dimensionName];
+    return definition?.sql ?? definition?.column ?? dimensionName;
+}
+export function resolveFilterField(ds, filterField) {
+    const resolvedField = ds.filters[filterField]?.field ?? filterField;
+    return resolveDimensionExpression(ds, resolvedField);
+}
+export function buildDimensionSelectionPlan(ds, dimensions, grain) {
+    const selectParts = [];
+    const groupByParts = [];
+    if (grain) {
+        const fn = GRAIN_FUNCTIONS[grain];
+        selectParts.push(`${fn}(${ds.timeKey}) AS period`);
+        groupByParts.push("period");
+    }
+    for (const dimensionName of dimensions) {
+        const expression = resolveDimensionExpression(ds, dimensionName);
+        if (expression === dimensionName) {
+            selectParts.push(dimensionName);
+        }
+        else {
+            selectParts.push(`${expression} AS ${dimensionName}`);
+        }
+        groupByParts.push(dimensionName);
+    }
+    return { selectParts, groupByParts };
+}
+export function applyAggregationSpec(qb, ds, spec, alias) {
+    const fieldOrExpr = resolveDimensionExpression(ds, spec.field);
+    switch (spec.aggregation) {
+        case "sum":
+            return qb.sum(fieldOrExpr, alias);
+        case "count":
+            return qb.count(fieldOrExpr, alias);
+        case "countDistinct":
+            return qb.countDistinct(fieldOrExpr, alias);
+        case "avg":
+            return qb.avg(fieldOrExpr, alias);
+        case "min":
+            return qb.min(fieldOrExpr, alias);
+        case "max":
+            return qb.max(fieldOrExpr, alias);
+        default:
+            throw new Error(`Unknown aggregation type: ${spec.aggregation}`);
+    }
+}
+export function applyMeasureDefinition(qb, ds, name, definition) {
+    const fieldOrExpr = definition.sql ?? resolveDimensionExpression(ds, definition.field);
+    switch (definition.aggregation) {
+        case "sum":
+            return qb.sum(fieldOrExpr, name);
+        case "count":
+            return qb.count(fieldOrExpr, name);
+        case "countDistinct":
+            return qb.countDistinct(fieldOrExpr, name);
+        case "avg":
+            return qb.avg(fieldOrExpr, name);
+        case "min":
+            return qb.min(fieldOrExpr, name);
+        case "max":
+            return qb.max(fieldOrExpr, name);
+        default:
+            throw new Error(`Unsupported measure aggregation: ${definition.aggregation}`);
+    }
+}
+export function appendOrderLimitOffset(qb, orderBy, grain, limit, offset) {
+    if (orderBy && orderBy.length > 0) {
+        for (const order of orderBy) {
+            qb = qb.orderBy(order.field, order.direction.toUpperCase());
+        }
+    }
+    else if (grain) {
+        qb = qb.orderBy("period", "ASC");
+    }
+    if (limit != null) {
+        qb = qb.limit(limit);
+    }
+    if (offset != null) {
+        qb = qb.offset(offset);
+    }
+    return qb;
+}
+export function resolveTenantFilterColumn(_ds, context) {
+    return context?.runtime?.tenant?.column;
+}

package/dist/registry.d.ts

@@ -0,0 +1,8 @@
+/**
+ * DatasetRegistry — runtime registry of defined datasets.
+ *
+ * Used by MetricExecutor and serve() to discover datasets at startup.
+ */
+import type { DatasetRegistryInstance } from './types.js';
+export declare function createDatasetRegistry(): DatasetRegistryInstance;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAmB,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE3E,wBAAgB,qBAAqB,IAAI,uBAAuB,CAyB/D"}

package/dist/registry.js

@@ -0,0 +1,25 @@
+/**
+ * DatasetRegistry — runtime registry of defined datasets.
+ *
+ * Used by MetricExecutor and serve() to discover datasets at startup.
+ */
+export function createDatasetRegistry() {
+    const datasets = new Map();
+    return {
+        register(ds) {
+            if (datasets.has(ds.name)) {
+                throw new Error(`Dataset "${ds.name}" is already registered. Dataset names must be unique.`);
+            }
+            datasets.set(ds.name, ds);
+        },
+        get(name) {
+            return datasets.get(name);
+        },
+        getAll() {
+            return Array.from(datasets.values());
+        },
+        has(name) {
+            return datasets.has(name);
+        },
+    };
+}

package/dist/relationships.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Relationship helpers for dataset definitions.
+ *
+ * These helpers currently define semantic model metadata only. The shipped
+ * executor does not yet resolve relationship paths into joined dataset queries
+ * or cross-dataset metrics.
+ *
+ * @example
+ * ```ts
+ * const Orders = dataset("orders", {
+ *   source: "orders",
+ *   fields: { ... },
+ *   relationships: {
+ *     customer: belongsTo(() => Customers, { from: "customerId", to: "id" }),
+ *   },
+ * });
+ * ```
+ */
+import type { RelationshipDefinition } from './types.js';
+/** Many-to-one relationship (FK on this table). */
+export declare function belongsTo(target: () => {
+    __type: 'dataset';
+    name: string;
+}, join: {
+    from: string;
+    to: string;
+}): RelationshipDefinition;
+/** One-to-many relationship (FK on target table). */
+export declare function hasMany(target: () => {
+    __type: 'dataset';
+    name: string;
+}, join: {
+    from: string;
+    to: string;
+}): RelationshipDefinition;
+/** One-to-one relationship (FK on target table). */
+export declare function hasOne(target: () => {
+    __type: 'dataset';
+    name: string;
+}, join: {
+    from: string;
+    to: string;
+}): RelationshipDefinition;
+//# sourceMappingURL=relationships.d.ts.map

package/dist/relationships.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../src/relationships.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAoB,MAAM,YAAY,CAAC;AAgB3E,mDAAmD;AACnD,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACjD,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAExB;AAED,qDAAqD;AACrD,wBAAgB,OAAO,CACrB,MAAM,EAAE,MAAM;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACjD,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAExB;AAED,oDAAoD;AACpD,wBAAgB,MAAM,CACpB,MAAM,EAAE,MAAM;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACjD,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAExB"}

package/dist/relationships.js

@@ -0,0 +1,39 @@
+/**
+ * Relationship helpers for dataset definitions.
+ *
+ * These helpers currently define semantic model metadata only. The shipped
+ * executor does not yet resolve relationship paths into joined dataset queries
+ * or cross-dataset metrics.
+ *
+ * @example
+ * ```ts
+ * const Orders = dataset("orders", {
+ *   source: "orders",
+ *   fields: { ... },
+ *   relationships: {
+ *     customer: belongsTo(() => Customers, { from: "customerId", to: "id" }),
+ *   },
+ * });
+ * ```
+ */
+function createRelationship(kind, target, join) {
+    return {
+        __type: 'relationship',
+        kind,
+        target,
+        from: join.from,
+        to: join.to,
+    };
+}
+/** Many-to-one relationship (FK on this table). */
+export function belongsTo(target, join) {
+    return createRelationship('belongsTo', target, join);
+}
+/** One-to-many relationship (FK on target table). */
+export function hasMany(target, join) {
+    return createRelationship('hasMany', target, join);
+}
+/** One-to-one relationship (FK on target table). */
+export function hasOne(target, join) {
+    return createRelationship('hasOne', target, join);
+}

package/dist/sql-utils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SQL utility functions for safe SQL generation.
+ */
+/**
+ * Validates that a string is a safe SQL identifier (column/table name).
+ * Allows only alphanumeric characters and underscores, starting with letter or underscore.
+ *
+ * @param identifier - The identifier to validate
+ * @returns true if valid, false otherwise
+ */
+export declare function isSafeSQLIdentifier(identifier: string): boolean;
+/**
+ * Validates and throws if identifier is not safe for SQL.
+ *
+ * @param identifier - The identifier to validate
+ * @param context - Context for error message (e.g., "dimension name", "field name")
+ * @throws Error if identifier is not safe
+ */
+export declare function validateSQLIdentifier(identifier: string, context: string): void;
+/**
+ * Quotes a SQL identifier for safe use in queries.
+ * Uses double quotes which is standard SQL.
+ *
+ * @param identifier - The identifier to quote
+ * @returns Quoted identifier
+ */
+export declare function quoteSQLIdentifier(identifier: string): string;
+//# sourceMappingURL=sql-utils.d.ts.map

package/dist/sql-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-utils.d.ts","sourceRoot":"","sources":["../src/sql-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAO/E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAI7D"}

package/dist/sql-utils.js

@@ -0,0 +1,38 @@
+/**
+ * SQL utility functions for safe SQL generation.
+ */
+/**
+ * Validates that a string is a safe SQL identifier (column/table name).
+ * Allows only alphanumeric characters and underscores, starting with letter or underscore.
+ *
+ * @param identifier - The identifier to validate
+ * @returns true if valid, false otherwise
+ */
+export function isSafeSQLIdentifier(identifier) {
+    return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(identifier);
+}
+/**
+ * Validates and throws if identifier is not safe for SQL.
+ *
+ * @param identifier - The identifier to validate
+ * @param context - Context for error message (e.g., "dimension name", "field name")
+ * @throws Error if identifier is not safe
+ */
+export function validateSQLIdentifier(identifier, context) {
+    if (!isSafeSQLIdentifier(identifier)) {
+        throw new Error(`Invalid ${context}: "${identifier}". Must contain only letters, numbers, and underscores, ` +
+            `and start with a letter or underscore.`);
+    }
+}
+/**
+ * Quotes a SQL identifier for safe use in queries.
+ * Uses double quotes which is standard SQL.
+ *
+ * @param identifier - The identifier to quote
+ * @returns Quoted identifier
+ */
+export function quoteSQLIdentifier(identifier) {
+    // Escape any existing double quotes by doubling them
+    const escaped = identifier.replace(/"/g, '""');
+    return `"${escaped}"`;
+}

package/dist/types.d.ts

@@ -0,0 +1,214 @@
+import type { QueryBuilderFactoryLike } from './query-builder-protocol.js';
+export type FieldType = 'string' | 'number' | 'boolean' | 'timestamp';
+export type DimensionType = FieldType;
+export interface DimensionOptions {
+    label?: string;
+    description?: string;
+    column?: string;
+    sql?: string;
+    filterable?: boolean;
+    groupable?: boolean;
+}
+export interface DimensionDefinition<TType extends DimensionType = DimensionType> {
+    __type: 'field_definition';
+    fieldType: TType;
+    label?: string;
+    description?: string;
+    column?: string;
+    sql?: string;
+    filterable?: boolean;
+    groupable?: boolean;
+}
+export type InferDimensionType<T extends DimensionDefinition> = T['fieldType'] extends 'string' ? string : T['fieldType'] extends 'number' ? number : T['fieldType'] extends 'boolean' ? boolean : T['fieldType'] extends 'timestamp' ? string : never;
+export type RelationshipKind = 'belongsTo' | 'hasMany' | 'hasOne';
+export interface RelationshipDefinition {
+    __type: 'relationship';
+    kind: RelationshipKind;
+    target: () => {
+        __type: 'dataset';
+        name: string;
+    };
+    from: string;
+    to: string;
+}
+export type AggregationType = 'sum' | 'count' | 'countDistinct' | 'avg' | 'min' | 'max';
+export type MeasureAggregation = AggregationType;
+export interface AggregationSpec {
+    __type: 'aggregation_spec';
+    aggregation: AggregationType;
+    field: string;
+}
+export interface MeasureOptions {
+    sql?: string;
+    label?: string;
+    description?: string;
+}
+export interface MeasureDefinition {
+    __type: 'measure_definition';
+    aggregation: MeasureAggregation;
+    field: string;
+    sql?: string;
+    label?: string;
+    description?: string;
+}
+export type FormulaExpr = {
+    __type: 'formula_expr';
+    toSQL: () => string;
+};
+export interface MetricRef<TDatasetName extends string = string, TMetricName extends string = string> {
+    __type: 'metric_ref';
+    datasetName: TDatasetName;
+    name: TMetricName;
+    spec: AggregationSpec | DerivedMetricSpec;
+    label?: string;
+    description?: string;
+    dataset: DatasetInstance<any, any, any>;
+    by(grain: TimeGrain): GrainedMetricRef<TDatasetName, TMetricName>;
+    contract(): MetricContract;
+}
+export interface DerivedMetricSpec {
+    __type: 'derived_metric_spec';
+    uses: Record<string, MetricRef>;
+    formula: (inputs: Record<string, string>) => FormulaExpr;
+}
+export interface GrainedMetricRef<TDatasetName extends string = string, TMetricName extends string = string> {
+    __type: 'grained_metric_ref';
+    metric: MetricRef<TDatasetName, TMetricName>;
+    grain: TimeGrain;
+    contract(): MetricContract;
+}
+export type MetricHandle<TDatasetName extends string = string, TMetricName extends string = string> = MetricRef<TDatasetName, TMetricName> | GrainedMetricRef<TDatasetName, TMetricName>;
+export type TimeGrain = 'day' | 'week' | 'month' | 'quarter' | 'year';
+export interface MetricContract {
+    kind: 'metric' | 'derived_metric' | 'grained_metric';
+    name: string;
+    dataset: string;
+    valueType: 'number';
+    label?: string;
+    description?: string;
+    dimensions: string[];
+    measures?: string[];
+    filters: string[];
+    grains: TimeGrain[];
+    grain?: TimeGrain;
+    requires?: string[];
+    tenantScoped: boolean;
+}
+export interface MetricFilter {
+    field: string;
+    operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'between' | 'like';
+    value: unknown;
+}
+export interface MetricOrderBy {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+export interface MetricQuery {
+    dimensions?: string[];
+    filters?: MetricFilter[];
+    orderBy?: MetricOrderBy[];
+    limit?: number;
+    offset?: number;
+    by?: TimeGrain;
+}
+export interface MetricResultMeta {
+    timingMs?: number;
+    sql?: string;
+    tenant?: string;
+}
+export interface MetricResult<T = Record<string, unknown>> {
+    data: T[];
+    meta?: MetricResultMeta;
+}
+export interface SemanticTenantRuntime {
+    id: string;
+    column: string;
+    handledByBuilder: boolean;
+}
+export interface SemanticExecutionRuntime {
+    builderFactory?: QueryBuilderFactoryLike;
+    tenant?: SemanticTenantRuntime;
+}
+export interface ExecutionContext {
+    runtime?: SemanticExecutionRuntime;
+}
+export interface SemanticFilterDefinition {
+    __type: 'filter_definition';
+    field: string;
+    label?: string;
+    description?: string;
+    operators?: MetricFilter['operator'][];
+}
+export type SemanticFiltersDefinition = Record<string, SemanticFilterDefinition>;
+export interface DatasetLimits {
+    maxDimensions?: number;
+    maxMeasures?: number;
+    maxFilters?: number;
+    maxResultSize?: number;
+}
+export interface BaseMetricConfig<TDimensions extends Record<string, DimensionDefinition> = Record<string, DimensionDefinition>, TMeasures extends Record<string, MeasureDefinition> = Record<string, MeasureDefinition>> {
+    measure: keyof TMeasures & string;
+    label?: string;
+    description?: string;
+}
+export interface DerivedMetricConfig {
+    uses: Record<string, MetricRef>;
+    formula: (inputs: Record<string, string>) => FormulaExpr;
+    label?: string;
+    description?: string;
+}
+export interface DatasetQueryConfig<TDimensions extends Record<string, DimensionDefinition> = Record<string, DimensionDefinition>, TMeasures extends Record<string, MeasureDefinition> = Record<string, MeasureDefinition>> {
+    dimensions?: Array<keyof TDimensions & string>;
+    measures?: Array<keyof TMeasures & string>;
+    filters?: MetricFilter[];
+    orderBy?: MetricOrderBy[];
+    limit?: number;
+    offset?: number;
+    by?: TimeGrain;
+}
+export interface DatasetQueryContract {
+    dataset: string;
+    dimensions: string[];
+    measures: string[];
+    filters: string[];
+    grains: TimeGrain[];
+    tenantScoped: boolean;
+}
+export interface DatasetQueryRef<TDimensions extends Record<string, DimensionDefinition> = Record<string, DimensionDefinition>, TMeasures extends Record<string, MeasureDefinition> = Record<string, MeasureDefinition>> {
+    __type: 'dataset_query_ref';
+    dataset: DatasetInstance<TDimensions, TMeasures, any>;
+    config: DatasetQueryConfig<TDimensions, TMeasures>;
+    contract(): DatasetQueryContract;
+}
+export interface DatasetConfig<TDimensions extends Record<string, DimensionDefinition> = Record<string, DimensionDefinition>, TMeasures extends Record<string, MeasureDefinition> = Record<string, MeasureDefinition>, TRelationships extends Record<string, RelationshipDefinition> = Record<string, never>> {
+    source: string;
+    tenantKey?: string;
+    timeKey?: string;
+    dimensions: TDimensions;
+    measures?: TMeasures;
+    filters?: SemanticFiltersDefinition;
+    relationships?: TRelationships;
+    limits?: DatasetLimits;
+}
+export interface DatasetInstance<TDimensions extends Record<string, DimensionDefinition> = Record<string, DimensionDefinition>, TMeasures extends Record<string, MeasureDefinition> = Record<string, MeasureDefinition>, TRelationships extends Record<string, RelationshipDefinition> = Record<string, never>> {
+    __type: 'dataset';
+    name: string;
+    source: string;
+    tenantKey?: string;
+    timeKey?: string;
+    dimensions: TDimensions;
+    measures: TMeasures;
+    filters: SemanticFiltersDefinition;
+    relationships: TRelationships;
+    limits?: DatasetLimits;
+    metric<TName extends string>(metricName: TName, metricConfig: BaseMetricConfig<TDimensions, TMeasures> | DerivedMetricConfig): MetricRef<string, TName>;
+    query(config: DatasetQueryConfig<TDimensions, TMeasures>): DatasetQueryRef<TDimensions, TMeasures>;
+}
+export interface DatasetRegistryInstance {
+    register(ds: DatasetInstance): void;
+    get(name: string): DatasetInstance | undefined;
+    getAll(): DatasetInstance[];
+    has(name: string): boolean;
+}
+export type DatasetFieldNames<TDataset extends DatasetInstance> = keyof TDataset['dimensions'] & string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared validation utilities for semantic layer queries.
+ */
+import type { FieldType, MetricFilter } from './types.js';
+/**
+ * Result of a validation operation.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Checks if a value matches the expected field type.
+ *
+ * @param fieldType - The expected field type
+ * @param value - The value to check
+ * @returns true if the value matches the field type
+ */
+export declare function matchesFieldType(fieldType: FieldType, value: unknown): boolean;
+/**
+ * Validates a filter value against the expected field type.
+ *
+ * @param filter - The filter to validate
+ * @param fieldType - The expected field type
+ * @returns null if valid, error message if invalid
+ */
+export declare function validateFilterValue(filter: MetricFilter, fieldType: FieldType): string | null;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAY9E;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CA0C7F"}

package/dist/validation.js

@@ -0,0 +1,73 @@
+/**
+ * Shared validation utilities for semantic layer queries.
+ */
+/**
+ * Checks if a value matches the expected field type.
+ *
+ * @param fieldType - The expected field type
+ * @param value - The value to check
+ * @returns true if the value matches the field type
+ */
+export function matchesFieldType(fieldType, value) {
+    switch (fieldType) {
+        case 'string':
+        case 'timestamp':
+            return typeof value === 'string';
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        default:
+            return false;
+    }
+}
+/**
+ * Validates a filter value against the expected field type.
+ *
+ * @param filter - The filter to validate
+ * @param fieldType - The expected field type
+ * @returns null if valid, error message if invalid
+ */
+export function validateFilterValue(filter, fieldType) {
+    switch (filter.operator) {
+        case 'eq':
+        case 'neq':
+            return matchesFieldType(fieldType, filter.value)
+                ? null
+                : `"${filter.operator}" expects a ${fieldType} value for field "${filter.field}".`;
+        case 'gt':
+        case 'gte':
+        case 'lt':
+        case 'lte':
+            if (fieldType === 'boolean') {
+                return `"${filter.operator}" is not supported for boolean field "${filter.field}".`;
+            }
+            return matchesFieldType(fieldType, filter.value)
+                ? null
+                : `"${filter.operator}" expects a ${fieldType} value for field "${filter.field}".`;
+        case 'like':
+            if (fieldType !== 'string' && fieldType !== 'timestamp') {
+                return `"like" is only supported for string or timestamp field "${filter.field}".`;
+            }
+            return typeof filter.value === 'string'
+                ? null
+                : `"like" expects a string value for field "${filter.field}".`;
+        case 'in':
+        case 'notIn':
+            if (!Array.isArray(filter.value) || filter.value.length === 0) {
+                return `"${filter.operator}" expects a non-empty array for field "${filter.field}".`;
+            }
+            return filter.value.every(value => matchesFieldType(fieldType, value))
+                ? null
+                : `"${filter.operator}" expects ${fieldType} values for field "${filter.field}".`;
+        case 'between':
+            if (!Array.isArray(filter.value) || filter.value.length !== 2) {
+                return `"between" expects a two-item array for field "${filter.field}".`;
+            }
+            return filter.value.every(value => matchesFieldType(fieldType, value))
+                ? null
+                : `"between" expects ${fieldType} values for field "${filter.field}".`;
+        default:
+            return null;
+    }
+}