@framers/sql-storage-adapter 0.7.1 → 0.7.3

package/dist/cjs/core/contracts/performance.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Performance Configuration Types for SQL Storage Adapter
+ *
+ * This module defines the performance tier system, caching configuration,
+ * and optimization options that enable cost/accuracy tradeoffs across
+ * all adapter implementations.
+ *
+ * @packageDocumentation
+ * @module @framers/sql-storage-adapter/performance
+ *
+ * @remarks
+ * The performance system is designed to be:
+ * - **Platform-agnostic**: Same API across browser, mobile, desktop, cloud
+ * - **Extensible**: Hooks and metadata support for custom extensions
+ * - **Configurable**: Sensible defaults with full override capability
+ * - **Observable**: Built-in metrics and slow query logging
+ *
+ * @example Basic usage with tier presets
+ * ```typescript
+ * import { createDatabase } from '@framers/sql-storage-adapter';
+ *
+ * // Development: prioritize speed
+ * const devDb = await createDatabase({
+ *   performance: { tier: 'fast' }
+ * });
+ *
+ * // Production analytics: prioritize accuracy
+ * const analyticsDb = await createDatabase({
+ *   performance: { tier: 'accurate', trackMetrics: true }
+ * });
+ * ```
+ */
+/**
+ * Performance tier presets for common use cases.
+ *
+ * Each tier provides sensible defaults that can be individually overridden.
+ * The tier affects caching, batching, validation, and query optimization.
+ *
+ * | Tier | Use Case | Caching | Batching | Validation |
+ * |------|----------|---------|----------|------------|
+ * | `fast` | Development, testing | Aggressive | Yes | Minimal |
+ * | `balanced` | General production | Moderate | No | Standard |
+ * | `accurate` | Analytics, reporting | Disabled | No | Full |
+ * | `efficient` | Mobile, battery-constrained | Moderate | Yes | Minimal |
+ * | `custom` | Full manual control | Manual | Manual | Manual |
+ *
+ * @example
+ * ```typescript
+ * // Mobile app with battery optimization
+ * const db = await createDatabase({
+ *   performance: { tier: 'efficient' }
+ * });
+ * ```
+ */
+export type PerformanceTier = 'fast' | 'balanced' | 'accurate' | 'efficient' | 'custom';
+/**
+ * Default settings for each performance tier.
+ *
+ * @internal
+ */
+export declare const TIER_DEFAULTS: Record<Exclude<PerformanceTier, 'custom'>, Readonly<PerformanceSettings>>;
+/**
+ * Individual performance settings (all fields required).
+ *
+ * @internal
+ * Used internally after merging tier defaults with user overrides.
+ */
+export interface PerformanceSettings {
+    /** Enable query result caching */
+    readonly cacheEnabled: boolean;
+    /** Cache TTL in milliseconds */
+    readonly cacheTtlMs: number;
+    /** Maximum cache entries */
+    readonly cacheMaxEntries: number;
+    /** Enable write batching */
+    readonly batchWrites: boolean;
+    /** Batch flush interval in ms */
+    readonly batchFlushIntervalMs: number;
+    /** Maximum batch size before auto-flush */
+    readonly batchMaxSize: number;
+    /** Validate SQL before execution */
+    readonly validateSql: boolean;
+    /** Track performance metrics */
+    readonly trackMetrics: boolean;
+    /** Log slow queries above this threshold in ms */
+    readonly slowQueryThresholdMs: number;
+    /** Retry transient errors */
+    readonly retryOnError: boolean;
+    /** Maximum retry attempts */
+    readonly maxRetries: number;
+    /** Retry delay in ms */
+    readonly retryDelayMs: number;
+}
+/**
+ * Performance configuration options provided by users.
+ *
+ * All fields are optional; unspecified fields use tier defaults.
+ *
+ * @example Override specific settings while using a tier
+ * ```typescript
+ * const db = await createDatabase({
+ *   performance: {
+ *     tier: 'balanced',
+ *     cacheTtlMs: 30000,     // Override: longer cache
+ *     trackMetrics: true,    // Override: enable metrics
+ *   }
+ * });
+ * ```
+ */
+export interface PerformanceConfig {
+    /**
+     * Performance tier preset.
+     *
+     * @defaultValue 'balanced'
+     */
+    tier?: PerformanceTier;
+    /**
+     * Enable query result caching.
+     *
+     * When enabled, identical SELECT queries return cached results
+     * until the cache TTL expires or cache is invalidated.
+     *
+     * @remarks
+     * - Caching is per-adapter instance (not shared)
+     * - Cache is invalidated on any write operation to affected tables
+     * - Use `accurate` tier for systems where stale data is unacceptable
+     *
+     * @defaultValue tier-dependent
+     */
+    cacheEnabled?: boolean;
+    /**
+     * Cache time-to-live in milliseconds.
+     *
+     * After this duration, cached query results are considered stale
+     * and will be re-fetched on next access.
+     *
+     * @defaultValue 5000 for balanced tier
+     */
+    cacheTtlMs?: number;
+    /**
+     * Maximum number of cached query results.
+     *
+     * When exceeded, least-recently-used entries are evicted.
+     *
+     * @defaultValue 1000 for balanced tier
+     */
+    cacheMaxEntries?: number;
+    /**
+     * Enable write batching.
+     *
+     * When enabled, write operations (INSERT, UPDATE, DELETE) are
+     * collected and executed in batches to reduce I/O operations.
+     *
+     * @remarks
+     * - Recommended for mobile/browser environments
+     * - Not recommended for systems requiring immediate consistency
+     * - Batch is flushed on `batchFlushIntervalMs` or `batchMaxSize`
+     *
+     * @defaultValue false for balanced tier, true for efficient tier
+     */
+    batchWrites?: boolean;
+    /**
+     * Batch flush interval in milliseconds.
+     *
+     * Accumulated writes are flushed after this interval.
+     *
+     * @defaultValue 100 for balanced tier
+     */
+    batchFlushIntervalMs?: number;
+    /**
+     * Maximum batch size before auto-flush.
+     *
+     * When batch reaches this size, it is immediately flushed
+     * regardless of the flush interval.
+     *
+     * @defaultValue 50 for balanced tier
+     */
+    batchMaxSize?: number;
+    /**
+     * Validate SQL statements before execution.
+     *
+     * Performs basic syntax and injection checks.
+     *
+     * @defaultValue true for balanced tier
+     */
+    validateSql?: boolean;
+    /**
+     * Track performance metrics.
+     *
+     * When enabled, the adapter tracks:
+     * - Total queries/mutations/transactions
+     * - Average query duration
+     * - Error counts
+     * - Uptime
+     *
+     * Retrieve metrics via `adapter.getMetrics()`.
+     *
+     * @defaultValue true for balanced tier
+     */
+    trackMetrics?: boolean;
+    /**
+     * Slow query logging threshold in milliseconds.
+     *
+     * Queries exceeding this duration are logged at warn level.
+     *
+     * @defaultValue 100 for balanced tier
+     */
+    slowQueryThresholdMs?: number;
+    /**
+     * Retry operations on transient errors.
+     *
+     * Transient errors include network timeouts, connection resets,
+     * and deadlocks.
+     *
+     * @defaultValue true for balanced tier
+     */
+    retryOnError?: boolean;
+    /**
+     * Maximum retry attempts.
+     *
+     * @defaultValue 3 for balanced tier
+     */
+    maxRetries?: number;
+    /**
+     * Delay between retry attempts in milliseconds.
+     *
+     * Uses exponential backoff: delay * 2^attempt.
+     *
+     * @defaultValue 100 for balanced tier
+     */
+    retryDelayMs?: number;
+}
+/**
+ * Cache entry for query results.
+ *
+ * @internal
+ */
+export interface CacheEntry<T = unknown> {
+    /** Cached result data */
+    readonly data: T;
+    /** Timestamp when entry was created (ms since epoch) */
+    readonly createdAt: number;
+    /** Timestamp when entry expires (ms since epoch) */
+    readonly expiresAt: number;
+    /** Tables affected by this query (for invalidation) */
+    readonly affectedTables: ReadonlyArray<string>;
+    /** Cache hit count for LRU tracking */
+    hits: number;
+    /** Last access timestamp for LRU tracking */
+    lastAccessedAt: number;
+}
+/**
+ * Cache statistics for monitoring (public API is readonly).
+ */
+export interface CacheStats {
+    /** Total cache hits */
+    readonly hits: number;
+    /** Total cache misses */
+    readonly misses: number;
+    /** Hit ratio (hits / (hits + misses)) */
+    readonly hitRatio: number;
+    /** Current number of entries */
+    readonly size: number;
+    /** Total bytes used (approximate) */
+    readonly bytesUsed: number;
+    /** Number of evictions */
+    readonly evictions: number;
+    /** Number of invalidations */
+    readonly invalidations: number;
+}
+/**
+ * Mutable version of CacheStats for internal use.
+ */
+export type MutableCacheStats = {
+    -readonly [K in keyof CacheStats]: CacheStats[K];
+};
+/**
+ * Resolves performance configuration by merging tier defaults with user overrides.
+ *
+ * @param config - User-provided performance configuration
+ * @returns Fully resolved performance settings
+ *
+ * @example
+ * ```typescript
+ * const settings = resolvePerformanceConfig({ tier: 'fast', cacheTtlMs: 10000 });
+ * // Returns fast tier defaults with cacheTtlMs overridden to 10000
+ * ```
+ */
+export declare function resolvePerformanceConfig(config?: PerformanceConfig): PerformanceSettings;
+/**
+ * Checks if an error is transient and should be retried.
+ *
+ * @param error - The error to check
+ * @returns true if the error is transient
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await db.run('INSERT INTO users (name) VALUES (?)', ['Alice']);
+ * } catch (error) {
+ *   if (isTransientError(error)) {
+ *     // Retry the operation
+ *   }
+ * }
+ * ```
+ */
+export declare function isTransientError(error: unknown): boolean;
+//# sourceMappingURL=performance.d.ts.map

