@framers/sql-storage-adapter 0.7.2 → 0.7.4

package/dist/cjs/adapters/baseStorageAdapter.d.ts

@@ -0,0 +1,368 @@
+/**
+ * Abstract base class for SQL storage adapters.
+ *
+ * Provides common functionality and enforces consistent behavior across all adapters.
+ * Follows the Template Method pattern - subclasses implement adapter-specific logic
+ * while the base class handles cross-cutting concerns.
+ *
+ * ## Responsibilities
+ * - Parameter validation and sanitization
+ * - Error handling and standardization
+ * - Lifecycle management (open/close state tracking)
+ * - Performance monitoring with configurable tiers
+ * - Query result caching (optional)
+ * - Lifecycle hooks for RAG integration
+ * - Logging and diagnostics
+ *
+ * @example Implementing a new adapter
+ * ```typescript
+ * export class MyAdapter extends BaseStorageAdapter {
+ *   protected async doOpen(options?: StorageOpenOptions): Promise<void> {
+ *     // Adapter-specific connection logic
+ *   }
+ *
+ *   protected async doRun(statement: string, parameters?: StorageParameters): Promise<StorageRunResult> {
+ *     // Adapter-specific mutation logic
+ *   }
+ *
+ *   // ... implement other abstract methods
+ * }
+ * ```
+ *
+ * @example Using with performance tiers and hooks
+ * ```typescript
+ * const adapter = new MyAdapter({
+ *   performance: { tier: 'balanced', trackMetrics: true },
+ *   hooks: {
+ *     onBeforeWrite: async (ctx) => {
+ *       // Generate embedding for RAG
+ *       ctx.metadata = { embedding: await embed(ctx.parameters?.[0]) };
+ *       return ctx;
+ *     }
+ *   }
+ * });
+ * ```
+ */
+import type { StorageAdapter, StorageCapability, StorageOpenOptions, StorageParameters, StorageRunResult, BatchOperation, BatchResult, PreparedStatement } from '../core/contracts/index.js';
+import type { PerformanceConfig, PerformanceSettings, CacheStats } from '../core/contracts/performance.js';
+import type { StorageHooks } from '../core/contracts/hooks.js';
+/**
+ * Options for BaseStorageAdapter configuration.
+ *
+ * @example Basic options
+ * ```typescript
+ * const adapter = new MyAdapter({ verbose: true });
+ * ```
+ *
+ * @example With performance tier
+ * ```typescript
+ * const adapter = new MyAdapter({
+ *   performance: { tier: 'fast' }
+ * });
+ * ```
+ *
+ * @example With hooks for RAG
+ * ```typescript
+ * const adapter = new MyAdapter({
+ *   hooks: {
+ *     onAfterWrite: async (ctx, result) => {
+ *       await updateVectorIndex(result.lastInsertRowid, ctx.metadata?.embedding);
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export interface BaseAdapterOptions {
+    /** Enable detailed logging (default: false) */
+    verbose?: boolean;
+    /**
+     * Enable performance tracking and metrics collection.
+     * @defaultValue true when tier is 'balanced' or 'accurate'
+     */
+    trackPerformance?: boolean;
+    /**
+     * Performance tier configuration.
+     * Controls caching, batching, validation, and retry behavior.
+     * @defaultValue { tier: 'balanced' }
+     */
+    performance?: PerformanceConfig;
+    /**
+     * Lifecycle hooks for extending adapter behavior.
+     * Useful for RAG integration, logging, analytics, and auditing.
+     */
+    hooks?: StorageHooks;
+    /**
+     * Validate SQL statements before execution.
+     * Convenience option that overrides performance.validateSql.
+     * @defaultValue true
+     */
+    validateSQL?: boolean;
+}
+/**
+ * Performance metrics tracked by the base adapter.
+ */
+export interface AdapterMetrics {
+    /** Total number of queries executed */
+    totalQueries: number;
+    /** Total number of mutations (INSERT/UPDATE/DELETE) */
+    totalMutations: number;
+    /** Total number of transactions */
+    totalTransactions: number;
+    /** Total number of errors */
+    totalErrors: number;
+    /** Average query duration in milliseconds */
+    averageQueryDuration: number;
+    /** Time when adapter was opened */
+    openedAt: Date | null;
+    /** Cache statistics (if caching enabled) */
+    cache?: CacheStats;
+    /** Slow query count */
+    slowQueries: number;
+    /** Retry count */
+    retries: number;
+}
+/**
+ * Abstract base class for SQL storage adapters.
+ *
+ * Implements common functionality shared by all adapters:
+ * - State management (open/close tracking)
+ * - Parameter validation
+ * - Error handling and wrapping
+ * - Performance metrics with configurable tiers
+ * - Query result caching (tier-dependent)
+ * - Lifecycle hooks for RAG and analytics
+ * - Logging and diagnostics
+ */
+export declare abstract class BaseStorageAdapter implements StorageAdapter {
+    abstract readonly kind: string;
+    abstract readonly capabilities: ReadonlySet<StorageCapability>;
+    private state;
+    protected readonly options: BaseAdapterOptions;
+    protected readonly performanceSettings: PerformanceSettings;
+    protected readonly hooks: StorageHooks;
+    private metrics;
+    private queryCache;
+    private cacheStats;
+    private queryDurations;
+    private readonly MAX_DURATION_SAMPLES;
+    /**
+     * 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?: BaseAdapterOptions);
+    /**
+     * Opens the adapter connection.
+     * Handles state management and delegates to subclass implementation.
+     */
+    open(options?: StorageOpenOptions): Promise<void>;
+    /**
+     * Executes a mutation statement (INSERT, UPDATE, DELETE).
+     *
+     * Invokes `onBeforeWrite` and `onAfterWrite` hooks if configured.
+     * Supports retry on transient errors based on performance tier.
+     */
+    run(statement: string, parameters?: StorageParameters): Promise<StorageRunResult>;
+    /**
+     * Retrieves a single row.
+     *
+     * Supports caching based on performance tier and invokes query hooks.
+     */
+    get<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T | null>;
+    /**
+     * Retrieves all rows.
+     *
+     * Supports caching based on performance tier and invokes query hooks.
+     */
+    all<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T[]>;
+    /**
+     * Executes a SQL script.
+     */
+    exec(script: string): Promise<void>;
+    /**
+     * Executes a transaction.
+     *
+     * Invokes transaction hooks and invalidates cache on completion.
+     */
+    transaction<T>(fn: (trx: StorageAdapter) => Promise<T>): Promise<T>;
+    /**
+     * Closes the adapter connection.
+     */
+    close(): Promise<void>;
+    /**
+     * Executes a batch of operations (optional).
+     */
+    batch(operations: BatchOperation[]): Promise<BatchResult>;
+    /**
+     * Creates a prepared statement (optional).
+     */
+    prepare<T = unknown>(statement: string): PreparedStatement<T>;
+    /**
+     * Adapter-specific open logic.
+     * Called by base class after state validation.
+     */
+    protected abstract performOpen(options?: StorageOpenOptions): Promise<void>;
+    /**
+     * Adapter-specific mutation logic.
+     */
+    protected abstract performRun(statement: string, parameters?: StorageParameters): Promise<StorageRunResult>;
+    /**
+     * Adapter-specific single-row query logic.
+     */
+    protected abstract performGet<T>(statement: string, parameters?: StorageParameters): Promise<T | null>;
+    /**
+     * Adapter-specific multi-row query logic.
+     */
+    protected abstract performAll<T>(statement: string, parameters?: StorageParameters): Promise<T[]>;
+    /**
+     * Adapter-specific script execution logic.
+     */
+    protected abstract performExec(script: string): Promise<void>;
+    /**
+     * Adapter-specific transaction logic.
+     */
+    protected abstract performTransaction<T>(fn: (trx: StorageAdapter) => Promise<T>): Promise<T>;
+    /**
+     * Adapter-specific close logic.
+     */
+    protected abstract performClose(): Promise<void>;
+    /**
+     * Adapter-specific batch logic (optional).
+     * Only called if adapter declares 'batch' capability.
+     */
+    protected performBatch?(operations: BatchOperation[]): Promise<BatchResult>;
+    /**
+     * Adapter-specific prepared statement logic (optional).
+     * Only called if adapter declares 'prepared' capability.
+     */
+    protected performPrepare?<T>(statement: string): PreparedStatement<T>;
+    /**
+     * Asserts that adapter is in open state.
+     * @throws {Error} If adapter is not open
+     */
+    protected assertOpen(): void;
+    /**
+     * Validates SQL statement.
+     * @throws {Error} If statement is invalid
+     */
+    protected validateStatement(statement: string): void;
+    /**
+     * Generates a cache key for a query.
+     * Includes operation type to prevent get/all cache collisions.
+     */
+    private getCacheKey;
+    /**
+     * Gets a value from cache if valid.
+     */
+    private getFromCache;
+    /**
+     * Sets a value in cache.
+     */
+    private setCache;
+    /**
+     * Invalidates cache entries for specific tables.
+     */
+    private invalidateCache;
+    /**
+     * Clears entire cache.
+     */
+    private clearCache;
+    /**
+     * Evicts least recently used cache entry.
+     */
+    private evictLRU;
+    /**
+     * Updates cache hit ratio.
+     */
+    private updateCacheHitRatio;
+    /**
+     * Executes an operation with retry logic.
+     */
+    private executeWithRetry;
+    /**
+     * Sleep utility for retry delays.
+     */
+    private sleep;
+    /**
+     * Extracts table names from a SQL statement.
+     *
+     * @remarks
+     * Simple regex-based extraction. For complex queries, consider
+     * using a proper SQL parser.
+     */
+    private extractTables;
+    /**
+     * Checks if query duration exceeds slow query threshold.
+     */
+    private checkSlowQuery;
+    /**
+     * Wraps an error with adapter context.
+     */
+    protected wrapError(message: string, error: unknown): Error;
+    /**
+     * Logs a message if verbose mode is enabled.
+     */
+    protected log(message: string): void;
+    /**
+     * Logs a warning message (always outputs regardless of verbose).
+     */
+    protected logWarn(message: string): void;
+    /**
+     * Tracks query duration for performance metrics.
+     */
+    private trackDuration;
+    /**
+     * Gets current adapter state.
+     */
+    getState(): string;
+    /**
+     * Gets performance metrics.
+     */
+    getMetrics(): Readonly<AdapterMetrics>;
+    /**
+     * Gets cache statistics.
+     */
+    getCacheStats(): Readonly<CacheStats> | null;
+    /**
+     * Gets current performance settings.
+     */
+    getPerformanceSettings(): Readonly<PerformanceSettings>;
+    /**
+     * Checks if adapter is open.
+     */
+    isOpen(): boolean;
+    /**
+     * Checks if adapter is closed.
+     */
+    isClosed(): boolean;
+    /**
+     * Gets uptime in milliseconds.
+     */
+    getUptime(): number;
+}
+//# sourceMappingURL=baseStorageAdapter.d.ts.map