@framers/sql-storage-adapter 0.1.0

package/dist/database.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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 './types';
+import { type AdapterKind } from './resolver';
+import type { PostgresAdapterOptions } from './adapters/postgresAdapter';
+import type { CapacitorAdapterOptions } from './adapters/capacitorSqliteAdapter';
+/**
+ * Database connection options.
+ */
+export interface DatabaseOptions {
+    /**
+     * Database URL (e.g., postgresql://user:pass@host/db).
+     * If provided, PostgreSQL will be used.
+     */
+    url?: string;
+    /**
+     * File path for SQLite database.
+     * Used for local/offline storage.
+     */
+    file?: string;
+    /**
+     * PostgreSQL-specific configuration.
+     * Automatically uses PostgreSQL when provided.
+     */
+    postgres?: PostgresAdapterOptions;
+    /**
+     * Mobile (Capacitor) configuration.
+     * Automatically detected on mobile platforms.
+     */
+    mobile?: CapacitorAdapterOptions;
+    /**
+     * 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[];
+}
+/**
+ * Create a database connection.
+ * Automatically picks the best database for your environment.
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect (PostgreSQL in prod, SQLite locally)
+ * const db = await createDatabase();
+ *
+ * // Specify database URL
+ * const db = await createDatabase({
+ *   url: process.env.DATABASE_URL
+ * });
+ *
+ * // 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
+ *   }
+ * });
+ * ```
+ */
+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';
+//# sourceMappingURL=database.d.ts.map

package/dist/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAwD,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACpG,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAElC;;;OAGG;IACH,MAAM,CAAC,EAAE,uBAAuB,CAAC;IAEjC;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAE/D;;;OAGG;IACH,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,cAAc,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgD3F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,GAAG,sBAAsB,GACtC,OAAO,CAAC,cAAc,CAAC,CAKzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAE5E;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,cAAc,CAAC,CAEpE;AAGD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}

package/dist/database.js

