@framers/sql-storage-adapter 0.7.1 → 0.7.3

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

@@ -0,0 +1,260 @@
+/**
+ * @packageDocumentation
+ * Core type definitions for the SQL storage adapter abstraction.
+ *
+ * This package provides a unified interface for SQL storage across multiple platforms,
+ * with automatic fallback mechanisms and runtime detection.
+ */
+/**
+ * Supported storage capability flags.
+ *
+ * These flags indicate what features are available for each adapter implementation.
+ * Consumers should check these capabilities before attempting operations that may
+ * not be universally supported.
+ */
+export type StorageCapability = 'sync' | 'transactions' | 'wal' | 'locks' | 'persistence' | 'streaming' | 'batch' | 'prepared' | 'concurrent' | 'json' | 'arrays';
+/**
+ * Parameter payload accepted by storage statements.
+ *
+ * Parameters can be provided in multiple formats:
+ * - Named parameters: `{ name: 'John', age: 30 }` for statements like `WHERE name = @name`
+ * - Positional parameters: `['John', 30]` for statements like `WHERE name = ? AND age = ?`
+ * - No parameters: `undefined` or `null` for parameterless queries
+ */
+export type StorageParameters = undefined | null | Record<string, unknown> | Array<string | number | null | Uint8Array | unknown>;
+/**
+ * Result metadata for mutation statements (INSERT, UPDATE, DELETE).
+ */
+export interface StorageRunResult {
+    /** Number of rows affected by the statement. */
+    changes: number;
+    /** Row identifier (if available) returned by the underlying engine. */
+    lastInsertRowid?: string | number | null;
+}
+/**
+ * Batch operation descriptor for bulk operations.
+ */
+export interface BatchOperation {
+    /** SQL statement to execute */
+    statement: string;
+    /** Parameters for this specific operation */
+    parameters?: StorageParameters;
+}
+/**
+ * Result of a batch operation execution.
+ */
+export interface BatchResult {
+    /** Number of successfully executed operations */
+    successful: number;
+    /** Number of failed operations */
+    failed: number;
+    /** Individual results for each operation (if adapter supports it) */
+    results?: StorageRunResult[];
+    /** Errors for failed operations (if any) */
+    errors?: Array<{
+        index: number;
+        error: Error;
+    }>;
+}
+/**
+ * Options accepted when opening a storage adapter.
+ */
+export interface StorageOpenOptions {
+    /** Absolute path to the primary database file (when applicable). */
+    filePath?: string;
+    /** Connection string (PostgreSQL, etc.). */
+    connectionString?: string;
+    /** Optional flag to force read-only mode. */
+    readOnly?: boolean;
+    /** Arbitrary adapter-specific options bag. */
+    adapterOptions?: Record<string, unknown>;
+    /**
+     * SQLite: `true` turns foreign-key enforcement on and `false` turns it off
+     * (`PRAGMA foreign_keys`) when the adapter opens, and the setting holds
+     * when sql.js reopens its connection (a save, an export, an import). Left
+     * out, each engine keeps its default: better-sqlite3 is built with
+     * `SQLITE_DEFAULT_FOREIGN_KEYS=1` and enforces them; sql.js, IndexedDB and
+     * Capacitor do not. PostgreSQL always enforces foreign keys and ignores this.
+     */
+    foreignKeys?: boolean;
+}
+/**
+ * Core SQL storage adapter interface.
+ *
+ * Every adapter implementation must fulfill this contract to ensure
+ * compatibility across different SQL backends. Check the `capabilities`
+ * property to determine which optional features are supported.
+ *
+ * ## Error Handling
+ * All methods should throw meaningful errors when operations fail.
+ * Adapters should not silently fail or return undefined on errors.
+ *
+ * ## Thread Safety
+ * Adapters should document their thread-safety guarantees. SQLite adapters
+ * typically don't support concurrent writes, while PostgreSQL does.
+ */
+export interface StorageAdapter {
+    /** Identifier for logging/diagnostics (e.g., 'better-sqlite3', 'postgres'). */
+    readonly kind: string;
+    /** Capability flags indicating supported features. */
+    readonly capabilities: ReadonlySet<StorageCapability>;
+    /**
+     * Opens the underlying connection or initializes the backing store.
+     *
+     * @throws {Error} If connection cannot be established
+     * @example
+     * await adapter.open({ filePath: '/path/to/db.sqlite3' });
+     */
+    open(options?: StorageOpenOptions): Promise<void>;
+    /**
+     * Executes a mutation statement (INSERT, UPDATE, DELETE).
+     *
+     * @param statement - SQL statement to execute
+     * @param parameters - Optional parameters for the statement
+     * @returns Metadata about affected rows
+     * @throws {Error} If statement execution fails
+     * @example
+     * const result = await adapter.run('INSERT INTO users (name) VALUES (?)', ['John']);
+     * console.log(`Inserted with ID: ${result.lastInsertRowid}`);
+     */
+    run(statement: string, parameters?: StorageParameters): Promise<StorageRunResult>;
+    /**
+     * Retrieves a single row (or null if none found).
+     *
+     * @param statement - SQL SELECT statement
+     * @param parameters - Optional parameters for the statement
+     * @returns First row or null if no results
+     * @throws {Error} If query execution fails
+     * @example
+     * const user = await adapter.get<User>('SELECT * FROM users WHERE id = ?', [123]);
+     */
+    get<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T | null>;
+    /**
+     * Retrieves all rows returned by the statement.
+     *
+     * WARNING: For large result sets, this loads everything into memory.
+     * Consider using streaming (if supported) for large queries.
+     *
+     * @param statement - SQL SELECT statement
+     * @param parameters - Optional parameters for the statement
+     * @returns Array of all matching rows (empty array if none)
+     * @throws {Error} If query execution fails
+     * @example
+     * const users = await adapter.all<User>('SELECT * FROM users WHERE age > ?', [18]);
+     */
+    all<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T[]>;
+    /**
+     * Executes a script containing multiple SQL statements.
+     *
+     * Statements are typically delimited by semicolons. This is useful for
+     * running migrations or initialization scripts. No results are returned.
+     *
+     * @param script - SQL script with multiple statements
+     * @throws {Error} If any statement in the script fails
+     * @example
+     * await adapter.exec(`
+     *   CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);
+     *   CREATE INDEX idx_users_name ON users(name);
+     * `);
+     */
+    exec(script: string): Promise<void>;
+    /**
+     * Executes a callback within a database transaction.
+     *
+     * The transaction is automatically committed on success or rolled back
+     * on error. Nested transactions may not be supported by all adapters.
+     *
+     * @param fn - Async callback to execute within the transaction
+     * @returns Result of the callback function
+     * @throws {Error} Transaction is rolled back and error is re-thrown
+     * @example
+     * const result = await adapter.transaction(async (trx) => {
+     *   await trx.run('INSERT INTO accounts (balance) VALUES (?)', [100]);
+     *   await trx.run('INSERT INTO logs (action) VALUES (?)', ['account_created']);
+     *   return { success: true };
+     * });
+     */
+    transaction<T>(fn: (trx: StorageAdapter) => Promise<T>): Promise<T>;
+    /**
+     * Closes the underlying connection and releases resources.
+     *
+     * After calling close(), the adapter should not be used again.
+     * Always close adapters when done to prevent resource leaks.
+     *
+     * @example
+     * try {
+     *   await adapter.open();
+     *   // ... use adapter ...
+     * } finally {
+     *   await adapter.close();
+     * }
+     */
+    close(): Promise<void>;
+    /**
+     * Executes multiple operations in a batch (if supported).
+     *
+     * This is more efficient than executing operations individually,
+     * especially for bulk inserts. Check if 'batch' capability is present.
+     *
+     * @param operations - Array of operations to execute
+     * @returns Batch execution results
+     * @throws {Error} If adapter doesn't support batch operations
+     * @example
+     * if (adapter.capabilities.has('batch')) {
+     *   const result = await adapter.batch([
+     *     { statement: 'INSERT INTO users (name) VALUES (?)', parameters: ['Alice'] },
+     *     { statement: 'INSERT INTO users (name) VALUES (?)', parameters: ['Bob'] }
+     *   ]);
+     * }
+     */
+    batch?(operations: BatchOperation[]): Promise<BatchResult>;
+    /**
+     * Returns a prepared statement for repeated execution (if supported).
+     *
+     * Prepared statements improve performance for frequently executed queries
+     * and provide better protection against SQL injection. Check if 'prepared'
+     * capability is present.
+     *
+     * @param statement - SQL statement to prepare
+     * @returns Prepared statement handle
+     * @throws {Error} If adapter doesn't support prepared statements
+     */
+    prepare?<T = unknown>(statement: string): PreparedStatement<T>;
+}
+/**
+ * Prepared statement interface for repeated query execution.
+ */
+export interface PreparedStatement<T = unknown> {
+    run(parameters?: StorageParameters): Promise<StorageRunResult>;
+    get(parameters?: StorageParameters): Promise<T | null>;
+    all(parameters?: StorageParameters): Promise<T[]>;
+    finalize(): Promise<void>;
+}
+/**
+ * Shape of adapter factories returned by resolver modules.
+ */
+export type StorageAdapterFactory = () => Promise<StorageAdapter>;
+/**
+ * Error thrown when no adapter can be resolved.
+ */
+export declare class StorageResolutionError extends Error {
+    readonly causes: unknown[];
+    constructor(message: string, causes?: unknown[]);
+}
+/**
+ * Performance configuration types for cost/accuracy optimization.
+ * See `OPTIMIZATION_GUIDE.md` for detailed usage documentation.
+ */
+export * from './performance.js';
+/**
+ * Lifecycle hooks for extending adapter behavior.
+ * Designed for RAG integration, analytics, and auditing.
+ */
+export * from './hooks.js';
+export type { SqlDialect, JsonValueType, CastType, IntervalUnit, DateBucketUnit, ColumnKind } from './dialect.js';
+export type { IFullTextSearch } from './fts.js';
+export type { IBlobCodec } from './blobCodec.js';
+export type { IDatabaseExporter } from './exporter.js';
+export type { StorageFeatures } from './features.js';
+export { createStorageFeatures } from './features.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,41 @@
+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 __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var contracts_exports = {};
+__export(contracts_exports, {
+  StorageResolutionError: () => StorageResolutionError,
+  createStorageFeatures: () => import_features.createStorageFeatures
+});
+module.exports = __toCommonJS(contracts_exports);
+__reExport(contracts_exports, require("./performance.js"), module.exports);
+__reExport(contracts_exports, require("./hooks.js"), module.exports);
+var import_features = require("./features.js");
+class StorageResolutionError extends Error {
+  constructor(message, causes = []) {
+    super(message);
+    this.causes = causes;
+    this.name = "StorageResolutionError";
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StorageResolutionError,
+  createStorageFeatures,
+  ...require("./performance.js"),
+  ...require("./hooks.js")
+});

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

