bunsane 0.1.4 → 0.2.0

package/query/QueryContext.ts

@@ -0,0 +1,170 @@
+import { ComponentRegistry, type BaseComponent, type ComponentDataType } from "../core/components";
+import { FilterBuilderRegistry } from "./FilterBuilderRegistry";
+import type { SQL } from "bun";
+
+export interface QueryFilter {
+    field: string;
+    operator: string;
+    value: any;
+}
+
+export interface SortOrder {
+    component: string;
+    property: string;
+    direction: "ASC" | "DESC";
+    nullsFirst?: boolean;
+}
+
+export class QueryContext {
+    public params: any[] = [];
+    public paramIndex: number = 1;
+    public tableAliases: Map<string, string> = new Map();
+    public sqlFragments: string[] = [];
+    public componentIds: Set<string> = new Set();
+    public excludedComponentIds: Set<string> = new Set();
+    public componentFilters: Map<string, QueryFilter[]> = new Map();
+    public sortOrders: SortOrder[] = [];
+    public excludedEntityIds: Set<string> = new Set();
+    public withId: string | null = null;
+    public limit: number | null = null;
+    public offsetValue: number = 0;
+
+    // Cursor-based pagination (more efficient than OFFSET for large datasets)
+    public cursorId: string | null = null;
+    public cursorDirection: 'after' | 'before' = 'after';
+    public hasCTE: boolean = false;
+    public cteName: string = "";
+    public eagerComponents: Set<string> = new Set();
+    public paginationAppliedInCTE: boolean = false;
+
+    private trx: SQL | undefined;
+    constructor(trx?: SQL) {
+        this.trx = trx;
+    }
+
+    /**
+     * Get the database connection (transaction or default db)
+     */
+    public getDb(): SQL | undefined {
+        return this.trx;
+    }
+
+    public getNextAlias(prefix: string = "t"): string {
+        const count = this.tableAliases.size;
+        const alias = `${prefix}${count}`;
+        this.tableAliases.set(alias, alias);
+        return alias;
+    }
+
+    public addParam(value: any): number {
+        this.params.push(value);
+        return this.paramIndex++;
+    }
+
+    /**
+     * Reset the context for reuse (clears params and resets paramIndex)
+     */
+    public reset(): void {
+        this.params = [];
+        this.paramIndex = 1;
+        this.tableAliases.clear();
+        this.sqlFragments = [];
+    }
+
+    public addParams(values: any[]): number[] {
+        const indices: number[] = [];
+        for (const value of values) {
+            indices.push(this.addParam(value));
+        }
+        return indices;
+    }
+
+    public addSqlFragment(fragment: string): void {
+        this.sqlFragments.push(fragment);
+    }
+
+    public getComponentId(componentCtor: new (...args: any[]) => BaseComponent): string | undefined {
+        return ComponentRegistry.getComponentId(componentCtor.name);
+    }
+
+    /**
+     * Generate a cache key fingerprint for prepared statement caching
+     */
+    public generateCacheKey(): string {
+        // Create a deterministic fingerprint of the query structure
+        const components = Array.from(this.componentIds).sort().join(',');
+        const excludedComponents = Array.from(this.excludedComponentIds).sort().join(',');
+        const filters = Array.from(this.componentFilters.entries())
+            .map(([typeId, filters]) => `${typeId}:${filters.map(f => {
+                // For IN/NOT IN operators, include array length in cache key
+                // This ensures different array lengths produce different cache keys
+                // preventing prepared statement parameter count mismatches
+                if ((f.operator === 'IN' || f.operator === 'NOT IN') && Array.isArray(f.value)) {
+                    return `${f.field}${f.operator}[${f.value.length}]`;
+                }
+                return `${f.field}${f.operator}`;
+            }).sort().join('|')}`)
+            .sort()
+            .join(';');
+        const sorts = this.sortOrders
+            .map(s => `${s.component}.${s.property}:${s.direction}`)
+            .sort()
+            .join(',');
+
+        // Extract custom filter operators for cache key differentiation
+        const customOperators = this.extractCustomOperators();
+        const customOps = customOperators.length > 0 ? `customOps:${customOperators.sort().join(',')}` : '';
+
+        // Include pagination in cache key to prevent prepared statement collision
+        // when same query is executed with different pagination settings
+        const paginationKey = `limit:${this.limit !== null ? 'yes' : 'no'}|offset:${this.offsetValue > 0 ? 'yes' : 'no'}|cursor:${this.cursorId !== null ? this.cursorDirection : 'no'}`;
+
+        // Include excluded entity IDs count for cache key differentiation
+        const excludedEntityCount = this.excludedEntityIds.size;
+        const excludedEntitiesKey = excludedEntityCount > 0 ? `|excludedEntities:${excludedEntityCount}` : '';
+
+        const key = `${components}|${excludedComponents}|${filters}|${sorts}|${this.hasCTE}|${this.cteName}|${customOps}|${paginationKey}${excludedEntitiesKey}`;
+        return key;
+    }
+
+    /**
+     * Extract custom filter operators from component filters
+     * Used for cache key generation to differentiate queries with custom filters
+     */
+    private extractCustomOperators(): string[] {
+        const customOperators: string[] = [];
+
+        for (const filters of this.componentFilters.values()) {
+            for (const filter of filters) {
+                if (FilterBuilderRegistry.has(filter.operator)) {
+                    customOperators.push(filter.operator);
+                }
+            }
+        }
+
+        return customOperators;
+    }
+
+    public clone(): QueryContext {
+        const clone = new QueryContext();
+        clone.params = [...this.params];
+        clone.paramIndex = this.paramIndex;
+        clone.tableAliases = new Map(this.tableAliases);
+        clone.sqlFragments = [...this.sqlFragments];
+        clone.componentIds = new Set(this.componentIds);
+        clone.excludedComponentIds = new Set(this.excludedComponentIds);
+        clone.componentFilters = new Map(this.componentFilters);
+        clone.sortOrders = [...this.sortOrders];
+        clone.excludedEntityIds = new Set(this.excludedEntityIds);
+        clone.withId = this.withId;
+        clone.limit = this.limit;
+        clone.offsetValue = this.offsetValue;
+        clone.cursorId = this.cursorId;
+        clone.cursorDirection = this.cursorDirection;
+        clone.hasCTE = this.hasCTE;
+        clone.cteName = this.cteName;
+        clone.eagerComponents = new Set(this.eagerComponents);
+        clone.paginationAppliedInCTE = this.paginationAppliedInCTE;
+        return clone;
+    }
+}

