@framers/sql-storage-adapter 0.7.2 → 0.7.4

package/dist/cjs/adapters/baseStorageAdapter.js

@@ -0,0 +1,744 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var baseStorageAdapter_exports = {};
+__export(baseStorageAdapter_exports, {
+  BaseStorageAdapter: () => BaseStorageAdapter
+});
+module.exports = __toCommonJS(baseStorageAdapter_exports);
+var import_performance = require("../core/contracts/performance.js");
+var import_hooks = require("../core/contracts/hooks.js");
+var import_logger = require("../shared/logger.js");
+var AdapterState;
+(function(AdapterState2) {
+  AdapterState2["CLOSED"] = "closed";
+  AdapterState2["OPENING"] = "opening";
+  AdapterState2["OPEN"] = "open";
+  AdapterState2["CLOSING"] = "closing";
+  AdapterState2["ERROR"] = "error";
+})(AdapterState || (AdapterState = {}));
+class BaseStorageAdapter {
+  /**
+   * Creates a new adapter instance.
+   *
+   * @param options - Configuration options for the adapter
+   *
+   * @example Default balanced tier
+   * ```typescript
+   * const adapter = new MyAdapter();
+   * ```
+   *
+   * @example Fast tier for development
+   * ```typescript
+   * const adapter = new MyAdapter({
+   *   performance: { tier: 'fast' },
+   *   verbose: true
+   * });
+   * ```
+   *
+   * @example With RAG hooks
+   * ```typescript
+   * const adapter = new MyAdapter({
+   *   hooks: {
+   *     onBeforeWrite: async (ctx) => {
+   *       ctx.metadata = { embedding: await embed(ctx.parameters) };
+   *       return ctx;
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  constructor(options = {}) {
+    this.state = AdapterState.CLOSED;
+    this.metrics = {
+      totalQueries: 0,
+      totalMutations: 0,
+      totalTransactions: 0,
+      totalErrors: 0,
+      averageQueryDuration: 0,
+      openedAt: null,
+      slowQueries: 0,
+      retries: 0
+    };
+    this.queryCache = /* @__PURE__ */ new Map();
+    this.cacheStats = {
+      hits: 0,
+      misses: 0,
+      hitRatio: 0,
+      size: 0,
+      bytesUsed: 0,
+      evictions: 0,
+      invalidations: 0
+    };
+    this.queryDurations = [];
+    this.MAX_DURATION_SAMPLES = 100;
+    this.options = options;
+    const perfConfig = options.performance ?? {};
+    const resolvedSettings = (0, import_performance.resolvePerformanceConfig)(perfConfig);
+    if (options.validateSQL !== void 0) {
+      this.performanceSettings = {
+        ...resolvedSettings,
+        validateSql: options.validateSQL
+      };
+    } else {
+      this.performanceSettings = resolvedSettings;
+    }
+    this.hooks = options.hooks ?? {};
+  }
+  // ============================================================================
+  // Public Interface (Template Methods)
+  // ============================================================================
+  /**
+   * Opens the adapter connection.
+   * Handles state management and delegates to subclass implementation.
+   */
+  async open(options) {
+    if (this.state === AdapterState.OPEN) {
+      this.log("Adapter already open, skipping open()");
+      return;
+    }
+    if (this.state === AdapterState.OPENING) {
+      throw new Error(`[${this.kind}] Adapter is already opening`);
+    }
+    this.state = AdapterState.OPENING;
+    try {
+      await this.performOpen(options);
+      this.state = AdapterState.OPEN;
+      this.metrics.openedAt = /* @__PURE__ */ new Date();
+      this.log("Adapter opened successfully");
+    } catch (error) {
+      this.state = AdapterState.ERROR;
+      this.metrics.totalErrors++;
+      throw this.wrapError("Failed to open adapter", error);
+    }
+  }
+  /**
+   * Executes a mutation statement (INSERT, UPDATE, DELETE).
+   *
+   * Invokes `onBeforeWrite` and `onAfterWrite` hooks if configured.
+   * Supports retry on transient errors based on performance tier.
+   */
+  async run(statement, parameters) {
+    this.assertOpen();
+    this.validateStatement(statement);
+    const startTime = Date.now();
+    const operationId = (0, import_hooks.generateOperationId)();
+    let context = {
+      operationId,
+      operation: "run",
+      startTime,
+      adapterKind: this.kind,
+      statement,
+      parameters,
+      affectedTables: this.extractTables(statement)
+    };
+    try {
+      if (this.hooks.onBeforeWrite) {
+        const hookResult = await this.hooks.onBeforeWrite(context);
+        if (hookResult === void 0) {
+          return { changes: 0 };
+        }
+        context = hookResult;
+      }
+      const result = await this.executeWithRetry(() => this.performRun(context.statement, context.parameters), context);
+      const duration = Date.now() - startTime;
+      this.metrics.totalMutations++;
+      this.trackDuration(duration);
+      this.checkSlowQuery(duration, context.statement);
+      if (this.performanceSettings.cacheEnabled && context.affectedTables) {
+        this.invalidateCache(context.affectedTables);
+      }
+      this.log(`Mutation executed: ${statement.substring(0, 50)}... (${result.changes} rows affected)`);
+      if (this.hooks.onAfterWrite) {
+        await this.hooks.onAfterWrite(context, result);
+      }
+      return result;
+    } catch (error) {
+      this.metrics.totalErrors++;
+      const wrappedError = this.wrapError(`Failed to execute mutation: ${statement}`, error);
+      if (this.hooks.onError) {
+        const hookResult = await this.hooks.onError(wrappedError, context);
+        if (hookResult === void 0) {
+          return { changes: 0 };
+        }
+        throw hookResult;
+      }
+      throw wrappedError;
+    }
+  }
+  /**
+   * Retrieves a single row.
+   *
+   * Supports caching based on performance tier and invokes query hooks.
+   */
+  async get(statement, parameters) {
+    this.assertOpen();
+    this.validateStatement(statement);
+    const startTime = Date.now();
+    const operationId = (0, import_hooks.generateOperationId)();
+    const cacheKey = this.getCacheKey("get", statement, parameters);
+    if (this.performanceSettings.cacheEnabled) {
+      const cached = this.getFromCache(cacheKey);
+      if (cached !== void 0) {
+        return cached;
+      }
+    }
+    let context = {
+      operationId,
+      operation: "get",
+      startTime,
+      adapterKind: this.kind,
+      statement,
+      parameters,
+      affectedTables: this.extractTables(statement)
+    };
+    try {
+      if (this.hooks.onBeforeQuery) {
+        const hookResult = await this.hooks.onBeforeQuery(context);
+        if (hookResult === void 0) {
+          return null;
+        }
+        context = hookResult;
+      }
+      let result = await this.executeWithRetry(() => this.performGet(context.statement, context.parameters), context);
+      const duration = Date.now() - startTime;
+      this.metrics.totalQueries++;
+      this.trackDuration(duration);
+      this.checkSlowQuery(duration, context.statement);
+      this.log(`Query executed: ${statement.substring(0, 50)}... (${result ? "1 row" : "no rows"})`);
+      if (this.hooks.onAfterQuery) {
+        const hookResult = await this.hooks.onAfterQuery(context, result);
+        if (hookResult !== void 0) {
+          result = hookResult;
+        }
+      }
+      if (this.performanceSettings.cacheEnabled) {
+        this.setCache(cacheKey, result, context.affectedTables);
+      }
+      return result;
+    } catch (error) {
+      this.metrics.totalErrors++;
+      const wrappedError = this.wrapError(`Failed to execute query: ${statement}`, error);
+      if (this.hooks.onError) {
+        const hookResult = await this.hooks.onError(wrappedError, context);
+        if (hookResult === void 0) {
+          return null;
+        }
+        throw hookResult;
+      }
+      throw wrappedError;
+    }
+  }
+  /**
+   * Retrieves all rows.
+   *
+   * Supports caching based on performance tier and invokes query hooks.
+   */
+  async all(statement, parameters) {
+    this.assertOpen();
+    this.validateStatement(statement);
+    const startTime = Date.now();
+    const operationId = (0, import_hooks.generateOperationId)();
+    const cacheKey = this.getCacheKey("all", statement, parameters);
+    if (this.performanceSettings.cacheEnabled) {
+      const cached = this.getFromCache(cacheKey);
+      if (cached !== void 0) {
+        return cached;
+      }
+    }
+    let context = {
+      operationId,
+      operation: "all",
+      startTime,
+      adapterKind: this.kind,
+      statement,
+      parameters,
+      affectedTables: this.extractTables(statement)
+    };
+    try {
+      if (this.hooks.onBeforeQuery) {
+        const hookResult = await this.hooks.onBeforeQuery(context);
+        if (hookResult === void 0) {
+          return [];
+        }
+        context = hookResult;
+      }
+      let results = await this.executeWithRetry(() => this.performAll(context.statement, context.parameters), context);
+      const duration = Date.now() - startTime;
+      this.metrics.totalQueries++;
+      this.trackDuration(duration);
+      this.checkSlowQuery(duration, context.statement);
+      this.log(`Query executed: ${statement.substring(0, 50)}... (${results.length} rows)`);
+      if (this.hooks.onAfterQuery) {
+        const hookResult = await this.hooks.onAfterQuery(context, results);
+        if (hookResult !== void 0) {
+          results = hookResult;
+        }
+      }
+      if (this.performanceSettings.cacheEnabled) {
+        this.setCache(cacheKey, results, context.affectedTables);
+      }
+      return results;
+    } catch (error) {
+      this.metrics.totalErrors++;
+      const wrappedError = this.wrapError(`Failed to execute query: ${statement}`, error);
+      if (this.hooks.onError) {
+        const hookResult = await this.hooks.onError(wrappedError, context);
+        if (hookResult === void 0) {
+          return [];
+        }
+        throw hookResult;
+      }
+      throw wrappedError;
+    }
+  }
+  /**
+   * Executes a SQL script.
+   */
+  async exec(script) {
+    this.assertOpen();
+    if (!script || !script.trim()) {
+      throw new Error("SQL script cannot be empty");
+    }
+    const startTime = Date.now();
+    try {
+      await this.performExec(script);
+      this.trackDuration(Date.now() - startTime);
+      this.log(`Script executed successfully`);
+    } catch (error) {
+      this.metrics.totalErrors++;
+      throw this.wrapError("Failed to execute script", error);
+    }
+  }
+  /**
+   * Executes a transaction.
+   *
+   * Invokes transaction hooks and invalidates cache on completion.
+   */
+  async transaction(fn) {
+    this.assertOpen();
+    const startTime = Date.now();
+    const operationId = (0, import_hooks.generateOperationId)();
+    let context = {
+      operationId,
+      operation: "transaction",
+      startTime,
+      adapterKind: this.kind
+    };
+    try {
+      if (this.hooks.onBeforeTransaction) {
+        const hookResult = await this.hooks.onBeforeTransaction(context);
+        if (hookResult === void 0) {
+          throw new Error("Transaction aborted by hook");
+        }
+        context = hookResult;
+      }
+      const result = await this.performTransaction(fn);
+      context.outcome = "committed";
+      this.metrics.totalTransactions++;
+      this.trackDuration(Date.now() - startTime);
+      this.log("Transaction committed successfully");
+      if (this.performanceSettings.cacheEnabled) {
+        this.clearCache();
+      }
+      if (this.hooks.onAfterTransaction) {
+        await this.hooks.onAfterTransaction(context);
+      }
+      return result;
+    } catch (error) {
+      context.outcome = "rolled_back";
+      this.metrics.totalErrors++;
+      const wrappedError = this.wrapError("Transaction failed", error);
+      if (this.hooks.onAfterTransaction) {
+        await this.hooks.onAfterTransaction(context);
+      }
+      if (this.hooks.onError) {
+        const hookResult = await this.hooks.onError(wrappedError, context);
+        if (hookResult === void 0) {
+          throw new Error("Transaction rolled back");
+        }
+        throw hookResult;
+      }
+      throw wrappedError;
+    }
+  }
+  /**
+   * Closes the adapter connection.
+   */
+  async close() {
+    if (this.state === AdapterState.CLOSED) {
+      this.log("Adapter already closed, skipping close()");
+      return;
+    }
+    if (this.state === AdapterState.CLOSING) {
+      throw new Error(`[${this.kind}] Adapter is already closing`);
+    }
+    this.state = AdapterState.CLOSING;
+    try {
+      await this.performClose();
+      this.state = AdapterState.CLOSED;
+      this.log("Adapter closed successfully");
+    } catch (error) {
+      this.state = AdapterState.ERROR;
+      throw this.wrapError("Failed to close adapter", error);
+    }
+  }
+  /**
+   * Executes a batch of operations (optional).
+   */
+  async batch(operations) {
+    this.assertOpen();
+    if (!this.capabilities.has("batch")) {
+      throw new Error(`[${this.kind}] Batch operations are not supported`);
+    }
+    if (!this.performBatch) {
+      throw new Error(`[${this.kind}] Batch operations not implemented`);
+    }
+    if (!operations || operations.length === 0) {
+      throw new Error("Batch operations cannot be empty");
+    }
+    const startTime = Date.now();
+    try {
+      const result = await this.performBatch(operations);
+      this.trackDuration(Date.now() - startTime);
+      this.log(`Batch executed: ${result.successful} successful, ${result.failed} failed`);
+      return result;
+    } catch (error) {
+      this.metrics.totalErrors++;
+      throw this.wrapError("Batch execution failed", error);
+    }
+  }
+  /**
+   * Creates a prepared statement (optional).
+   */
+  prepare(statement) {
+    this.assertOpen();
+    if (!this.capabilities.has("prepared")) {
+      throw new Error(`[${this.kind}] Prepared statements are not supported`);
+    }
+    if (!this.performPrepare) {
+      throw new Error(`[${this.kind}] Prepared statements not implemented`);
+    }
+    this.validateStatement(statement);
+    return this.performPrepare(statement);
+  }
+  // ============================================================================
+  // Protected Helper Methods (Available to subclasses)
+  // ============================================================================
+  /**
+   * Asserts that adapter is in open state.
+   * @throws {Error} If adapter is not open
+   */
+  assertOpen() {
+    if (this.state !== AdapterState.OPEN) {
+      throw new Error(`[${this.kind}] Adapter is not open (current state: ${this.state})`);
+    }
+  }
+  /**
+   * Validates SQL statement.
+   * @throws {Error} If statement is invalid
+   */
+  validateStatement(statement) {
+    if (!this.performanceSettings.validateSql) {
+      return;
+    }
+    if (!statement || !statement.trim()) {
+      throw new Error("SQL statement cannot be empty");
+    }
+    if (statement.includes("--") && !statement.includes("-- ")) {
+      this.log("Warning: SQL comment detected in statement");
+    }
+  }
+  // ============================================================================
+  // Cache Management
+  // ============================================================================
+  /**
+   * Generates a cache key for a query.
+   * Includes operation type to prevent get/all cache collisions.
+   */
+  getCacheKey(operation, statement, parameters) {
+    const paramStr = parameters ? JSON.stringify(parameters) : "";
+    return `${operation}::${statement}::${paramStr}`;
+  }
+  /**
+   * Gets a value from cache if valid.
+   */
+  getFromCache(key) {
+    const entry = this.queryCache.get(key);
+    if (!entry) {
+      this.cacheStats.misses++;
+      this.updateCacheHitRatio();
+      return void 0;
+    }
+    if (Date.now() > entry.expiresAt) {
+      this.queryCache.delete(key);
+      this.cacheStats.misses++;
+      this.updateCacheHitRatio();
+      return void 0;
+    }
+    entry.hits++;
+    entry.lastAccessedAt = Date.now();
+    this.cacheStats.hits++;
+    this.updateCacheHitRatio();
+    return entry.data;
+  }
+  /**
+   * Sets a value in cache.
+   */
+  setCache(key, data, affectedTables) {
+    if (this.queryCache.size >= this.performanceSettings.cacheMaxEntries) {
+      this.evictLRU();
+    }
+    const now = Date.now();
+    const entry = {
+      data,
+      createdAt: now,
+      expiresAt: now + this.performanceSettings.cacheTtlMs,
+      affectedTables: affectedTables ?? [],
+      hits: 0,
+      lastAccessedAt: now
+    };
+    this.queryCache.set(key, entry);
+    this.cacheStats.size = this.queryCache.size;
+  }
+  /**
+   * Invalidates cache entries for specific tables.
+   */
+  invalidateCache(tables) {
+    const tableSet = new Set(tables.map((t) => t.toLowerCase()));
+    for (const [key, entry] of this.queryCache.entries()) {
+      const hasAffectedTable = entry.affectedTables.some((t) => tableSet.has(t.toLowerCase()));
+      if (hasAffectedTable) {
+        this.queryCache.delete(key);
+        this.cacheStats.invalidations++;
+      }
+    }
+    this.cacheStats.size = this.queryCache.size;
+  }
+  /**
+   * Clears entire cache.
+   */
+  clearCache() {
+    this.queryCache.clear();
+    this.cacheStats.size = 0;
+  }
+  /**
+   * Evicts least recently used cache entry.
+   */
+  evictLRU() {
+    let oldest = null;
+    for (const [key, entry] of this.queryCache.entries()) {
+      if (!oldest || entry.lastAccessedAt < oldest.time) {
+        oldest = { key, time: entry.lastAccessedAt };
+      }
+    }
+    if (oldest) {
+      this.queryCache.delete(oldest.key);
+      this.cacheStats.evictions++;
+    }
+  }
+  /**
+   * Updates cache hit ratio.
+   */
+  updateCacheHitRatio() {
+    const total = this.cacheStats.hits + this.cacheStats.misses;
+    this.cacheStats.hitRatio = total > 0 ? this.cacheStats.hits / total : 0;
+  }
+  // ============================================================================
+  // Retry Logic
+  // ============================================================================
+  /**
+   * Executes an operation with retry logic.
+   */
+  async executeWithRetry(operation, context) {
+    if (!this.performanceSettings.retryOnError) {
+      return operation();
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= this.performanceSettings.maxRetries; attempt++) {
+      try {
+        return await operation();
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (!(0, import_performance.isTransientError)(lastError) || attempt >= this.performanceSettings.maxRetries) {
+          throw lastError;
+        }
+        this.metrics.retries++;
+        const delay = this.performanceSettings.retryDelayMs * Math.pow(2, attempt);
+        this.log(`Retrying operation ${context.operationId} in ${delay}ms (attempt ${attempt + 1})`);
+        await this.sleep(delay);
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * Sleep utility for retry delays.
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  // ============================================================================
+  // SQL Parsing Utilities
+  // ============================================================================
+  /**
+   * Extracts table names from a SQL statement.
+   *
+   * @remarks
+   * Simple regex-based extraction. For complex queries, consider
+   * using a proper SQL parser.
+   */
+  extractTables(statement) {
+    const tables = [];
+    const upperStatement = statement.toUpperCase();
+    const fromMatch = upperStatement.match(/FROM\s+([^\s,;(]+)/gi);
+    if (fromMatch) {
+      fromMatch.forEach((match) => {
+        const table = match.replace(/^FROM\s+/i, "").trim();
+        if (table && !table.startsWith("(")) {
+          tables.push(table.toLowerCase());
+        }
+      });
+    }
+    const insertMatch = statement.match(/INSERT\s+INTO\s+([^\s(]+)/i);
+    if (insertMatch?.[1]) {
+      tables.push(insertMatch[1].toLowerCase());
+    }
+    const updateMatch = statement.match(/UPDATE\s+([^\s]+)/i);
+    if (updateMatch?.[1]) {
+      tables.push(updateMatch[1].toLowerCase());
+    }
+    const deleteMatch = statement.match(/DELETE\s+FROM\s+([^\s]+)/i);
+    if (deleteMatch?.[1]) {
+      tables.push(deleteMatch[1].toLowerCase());
+    }
+    const joinMatches = statement.match(/JOIN\s+([^\s]+)/gi);
+    if (joinMatches) {
+      joinMatches.forEach((match) => {
+        const table = match.replace(/^JOIN\s+/i, "").trim();
+        tables.push(table.toLowerCase());
+      });
+    }
+    return [...new Set(tables)];
+  }
+  /**
+   * Checks if query duration exceeds slow query threshold.
+   */
+  checkSlowQuery(duration, statement) {
+    if (duration > this.performanceSettings.slowQueryThresholdMs) {
+      this.metrics.slowQueries++;
+      this.log(`SLOW QUERY (${duration}ms): ${statement.substring(0, 100)}...`);
+    }
+  }
+  /**
+   * Wraps an error with adapter context.
+   */
+  wrapError(message, error) {
+    const originalMessage = error instanceof Error ? error.message : String(error);
+    const wrappedError = new Error(`[${this.kind}] ${message}: ${originalMessage}`);
+    if (error instanceof Error && error.stack) {
+      wrappedError.stack = error.stack;
+    }
+    return wrappedError;
+  }
+  /**
+   * Logs a message if verbose mode is enabled.
+   */
+  log(message) {
+    if (this.options.verbose) {
+      const logger = (0, import_logger.getStorageLogger)();
+      (logger.debug ?? logger.info).call(logger, { scope: this.kind }, message);
+    }
+  }
+  /**
+   * Logs a warning message (always outputs regardless of verbose).
+   */
+  logWarn(message) {
+    (0, import_logger.getStorageLogger)().warn({ scope: this.kind }, message);
+  }
+  /**
+   * Tracks query duration for performance metrics.
+   */
+  trackDuration(duration) {
+    if (!this.options.trackPerformance) {
+      return;
+    }
+    this.queryDurations.push(duration);
+    if (this.queryDurations.length > this.MAX_DURATION_SAMPLES) {
+      this.queryDurations.shift();
+    }
+    const sum = this.queryDurations.reduce((a, b) => a + b, 0);
+    this.metrics.averageQueryDuration = sum / this.queryDurations.length;
+  }
+  // ============================================================================
+  // Public Utility Methods
+  // ============================================================================
+  /**
+   * Gets current adapter state.
+   */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Gets performance metrics.
+   */
+  getMetrics() {
+    return {
+      ...this.metrics,
+      cache: this.performanceSettings.cacheEnabled ? { ...this.cacheStats } : void 0
+    };
+  }
+  /**
+   * Gets cache statistics.
+   */
+  getCacheStats() {
+    if (!this.performanceSettings.cacheEnabled) {
+      return null;
+    }
+    return { ...this.cacheStats };
+  }
+  /**
+   * Gets current performance settings.
+   */
+  getPerformanceSettings() {
+    return { ...this.performanceSettings };
+  }
+  /**
+   * Checks if adapter is open.
+   */
+  isOpen() {
+    return this.state === AdapterState.OPEN;
+  }
+  /**
+   * Checks if adapter is closed.
+   */
+  isClosed() {
+    return this.state === AdapterState.CLOSED;
+  }
+  /**
+   * Gets uptime in milliseconds.
+   */
+  getUptime() {
+    if (!this.metrics.openedAt) {
+      return 0;
+    }
+    return Date.now() - this.metrics.openedAt.getTime();
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BaseStorageAdapter
+});