@undefineds.co/xpod 0.3.74 → 0.4.0-rc.139

package/dist/storage/sparql/QuintEngine.js

@@ -1,150 +0,0 @@
-"use strict";
-/**
- * QuintEngine - Configurable SPARQL engine backed by QuintStore
- *
- * Store type (SQLite/PostgreSQL) determined by endpoint scheme.
- *
- * Usage:
- * ```json
- * {
- *   "@type": "QuintEngine",
- *   "endpoint": "postgresql://user:pass@localhost/db"
- * }
- * ```
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.QuintEngine = void 0;
-const SqliteQuintStore_1 = require("../quint/SqliteQuintStore");
-const PgQuintStore_1 = require("../quint/PgQuintStore");
-const ComunicaQuintEngine_1 = require("./ComunicaQuintEngine");
-/**
- * QuintEngine - Injectable SPARQL engine with configurable backend
- *
- * This class provides a unified interface for SPARQL queries backed by
- * either SQLite or PostgreSQL QuintStore implementations.
- */
-class QuintEngine {
-    constructor(args) {
-        this.isOpen = false;
-        const { storeType, connectionString } = this.parseEndpoint(args.endpoint);
-        this.storeType = storeType;
-        // Create appropriate store based on scheme
-        if (storeType === 'postgresql') {
-            this.store = new PgQuintStore_1.PgQuintStore({
-                connectionString,
-            });
-        }
-        else {
-            this.store = new SqliteQuintStore_1.SqliteQuintStore({
-                path: connectionString,
-            });
-        }
-        this.engine = new ComunicaQuintEngine_1.ComunicaQuintEngine(this.store, {
-            debug: args.debug,
-        });
-    }
-    /**
-     * Parse endpoint string to extract store type and connection string
-     *
-     * Formats:
-     * - sqlite:/path/to/db -> SQLite with file path
-     * - sqlite::memory: -> SQLite in-memory
-     * - postgresql://user:pass@host/db -> PostgreSQL
-     * - postgres://user:pass@host/db -> PostgreSQL (alias)
-     */
-    parseEndpoint(endpoint) {
-        if (endpoint.startsWith('sqlite:')) {
-            // sqlite:/path/to/db or sqlite::memory:
-            const path = endpoint.slice('sqlite:'.length);
-            return {
-                storeType: 'sqlite',
-                connectionString: path || ':memory:',
-            };
-        }
-        if (endpoint.startsWith('postgresql://') || endpoint.startsWith('postgres://')) {
-            return {
-                storeType: 'postgresql',
-                connectionString: endpoint,
-            };
-        }
-        // Default: treat as SQLite file path for backward compatibility
-        return {
-            storeType: 'sqlite',
-            connectionString: endpoint,
-        };
-    }
-    /**
-     * Open the underlying store connection
-     */
-    async open() {
-        if (!this.isOpen) {
-            await this.store.open();
-            this.isOpen = true;
-        }
-    }
-    /**
-     * Close the store connection
-     */
-    async close() {
-        if (this.isOpen) {
-            await this.store.close();
-            this.isOpen = false;
-        }
-    }
-    /**
-     * Ensure store is open, auto-open if needed
-     */
-    async ensureOpen() {
-        if (!this.isOpen) {
-            await this.open();
-        }
-    }
-    /**
-     * Execute SELECT query
-     */
-    async queryBindings(query, context) {
-        await this.ensureOpen();
-        return this.engine.queryBindings(query, context);
-    }
-    /**
-     * Execute ASK query
-     */
-    async queryBoolean(query, context) {
-        await this.ensureOpen();
-        return this.engine.queryBoolean(query, context);
-    }
-    /**
-     * Execute CONSTRUCT/DESCRIBE query
-     */
-    async queryQuads(query, context) {
-        await this.ensureOpen();
-        return this.engine.queryQuads(query, context);
-    }
-    /**
-     * Execute UPDATE query (INSERT/DELETE)
-     */
-    async queryVoid(query, context) {
-        await this.ensureOpen();
-        return this.engine.queryVoid(query, context);
-    }
-    /**
-     * Get the underlying QuintStore for direct operations
-     */
-    getStore() {
-        return this.store;
-    }
-    /**
-     * Get the underlying ComunicaQuintEngine
-     */
-    getEngine() {
-        return this.engine;
-    }
-    /**
-     * Get the store type
-     */
-    getStoreType() {
-        return this.storeType;
-    }
-}
-exports.QuintEngine = QuintEngine;
-//# sourceMappingURL=QuintEngine.js.map