package/query/QueryDAG.ts

@@ -0,0 +1,122 @@
+import { QueryNode } from "./QueryNode";
+import type { QueryResult } from "./QueryNode";
+import { QueryContext } from "./QueryContext";
+import { SourceNode } from "./SourceNode";
+import { ComponentInclusionNode } from "./ComponentInclusionNode";
+import { CTENode } from "./CTENode";
+
+export class QueryDAG {
+    private nodes: QueryNode[] = [];
+    private rootNode: QueryNode | null = null;
+
+    public addNode(node: QueryNode): void {
+        if (!this.nodes.includes(node)) {
+            this.nodes.push(node);
+        }
+    }
+
+    public setRootNode(node: QueryNode): void {
+        this.rootNode = node;
+        this.addNode(node);
+    }
+
+    public getRootNode(): QueryNode | null {
+        return this.rootNode;
+    }
+
+    public getNodes(): QueryNode[] {
+        return [...this.nodes];
+    }
+
+    /**
+     * Execute the DAG by finding and executing the final node in the chain
+     */
+    public execute(context: QueryContext): QueryResult {
+        if (!this.rootNode) {
+            throw new Error("No root node set in QueryDAG");
+        }
+
+        // Get all nodes in topological order
+        const allNodes = this.rootNode.getTopologicalOrder();
+        
+        // Check if we have a CTENode and execute it first to set context
+        const cteNode = allNodes.find(node => node instanceof CTENode) as CTENode;
+        let cteSql = '';
+        if (cteNode) {
+            // Execute CTE node first to set context and get SQL
+            const cteResult = cteNode.execute(context);
+            cteSql = cteResult.sql;
+        }
+        
+        // The leaf node is the one that no other node depends on
+        // Find it by checking which nodes are not in any node's dependencies
+        const nodesInDependencies = new Set<QueryNode>();
+        for (const node of allNodes) {
+            for (const dep of node.getDependencies()) {
+                nodesInDependencies.add(dep);
+            }
+        }
+        
+        const leafNodes = allNodes.filter(node => !nodesInDependencies.has(node));
+        
+        if (leafNodes.length === 0) {
+            throw new Error("No leaf node found in DAG");
+        }
+        
+        // If multiple leaf nodes, take the last one in topological order
+        const leafNode = leafNodes[leafNodes.length - 1]!;
+
+        // Execute only the leaf node - it will get results from its dependencies
+        const result = leafNode.execute(context);
+
+        // If CTE is present, combine CTE SQL with main query
+        if (context.hasCTE && context.cteName && cteSql) {
+            // Combine CTE SQL with main query SQL
+            result.sql = cteSql + (result.sql ? '\n' + result.sql : '');
+        }
+
+        return result;
+    }
+
+    /**
+     * Build a basic DAG for component-based queries
+     */
+    public static buildBasicQuery(context: QueryContext): QueryDAG {
+        const dag = new QueryDAG();
+
+        // Count total filters across all components
+        let totalFilters = 0;
+        for (const filters of context.componentFilters.values()) {
+            totalFilters += filters.length;
+        }
+
+        // If we have multiple component filters (>= 2), use CTE for optimization
+        const useCTE = totalFilters >= 2 && context.componentIds.size > 0;
+
+        if (useCTE) {
+            // Create CTE node as root
+            const cteNode = new CTENode();
+            dag.setRootNode(cteNode);
+
+            // If we have component requirements, add component inclusion node
+            if (context.componentIds.size > 0 || context.excludedComponentIds.size > 0) {
+                const componentNode = new ComponentInclusionNode();
+                componentNode.addDependency(cteNode);
+                dag.addNode(componentNode);
+            }
+        } else {
+            // Create source node
+            const sourceNode = new SourceNode();
+            dag.setRootNode(sourceNode);
+
+            // If we have component requirements, add component inclusion node
+            if (context.componentIds.size > 0 || context.excludedComponentIds.size > 0) {
+                const componentNode = new ComponentInclusionNode();
+                componentNode.addDependency(sourceNode);
+                dag.addNode(componentNode);
+            }
+        }
+
+        return dag;
+    }
+}