@@ -0,0 +1,46 @@
+/**
+ * Adapter-specific limitation definitions.
+ *
+ * This module provides concrete limitation specifications for each
+ * supported database adapter, enabling runtime introspection and
+ * automatic constraint enforcement.
+ */
+import type { AdapterLimitations } from './context.js';
+/**
+ * Limitations for better-sqlite3 adapter.
+ */
+export declare const BETTER_SQLITE3_LIMITATIONS: AdapterLimitations;
+/**
+ * Limitations for SQL.js adapter (WebAssembly SQLite).
+ */
+export declare const SQLJS_LIMITATIONS: AdapterLimitations;
+/**
+ * Limitations for Capacitor SQLite adapter (mobile).
+ */
+export declare const CAPACITOR_SQLITE_LIMITATIONS: AdapterLimitations;
+/**
+ * Limitations for PostgreSQL adapter.
+ */
+export declare const POSTGRES_LIMITATIONS: AdapterLimitations;
+/**
+ * Limitations for Supabase adapter (PostgreSQL with extensions).
+ */
+export declare const SUPABASE_LIMITATIONS: AdapterLimitations;
+/**
+ * Map adapter kinds to their limitation definitions.
+ */
+export declare const ADAPTER_LIMITATIONS_MAP: {
+    readonly 'better-sqlite3': AdapterLimitations;
+    readonly sqljs: AdapterLimitations;
+    readonly capacitor: AdapterLimitations;
+    readonly postgres: AdapterLimitations;
+    readonly supabase: AdapterLimitations;
+};
+/**
+ * Get limitations for a specific adapter kind.
+ *
+ * @param kind - Adapter kind
+ * @returns Adapter limitations
+ */
+export declare function getLimitationsForAdapter(kind: keyof typeof ADAPTER_LIMITATIONS_MAP): AdapterLimitations;
+//# sourceMappingURL=limitations.d.ts.map

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

