bunsane 0.1.4 → 0.2.0

package/query/FilterBuilder.ts

@@ -0,0 +1,127 @@
+/**
+ * Custom Filter Builder System for Bunsane Query Framework
+ *
+ * This module provides the core types and interfaces for extensible query filtering,
+ * enabling plugins to register custom filter operators that integrate seamlessly
+ * with the DAG-based Query system.
+ */
+
+import type { QueryFilter } from "./QueryContext";
+import type { QueryContext } from "./QueryContext";
+
+/**
+ * Result returned by a custom filter builder function
+ */
+export interface FilterResult {
+    /** The SQL fragment to append to the WHERE clause */
+    sql: string;
+    /** Number of parameters added to the context by this filter */
+    addedParams: number;
+}
+
+/**
+ * Function signature for custom filter builders
+ *
+ * @param filter - The filter specification containing field, operator, and value
+ * @param alias - The table alias for the component table (e.g., "c" for components)
+ * @param context - The query context for parameter management and caching
+ * @returns FilterResult containing SQL fragment and parameter count
+ */
+export type FilterBuilder = (filter: QueryFilter, alias: string, context: QueryContext) => FilterResult;
+
+/**
+ * Options for advanced filter builder configuration
+ */
+export interface FilterBuilderOptions {
+    /** Whether this filter supports LATERAL join optimization */
+    supportsLateral?: boolean;
+    /** Whether this filter requires database indexes for optimal performance */
+    requiresIndex?: boolean;
+    /** Complexity score for performance monitoring (0-10, higher = more complex) */
+    complexityScore?: number;
+    /** Optional validation function for filter values */
+    validate?: (filter: QueryFilter) => boolean;
+}
+
+/**
+ * Build a JSON path expression for nested field access
+ *
+ * @param field - The field path (e.g., "location.coordinates.latitude")
+ * @param alias - The table alias (e.g., "c")
+ * @returns PostgreSQL JSON path expression
+ *
+ * @example
+ * buildJSONPath("device.unique_id", "c") // "c.data->'device'->>'unique_id'"
+ * buildJSONPath("latitude", "c") // "c.data->>'latitude'"
+ */
+export function buildJSONPath(field: string, alias: string): string {
+    if (field.includes('.')) {
+        const parts = field.split('.');
+        const lastPart = parts.pop()!;
+        const nestedPath = parts.map(p => `'${p}'`).join('->');
+        return `${alias}.data->${nestedPath}->>'${lastPart}'`;
+    } else {
+        return `${alias}.data->>'${field}'`;
+    }
+}
+
+/**
+ * Compose multiple filter builders into a single builder that applies all conditions
+ *
+ * This allows chaining multiple custom filters together (e.g., spatial proximity AND full-text search).
+ * All builders are executed and their SQL fragments are combined with AND.
+ *
+ * @param builders - Array of filter builders to compose
+ * @returns A composed filter builder function
+ *
+ * @example
+ * const spatialAndTextBuilder = composeFilters([withinDistanceBuilder, fullTextSearchBuilder]);
+ * // Results in: (spatial_condition) AND (text_search_condition)
+ */
+export function composeFilters(builders: FilterBuilder[]): FilterBuilder {
+    if (builders.length === 0) {
+        throw new Error('Cannot compose empty array of filter builders');
+    }
+
+    return (filter: QueryFilter, alias: string, context: QueryContext): FilterResult => {
+        const conditions: string[] = [];
+        let totalParams = 0;
+
+        for (const builder of builders) {
+            const result = builder(filter, alias, context);
+            if (result.sql.trim()) {
+                conditions.push(`(${result.sql})`);
+            }
+            totalParams += result.addedParams;
+        }
+
+        return {
+            sql: conditions.join(' AND '),
+            addedParams: totalParams
+        };
+    };
+}
+
+/**
+ * Create a filter builder that adds SQL hints for index usage
+ *
+ * This wrapper adds PostgreSQL query hints to suggest index usage to the planner.
+ * Useful for custom filters that require specific indexes for optimal performance.
+ *
+ * @param builder - The original filter builder
+ * @param indexHint - The index name to hint (e.g., "idx_spatial_location")
+ * @returns A filter builder that includes index hints
+ *
+ * @example
+ * const hintedBuilder = withIndexHint(spatialBuilder, 'idx_spatial_location');
+ * // Generates: /* INDEX: idx_spatial_location */ (spatial_condition)
+ */
+export function withIndexHint(builder: FilterBuilder, indexHint: string): FilterBuilder {
+    return (filter: QueryFilter, alias: string, context: QueryContext): FilterResult => {
+        const result = builder(filter, alias, context);
+        return {
+            sql: `/* INDEX: ${indexHint} */ ${result.sql}`,
+            addedParams: result.addedParams
+        };
+    };
+}

package/query/FilterBuilderRegistry.ts

