@aifabrix/miso-client 3.8.2 → 3.9.0

package/dist/utils/filter-schema.utils.js

@@ -0,0 +1,381 @@
+"use strict";
+/**
+ * Filter schema utilities for validation and SQL compilation.
+ * Provides type-safe filter validation against schemas and PostgreSQL-safe SQL generation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFilterError = createFilterError;
+exports.coerceValue = coerceValue;
+exports.validateFilter = validateFilter;
+exports.validateFilters = validateFilters;
+exports.compileFilter = compileFilter;
+exports.createFilterSchema = createFilterSchema;
+exports.loadFilterSchema = loadFilterSchema;
+const filter_schema_types_1 = require("../types/filter-schema.types");
+/**
+ * Create a structured filter validation error.
+ * @param code - Error code from FilterErrorCode
+ * @param message - Human-readable error message
+ * @param extras - Additional error context (field, operator, value, etc.)
+ * @returns FilterValidationError object
+ */
+function createFilterError(code, message, extras) {
+    return {
+        code,
+        message,
+        ...extras,
+    };
+}
+/**
+ * Validate UUID format.
+ * @param value - Value to validate
+ * @returns True if value is a valid UUID
+ */
+function isValidUUID(value) {
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(value);
+}
+/**
+ * Validate timestamp format.
+ * @param value - Value to validate
+ * @returns True if value is a valid timestamp
+ */
+function isValidTimestamp(value) {
+    const date = new Date(value);
+    return !isNaN(date.getTime());
+}
+/**
+ * Coerce a value to the appropriate type based on field definition.
+ * @param value - Value to coerce
+ * @param fieldDef - Field definition with type information
+ * @returns Coerced value
+ * @throws Error if value cannot be coerced
+ */
+function coerceValue(value, fieldDef) {
+    if (value === null)
+        return null;
+    switch (fieldDef.type) {
+        case "number": {
+            if (Array.isArray(value)) {
+                return value.map((v) => {
+                    const num = Number(v);
+                    if (isNaN(num)) {
+                        throw new Error(`Cannot coerce "${v}" to number`);
+                    }
+                    return num;
+                });
+            }
+            const num = Number(value);
+            if (isNaN(num)) {
+                throw new Error(`Cannot coerce "${value}" to number`);
+            }
+            return num;
+        }
+        case "boolean": {
+            if (typeof value === "boolean") {
+                return value;
+            }
+            if (value === "true" || value === "1") {
+                return true;
+            }
+            if (value === "false" || value === "0") {
+                return false;
+            }
+            throw new Error(`Cannot coerce "${value}" to boolean`);
+        }
+        case "timestamp": {
+            if (typeof value === "string") {
+                const date = new Date(value);
+                if (isNaN(date.getTime())) {
+                    throw new Error(`Cannot coerce "${value}" to timestamp`);
+                }
+                return date.toISOString();
+            }
+            return value;
+        }
+        case "uuid":
+        case "string":
+        case "enum":
+        default:
+            return value;
+    }
+}
+/**
+ * Validate a single filter against a schema.
+ * @param filter - Filter option to validate
+ * @param schema - Filter schema to validate against
+ * @returns FilterValidationError if invalid, null if valid
+ */
+function validateFilter(filter, schema) {
+    const fieldDef = schema.fields[filter.field];
+    // Check if field exists in schema
+    if (!fieldDef) {
+        return createFilterError(filter_schema_types_1.FilterErrorCode.UNKNOWN_FIELD, `Field '${filter.field}' is not allowed for filtering on '${schema.resource}'`, { field: filter.field });
+    }
+    // Check if operator is allowed for this field
+    if (!fieldDef.operators.includes(filter.op)) {
+        return createFilterError(filter_schema_types_1.FilterErrorCode.INVALID_OPERATOR, `Operator '${filter.op}' is not allowed for field '${filter.field}'`, {
+            field: filter.field,
+            operator: filter.op,
+            allowedOperators: fieldDef.operators,
+        });
+    }
+    // Skip value validation for null operators
+    if (filter.op === "isNull" || filter.op === "isNotNull") {
+        return null;
+    }
+    // Validate value based on field type
+    const valueError = validateFieldValue(filter.value, fieldDef, filter.field, filter.op);
+    if (valueError) {
+        return valueError;
+    }
+    return null;
+}
+/**
+ * Validate field value against field definition.
+ */
+function validateFieldValue(value, fieldDef, fieldName, op) {
+    if (value === null) {
+        return null;
+    }
+    // Validate array for in/nin operators
+    if (op === "in" || op === "nin") {
+        if (!Array.isArray(value)) {
+            return createFilterError(filter_schema_types_1.FilterErrorCode.INVALID_IN, `Operator '${op}' requires an array value for field '${fieldName}'`, { field: fieldName, operator: op, value });
+        }
+        if (value.length === 0) {
+            return createFilterError(filter_schema_types_1.FilterErrorCode.INVALID_IN, `Operator '${op}' requires a non-empty array for field '${fieldName}'`, { field: fieldName, operator: op, value });
+        }
+        // Validate each array element
+        for (const item of value) {
+            const itemError = validateSingleValue(item, fieldDef, fieldName);
+            if (itemError) {
+                return itemError;
+            }
+        }
+        return null;
+    }
+    return validateSingleValue(value, fieldDef, fieldName);
+}
+/**
+ * Validate a single value against field definition.
+ */
+function validateSingleValue(value, fieldDef, fieldName) {
+    switch (fieldDef.type) {
+        case "uuid":
+            if (typeof value !== "string" || !isValidUUID(value)) {
+                return createFilterError(filter_schema_types_1.FilterErrorCode.INVALID_UUID, `Invalid UUID value for field '${fieldName}': ${value}`, { field: fieldName, value });
+            }
+            break;
+        case "timestamp":
+            if (typeof value !== "string" || !isValidTimestamp(value)) {
+                return createFilterError(filter_schema_types_1.FilterErrorCode.INVALID_DATE, `Invalid timestamp value for field '${fieldName}': ${value}`, { field: fieldName, value });
+            }
+            break;
+        case "number":
+            if (typeof value !== "number" && isNaN(Number(value))) {
+                return createFilterError(filter_schema_types_1.FilterErrorCode.INVALID_TYPE, `Expected number for field '${fieldName}', got ${typeof value}`, { field: fieldName, value });
+            }
+            break;
+        case "boolean":
+            if (typeof value !== "boolean" && value !== "true" && value !== "false") {
+                return createFilterError(filter_schema_types_1.FilterErrorCode.INVALID_TYPE, `Expected boolean for field '${fieldName}', got ${typeof value}`, { field: fieldName, value });
+            }
+            break;
+        case "enum":
+            if (fieldDef.enumValues && !fieldDef.enumValues.includes(String(value))) {
+                return createFilterError(filter_schema_types_1.FilterErrorCode.INVALID_ENUM, `Invalid value '${value}' for field '${fieldName}'. Allowed: ${fieldDef.enumValues.join(", ")}`, { field: fieldName, value, allowedValues: fieldDef.enumValues });
+            }
+            break;
+    }
+    return null;
+}
+/**
+ * Validate multiple filters against a schema.
+ * @param filters - Array of filter options to validate
+ * @param schema - Filter schema to validate against
+ * @returns FilterValidationResult with valid flag and any errors
+ */
+function validateFilters(filters, schema) {
+    const errors = [];
+    for (const filter of filters) {
+        const error = validateFilter(filter, schema);
+        if (error) {
+            errors.push(error);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Map filter operator to SQL operator.
+ */
+function operatorToSql(op, column, paramIndex) {
+    switch (op) {
+        case "eq":
+            return { sql: `${column} = $${paramIndex}`, hasParam: true };
+        case "neq":
+            return { sql: `${column} != $${paramIndex}`, hasParam: true };
+        case "gt":
+            return { sql: `${column} > $${paramIndex}`, hasParam: true };
+        case "gte":
+            return { sql: `${column} >= $${paramIndex}`, hasParam: true };
+        case "lt":
+            return { sql: `${column} < $${paramIndex}`, hasParam: true };
+        case "lte":
+            return { sql: `${column} <= $${paramIndex}`, hasParam: true };
+        case "in":
+            return { sql: `${column} = ANY($${paramIndex})`, hasParam: true };
+        case "nin":
+            return { sql: `${column} != ALL($${paramIndex})`, hasParam: true };
+        case "like":
+            return { sql: `${column} LIKE $${paramIndex}`, hasParam: true };
+        case "ilike":
+            return { sql: `${column} ILIKE $${paramIndex}`, hasParam: true };
+        case "contains":
+            return { sql: `${column} ILIKE $${paramIndex}`, hasParam: true };
+        case "isNull":
+            return { sql: `${column} IS NULL`, hasParam: false };
+        case "isNotNull":
+            return { sql: `${column} IS NOT NULL`, hasParam: false };
+        default:
+            return { sql: `${column} = $${paramIndex}`, hasParam: true };
+    }
+}
+/**
+ * Compile filters to PostgreSQL-safe parameterized SQL.
+ * @param filters - Array of filter options to compile
+ * @param schema - Filter schema for column name mapping
+ * @param logic - Logic operator to join clauses ("and" or "or"), defaults to "and"
+ * @returns CompiledFilter with SQL string and params array
+ * @throws Error if a filter references an unknown field
+ *
+ * @example
+ * ```typescript
+ * const schema: FilterSchema = {
+ *   resource: "applications",
+ *   fields: {
+ *     name: { column: "name", type: "string", operators: ["eq", "ilike"] },
+ *     status: { column: "status", type: "enum", operators: ["eq", "in"], enumValues: ["active", "disabled"] }
+ *   }
+ * };
+ *
+ * const filters = [
+ *   { field: "status", op: "eq", value: "active" },
+ *   { field: "name", op: "ilike", value: "%test%" }
+ * ];
+ *
+ * const result = compileFilter(filters, schema);
+ * // result.sql = "status = $1 AND name ILIKE $2"
+ * // result.params = ["active", "%test%"]
+ * ```
+ */
+function compileFilter(filters, schema, logic = "and") {
+    if (filters.length === 0)
+        return { sql: "", params: [] };
+    const params = [];
+    const clauses = [];
+    for (const filter of filters) {
+        const fieldDef = schema.fields[filter.field];
+        if (!fieldDef) {
+            throw new Error(`Unknown field '${filter.field}' in schema '${schema.resource}'`);
+        }
+        const column = fieldDef.column;
+        let value = filter.value;
+        // Coerce value based on field type
+        try {
+            value = coerceValue(value, fieldDef);
+        }
+        catch {
+            // If coercion fails, use original value (validation should catch type errors)
+        }
+        // Handle contains operator - wrap value with %
+        if (filter.op === "contains" && typeof value === "string") {
+            value = `%${value}%`;
+        }
+        const paramIndex = params.length + 1;
+        const { sql, hasParam } = operatorToSql(filter.op, column, paramIndex);
+        clauses.push(sql);
+        if (hasParam) {
+            params.push(value);
+        }
+    }
+    const joinOperator = logic === "or" ? " OR " : " AND ";
+    return {
+        sql: clauses.join(joinOperator),
+        params,
+    };
+}
+/**
+ * Create a filter schema from field definitions.
+ * Convenience function for creating schemas with default operators.
+ * @param resource - Resource name
+ * @param fields - Partial field definitions (operators will be filled from defaults)
+ * @param version - Optional schema version
+ * @returns Complete FilterSchema
+ */
+function createFilterSchema(resource, fields, version) {
+    const completeFields = {};
+    for (const [fieldName, fieldDef] of Object.entries(fields)) {
+        completeFields[fieldName] = {
+            ...fieldDef,
+            operators: fieldDef.operators || filter_schema_types_1.DefaultOperatorsByType[fieldDef.type],
+        };
+    }
+    return {
+        resource,
+        version,
+        fields: completeFields,
+    };
+}
+/**
+ * Load a filter schema from a JSON object.
+ * @param json - JSON object representing a filter schema
+ * @returns Parsed FilterSchema
+ * @throws Error if schema format is invalid
+ */
+function loadFilterSchema(json) {
+    if (typeof json !== "object" || json === null) {
+        throw new Error("Invalid filter schema: expected object");
+    }
+    const obj = json;
+    if (typeof obj.resource !== "string") {
+        throw new Error("Invalid filter schema: missing 'resource' field");
+    }
+    if (typeof obj.fields !== "object" || obj.fields === null) {
+        throw new Error("Invalid filter schema: missing 'fields' object");
+    }
+    const fields = obj.fields;
+    const parsedFields = {};
+    for (const [fieldName, fieldDef] of Object.entries(fields)) {
+        if (typeof fieldDef !== "object" || fieldDef === null) {
+            throw new Error(`Invalid filter schema: field '${fieldName}' must be an object`);
+        }
+        const def = fieldDef;
+        if (typeof def.column !== "string") {
+            throw new Error(`Invalid filter schema: field '${fieldName}' missing 'column'`);
+        }
+        if (typeof def.type !== "string") {
+            throw new Error(`Invalid filter schema: field '${fieldName}' missing 'type'`);
+        }
+        if (!Array.isArray(def.operators)) {
+            throw new Error(`Invalid filter schema: field '${fieldName}' missing 'operators' array`);
+        }
+        parsedFields[fieldName] = {
+            column: def.column,
+            type: def.type,
+            operators: def.operators,
+            enumValues: Array.isArray(def.enumValues) ? def.enumValues : undefined,
+            nullable: typeof def.nullable === "boolean" ? def.nullable : undefined,
+            description: typeof def.description === "string" ? def.description : undefined,
+        };
+    }
+    return {
+        resource: obj.resource,
+        version: typeof obj.version === "string" ? obj.version : undefined,
+        fields: parsedFields,
+    };
+}
+//# sourceMappingURL=filter-schema.utils.js.map

package/dist/utils/filter-schema.utils.js.map

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

package/dist/utils/filter.utils.d.ts

@@ -5,7 +5,10 @@ import type { FilterOption, FilterQuery } from "../types/filter.types";
 import { FilterBuilder } from "../types/filter.types";
 /**
  * Parse filter query parameters into structured FilterOption array.
- * Supports JSON format: object, JSON string, or URL-encoded JSON string.
+ * Supports both JSON format and colon format.
+ *
+ * **JSON format**: object, JSON string, or URL-encoded JSON string
+ * **Colon format**: "field:operator:value" (e.g., "status:eq:active", "region:in:eu,us")
  *
  * @param query - Query parameters object (e.g., from URLSearchParams or request query)
  * @returns Array of parsed filter options
@@ -13,126 +16,47 @@ import { FilterBuilder } from "../types/filter.types";
  *
  * @example
  * ```typescript
- * // Direct object format
+ * // JSON object format
  * parseFilterParams({ filter: { status: { eq: 'active' } } });
  *
- * // JSON string format
- * parseFilterParams({ filter: '{"status": {"eq": "active"}}' });
- *
- * // URL-encoded JSON (from query string)
- * parseFilterParams({ filter: '%7B%22status%22%3A%7B%22eq%22%3A%22active%22%7D%7D' });
+ * // Colon format (single filter)
+ * parseFilterParams({ filter: 'status:eq:active' });
  *
- * // Multiple filters with null checks
- * parseFilterParams({
- *   filter: {
- *     status: { eq: 'active' },
- *     deletedAt: { isNull: null },
- *     region: { in: ['eu', 'us'] }
- *   }
- * });
+ * // Colon format (multiple filters as array)
+ * parseFilterParams({ filter: ['status:eq:active', 'region:in:eu,us'] });
  * ```
  */
 export declare function parseFilterParams(query: Record<string, unknown>): FilterOption[];
 /**
  * Build query string from FilterQuery object using JSON format for filters.
- *
  * @param options - FilterQuery object with filters, sort, pagination, and field selection
  * @returns Query string with URL-encoded JSON filter format
- *
- * @example
- * ```typescript
- * buildQueryString({
- *   filters: [
- *     { field: 'status', op: 'eq', value: 'active' },
- *     { field: 'age', op: 'gte', value: 18 }
- *   ],
- *   sort: ['-updated_at'],
- *   page: 1,
- *   pageSize: 25
- * });
- * // Returns: "filter=%7B%22status%22%3A%7B%22eq%22%3A%22active%22%7D%2C%22age%22%3A%7B%22gte%22%3A18%7D%7D&sort=-updated_at&page=1&page_size=25"
- * ```
  */
 export declare function buildQueryString(options: FilterQuery): string;
 /**
  * Apply filters locally to an array (used for mocks/tests).
  * Supports all operators including isNull and isNotNull.
- *
  * @param data - Array of items to filter
  * @param filters - Array of filter options to apply
  * @returns Filtered array
- *
- * @example
- * ```typescript
- * const items = [
- *   { id: 1, status: 'active', deletedAt: null },
- *   { id: 2, status: 'inactive', deletedAt: '2024-01-01' }
- * ];
- *
- * applyFilters(items, [
- *   { field: 'status', op: 'eq', value: 'active' },
- *   { field: 'deletedAt', op: 'isNull', value: null }
- * ]);
- * ```
  */
 export declare function applyFilters<T extends Record<string, unknown>>(data: T[], filters: FilterOption[]): T[];
 /**
  * Validate JSON filter structure.
- *
  * @param filter - Filter object to validate
  * @throws Error if filter structure is invalid
- *
- * @example
- * ```typescript
- * // Valid filter
- * validateJsonFilter({ status: { eq: 'active' } });
- *
- * // Invalid - throws error
- * validateJsonFilter({ status: 'active' }); // Error: must have operator dictionary
- * ```
  */
 export declare function validateJsonFilter(filter: unknown): void;
 /**
  * Convert FilterQuery to JSON filter format.
- * Useful for serialization and debugging.
- *
  * @param filterQuery - FilterQuery object to convert
  * @returns JSON filter object (e.g., {"status": {"eq": "active"}})
- *
- * @example
- * ```typescript
- * filterQueryToJson({
- *   filters: [
- *     { field: 'status', op: 'eq', value: 'active' },
- *     { field: 'age', op: 'gte', value: 18 }
- *   ]
- * });
- * // Returns: { status: { eq: 'active' }, age: { gte: 18 } }
- * ```
  */
 export declare function filterQueryToJson(filterQuery: FilterQuery): Record<string, Record<string, unknown>>;
 /**
  * Convert JSON filter format to FilterQuery.
- * Convenience wrapper around parseFilterParams().
- *
  * @param jsonFilter - JSON filter object (e.g., {"status": {"eq": "active"}})
  * @returns FilterQuery object
- *
- * @example
- * ```typescript
- * jsonToFilterQuery({
- *   status: { eq: 'active' },
- *   age: { gte: 18 },
- *   region: { in: ['eu', 'us'] }
- * });
- * // Returns: {
- * //   filters: [
- * //     { field: 'status', op: 'eq', value: 'active' },
- * //     { field: 'age', op: 'gte', value: 18 },
- * //     { field: 'region', op: 'in', value: ['eu', 'us'] }
- * //   ]
- * // }
- * ```
  */
 export declare function jsonToFilterQuery(jsonFilter: Record<string, Record<string, unknown>>): FilterQuery;
 export { FilterBuilder };

package/dist/utils/filter.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filter.utils.d.ts","sourceRoot":"","sources":["../../src/utils/filter.utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAkB,MAAM,uBAAuB,CAAC;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAqGtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,YAAY,EAAE,CA2DhB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CA4B7D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,IAAI,EAAE,CAAC,EAAE,EACT,OAAO,EAAE,YAAY,EAAE,GACtB,CAAC,EAAE,CA0CL;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CA2BxD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAanG;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAClD,WAAW,CAGb;AAGD,OAAO,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"filter.utils.d.ts","sourceRoot":"","sources":["../../src/utils/filter.utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAkB,MAAM,uBAAuB,CAAC;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AA+DtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,EAAE,CA8FhF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAwB7D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,IAAI,EAAE,CAAC,EAAE,EACT,OAAO,EAAE,YAAY,EAAE,GACtB,CAAC,EAAE,CAuCL;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAwBxD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAWnG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAClD,WAAW,CAGb;AAGD,OAAO,EAAE,aAAa,EAAE,CAAC"}