@@ -0,0 +1,136 @@
+/**
+ * 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 { resolveStorageAdapter } from './resolver';
+/**
+ * Create a database connection.
+ * Automatically picks the best database for your environment.
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect (PostgreSQL in prod, SQLite locally)
+ * const db = await createDatabase();
+ *
+ * // Specify database URL
+ * const db = await createDatabase({
+ *   url: process.env.DATABASE_URL
+ * });
+ *
+ * // 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
+ *   }
+ * });
+ * ```
+ */
+export async function createDatabase(options = {}) {
+    const resolverOptions = {};
+    // Handle URL (PostgreSQL)
+    if (options.url) {
+        resolverOptions.postgres = { connectionString: options.url };
+    }
+    // Handle PostgreSQL config
+    if (options.postgres) {
+        resolverOptions.postgres = options.postgres;
+    }
+    // Handle file path
+    if (options.file) {
+        resolverOptions.filePath = options.file;
+    }
+    // Handle mobile config
+    if (options.mobile) {
+        resolverOptions.capacitor = options.mobile;
+    }
+    // Handle explicit type
+    if (options.type) {
+        const typeMap = {
+            'postgres': 'postgres',
+            'sqlite': 'better-sqlite3',
+            'browser': 'sqljs',
+            'mobile': 'capacitor',
+            'memory': 'better-sqlite3' // Memory mode uses better-sqlite3 with :memory:
+        };
+        resolverOptions.priority = [typeMap[options.type]];
+        // Set in-memory mode for SQLite
+        if (options.type === 'memory') {
+            resolverOptions.filePath = ':memory:';
+        }
+    }
+    // Handle custom priority
+    if (options.priority) {
+        resolverOptions.priority = options.priority;
+    }
+    const adapter = await resolveStorageAdapter(resolverOptions);
+    await adapter.open(resolverOptions.openOptions);
+    return adapter;
+}
+/**
+ * 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 async function connectDatabase(config) {
+    if (typeof config === 'string') {
+        return createDatabase({ url: config });
+    }
+    return createDatabase({ postgres: config });
+}
+/**
+ * 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 async function openDatabase(filePath) {
+    return createDatabase({ file: filePath });
+}
+/**
+ * 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 async function createMemoryDatabase() {
+    return openDatabase(':memory:');
+}
+// Re-export for backwards compatibility
+export { resolveStorageAdapter } from './resolver';
+//# sourceMappingURL=database.js.map

package/dist/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,qBAAqB,EAAmD,MAAM,YAAY,CAAC;AA6CpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,UAA2B,EAAE;IAChE,MAAM,eAAe,GAA6B,EAAE,CAAC;IAErD,0BAA0B;IAC1B,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAChB,eAAe,CAAC,QAAQ,GAAG,EAAE,gBAAgB,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;IAC/D,CAAC;IAED,2BAA2B;IAC3B,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,eAAe,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC9C,CAAC;IAED,mBAAmB;IACnB,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,eAAe,CAAC,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1C,CAAC;IAED,uBAAuB;IACvB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,eAAe,CAAC,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAC7C,CAAC;IAED,uBAAuB;IACvB,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,MAAM,OAAO,GAAG;YACd,UAAU,EAAE,UAAU;YACtB,QAAQ,EAAE,gBAAgB;YAC1B,SAAS,EAAE,OAAO;YAClB,QAAQ,EAAE,WAAW;YACrB,QAAQ,EAAE,gBAAgB,CAAE,gDAAgD;SACpE,CAAC;QACX,eAAe,CAAC,QAAQ,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAEnD,gCAAgC;QAChC,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9B,eAAe,CAAC,QAAQ,GAAG,UAAU,CAAC;QACxC,CAAC;IACH,CAAC;IAED,yBAAyB;IACzB,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,eAAe,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC9C,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,qBAAqB,CAAC,eAAe,CAAC,CAAC;IAC7D,MAAM,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;IAChD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAuC;IAEvC,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,cAAc,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,cAAc,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAgB;IACjD,OAAO,cAAc,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,OAAO,YAAY,CAAC,UAAU,CAAC,CAAC;AAClC,CAAC;AAED,wCAAwC;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export * from './types';
+export * from './types/extensions';
+export * from './types/context';
+export * from './types/events';
+export * from './types/limitations';
+export * from './adapters/betterSqliteAdapter';
+export * from './adapters/sqlJsAdapter';
+export * from './adapters/capacitorSqliteAdapter';
+export * from './adapters/postgresAdapter';
+export * from './database';
+export * from './resolver';
+export * from './utils/dataExport';
+export * from './utils/dataImport';
+export * from './utils/migration';
+export * from './utils/cloudBackup';
+export * from './utils/syncManager';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,SAAS,CAAC;AAGxB,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AAGpC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,yBAAyB,CAAC;AACxC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAG3C,cAAc,YAAY,CAAC;AAG3B,cAAc,YAAY,CAAC;AAG3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+// Core types and interfaces
+export * from './types';
+// Extended types for advanced features
+export * from './types/extensions';
+export * from './types/context';
+export * from './types/events';
+export * from './types/limitations';
+// Adapter implementations
+export * from './adapters/betterSqliteAdapter';
+export * from './adapters/sqlJsAdapter';
+export * from './adapters/capacitorSqliteAdapter';
+export * from './adapters/postgresAdapter';
+// High-level API (recommended)
+export * from './database';
+// Low-level resolver (advanced usage)
+export * from './resolver';
+// Data export/import/migration utilities
+export * from './utils/dataExport';
+export * from './utils/dataImport';
+export * from './utils/migration';
+// Cloud backup and scheduled backup utilities
+export * from './utils/cloudBackup';
+// Sync manager for offline/online hybrid databases
+export * from './utils/syncManager';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,cAAc,SAAS,CAAC;AAExB,uCAAuC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AAEpC,0BAA0B;AAC1B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,yBAAyB,CAAC;AACxC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAE3C,+BAA+B;AAC/B,cAAc,YAAY,CAAC;AAE3B,sCAAsC;AACtC,cAAc,YAAY,CAAC;AAE3B,yCAAyC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAElC,8CAA8C;AAC9C,cAAc,qBAAqB,CAAC;AAEpC,mDAAmD;AACnD,cAAc,qBAAqB,CAAC"}

package/dist/resolver.d.ts

@@ -0,0 +1,24 @@
+import type { StorageAdapter, StorageOpenOptions } from './types';
+import type { AdapterKind } from './types/context';
+import { type CapacitorAdapterOptions } from './adapters/capacitorSqliteAdapter';
+export type { AdapterKind } from './types/context';
+export interface StorageResolutionOptions {
+    /** Absolute path for sqlite file (used by better-sqlite3/sql.js when persistence is desired). */
+    filePath?: string;
+    /** Explicit adapter priority override. */
+    priority?: AdapterKind[];
+    /** Options passed to the Capacitor adapter. */
+    capacitor?: CapacitorAdapterOptions;
+    /** Options passed to the Postgres adapter. */
+    postgres?: {
+        connectionString?: string;
+    };
+    /** Options forwarded to adapter.open. */
+    openOptions?: StorageOpenOptions;
+}
+/**
+ * Resolves the most appropriate storage adapter for the current runtime.
+ * Tries candidates in the supplied priority order and falls back when one fails.
+ */
+export declare const resolveStorageAdapter: (options?: StorageResolutionOptions) => Promise<StorageAdapter>;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAyB,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAEzF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD,OAAO,EAAgC,KAAK,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAI/G,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,MAAM,WAAW,wBAAwB;IACvC,iGAAiG;IACjG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,uBAAuB,CAAC;IACpC,8CAA8C;IAC9C,QAAQ,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,yCAAyC;IACzC,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAgBD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAU,UAAS,wBAA6B,KAAG,OAAO,CAAC,cAAc,CA4E1G,CAAC"}