package/query/QueryNode.ts

@@ -0,0 +1,65 @@
+import { QueryContext } from "./QueryContext";
+
+export interface QueryResult {
+    sql: string;
+    params: any[];
+    context: QueryContext;
+}
+
+export abstract class QueryNode {
+    protected dependencies: QueryNode[] = [];
+    protected dependents: QueryNode[] = [];
+
+    public addDependency(node: QueryNode): void {
+        if (!this.dependencies.includes(node)) {
+            this.dependencies.push(node);
+            node.addDependent(this);
+        }
+    }
+
+    public addDependent(node: QueryNode): void {
+        if (!this.dependents.includes(node)) {
+            this.dependents.push(node);
+        }
+    }
+
+    public getDependencies(): QueryNode[] {
+        return [...this.dependencies];
+    }
+
+    public getDependents(): QueryNode[] {
+        return [...this.dependents];
+    }
+
+    public abstract execute(context: QueryContext): QueryResult;
+
+    public abstract getNodeType(): string;
+
+    /**
+     * Get all nodes in topological order (dependencies first)
+     */
+    public getTopologicalOrder(visited: Set<QueryNode> = new Set(), result: QueryNode[] = []): QueryNode[] {
+        if (visited.has(this)) {
+            return result;
+        }
+
+        visited.add(this);
+
+        // Visit all dependencies first
+        for (const dep of this.dependencies) {
+            dep.getTopologicalOrder(visited, result);
+        }
+
+        // Then add this node
+        if (!result.includes(this)) {
+            result.push(this);
+        }
+
+        // Then visit all dependents (nodes that depend on this)
+        for (const dependent of this.dependents) {
+            dependent.getTopologicalOrder(visited, result);
+        }
+
+        return result;
+    }
+}

