@push.rocks/smartmongo 3.0.0 → 4.0.0

package/ts/tsmdb/engine/QueryPlanner.ts

@@ -0,0 +1,393 @@
+import * as plugins from '../tsmdb.plugins.js';
+import type { Document, IStoredDocument } 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;
+}
+
+/**
+ * Filter operator analysis
+ */
+interface IFilterOperatorInfo {
+  field: string;
+  operators: string[];
+  equality: boolean;
+  range: boolean;
+  in: boolean;
+  exists: boolean;
+  regex: boolean;
+  values: Record<string, any>;
+}
+
+/**
+ * QueryPlanner - Analyzes queries and selects optimal execution plans
+ */
+export class QueryPlanner {
+  private indexEngine: IndexEngine;
+
+  constructor(indexEngine: IndexEngine) {
+    this.indexEngine = indexEngine;
+  }
+
+  /**
+   * Generate an execution plan for a query filter
+   */
+  async plan(filter: Document): Promise<IQueryPlan> {
+    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: IQueryPlan | null = 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
+   */
+  private analyzeFilter(filter: Document, prefix = ''): Map<string, IFilterOperatorInfo> {
+    const result = new Map<string, IFilterOperatorInfo>();
+
+    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: IFilterOperatorInfo = {
+        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
+   */
+  private scoreIndex(
+    index: { name: string; key: Record<string, any>; unique?: boolean; sparse?: boolean },
+    operatorInfo: Map<string, IFilterOperatorInfo>,
+    filter: Document
+  ): IQueryPlan {
+    const indexFields = Object.keys(index.key);
+    const usedFields: string[] = [];
+    let usesRange = false;
+    let canUseIndex = true;
+    let selectivity = 1.0;
+    let residualFilter: Document | undefined;
+
+    // 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: Record<string, any> = {};
+    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)
+   */
+  private calculateScore(plan: IQueryPlan): number {
+    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: Document): Promise<{
+    queryPlanner: {
+      plannerVersion: number;
+      namespace: string;
+      indexFilterSet: boolean;
+      winningPlan: IQueryPlan;
+      rejectedPlans: IQueryPlan[];
+    };
+  }> {
+    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: IQueryPlan[] = [];
+
+    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),
+      },
+    };
+  }
+}

package/ts/tsmdb/engine/SessionEngine.ts