package/dist/resolver.js

@@ -0,0 +1,91 @@
+import path from 'path';
+import { StorageResolutionError } from './types';
+import { createBetterSqliteAdapter } from './adapters/betterSqliteAdapter';
+import { createSqlJsAdapter } from './adapters/sqlJsAdapter';
+import { createCapacitorSqliteAdapter } from './adapters/capacitorSqliteAdapter';
+import { createPostgresAdapter } from './adapters/postgresAdapter';
+const isCapacitorRuntime = () => {
+    if (typeof window === 'undefined') {
+        return false;
+    }
+    const maybeCapacitor = window.Capacitor;
+    return Boolean(maybeCapacitor?.isNativePlatform?.());
+};
+/**
+ * Resolves the most appropriate storage adapter for the current runtime.
+ * Tries candidates in the supplied priority order and falls back when one fails.
+ */
+export const resolveStorageAdapter = async (options = {}) => {
+    const envOverride = process.env.STORAGE_ADAPTER;
+    const postgresConnection = options.postgres?.connectionString ?? process.env.DATABASE_URL ?? undefined;
+    const filePath = options.filePath ?? path.join(process.cwd(), 'db_data', 'app.sqlite3');
+    const defaultPriority = (() => {
+        if (options.priority && options.priority.length > 0) {
+            return options.priority;
+        }
+        if (envOverride) {
+            return [envOverride];
+        }
+        if (isCapacitorRuntime()) {
+            return ['capacitor', 'sqljs'];
+        }
+        if (postgresConnection) {
+            return ['postgres', 'better-sqlite3', 'sqljs'];
+        }
+        return ['better-sqlite3', 'sqljs'];
+    })();
+    const candidates = defaultPriority.map((name) => {
+        switch (name) {
+            case 'postgres': {
+                return {
+                    name,
+                    factory: async () => {
+                        if (!postgresConnection) {
+                            throw new Error('DATABASE_URL or postgres connection string not provided.');
+                        }
+                        return createPostgresAdapter(postgresConnection);
+                    },
+                    openOptions: { connectionString: postgresConnection }
+                };
+            }
+            case 'better-sqlite3':
+                return {
+                    name,
+                    factory: async () => createBetterSqliteAdapter(filePath),
+                    openOptions: { filePath }
+                };
+            case 'capacitor':
+                return {
+                    name,
+                    factory: async () => createCapacitorSqliteAdapter(options.capacitor)
+                };
+            case 'sqljs':
+            default:
+                return {
+                    name: 'sqljs',
+                    factory: async () => createSqlJsAdapter(),
+                    openOptions: { filePath }
+                };
+        }
+    });
+    const errors = [];
+    for (const candidate of candidates) {
+        try {
+            const adapter = await candidate.factory();
+            const openOptions = {
+                ...candidate.openOptions,
+                ...options.openOptions,
+            };
+            await adapter.open(openOptions);
+            console.info(`[StorageAdapter] Using adapter "${candidate.name}".`);
+            return adapter;
+        }
+        catch (error) {
+            console.warn(`[StorageAdapter] Failed to initialise adapter "${candidate.name}".`, error);
+            errors.push(error);
+            continue;
+        }
+    }
+    throw new StorageResolutionError('Unable to resolve a storage adapter for the current environment.', errors);
+};
+//# sourceMappingURL=resolver.js.map