package/dist/storage/sparql/QuintQuerySource.d.ts

@@ -1,241 +0,0 @@
-/**
- * QuintQuerySource - IQuerySource implementation for QuintStore
- *
- * This implements Comunica's IQuerySource interface to enable proper FILTER pushdown.
- * Unlike RDF.Store.match() which only receives 4 terms, IQuerySource.queryBindings()
- * receives the full SPARQL algebra including FILTER expressions.
- *
- * Design:
- * - Delegates filter extraction to FilterPushdownExtractor
- * - Delegates pattern building to PatternBuilder
- * - Delegates in-memory evaluation to ExpressionEvaluator
- * - Coordinates these components to execute queries efficiently
- */
-import type { Quad, Variable, Bindings } from '@rdfjs/types';
-import type { AsyncIterator } from 'asynciterator';
-import { Algebra } from 'sparqlalgebrajs';
-import type { QuintStore, TermName } from '../quint/types';
-import type { SecurityFilters } from './ComunicaQuintEngine';
-export interface IActionContext {
-    get<V>(key: {
-        name: string;
-    }): V | undefined;
-    getSafe<V>(key: {
-        name: string;
-    }): V;
-    has(key: {
-        name: string;
-    }): boolean;
-}
-export interface FragmentSelectorShape {
-    type: 'operation' | 'conjunction' | 'disjunction' | 'negation' | 'arity';
-    operation?: {
-        operationType: 'type' | 'pattern' | 'wildcard';
-        type?: string;
-        pattern?: Algebra.Operation;
-    };
-    children?: FragmentSelectorShape[];
-    child?: FragmentSelectorShape;
-    variablesOptional?: Variable[];
-    joinBindings?: true;
-    filterBindings?: true;
-    min?: number;
-    max?: number;
-}
-export interface BindingsStream extends AsyncIterator<Bindings> {
-}
-export interface IQueryBindingsOptions {
-    joinBindings?: {
-        bindings: BindingsStream;
-        metadata: unknown;
-    };
-    filterBindings?: {
-        bindings: BindingsStream;
-        metadata: unknown;
-    };
-}
-export interface MetadataValidationState {
-}
-/**
- * IQuerySource interface compatible with Comunica
- */
-export interface IQuerySource {
-    referenceValue: unknown;
-    getSelectorShape(context: IActionContext): Promise<FragmentSelectorShape>;
-    queryBindings(operation: Algebra.Operation, context: IActionContext, options?: IQueryBindingsOptions): BindingsStream;
-    queryQuads(operation: Algebra.Operation, context: IActionContext): AsyncIterator<Quad>;
-    queryBoolean(operation: Algebra.Ask, context: IActionContext): Promise<boolean>;
-    queryVoid(operation: Algebra.Update, context: IActionContext): Promise<void>;
-    toString(): string;
-}
-interface OptimizeParams {
-    limit?: number;
-    offset?: number;
-    order?: TermName[];
-    /** 原始 ORDER BY 变量名，用于分析绑定位置 */
-    orderVarName?: string;
-    reverse?: boolean;
-}
-/**
- * QuintQuerySource implements IQuerySource for QuintStore
- *
- * Key features:
- * 1. Declares support for FILTER operations via getSelectorShape()
- * 2. Receives full SPARQL algebra in queryBindings() including FILTERs
- * 3. Extracts filter conditions and pushes them down to QuintStore
- * 4. Applies security filters (ACL) unconditionally
- * 5. Tree-based evaluation for remaining non-pushdownable expressions
- */
-export declare class QuintQuerySource implements IQuerySource {
-    readonly referenceValue: unknown;
-    private readonly store;
-    private readonly debug;
-    private readonly bindingsFactory;
-    private readonly getSecurityFilters;
-    private readonly getOptimizeParams;
-    private readonly getFilterExpression;
-    private readonly filterExtractor;
-    private readonly patternBuilder;
-    private readonly expressionEvaluator;
-    constructor(store: QuintStore, options: {
-        debug?: boolean;
-        bindingsFactory: any;
-        getSecurityFilters: () => SecurityFilters | undefined;
-        getOptimizeParams: () => OptimizeParams | null;
-        getFilterExpression?: (varName: string) => Algebra.Expression | undefined;
-    });
-    /**
-     * Declare the operations this source supports
-     *
-     * We support:
-     * - Basic quad patterns (for simple queries)
-     * - FILTER operations (for filter pushdown)
-     * - BGP operations (for multi-pattern queries)
-     * - joinBindings: allows Comunica to push JOIN operations down to us
-     *
-     * The joinBindings support enables ActorRdfJoinMultiBindSource to push
-     * multiple patterns to us efficiently, using SQL JOINs instead of
-     * Comunica's nested loop approach.
-     */
-    getSelectorShape(_context: IActionContext): Promise<FragmentSelectorShape>;
-    /**
-     * Query bindings - main entry point for SPARQL queries
-     *
-     * When Comunica's ActorRdfJoinMultiBindSource selects us for a join operation,
-     * it passes options.joinBindings containing bindings from the first pattern.
-     * We need to use these bindings to filter our query results efficiently.
-     */
-    queryBindings(operation: Algebra.Operation, _context: IActionContext, options?: IQueryBindingsOptions): BindingsStream;
-    /**
-     * Execute query and return bindings
-     *
-     * If options.joinBindings is provided, we need to:
-     * 1. Collect bindings from the stream (these are from the first pattern in the JOIN)
-     * 2. Extract variable values that overlap with our patterns
-     * 3. Use those values as IN conditions in our query
-     * 4. JOIN the results with the incoming bindings
-     */
-    private executeQuery;
-    /**
-     * Execute a bind join: use incoming bindings to filter our query
-     *
-     * This is called when Comunica's ActorRdfJoinMultiBindSource pushes bindings to us.
-     * We use SQL IN clause to efficiently query only the rows matching the incoming bindings.
-     */
-    private executeBindJoin;
-    /**
-     * Execute bind join for a single pattern using IN filter
-     */
-    private executeBindJoinSimple;
-    /**
-     * Execute bind join for multiple patterns using compound query
-     */
-    private executeBindJoinCompound;
-    /**
-     * Hash join two binding sets on a common variable
-     */
-    private hashJoin;
-    /**
-     * Merge two bindings, returning null if they conflict
-     */
-    private mergeBindings;
-    /**
-     * Cartesian product of two binding sets
-     */
-    private cartesianJoin;
-    /**
-     * Execute OR branches with union semantics
-     */
-    private executeOrBranches;
-    /**
-     * Try to execute a compound query for multiple patterns joined by same subject
-     * Returns null if compound query is not applicable
-     */
-    private tryCompoundQuery;
-    /**
-     * Execute multiple patterns individually and hash-join results on shared variables.
-     * Used when compound query is not applicable (e.g. inverse patterns with different subject vars).
-     */
-    private executeMultiPatternJoin;
-    /**
-     * Extract simple equality bindings from a FILTER expression.
-     * E.g. FILTER(?subject = <uri>) -> { subject: "uri" }
-     */
-    private extractFilterBindings;
-    /**
-     * Hash-join two binding arrays on all shared variables.
-     */
-    private hashJoinBindings;
-    /**
-     * Distribute filter conditions to their respective patterns
-     * Returns a map of pattern index -> PushdownFilters
-     */
-    private distributeFiltersToPatterns;
-    /**
-     * Build SELECT clause config for patterns
-     */
-    private buildSelectForPatterns;
-    /**
-     * Convert CompoundResult array to Bindings array
-     */
-    private compoundResultsToBindings;
-    /**
-     * Deserialize a value from storage format to RDF Term
-     * Uses the same deserialization logic as QuintStore
-     */
-    private deserializeValue;
-    /**
-     * Convert quads to bindings based on pattern variables
-     */
-    private quadsToBindings;
-    /**
-     * Get the term from quad that matches the variable position in pattern
-     */
-    private getTermForVariable;
-    /**
-     * Extract BGP pattern and filter from operation
-     * Returns either a single pattern or multiple patterns (from BGP or JOIN)
-     */
-    extractPatternAndFilter(operation: Algebra.Operation): {
-        pattern: Algebra.Pattern;
-        patterns?: Algebra.Pattern[];
-        filter: Algebra.Expression | null;
-    };
-    /**
-     * Get variables from operation
-     */
-    private getVariablesFromOperation;
-    queryQuads(operation: Algebra.Operation, _context: IActionContext): AsyncIterator<Quad>;
-    queryBoolean(operation: Algebra.Ask, _context: IActionContext): Promise<boolean>;
-    queryVoid(_operation: Algebra.Update, _context: IActionContext): Promise<void>;
-    /**
-     * 在 pattern 中查找变量绑定到哪个位置
-     *
-     * 例如：{ ?s <http://schema.org/name> ?name }
-     * - ?s 绑定到 subject
-     * - ?name 绑定到 object
-     */
-    private findVariableBinding;
-    toString(): string;
-}
-export {};