@@ -0,0 +1,218 @@
+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 limitations_exports = {};
+__export(limitations_exports, {
+  ADAPTER_LIMITATIONS_MAP: () => ADAPTER_LIMITATIONS_MAP,
+  BETTER_SQLITE3_LIMITATIONS: () => BETTER_SQLITE3_LIMITATIONS,
+  CAPACITOR_SQLITE_LIMITATIONS: () => CAPACITOR_SQLITE_LIMITATIONS,
+  POSTGRES_LIMITATIONS: () => POSTGRES_LIMITATIONS,
+  SQLJS_LIMITATIONS: () => SQLJS_LIMITATIONS,
+  SUPABASE_LIMITATIONS: () => SUPABASE_LIMITATIONS,
+  getLimitationsForAdapter: () => getLimitationsForAdapter
+});
+module.exports = __toCommonJS(limitations_exports);
+function createPerformanceCharacteristics(concurrency, persistence, transactionIsolation, usesConnectionPool, asyncExecution) {
+  return {
+    concurrency,
+    persistence,
+    transactionIsolation,
+    usesConnectionPool,
+    asyncExecution
+  };
+}
+const BETTER_SQLITE3_LIMITATIONS = {
+  maxConnections: 1,
+  // Single connection (SQLite limitation)
+  maxStatementLength: 1e6,
+  // 1MB
+  maxBatchSize: void 0,
+  // No hard limit, but memory constrained
+  maxParameterSize: void 0,
+  // Limited by available memory
+  supportedDataTypes: ["INTEGER", "REAL", "TEXT", "BLOB", "NULL"],
+  unsupportedFeatures: ["streaming", "concurrent", "json", "arrays"],
+  performanceCharacteristics: createPerformanceCharacteristics(
+    "single",
+    "file",
+    ["SERIALIZABLE"],
+    // SQLite only supports serializable
+    false,
+    // No connection pooling
+    false
+    // Synchronous by default
+  ),
+  constraints: {
+    supportsWAL: true,
+    supportsInMemory: true,
+    requiresFilePath: false
+    // Can use :memory:
+  }
+};
+const SQLJS_LIMITATIONS = {
+  maxConnections: 1,
+  // Single connection
+  maxStatementLength: 1e6,
+  // 1MB
+  maxBatchSize: void 0,
+  maxParameterSize: void 0,
+  supportedDataTypes: ["INTEGER", "REAL", "TEXT", "BLOB", "NULL"],
+  unsupportedFeatures: ["streaming", "concurrent", "json", "arrays", "wal", "locks"],
+  performanceCharacteristics: createPerformanceCharacteristics(
+    "single",
+    "memory",
+    // Typically in-memory or manual file persistence
+    ["SERIALIZABLE"],
+    false,
+    true
+    // Async wrapper over sync WASM
+  ),
+  constraints: {
+    supportsWAL: false,
+    supportsInMemory: true,
+    requiresFilePath: false,
+    requiresWASM: true,
+    browserCompatible: true
+  }
+};
+const CAPACITOR_SQLITE_LIMITATIONS = {
+  maxConnections: 1,
+  // Mobile SQLite single connection
+  maxStatementLength: 1e6,
+  maxBatchSize: void 0,
+  maxParameterSize: void 0,
+  supportedDataTypes: ["INTEGER", "REAL", "TEXT", "BLOB", "NULL"],
+  unsupportedFeatures: ["streaming", "concurrent", "json", "arrays"],
+  performanceCharacteristics: createPerformanceCharacteristics(
+    "single",
+    "file",
+    ["SERIALIZABLE"],
+    false,
+    true
+    // Async through Capacitor bridge
+  ),
+  constraints: {
+    supportsWAL: true,
+    supportsInMemory: false,
+    // Mobile requires file persistence
+    requiresFilePath: true,
+    requiresCapacitor: true,
+    mobileOnly: true
+  }
+};
+const POSTGRES_LIMITATIONS = {
+  maxConnections: 100,
+  // Default pool size (configurable)
+  maxStatementLength: 1073741824,
+  // 1GB theoretical limit
+  maxBatchSize: 1e3,
+  // Recommended batch size
+  maxParameterSize: 1073741824,
+  // 1GB for BYTEA/TEXT
+  supportedDataTypes: [
+    "INTEGER",
+    "BIGINT",
+    "SMALLINT",
+    "SERIAL",
+    "BIGSERIAL",
+    "REAL",
+    "DOUBLE PRECISION",
+    "NUMERIC",
+    "DECIMAL",
+    "TEXT",
+    "VARCHAR",
+    "CHAR",
+    "BYTEA",
+    "BOOLEAN",
+    "DATE",
+    "TIME",
+    "TIMESTAMP",
+    "TIMESTAMPTZ",
+    "JSON",
+    "JSONB",
+    "UUID",
+    "ARRAY",
+    "HSTORE",
+    "XML"
+  ],
+  unsupportedFeatures: ["wal"],
+  // WAL is PostgreSQL-specific, not exposed as capability
+  performanceCharacteristics: createPerformanceCharacteristics(
+    "pooled",
+    "network",
+    ["READ UNCOMMITTED", "READ COMMITTED", "REPEATABLE READ", "SERIALIZABLE"],
+    true,
+    // Connection pooling
+    true
+    // Fully async
+  ),
+  constraints: {
+    supportsWAL: false,
+    // Not relevant for client connections
+    supportsInMemory: false,
+    requiresFilePath: false,
+    requiresNetwork: true,
+    supportsReplication: true,
+    supportsPartitioning: true
+  }
+};
+const SUPABASE_LIMITATIONS = {
+  maxConnections: 15,
+  // Supabase free tier default
+  maxStatementLength: 1073741824,
+  maxBatchSize: 1e3,
+  maxParameterSize: 1073741824,
+  supportedDataTypes: [
+    ...POSTGRES_LIMITATIONS.supportedDataTypes,
+    "VECTOR"
+    // pgvector extension
+  ],
+  unsupportedFeatures: [],
+  performanceCharacteristics: createPerformanceCharacteristics("pooled", "network", ["READ COMMITTED", "REPEATABLE READ", "SERIALIZABLE"], true, true),
+  constraints: {
+    supportsWAL: false,
+    supportsInMemory: false,
+    requiresFilePath: false,
+    requiresNetwork: true,
+    supportsReplication: true,
+    supportsPartitioning: true,
+    supportsRowLevelSecurity: true,
+    supportsRealtimeSubscriptions: true,
+    // Supabase-specific
+    managedService: true
+  }
+};
+const ADAPTER_LIMITATIONS_MAP = {
+  "better-sqlite3": BETTER_SQLITE3_LIMITATIONS,
+  "sqljs": SQLJS_LIMITATIONS,
+  "capacitor": CAPACITOR_SQLITE_LIMITATIONS,
+  "postgres": POSTGRES_LIMITATIONS,
+  "supabase": SUPABASE_LIMITATIONS
+};
+function getLimitationsForAdapter(kind) {
+  return ADAPTER_LIMITATIONS_MAP[kind];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ADAPTER_LIMITATIONS_MAP,
+  BETTER_SQLITE3_LIMITATIONS,
+  CAPACITOR_SQLITE_LIMITATIONS,
+  POSTGRES_LIMITATIONS,
+  SQLJS_LIMITATIONS,
+  SUPABASE_LIMITATIONS,
+  getLimitationsForAdapter
+});