@push.rocks/smartmongo 3.0.0 → 4.0.0

package/dist_ts/tsmdb/engine/QueryPlanner.d.ts

@@ -0,0 +1,64 @@
+import type { Document } from '../types/interfaces.js';
+import { IndexEngine } from './IndexEngine.js';
+/**
+ * Query execution plan types
+ */
+export type TQueryPlanType = 'IXSCAN' | 'COLLSCAN' | 'FETCH' | 'IXSCAN_RANGE';
+/**
+ * Represents a query execution plan
+ */
+export interface IQueryPlan {
+    /** The type of scan used */
+    type: TQueryPlanType;
+    /** Index name if using an index */
+    indexName?: string;
+    /** Index key specification */
+    indexKey?: Record<string, 1 | -1 | string>;
+    /** Whether the query can be fully satisfied by the index */
+    indexCovering: boolean;
+    /** Estimated selectivity (0-1, lower is more selective) */
+    selectivity: number;
+    /** Whether range operators are used */
+    usesRange: boolean;
+    /** Fields used from the index */
+    indexFieldsUsed: string[];
+    /** Filter conditions that must be applied post-index lookup */
+    residualFilter?: Document;
+    /** Explanation for debugging */
+    explanation: string;
+}
+/**
+ * QueryPlanner - Analyzes queries and selects optimal execution plans
+ */
+export declare class QueryPlanner {
+    private indexEngine;
+    constructor(indexEngine: IndexEngine);
+    /**
+     * Generate an execution plan for a query filter
+     */
+    plan(filter: Document): Promise<IQueryPlan>;
+    /**
+     * Analyze filter to extract operator information per field
+     */
+    private analyzeFilter;
+    /**
+     * Score an index for the given filter
+     */
+    private scoreIndex;
+    /**
+     * Calculate overall score for a plan (higher is better)
+     */
+    private calculateScore;
+    /**
+     * Explain a query - returns detailed plan information
+     */
+    explain(filter: Document): Promise<{
+        queryPlanner: {
+            plannerVersion: number;
+            namespace: string;
+            indexFilterSet: boolean;
+            winningPlan: IQueryPlan;
+            rejectedPlans: IQueryPlan[];
+        };
+    }>;
+}

package/dist_ts/tsmdb/engine/QueryPlanner.js