package/dist/cjs/core/contracts/performance.js

@@ -0,0 +1,144 @@
+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 performance_exports = {};
+__export(performance_exports, {
+  TIER_DEFAULTS: () => TIER_DEFAULTS,
+  isTransientError: () => isTransientError,
+  resolvePerformanceConfig: () => resolvePerformanceConfig
+});
+module.exports = __toCommonJS(performance_exports);
+const TIER_DEFAULTS = {
+  fast: {
+    cacheEnabled: true,
+    cacheTtlMs: 3e4,
+    cacheMaxEntries: 500,
+    batchWrites: true,
+    batchFlushIntervalMs: 50,
+    batchMaxSize: 100,
+    validateSql: false,
+    trackMetrics: false,
+    slowQueryThresholdMs: 500,
+    retryOnError: false,
+    maxRetries: 1,
+    retryDelayMs: 100
+  },
+  balanced: {
+    cacheEnabled: true,
+    cacheTtlMs: 5e3,
+    cacheMaxEntries: 1e3,
+    batchWrites: false,
+    batchFlushIntervalMs: 100,
+    batchMaxSize: 50,
+    validateSql: true,
+    trackMetrics: true,
+    slowQueryThresholdMs: 100,
+    retryOnError: true,
+    maxRetries: 3,
+    retryDelayMs: 100
+  },
+  accurate: {
+    cacheEnabled: false,
+    cacheTtlMs: 0,
+    cacheMaxEntries: 0,
+    batchWrites: false,
+    batchFlushIntervalMs: 0,
+    batchMaxSize: 1,
+    validateSql: true,
+    trackMetrics: true,
+    slowQueryThresholdMs: 50,
+    retryOnError: true,
+    maxRetries: 5,
+    retryDelayMs: 200
+  },
+  efficient: {
+    cacheEnabled: true,
+    cacheTtlMs: 6e4,
+    cacheMaxEntries: 200,
+    batchWrites: true,
+    batchFlushIntervalMs: 500,
+    batchMaxSize: 20,
+    validateSql: false,
+    trackMetrics: false,
+    slowQueryThresholdMs: 200,
+    retryOnError: true,
+    maxRetries: 3,
+    retryDelayMs: 500
+  }
+};
+function resolvePerformanceConfig(config = {}) {
+  const tier = config.tier ?? "balanced";
+  if (tier === "custom") {
+    return {
+      cacheEnabled: config.cacheEnabled ?? false,
+      cacheTtlMs: config.cacheTtlMs ?? 0,
+      cacheMaxEntries: config.cacheMaxEntries ?? 0,
+      batchWrites: config.batchWrites ?? false,
+      batchFlushIntervalMs: config.batchFlushIntervalMs ?? 0,
+      batchMaxSize: config.batchMaxSize ?? 1,
+      validateSql: config.validateSql ?? true,
+      trackMetrics: config.trackMetrics ?? false,
+      slowQueryThresholdMs: config.slowQueryThresholdMs ?? 100,
+      retryOnError: config.retryOnError ?? false,
+      maxRetries: config.maxRetries ?? 1,
+      retryDelayMs: config.retryDelayMs ?? 100
+    };
+  }
+  const defaults = TIER_DEFAULTS[tier];
+  return {
+    cacheEnabled: config.cacheEnabled ?? defaults.cacheEnabled,
+    cacheTtlMs: config.cacheTtlMs ?? defaults.cacheTtlMs,
+    cacheMaxEntries: config.cacheMaxEntries ?? defaults.cacheMaxEntries,
+    batchWrites: config.batchWrites ?? defaults.batchWrites,
+    batchFlushIntervalMs: config.batchFlushIntervalMs ?? defaults.batchFlushIntervalMs,
+    batchMaxSize: config.batchMaxSize ?? defaults.batchMaxSize,
+    validateSql: config.validateSql ?? defaults.validateSql,
+    trackMetrics: config.trackMetrics ?? defaults.trackMetrics,
+    slowQueryThresholdMs: config.slowQueryThresholdMs ?? defaults.slowQueryThresholdMs,
+    retryOnError: config.retryOnError ?? defaults.retryOnError,
+    maxRetries: config.maxRetries ?? defaults.maxRetries,
+    retryDelayMs: config.retryDelayMs ?? defaults.retryDelayMs
+  };
+}
+function isTransientError(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const message = error.message.toLowerCase();
+  const transientPatterns = [
+    "timeout",
+    "connection reset",
+    "connection refused",
+    "econnreset",
+    "econnrefused",
+    "etimedout",
+    "network",
+    "deadlock",
+    "lock wait timeout",
+    "too many connections",
+    "connection pool",
+    "busy",
+    "temporarily unavailable"
+  ];
+  return transientPatterns.some((pattern) => message.includes(pattern));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TIER_DEFAULTS,
+  isTransientError,
+  resolvePerformanceConfig
+});