@@ -0,0 +1,202 @@
+/**
+ * Global Registry for Custom Filter Builders
+ *
+ * Provides thread-safe registration and lookup of custom filter operators.
+ * This registry enables plugins to extend the query system with domain-specific
+ * filtering capabilities (e.g., spatial queries, full-text search).
+ */
+
+import type { FilterBuilder, FilterBuilderOptions } from "./FilterBuilder";
+
+/**
+ * Registry entry containing the builder function and its options
+ */
+interface RegistryEntry {
+    builder: FilterBuilder;
+    options?: FilterBuilderOptions;
+    registeredBy?: string; // Plugin name for debugging
+    registeredAt: Date;
+    version?: string; // Semantic version for the filter implementation
+}
+
+/**
+ * Global registry for custom filter builders
+ *
+ * This class provides a static interface for registering and retrieving
+ * custom filter builders. It ensures thread-safe operations during
+ * plugin initialization.
+ */
+export class FilterBuilderRegistry {
+    private static registry: Map<string, RegistryEntry> = new Map();
+    private static lock: boolean = false;
+
+    /**
+     * Register a custom filter builder for a specific operator
+     *
+     * @param operator - The filter operator (e.g., "within_distance", "contains_point")
+     * @param builder - The filter builder function
+     * @param options - Optional configuration for the filter builder
+     * @param pluginName - Name of the plugin registering this builder (for debugging)
+     * @param version - Optional semantic version for the filter implementation (allows upgrades)
+     * @throws Error if the operator is already registered by a different plugin (unless version allows override)
+     */
+    public static register(
+        operator: string,
+        builder: FilterBuilder,
+        options?: FilterBuilderOptions,
+        pluginName?: string,
+        version?: string
+    ): void {
+        // Simple lock mechanism for thread safety
+        while (this.lock) {
+            // Busy wait - in practice, this should be very short
+            // Consider using a proper mutex in high-concurrency environments
+        }
+
+        this.lock = true;
+
+        try {
+            const existing = this.registry.get(operator);
+
+            if (existing) {
+                // Allow override if same plugin or if version is newer
+                const canOverride =
+                    (pluginName && existing.registeredBy === pluginName) ||
+                    (version && existing.version && this.isNewerVersion(version, existing.version));
+
+                if (!canOverride) {
+                    throw new Error(`Filter operator '${operator}' is already registered by '${existing.registeredBy || 'unknown'}' (v${existing.version || 'unknown'}). ` +
+                        `Cannot register from '${pluginName || 'unknown'}' (v${version || 'unknown'}) without version upgrade.`);
+                }
+            }
+
+            this.registry.set(operator, {
+                builder,
+                options,
+                registeredBy: pluginName,
+                registeredAt: new Date(),
+                version
+            });
+        } finally {
+            this.lock = false;
+        }
+    }
+
+    /**
+     * Check if a filter operator has a custom builder registered
+     *
+     * @param operator - The filter operator to check
+     * @returns true if a custom builder is registered for this operator
+     */
+    public static has(operator: string): boolean {
+        return this.registry.has(operator);
+    }
+
+    /**
+     * Get the custom filter builder for a specific operator
+     *
+     * @param operator - The filter operator
+     * @returns The filter builder function, or undefined if not registered
+     */
+    public static get(operator: string): FilterBuilder | undefined {
+        return this.registry.get(operator)?.builder;
+    }
+
+    /**
+     * Get the options for a registered filter builder
+     *
+     * @param operator - The filter operator
+     * @returns The filter builder options, or undefined if not registered
+     */
+    public static getOptions(operator: string): FilterBuilderOptions | undefined {
+        return this.registry.get(operator)?.options;
+    }
+
+    /**
+     * Unregister a custom filter builder
+     *
+     * @param operator - The filter operator to remove
+     * @returns true if the operator was registered and removed, false otherwise
+     */
+    public static unregister(operator: string): boolean {
+        // Simple lock mechanism
+        while (this.lock) {
+            // Busy wait
+        }
+
+        this.lock = true;
+
+        try {
+            return this.registry.delete(operator);
+        } finally {
+            this.lock = false;
+        }
+    }
+
+    /**
+     * List all registered filter operators with their metadata
+     *
+     * @returns Array of registered operators with metadata
+     */
+    public static listRegistered(): Array<{
+        operator: string;
+        options?: FilterBuilderOptions;
+        registeredBy?: string;
+        registeredAt: Date;
+        version?: string;
+    }> {
+        return Array.from(this.registry.entries()).map(([operator, entry]) => ({
+            operator,
+            options: entry.options,
+            registeredBy: entry.registeredBy,
+            registeredAt: entry.registeredAt,
+            version: entry.version
+        }));
+    }
+
+    /**
+     * Clear all registered filter builders (for testing purposes)
+     */
+    public static clear(): void {
+        // Simple lock mechanism
+        while (this.lock) {
+            // Busy wait
+        }
+
+        this.lock = true;
+
+        try {
+            this.registry.clear();
+        } finally {
+            this.lock = false;
+        }
+    }
+
+    /**
+     * Compare two semantic versions to determine if the first is newer
+     *
+     * @param newVersion - The new version string
+     * @param oldVersion - The old version string
+     * @returns true if newVersion is semantically newer than oldVersion
+     */
+    private static isNewerVersion(newVersion: string, oldVersion: string): boolean {
+        try {
+            const newParts = newVersion.split('.').map(n => parseInt(n, 10));
+            const oldParts = oldVersion.split('.').map(n => parseInt(n, 10));
+
+            // Compare major, minor, patch versions
+            for (let i = 0; i < Math.max(newParts.length, oldParts.length); i++) {
+                const newPart = newParts[i] || 0;
+                const oldPart = oldParts[i] || 0;
+
+                if (newPart > oldPart) return true;
+                if (newPart < oldPart) return false;
+            }
+
+            return false; // Same version
+        } catch {
+            // If parsing fails, fall back to string comparison
+            return newVersion > oldVersion;
+        }
+    }
+}