@@ -0,0 +1,292 @@
+import * as plugins from '../tsmdb.plugins.js';
+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 class SessionEngine {
+  private sessions: Map<string, ISession> = new Map();
+  private sessionTimeoutMs: number;
+  private cleanupInterval?: ReturnType<typeof setInterval>;
+  private transactionEngine?: TransactionEngine;
+
+  constructor(options?: ISessionEngineOptions) {
+    this.sessionTimeoutMs = options?.sessionTimeoutMs ?? 30 * 60 * 1000; // 30 minutes default
+    const cleanupIntervalMs = options?.cleanupIntervalMs ?? 60 * 1000; // 1 minute default
+
+    // Start cleanup interval
+    this.cleanupInterval = setInterval(() => {
+      this.cleanupExpiredSessions();
+    }, cleanupIntervalMs);
+  }
+
+  /**
+   * Set the transaction engine to use for auto-abort
+   */
+  setTransactionEngine(engine: TransactionEngine): void {
+    this.transactionEngine = engine;
+  }
+
+  /**
+   * Start a new session
+   */
+  startSession(sessionId?: string, metadata?: Record<string, any>): ISession {
+    const id = sessionId ?? new plugins.bson.UUID().toHexString();
+    const now = Date.now();
+
+    const session: ISession = {
+      id,
+      createdAt: now,
+      lastActivityAt: now,
+      inTransaction: false,
+      metadata,
+    };
+
+    this.sessions.set(id, session);
+    return session;
+  }
+
+  /**
+   * Get a session by ID
+   */
+  getSession(sessionId: string): ISession | undefined {
+    const session = this.sessions.get(sessionId);
+    if (session && this.isSessionExpired(session)) {
+      // Session expired, clean it up
+      this.endSession(sessionId);
+      return undefined;
+    }
+    return session;
+  }
+
+  /**
+   * Touch a session to update last activity time
+   */
+  touchSession(sessionId: string): boolean {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+
+    if (this.isSessionExpired(session)) {
+      this.endSession(sessionId);
+      return false;
+    }
+
+    session.lastActivityAt = Date.now();
+    return true;
+  }
+
+  /**
+   * End a session explicitly
+   * This will also abort any active transaction
+   */
+  async endSession(sessionId: string): Promise<boolean> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+
+    // If session has an active transaction, abort it
+    if (session.inTransaction && session.txnId && this.transactionEngine) {
+      try {
+        await this.transactionEngine.abortTransaction(session.txnId);
+      } catch (e) {
+        // Ignore abort errors during cleanup
+      }
+    }
+
+    this.sessions.delete(sessionId);
+    return true;
+  }
+
+  /**
+   * Start a transaction in a session
+   */
+  startTransaction(sessionId: string, txnId: string, txnNumber?: number): boolean {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+
+    if (this.isSessionExpired(session)) {
+      this.endSession(sessionId);
+      return false;
+    }
+
+    session.txnId = txnId;
+    session.txnNumber = txnNumber;
+    session.inTransaction = true;
+    session.lastActivityAt = Date.now();
+
+    return true;
+  }
+
+  /**
+   * End a transaction in a session (commit or abort)
+   */
+  endTransaction(sessionId: string): boolean {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+
+    session.txnId = undefined;
+    session.txnNumber = undefined;
+    session.inTransaction = false;
+    session.lastActivityAt = Date.now();
+
+    return true;
+  }
+
+  /**
+   * Get transaction ID for a session
+   */
+  getTransactionId(sessionId: string): string | undefined {
+    const session = this.sessions.get(sessionId);
+    return session?.txnId;
+  }
+
+  /**
+   * Check if session is in a transaction
+   */
+  isInTransaction(sessionId: string): boolean {
+    const session = this.sessions.get(sessionId);
+    return session?.inTransaction ?? false;
+  }
+
+  /**
+   * Check if a session is expired
+   */
+  isSessionExpired(session: ISession): boolean {
+    return Date.now() - session.lastActivityAt > this.sessionTimeoutMs;
+  }
+
+  /**
+   * Cleanup expired sessions
+   * This is called periodically by the cleanup interval
+   */
+  private async cleanupExpiredSessions(): Promise<void> {
+    const expiredSessions: string[] = [];
+
+    for (const [id, session] of this.sessions) {
+      if (this.isSessionExpired(session)) {
+        expiredSessions.push(id);
+      }
+    }
+
+    // End all expired sessions (this will also abort their transactions)
+    for (const sessionId of expiredSessions) {
+      await this.endSession(sessionId);
+    }
+  }
+
+  /**
+   * Get all active sessions
+   */
+  listSessions(): ISession[] {
+    const activeSessions: ISession[] = [];
+    for (const session of this.sessions.values()) {
+      if (!this.isSessionExpired(session)) {
+        activeSessions.push(session);
+      }
+    }
+    return activeSessions;
+  }
+
+  /**
+   * Get session count
+   */
+  getSessionCount(): number {
+    return this.sessions.size;
+  }
+
+  /**
+   * Get sessions with active transactions
+   */
+  getSessionsWithTransactions(): ISession[] {
+    return this.listSessions().filter(s => s.inTransaction);
+  }
+
+  /**
+   * Refresh session timeout
+   */
+  refreshSession(sessionId: string): boolean {
+    return this.touchSession(sessionId);
+  }
+
+  /**
+   * Close the session engine and cleanup
+   */
+  close(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = undefined;
+    }
+
+    // Clear all sessions
+    this.sessions.clear();
+  }
+
+  /**
+   * Get or create a session for a given session ID
+   * Useful for handling MongoDB driver session requests
+   */
+  getOrCreateSession(sessionId: string): ISession {
+    let session = this.getSession(sessionId);
+    if (!session) {
+      session = this.startSession(sessionId);
+    } else {
+      this.touchSession(sessionId);
+    }
+    return session;
+  }
+
+  /**
+   * Extract session ID from MongoDB lsid (logical session ID)
+   */
+  static extractSessionId(lsid: any): string | undefined {
+    if (!lsid) return undefined;
+
+    // MongoDB session ID format: { id: UUID }
+    if (lsid.id) {
+      if (lsid.id instanceof plugins.bson.UUID) {
+        return lsid.id.toHexString();
+      }
+      if (typeof lsid.id === 'string') {
+        return lsid.id;
+      }
+      if (lsid.id.$binary?.base64) {
+        // Binary UUID format
+        return Buffer.from(lsid.id.$binary.base64, 'base64').toString('hex');
+      }
+    }
+
+    return undefined;
+  }
+}

package/ts/tsmdb/index.ts

@@ -19,6 +19,8 @@ export type { IStorageAdapter } from './storage/IStorageAdapter.js';
 export { MemoryStorageAdapter } from './storage/MemoryStorageAdapter.js';
 export { FileStorageAdapter } from './storage/FileStorageAdapter.js';
 export { OpLog } from './storage/OpLog.js';
+export { WAL } from './storage/WAL.js';
+export type { IWalEntry, TWalOperation } from './storage/WAL.js';
 
 // Export engines
 export { QueryEngine } from './engine/QueryEngine.js';
@@ -26,6 +28,10 @@ export { UpdateEngine } from './engine/UpdateEngine.js';
 export { AggregationEngine } from './engine/AggregationEngine.js';
 export { IndexEngine } from './engine/IndexEngine.js';
 export { TransactionEngine } from './engine/TransactionEngine.js';
+export { QueryPlanner } from './engine/QueryPlanner.js';
+export type { IQueryPlan, TQueryPlanType } from './engine/QueryPlanner.js';
+export { SessionEngine } from './engine/SessionEngine.js';
+export type { ISession, ISessionEngineOptions } from './engine/SessionEngine.js';
 
 // Export server (the main entry point for using TsmDB)
 export { TsmdbServer } from './server/TsmdbServer.js';
@@ -35,3 +41,6 @@ export type { ITsmdbServerOptions } from './server/TsmdbServer.js';
 export { WireProtocol } from './server/WireProtocol.js';
 export { CommandRouter } from './server/CommandRouter.js';
 export type { ICommandHandler, IHandlerContext, ICursorState } from './server/CommandRouter.js';
+
+// Export utilities
+export * from './utils/checksum.js';