@@ -0,0 +1,308 @@
+import * as plugins from '../tsmdb.plugins.js';
+import { IndexEngine } from './IndexEngine.js';
+/**
+ * QueryPlanner - Analyzes queries and selects optimal execution plans
+ */
+export class QueryPlanner {
+    indexEngine;
+    constructor(indexEngine) {
+        this.indexEngine = indexEngine;
+    }
+    /**
+     * Generate an execution plan for a query filter
+     */
+    async plan(filter) {
+        await this.indexEngine['initialize']();
+        // Empty filter = full collection scan
+        if (!filter || Object.keys(filter).length === 0) {
+            return {
+                type: 'COLLSCAN',
+                indexCovering: false,
+                selectivity: 1.0,
+                usesRange: false,
+                indexFieldsUsed: [],
+                explanation: 'No filter specified, full collection scan required',
+            };
+        }
+        // Analyze the filter
+        const operatorInfo = this.analyzeFilter(filter);
+        // Get available indexes
+        const indexes = await this.indexEngine.listIndexes();
+        // Score each index
+        let bestPlan = null;
+        let bestScore = -1;
+        for (const index of indexes) {
+            const plan = this.scoreIndex(index, operatorInfo, filter);
+            if (plan.selectivity < 1.0) {
+                const score = this.calculateScore(plan);
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestPlan = plan;
+                }
+            }
+        }
+        // If no suitable index found, fall back to collection scan
+        if (!bestPlan || bestScore <= 0) {
+            return {
+                type: 'COLLSCAN',
+                indexCovering: false,
+                selectivity: 1.0,
+                usesRange: false,
+                indexFieldsUsed: [],
+                explanation: 'No suitable index found for this query',
+            };
+        }
+        return bestPlan;
+    }
+    /**
+     * Analyze filter to extract operator information per field
+     */
+    analyzeFilter(filter, prefix = '') {
+        const result = new Map();
+        for (const [key, value] of Object.entries(filter)) {
+            // Skip logical operators at the top level
+            if (key.startsWith('$')) {
+                if (key === '$and' && Array.isArray(value)) {
+                    // Merge $and conditions
+                    for (const subFilter of value) {
+                        const subInfo = this.analyzeFilter(subFilter, prefix);
+                        for (const [field, info] of subInfo) {
+                            if (result.has(field)) {
+                                // Merge operators
+                                const existing = result.get(field);
+                                existing.operators.push(...info.operators);
+                                existing.equality = existing.equality || info.equality;
+                                existing.range = existing.range || info.range;
+                                existing.in = existing.in || info.in;
+                                Object.assign(existing.values, info.values);
+                            }
+                            else {
+                                result.set(field, info);
+                            }
+                        }
+                    }
+                }
+                continue;
+            }
+            const fullKey = prefix ? `${prefix}.${key}` : key;
+            const info = {
+                field: fullKey,
+                operators: [],
+                equality: false,
+                range: false,
+                in: false,
+                exists: false,
+                regex: false,
+                values: {},
+            };
+            if (typeof value !== 'object' || value === null || value instanceof plugins.bson.ObjectId || value instanceof Date) {
+                // Direct equality
+                info.equality = true;
+                info.operators.push('$eq');
+                info.values['$eq'] = value;
+            }
+            else if (Array.isArray(value)) {
+                // Array equality (rare, but possible)
+                info.equality = true;
+                info.operators.push('$eq');
+                info.values['$eq'] = value;
+            }
+            else {
+                // Operator object
+                for (const [op, opValue] of Object.entries(value)) {
+                    if (op.startsWith('$')) {
+                        info.operators.push(op);
+                        info.values[op] = opValue;
+                        switch (op) {
+                            case '$eq':
+                                info.equality = true;
+                                break;
+                            case '$ne':
+                            case '$not':
+                                // These can use indexes but with low selectivity
+                                break;
+                            case '$in':
+                                info.in = true;
+                                break;
+                            case '$nin':
+                                // Can't efficiently use indexes
+                                break;
+                            case '$gt':
+                            case '$gte':
+                            case '$lt':
+                            case '$lte':
+                                info.range = true;
+                                break;
+                            case '$exists':
+                                info.exists = true;
+                                break;
+                            case '$regex':
+                                info.regex = true;
+                                break;
+                        }
+                    }
+                    else {
+                        // Nested object - recurse
+                        const nestedInfo = this.analyzeFilter({ [op]: opValue }, fullKey);
+                        for (const [nestedField, nestedFieldInfo] of nestedInfo) {
+                            result.set(nestedField, nestedFieldInfo);
+                        }
+                    }
+                }
+            }
+            if (info.operators.length > 0) {
+                result.set(fullKey, info);
+            }
+        }
+        return result;
+    }
+    /**
+     * Score an index for the given filter
+     */
+    scoreIndex(index, operatorInfo, filter) {
+        const indexFields = Object.keys(index.key);
+        const usedFields = [];
+        let usesRange = false;
+        let canUseIndex = true;
+        let selectivity = 1.0;
+        let residualFilter;
+        // Check each index field in order
+        for (const field of indexFields) {
+            const info = operatorInfo.get(field);
+            if (!info) {
+                // Index field not in filter - stop here
+                break;
+            }
+            usedFields.push(field);
+            // Calculate selectivity based on operator
+            if (info.equality) {
+                // Equality has high selectivity
+                selectivity *= 0.01; // Assume 1% match
+            }
+            else if (info.in) {
+                // $in selectivity depends on array size
+                const inValues = info.values['$in'];
+                if (Array.isArray(inValues)) {
+                    selectivity *= Math.min(0.5, inValues.length * 0.01);
+                }
+                else {
+                    selectivity *= 0.1;
+                }
+            }
+            else if (info.range) {
+                // Range queries have moderate selectivity
+                selectivity *= 0.25;
+                usesRange = true;
+                // After range, can't use more index fields efficiently
+                break;
+            }
+            else if (info.exists) {
+                // $exists can use sparse indexes
+                selectivity *= 0.5;
+            }
+            else {
+                // Other operators may not be indexable
+                canUseIndex = false;
+                break;
+            }
+        }
+        if (!canUseIndex || usedFields.length === 0) {
+            return {
+                type: 'COLLSCAN',
+                indexCovering: false,
+                selectivity: 1.0,
+                usesRange: false,
+                indexFieldsUsed: [],
+                explanation: `Index ${index.name} cannot be used for this query`,
+            };
+        }
+        // Build residual filter for conditions not covered by index
+        const coveredFields = new Set(usedFields);
+        const residualConditions = {};
+        for (const [field, info] of operatorInfo) {
+            if (!coveredFields.has(field)) {
+                // This field isn't covered by the index
+                if (info.equality) {
+                    residualConditions[field] = info.values['$eq'];
+                }
+                else {
+                    residualConditions[field] = info.values;
+                }
+            }
+        }
+        if (Object.keys(residualConditions).length > 0) {
+            residualFilter = residualConditions;
+        }
+        // Unique indexes have better selectivity for equality
+        if (index.unique && usedFields.length === indexFields.length) {
+            selectivity = Math.min(selectivity, 0.001); // At most 1 document
+        }
+        return {
+            type: usesRange ? 'IXSCAN_RANGE' : 'IXSCAN',
+            indexName: index.name,
+            indexKey: index.key,
+            indexCovering: Object.keys(residualConditions).length === 0,
+            selectivity,
+            usesRange,
+            indexFieldsUsed: usedFields,
+            residualFilter,
+            explanation: `Using index ${index.name} on fields [${usedFields.join(', ')}]`,
+        };
+    }
+    /**
+     * Calculate overall score for a plan (higher is better)
+     */
+    calculateScore(plan) {
+        let score = 0;
+        // Lower selectivity is better (fewer documents to fetch)
+        score += (1 - plan.selectivity) * 100;
+        // Index covering queries are best
+        if (plan.indexCovering) {
+            score += 50;
+        }
+        // More index fields used is better
+        score += plan.indexFieldsUsed.length * 10;
+        // Equality scans are better than range scans
+        if (!plan.usesRange) {
+            score += 20;
+        }
+        return score;
+    }
+    /**
+     * Explain a query - returns detailed plan information
+     */
+    async explain(filter) {
+        await this.indexEngine['initialize']();
+        // Analyze the filter
+        const operatorInfo = this.analyzeFilter(filter);
+        // Get available indexes
+        const indexes = await this.indexEngine.listIndexes();
+        // Score all indexes
+        const plans = [];
+        for (const index of indexes) {
+            const plan = this.scoreIndex(index, operatorInfo, filter);
+            plans.push(plan);
+        }
+        // Add collection scan as fallback
+        plans.push({
+            type: 'COLLSCAN',
+            indexCovering: false,
+            selectivity: 1.0,
+            usesRange: false,
+            indexFieldsUsed: [],
+            explanation: 'Full collection scan',
+        });
+        // Sort by score (best first)
+        plans.sort((a, b) => this.calculateScore(b) - this.calculateScore(a));
+        return {
+            queryPlanner: {
+                plannerVersion: 1,
+                namespace: `${this.indexEngine['dbName']}.${this.indexEngine['collName']}`,
+                indexFilterSet: false,
+                winningPlan: plans[0],
+                rejectedPlans: plans.slice(1),
+            },
+        };
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUXVlcnlQbGFubmVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vdHMvdHNtZGIvZW5naW5lL1F1ZXJ5UGxhbm5lci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLHFCQUFxQixDQUFDO0FBRS9DLE9BQU8sRUFBRSxXQUFXLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQTZDL0M7O0dBRUc7QUFDSCxNQUFNLE9BQU8sWUFBWTtJQUNmLFdBQVcsQ0FBYztJQUVqQyxZQUFZLFdBQXdCO1FBQ2xDLElBQUksQ0FBQyxXQUFXLEdBQUcsV0FBVyxDQUFDO0lBQ2pDLENBQUM7SUFFRDs7T0FFRztJQUNILEtBQUssQ0FBQyxJQUFJLENBQUMsTUFBZ0I7UUFDekIsTUFBTSxJQUFJLENBQUMsV0FBVyxDQUFDLFlBQVksQ0FBQyxFQUFFLENBQUM7UUFFdkMsc0NBQXNDO1FBQ3RDLElBQUksQ0FBQyxNQUFNLElBQUksTUFBTSxDQUFDLElBQUksQ0FBQyxNQUFNLENBQUMsQ0FBQyxNQUFNLEtBQUssQ0FBQyxFQUFFLENBQUM7WUFDaEQsT0FBTztnQkFDTCxJQUFJLEVBQUUsVUFBVTtnQkFDaEIsYUFBYSxFQUFFLEtBQUs7Z0JBQ3BCLFdBQVcsRUFBRSxHQUFHO2dCQUNoQixTQUFTLEVBQUUsS0FBSztnQkFDaEIsZUFBZSxFQUFFLEVBQUU7Z0JBQ25CLFdBQVcsRUFBRSxvREFBb0Q7YUFDbEUsQ0FBQztRQUNKLENBQUM7UUFFRCxxQkFBcUI7UUFDckIsTUFBTSxZQUFZLEdBQUcsSUFBSSxDQUFDLGFBQWEsQ0FBQyxNQUFNLENBQUMsQ0FBQztRQUVoRCx3QkFBd0I7UUFDeEIsTUFBTSxPQUFPLEdBQUcsTUFBTSxJQUFJLENBQUMsV0FBVyxDQUFDLFdBQVcsRUFBRSxDQUFDO1FBRXJELG1CQUFtQjtRQUNuQixJQUFJLFFBQVEsR0FBc0IsSUFBSSxDQUFDO1FBQ3ZDLElBQUksU0FBUyxHQUFHLENBQUMsQ0FBQyxD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

package/dist_ts/tsmdb/engine/SessionEngine.d.ts

@@ -0,0 +1,117 @@
+import type { TransactionEngine } from './TransactionEngine.js';
+/**
+ * Session state
+ */
+export interface ISession {
+    /** Session ID (UUID) */
+    id: string;
+    /** Timestamp when the session was created */
+    createdAt: number;
+    /** Timestamp of the last activity */
+    lastActivityAt: number;
+    /** Current transaction ID if any */
+    txnId?: string;
+    /** Transaction number for ordering */
+    txnNumber?: number;
+    /** Whether the session is in a transaction */
+    inTransaction: boolean;
+    /** Session metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Session engine options
+ */
+export interface ISessionEngineOptions {
+    /** Session timeout in milliseconds (default: 30 minutes) */
+    sessionTimeoutMs?: number;
+    /** Interval to check for expired sessions in ms (default: 60 seconds) */
+    cleanupIntervalMs?: number;
+}
+/**
+ * Session engine for managing client sessions
+ * - Tracks session lifecycle (create, touch, end)
+ * - Links sessions to transactions
+ * - Auto-aborts transactions on session expiry
+ */
+export declare class SessionEngine {
+    private sessions;
+    private sessionTimeoutMs;
+    private cleanupInterval?;
+    private transactionEngine?;
+    constructor(options?: ISessionEngineOptions);
+    /**
+     * Set the transaction engine to use for auto-abort
+     */
+    setTransactionEngine(engine: TransactionEngine): void;
+    /**
+     * Start a new session
+     */
+    startSession(sessionId?: string, metadata?: Record<string, any>): ISession;
+    /**
+     * Get a session by ID
+     */
+    getSession(sessionId: string): ISession | undefined;
+    /**
+     * Touch a session to update last activity time
+     */
+    touchSession(sessionId: string): boolean;
+    /**
+     * End a session explicitly
+     * This will also abort any active transaction
+     */
+    endSession(sessionId: string): Promise<boolean>;
+    /**
+     * Start a transaction in a session
+     */
+    startTransaction(sessionId: string, txnId: string, txnNumber?: number): boolean;
+    /**
+     * End a transaction in a session (commit or abort)
+     */
+    endTransaction(sessionId: string): boolean;
+    /**
+     * Get transaction ID for a session
+     */
+    getTransactionId(sessionId: string): string | undefined;
+    /**
+     * Check if session is in a transaction
+     */
+    isInTransaction(sessionId: string): boolean;
+    /**
+     * Check if a session is expired
+     */
+    isSessionExpired(session: ISession): boolean;
+    /**
+     * Cleanup expired sessions
+     * This is called periodically by the cleanup interval
+     */
+    private cleanupExpiredSessions;
+    /**
+     * Get all active sessions
+     */
+    listSessions(): ISession[];
+    /**
+     * Get session count
+     */
+    getSessionCount(): number;
+    /**
+     * Get sessions with active transactions
+     */
+    getSessionsWithTransactions(): ISession[];
+    /**
+     * Refresh session timeout
+     */
+    refreshSession(sessionId: string): boolean;
+    /**
+     * Close the session engine and cleanup
+     */
+    close(): void;
+    /**
+     * Get or create a session for a given session ID
+     * Useful for handling MongoDB driver session requests
+     */
+    getOrCreateSession(sessionId: string): ISession;
+    /**
+     * Extract session ID from MongoDB lsid (logical session ID)
+     */
+    static extractSessionId(lsid: any): string | undefined;
+}