package/dist/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"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"}

package/dist/types/context.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Runtime context and introspection types for storage adapters.
+ *
+ * These types enable runtime inspection of adapter capabilities,
+ * connection state, and performance characteristics without requiring
+ * developers to manually check capability flags.
+ */
+import type { StorageAdapter, StorageCapability } from '../types';
+import type { PerformanceMetrics } from './extensions';
+/**
+ * Type of database connection.
+ */
+export type ConnectionType = 'file' | 'memory' | 'network';
+/**
+ * Database engine identifier.
+ */
+export type DatabaseEngine = 'sqlite' | 'postgres' | 'mysql' | 'sqljs' | 'capacitor' | 'supabase';
+/**
+ * Adapter identifier used by the resolver.
+ */
+export type AdapterKind = 'postgres' | 'better-sqlite3' | 'capacitor' | 'sqljs' | 'supabase';
+/**
+ * Information about the current database connection.
+ */
+export interface ConnectionInfo {
+    /** Type of connection (file-based, in-memory, or network) */
+    type: ConnectionType;
+    /** Database engine being used */
+    engine: DatabaseEngine;
+    /** Engine version (if available) */
+    version?: string;
+    /** File path for file-based databases */
+    filePath?: string;
+    /** Host for network databases */
+    host?: string;
+    /** Database name for network databases */
+    database?: string;
+    /** Whether the connection is read-only */
+    readOnly: boolean;
+    /** When the connection was established */
+    connectedAt?: Date;
+}
+/**
+ * Concurrency model supported by the adapter.
+ */
+export type ConcurrencyModel = 'single' | 'pooled' | 'unlimited';
+/**
+ * Persistence model of the adapter.
+ */
+export type PersistenceModel = 'memory' | 'file' | 'network';
+/**
+ * Performance characteristics of an adapter.
+ */
+export interface PerformanceCharacteristics {
+    /** Concurrency model */
+    concurrency: ConcurrencyModel;
+    /** Persistence model */
+    persistence: PersistenceModel;
+    /** Supported transaction isolation levels */
+    transactionIsolation: string[];
+    /** Whether the adapter uses connection pooling */
+    usesConnectionPool: boolean;
+    /** Whether queries are executed asynchronously */
+    asyncExecution: boolean;
+}
+/**
+ * Adapter-specific limitations and constraints.
+ */
+export interface AdapterLimitations {
+    /** Maximum number of concurrent connections (if applicable) */
+    maxConnections?: number;
+    /** Maximum length of a single SQL statement (in bytes/characters) */
+    maxStatementLength?: number;
+    /** Maximum number of operations in a single batch */
+    maxBatchSize?: number;
+    /** Maximum size of a single parameter value (in bytes) */
+    maxParameterSize?: number;
+    /** Data types supported by this adapter */
+    supportedDataTypes: string[];
+    /** Features that are explicitly not supported */
+    unsupportedFeatures: string[];
+    /** Performance characteristics */
+    performanceCharacteristics: PerformanceCharacteristics;
+    /** Additional adapter-specific constraints */
+    constraints?: Record<string, unknown>;
+}
+/**
+ * Current health and status of the adapter.
+ */
+export interface AdapterStatus {
+    /** Whether the adapter is functioning correctly */
+    healthy: boolean;
+    /** Whether the adapter is currently connected */
+    connected: boolean;
+    /** Last error encountered (if any) */
+    lastError?: Error;
+    /** Timestamp of last successful query */
+    lastQuery?: Date;
+    /** Total number of queries executed */
+    totalQueries: number;
+    /** Total number of errors encountered */
+    errors: number;
+    /** Time since adapter was opened (in milliseconds) */
+    uptime: number;
+    /** Performance metrics (if available) */
+    metrics?: PerformanceMetrics;
+}
+/**
+ * Runtime context providing introspection into the current adapter.
+ *
+ * This interface provides a high-level API for querying adapter
+ * capabilities, connection state, and performance without requiring
+ * manual capability flag checking.
+ *
+ * @example
+ * ```typescript
+ * const context = adapter.context;
+ *
+ * // Simple boolean checks
+ * if (context.supportsBatch) {
+ *   await adapter.batch(operations);
+ * }
+ *
+ * // Get detailed status
+ * const status = context.getStatus();
+ * console.log(`Healthy: ${status.healthy}, Queries: ${status.totalQueries}`);
+ *
+ * // Get limitations
+ * const limits = context.getLimitations();
+ * console.log(`Max batch size: ${limits.maxBatchSize}`);
+ * ```
+ */
+export interface AdapterContext {
+    /** Reference to the underlying adapter */
+    readonly adapter: StorageAdapter;
+    /** Adapter kind identifier */
+    readonly kind: AdapterKind;
+    /** Set of capabilities supported by this adapter */
+    readonly capabilities: ReadonlySet<StorageCapability>;
+    /** Whether the adapter is currently open/connected */
+    readonly isOpen: boolean;
+    /** Whether the adapter supports synchronous operations */
+    readonly supportsSync: boolean;
+    /** Whether the adapter supports ACID transactions */
+    readonly supportsTransactions: boolean;
+    /** Whether the adapter supports batch operations */
+    readonly supportsBatch: boolean;
+    /** Whether the adapter supports prepared statements */
+    readonly supportsPrepared: boolean;
+    /** Whether the adapter supports streaming results */
+    readonly supportsStreaming: boolean;
+    /** Whether the adapter supports Write-Ahead Logging */
+    readonly supportsWAL: boolean;
+    /** Whether the adapter supports native JSON operations */
+    readonly supportsJSON: boolean;
+    /** Whether the adapter supports array data types */
+    readonly supportsArrays: boolean;
+    /** Whether the adapter supports concurrent connections */
+    readonly supportsConcurrent: boolean;
+    /** Whether the adapter persists data across restarts */
+    readonly supportsPersistence: boolean;
+    /** Information about the current connection */
+    readonly connectionInfo: ConnectionInfo;
+    /**
+     * Check if a specific capability is supported.
+     *
+     * @param capability - The capability to check
+     * @returns True if the capability is supported
+     *
+     * @example
+     * ```typescript
+     * if (context.hasCapability('streaming')) {
+     *   // Use streaming API
+     * }
+     * ```
+     */
+    hasCapability(capability: StorageCapability): boolean;
+    /**
+     * Require a specific capability, throwing an error if not supported.
+     *
+     * @param capability - The required capability
+     * @throws {Error} If the capability is not supported
+     *
+     * @example
+     * ```typescript
+     * context.requiresCapability('transactions');
+     * // Safe to use transactions now
+     * await adapter.transaction(async (trx) => { ... });
+     * ```
+     */
+    requiresCapability(capability: StorageCapability): void;
+    /**
+     * Get detailed limitations and constraints for this adapter.
+     *
+     * @returns Adapter-specific limitations
+     *
+     * @example
+     * ```typescript
+     * const limits = context.getLimitations();
+     * if (operations.length > limits.maxBatchSize) {
+     *   // Split into chunks
+     * }
+     * ```
+     */
+    getLimitations(): AdapterLimitations;
+    /**
+     * Get current health and status information.
+     *
+     * @returns Current adapter status
+     *
+     * @example
+     * ```typescript
+     * const status = context.getStatus();
+     * if (!status.healthy) {
+     *   logger.error('Database unhealthy', status.lastError);
+     * }
+     * ```
+     */
+    getStatus(): AdapterStatus;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/types/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/types/context.ts"],"names":[],"mappings":"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"}