package/query/SourceNode.ts

@@ -0,0 +1,53 @@
+import { QueryNode } from "./QueryNode";
+import type { QueryResult } from "./QueryNode";
+import { QueryContext } from "./QueryContext";
+
+export class SourceNode extends QueryNode {
+    public execute(context: QueryContext): QueryResult {
+        let sql = "SELECT id FROM entities WHERE deleted_at IS NULL";
+
+        if (context.withId) {
+            sql += ` AND id = $${context.addParam(context.withId)}`;
+        }
+
+        // Add entity exclusions if any
+        if (context.excludedEntityIds.size > 0) {
+            const excludedIds = Array.from(context.excludedEntityIds);
+            // Fix: Use the id directly instead of shift() which mutates the array
+            const placeholders = excludedIds.map((id) => `$${context.addParam(id)}`).join(', ');
+            sql += ` AND id NOT IN (${placeholders})`;
+        }
+
+        // Apply cursor-based pagination (more efficient than OFFSET)
+        if (context.cursorId !== null) {
+            const operator = context.cursorDirection === 'after' ? '>' : '<';
+            sql += ` AND id ${operator} $${context.addParam(context.cursorId)}`;
+        }
+
+        // Order by id - reverse for 'before' cursor direction
+        const orderDirection = context.cursorDirection === 'before' ? 'DESC' : 'ASC';
+        sql += ` ORDER BY id ${orderDirection}`;
+
+        // Only apply pagination if CTENode hasn't already applied it
+        // This prevents double parameter addition and incorrect SQL
+        if (!context.paginationAppliedInCTE) {
+            if (context.limit !== null) {
+                sql += ` LIMIT $${context.addParam(context.limit)}`;
+            }
+            // Only include OFFSET when not using cursor-based pagination
+            if (context.cursorId === null && (context.offsetValue > 0 || context.limit !== null)) {
+                sql += ` OFFSET $${context.addParam(context.offsetValue)}`;
+            }
+        }
+
+        return {
+            sql,
+            params: context.params,
+            context
+        };
+    }
+
+    public getNodeType(): string {
+        return "SourceNode";
+    }
+}

package/query/builders/FullTextSearchBuilder.ts