package/dist/cjs/core/database.d.ts

@@ -0,0 +1,220 @@
+/**
+ * High-level, user-friendly API for SQL storage.
+ *
+ * This module provides simple functions like:
+ * - createDatabase() - Automatically picks the best database for your environment
+ * - connectDatabase() - Explicit connection with clear options
+ * - openDatabase() - Simple file-based database
+ */
+import { type StorageAdapter } from './contracts/index.js';
+import { type AdapterKind } from './resolver.js';
+import type { PostgresAdapterOptions } from '../adapters/postgresAdapter.js';
+import type { CapacitorAdapterOptions } from '../adapters/capacitorSqliteAdapter.js';
+import type { IndexedDbAdapterOptions } from '../adapters/indexedDbAdapter.js';
+import type { StorageLogger } from '../shared/logger.js';
+/**
+ * Database connection options.
+ */
+export interface DatabaseOptions {
+    /**
+     * Database URL (e.g., postgresql://user:pass@host/db).
+     * If provided, PostgreSQL is used on Node, with no fallback to SQLite,
+     * unless `priority` or `type` says otherwise.
+     */
+    url?: string;
+    /**
+     * File path for SQLite database.
+     * Used for local/offline storage.
+     */
+    file?: string;
+    /**
+     * PostgreSQL-specific configuration, passed on to the Postgres adapter whole.
+     * When it names a server (a pool of the caller's, a connection string, or a
+     * host, database or user), PostgreSQL is used on Node, with no fallback to
+     * SQLite, unless `priority` or `type` says otherwise.
+     * `{ connectionString: process.env.DATABASE_URL }` with DATABASE_URL unset
+     * names none, and the local default is used.
+     */
+    postgres?: PostgresAdapterOptions;
+    /**
+     * Mobile (Capacitor) configuration.
+     * Automatically detected on mobile platforms.
+     */
+    mobile?: CapacitorAdapterOptions;
+    /**
+     * IndexedDB configuration for browser-native persistence, passed on to the
+     * IndexedDB adapter whole (`durability`, `crossTab` and the rest).
+     * Uses sql.js (WASM) for SQL execution + IndexedDB for storage.
+     *
+     * @example
+     * ```typescript
+     * const db = await createDatabase({
+     *   priority: ['indexeddb', 'sqljs'],
+     *   indexedDb: {
+     *     dbName: 'my-app-db',
+     *     sqlJsConfig: {
+     *       locateFile: (file) => `/wasm/${file}`
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    indexedDb?: IndexedDbAdapterOptions;
+    /**
+     * Force a specific database type.
+     * Leave empty to auto-detect.
+     */
+    type?: 'postgres' | 'sqlite' | 'browser' | 'mobile' | 'memory';
+    /**
+     * Custom priority order for adapter selection.
+     * Advanced: Only use if you need fine-grained control.
+     */
+    priority?: AdapterKind[];
+    /**
+     * Strict resolution, for servers: no local database stands in for a
+     * Postgres the options configure. Default: false.
+     *
+     * - A `url` or `postgres` option that names no server (an empty or unset
+     *   connection string and no host, database or user) fails on Node instead
+     *   of opening the local default, unless `file` is given.
+     * - A postgres candidate that fails ends resolution with an error, whatever
+     *   `priority` lists after it.
+     *
+     * `DATABASE_URL` in the environment does not count here, strict or not.
+     * See `StorageResolutionOptions.strict` for the resolver's side.
+     */
+    strict?: boolean;
+    /**
+     * SQLite: `true` turns foreign-key enforcement on and `false` turns it off
+     * when the adapter opens, and the setting holds when sql.js reopens its
+     * connection. Left out, each engine keeps its default: better-sqlite3
+     * enforces foreign keys, sql.js, IndexedDB and Capacitor do not.
+     * PostgreSQL always enforces them and ignores this. On the resolver, pass
+     * `openOptions: { foreignKeys: true }`.
+     */
+    foreignKeys?: boolean;
+    /**
+     * Keeps this database's tables apart from other users of the same database:
+     * a schema of its own on PostgreSQL, a file with the segment in its name on
+     * SQLite, a database name with the segment appended on IndexedDB and
+     * Capacitor. See `StorageResolutionOptions.segment`.
+     *
+     * @example
+     * ```typescript
+     * // AgentOS's tables beside the app's, in one PostgreSQL database
+     * const agentos = await createDatabase({ url: process.env.DATABASE_URL, segment: 'agentos' });
+     * ```
+     */
+    segment?: string;
+    /**
+     * The logger for this call's resolver lines (pino's fits). Default: the one
+     * `setStorageLogger()` set, else the console.
+     */
+    logger?: StorageLogger;
+}
+/**
+ * Create a database connection.
+ * Automatically picks the best database for your environment.
+ *
+ * @example
+ * ```typescript
+ * // The local default: better-sqlite3 (sql.js without it) on Node, IndexedDB in
+ * // a browser. DATABASE_URL in the environment does not change it.
+ * const db = await createDatabase();
+ *
+ * // PostgreSQL from DATABASE_URL on a server; strict fails when it is unset
+ * // instead of opening a local file
+ * const db = await createDatabase({
+ *   url: process.env.DATABASE_URL,
+ *   strict: true
+ * });
+ *
+ * // Specify file path
+ * const db = await createDatabase({
+ *   file: './my-app.db'
+ * });
+ *
+ * // Full PostgreSQL config
+ * const db = await createDatabase({
+ *   postgres: {
+ *     host: 'db.example.com',
+ *     database: 'myapp',
+ *     user: 'dbuser',
+ *     password: process.env.DB_PASSWORD,
+ *     ssl: true
+ *   }
+ * });
+ * ```
+ */
+/**
+ * Create (or auto-resolve) the most appropriate database adapter for the current
+ * runtime environment. Priority selection logic:
+ *
+ * 1. Explicit `options.priority` (caller-specified) wins entirely.
+ * 2. Explicit `options.type` is mapped to a single adapter priority.
+ * 3. Otherwise we auto-detect environment:
+ *    - Browser: ['indexeddb', 'sqljs']: the database is kept in IndexedDB,
+ *      with in-memory sql.js where IndexedDB cannot open. `file: ':memory:'`
+ *      (`createMemoryDatabase()`) keeps ['sqljs'], in memory.
+ *    - A Capacitor app on a phone: ['capacitor', 'indexeddb', 'sqljs'], as
+ *      the resolver chooses.
+ *    - Deno: ['sqljs']
+ *    - Node.js with a Postgres URL, or Postgres options that name a server:
+ *      ['postgres']. There is no fallback to SQLite: data meant for Postgres
+ *      would land in a local file. DATABASE_URL in the environment does not
+ *      count here.
+ *    - Node.js otherwise: ['better-sqlite3', 'sqljs'] (native first, wasm fallback)
+ *
+ * With `strict` on Node, a `url` or `postgres` option that names no server
+ * throws instead of choosing the local default (unless `file` is given), and a
+ * postgres candidate that fails ends resolution.
+ *
+ * The function never throws solely due to a native adapter absence; it falls
+ * back to next candidates. Only when no candidate can open will it bubble an error.
+ */
+export declare function createDatabase(options?: DatabaseOptions): Promise<StorageAdapter>;
+/**
+ * Connect to a remote database.
+ *
+ * @example
+ * ```typescript
+ * // Simple connection string
+ * const db = await connectDatabase('postgresql://user:pass@host/db');
+ *
+ * // With full config
+ * const db = await connectDatabase({
+ *   host: 'db.example.com',
+ *   database: 'myapp',
+ *   user: 'dbuser',
+ *   password: process.env.DB_PASSWORD,
+ *   ssl: true
+ * });
+ * ```
+ */
+export declare function connectDatabase(config: string | PostgresAdapterOptions): Promise<StorageAdapter>;
+/**
+ * Open a local database file.
+ *
+ * @example
+ * ```typescript
+ * // SQLite file
+ * const db = await openDatabase('./my-app.db');
+ *
+ * // In-memory database
+ * const db = await openDatabase(':memory:');
+ * ```
+ */
+export declare function openDatabase(filePath: string): Promise<StorageAdapter>;
+/**
+ * Create an in-memory database.
+ * Perfect for testing or temporary storage.
+ *
+ * @example
+ * ```typescript
+ * const db = await createMemoryDatabase();
+ * await db.exec('CREATE TABLE users (id INTEGER, name TEXT)');
+ * ```
+ */
+export declare function createMemoryDatabase(): Promise<StorageAdapter>;
+export { resolveStorageAdapter } from './resolver.js';
+//# sourceMappingURL=database.d.ts.map