@@ -0,0 +1,236 @@
+/**
+ * Full-Text Search Filter Builder
+ *
+ * Provides PostgreSQL full-text search capabilities as a custom filter builder.
+ * Demonstrates advanced filter builder patterns including validation and options.
+ */
+
+import type { FilterBuilder, FilterBuilderOptions } from "../FilterBuilder";
+import type { QueryFilter } from "../QueryContext";
+import type { QueryContext } from "../QueryContext";
+
+/**
+ * Full-text search filter value interface
+ */
+export interface FullTextFilterValue {
+    /** The search query text */
+    query: string;
+    /** Optional language for text search (defaults to 'english') */
+    language?: string;
+    /** Optional search type: 'plain' (default), 'phrase', 'web', 'tsquery' */
+    type?: 'plain' | 'phrase' | 'web' | 'tsquery';
+}
+
+/**
+ * Validate full-text search filter values
+ */
+function validateFullTextFilter(filter: QueryFilter): boolean {
+    const value = filter.value as FullTextFilterValue;
+
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+
+    if (!value.query || typeof value.query !== 'string' || value.query.trim().length === 0) {
+        return false;
+    }
+
+    if (value.language && typeof value.language !== 'string') {
+        return false;
+    }
+
+    if (value.type && !['plain', 'phrase', 'web', 'tsquery'].includes(value.type)) {
+        return false;
+    }
+
+    return true;
+}
+
+/**
+ * Full-text search filter builder using PostgreSQL's built-in text search
+ *
+ * Supports multiple search types:
+ * - plain: plainto_tsquery() - simple natural language search
+ * - phrase: phraseto_tsquery() - exact phrase matching
+ * - web: websearch_to_tsquery() - web-style search syntax
+ * - tsquery: raw tsquery syntax for advanced users
+ *
+ * @param filter - Filter containing FullTextFilterValue
+ * @param alias - Component table alias
+ * @param context - Query context for parameter management
+ * @returns SQL fragment for full-text search
+ */
+export const fullTextSearchBuilder: FilterBuilder = (
+    filter: QueryFilter,
+    alias: string,
+    context: QueryContext
+): { sql: string; addedParams: number } => {
+    const value = filter.value as FullTextFilterValue;
+    const { query, language = 'english', type = 'plain' } = value;
+
+    // Build the text search vector from the specified field
+    const fieldPath = filter.field.includes('.')
+        ? filter.field.split('.').map(p => `'${p}'`).join('->')
+        : `'${filter.field}'`;
+
+    const vectorSql = `to_tsvector('${language}', ${alias}.data->${fieldPath})`;
+
+    // Choose the appropriate query function based on type
+    let queryFunction: string;
+    switch (type) {
+        case 'phrase':
+            queryFunction = 'phraseto_tsquery';
+            break;
+        case 'web':
+            queryFunction = 'websearch_to_tsquery';
+            break;
+        case 'tsquery':
+            queryFunction = 'to_tsquery';
+            break;
+        case 'plain':
+        default:
+            queryFunction = 'plainto_tsquery';
+            break;
+    }
+
+    const querySql = `${queryFunction}('${language}', $${context.addParam(query)})`;
+
+    return {
+        sql: `${vectorSql} @@ ${querySql}`,
+        addedParams: 1
+    };
+};
+
+/**
+ * Full-text search filter builder with ranking (returns relevance score)
+ *
+ * This builder includes ranking information that can be used for ordering results
+ * by relevance. Note: This requires modifying the SELECT clause to include the rank.
+ *
+ * @param filter - Filter containing FullTextFilterValue
+ * @param alias - Component table alias
+ * @param context - Query context for parameter management
+ * @returns SQL fragment with ranking
+ */
+export const fullTextSearchWithRankBuilder: FilterBuilder = (
+    filter: QueryFilter,
+    alias: string,
+    context: QueryContext
+): { sql: string; addedParams: number } => {
+    const value = filter.value as FullTextFilterValue;
+    const { query, language = 'english', type = 'plain' } = value;
+
+    // Build the text search vector from the specified field
+    const fieldPath = filter.field.includes('.')
+        ? filter.field.split('.').map(p => `'${p}'`).join('->')
+        : `'${filter.field}'`;
+
+    const vectorSql = `to_tsvector('${language}', ${alias}.data->${fieldPath})`;
+
+    // Choose the appropriate query function based on type
+    let queryFunction: string;
+    switch (type) {
+        case 'phrase':
+            queryFunction = 'phraseto_tsquery';
+            break;
+        case 'web':
+            queryFunction = 'websearch_to_tsquery';
+            break;
+        case 'tsquery':
+            queryFunction = 'to_tsquery';
+            break;
+        case 'plain':
+        default:
+            queryFunction = 'plainto_tsquery';
+            break;
+    }
+
+    const querySql = `${queryFunction}('${language}', $${context.addParam(query)})`;
+
+    // Include ranking in the condition (can be used for ordering)
+    const rankSql = `ts_rank(${vectorSql}, ${querySql})`;
+
+    return {
+        sql: `${vectorSql} @@ ${querySql} /* RANK: ${rankSql} */`,
+        addedParams: 1
+    };
+};
+
+/**
+ * Full-text search filter builder options
+ */
+export const fullTextSearchOptions: FilterBuilderOptions = {
+    supportsLateral: true, // Full-text search works well with LATERAL joins
+    requiresIndex: true,   // Benefits greatly from GIN indexes on tsvector columns
+    complexityScore: 3,    // Moderate complexity due to text processing
+    validate: validateFullTextFilter
+};
+
+/**
+ * Full-text search with ranking options
+ */
+export const fullTextSearchWithRankOptions: FilterBuilderOptions = {
+    supportsLateral: true,
+    requiresIndex: true,
+    complexityScore: 4, // Higher complexity due to ranking calculation
+    validate: validateFullTextFilter
+};
+
+/**
+ * Helper function to create a full-text search filter with custom options
+ *
+ * @param language - Text search language (defaults to 'english')
+ * @param searchType - Search type ('plain', 'phrase', 'web', 'tsquery')
+ * @returns Configured filter builder and options
+ */
+export function createFullTextSearchBuilder(
+    language: string = 'english',
+    searchType: 'plain' | 'phrase' | 'web' | 'tsquery' = 'plain'
+): { builder: FilterBuilder; options: FilterBuilderOptions } {
+    const builder: FilterBuilder = (filter: QueryFilter, alias: string, context: QueryContext) => {
+        const value = filter.value as FullTextFilterValue;
+        const query = value.query;
+
+        // Build the text search vector from the specified field
+        const fieldPath = filter.field.includes('.')
+            ? filter.field.split('.').map(p => `'${p}'`).join('->')
+            : `'${filter.field}'`;
+
+        const vectorSql = `to_tsvector('${language}', ${alias}.data->${fieldPath})`;
+
+        // Choose the appropriate query function based on type
+        let queryFunction: string;
+        switch (searchType) {
+            case 'phrase':
+                queryFunction = 'phraseto_tsquery';
+                break;
+            case 'web':
+                queryFunction = 'websearch_to_tsquery';
+                break;
+            case 'tsquery':
+                queryFunction = 'to_tsquery';
+                break;
+            case 'plain':
+            default:
+                queryFunction = 'plainto_tsquery';
+                break;
+        }
+
+        const querySql = `${queryFunction}('${language}', $${context.addParam(query)})`;
+
+        return {
+            sql: `${vectorSql} @@ ${querySql}`,
+            addedParams: 1
+        };
+    };
+
+    return {
+        builder,
+        options: {
+            supportsLateral: true,
+            requiresIndex: true,
+            complexityScore: 3,
+            validate: validateFullTextFilter
+        }
+    };
+}

package/query/index.ts

@@ -0,0 +1,21 @@
+export { QueryContext } from "./QueryContext";
+export { QueryNode, type QueryResult } from "./QueryNode";
+export { SourceNode } from "./SourceNode";
+export { ComponentInclusionNode } from "./ComponentInclusionNode";
+export { QueryDAG } from "./QueryDAG";
+export { OrQuery } from "./OrQuery";
+export { OrNode } from "./OrNode";
+export { Query, or } from "./Query";
+
+export type FilterSchema<T = any> = {
+    [K in keyof T]?: {
+        field: string;
+        op: string;
+        value: string;
+    } | undefined;
+}
+
+// Custom Filter Builder exports
+export type { FilterBuilder, FilterResult, FilterBuilderOptions } from "./FilterBuilder";
+export { buildJSONPath } from "./FilterBuilder";
+export { FilterBuilderRegistry } from "./FilterBuilderRegistry";