@framers/sql-storage-adapter 0.3.5 → 0.4.2

package/dist/core/contracts/performance.js

@@ -0,0 +1,186 @@
+/**
+ * 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 }
+ * });
+ * ```
+ */
+/**
+ * Default settings for each performance tier.
+ *
+ * @internal
+ */
+export const TIER_DEFAULTS = {
+    fast: {
+        cacheEnabled: true,
+        cacheTtlMs: 30000,
+        cacheMaxEntries: 500,
+        batchWrites: true,
+        batchFlushIntervalMs: 50,
+        batchMaxSize: 100,
+        validateSql: false,
+        trackMetrics: false,
+        slowQueryThresholdMs: 500,
+        retryOnError: false,
+        maxRetries: 1,
+        retryDelayMs: 100,
+    },
+    balanced: {
+        cacheEnabled: true,
+        cacheTtlMs: 5000,
+        cacheMaxEntries: 1000,
+        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: 60000,
+        cacheMaxEntries: 200,
+        batchWrites: true,
+        batchFlushIntervalMs: 500,
+        batchMaxSize: 20,
+        validateSql: false,
+        trackMetrics: false,
+        slowQueryThresholdMs: 200,
+        retryOnError: true,
+        maxRetries: 3,
+        retryDelayMs: 500,
+    },
+};
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * 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 function resolvePerformanceConfig(config = {}) {
+    const tier = config.tier ?? 'balanced';
+    if (tier === 'custom') {
+        // Custom tier requires all fields to be specified
+        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,
+    };
+}
+/**
+ * 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 function isTransientError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const message = error.message.toLowerCase();
+    // Common transient error patterns
+    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));
+}
+//# sourceMappingURL=performance.js.map

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

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

package/dist/types/index.d.ts

@@ -2,10 +2,28 @@
  * Aggregated type exports for scenarios where consumers import from
  * "@framers/sql-storage-adapter/types". Ensures Node's specifier
  * resolution finds an index module alongside the compiled artifacts.
+ *
+ * @packageDocumentation
+ * @module @framers/sql-storage-adapter/types
+ *
+ * @remarks
+ * This module re-exports all public types from the sql-storage-adapter package.
+ * Import from here when you only need types without runtime code.
+ *
+ * @example
+ * ```typescript
+ * import type {
+ *   StorageAdapter,
+ *   PerformanceConfig,
+ *   StorageHooks
+ * } from '@framers/sql-storage-adapter/types';
+ * ```
  */
 export * from '../core/contracts';
 export * from '../core/contracts/context';
 export * from '../core/contracts/events';
 export * from '../core/contracts/extensions';
 export * from '../core/contracts/limitations';
+export * from '../core/contracts/performance';
+export * from '../core/contracts/hooks';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC"}

package/dist/types/index.js

@@ -2,10 +2,28 @@
  * Aggregated type exports for scenarios where consumers import from
  * "@framers/sql-storage-adapter/types". Ensures Node's specifier
  * resolution finds an index module alongside the compiled artifacts.
+ *
+ * @packageDocumentation
+ * @module @framers/sql-storage-adapter/types
+ *
+ * @remarks
+ * This module re-exports all public types from the sql-storage-adapter package.
+ * Import from here when you only need types without runtime code.
+ *
+ * @example
+ * ```typescript
+ * import type {
+ *   StorageAdapter,
+ *   PerformanceConfig,
+ *   StorageHooks
+ * } from '@framers/sql-storage-adapter/types';
+ * ```
  */
 export * from '../core/contracts/index.js';
 export * from '../core/contracts/context.js';
 export * from '../core/contracts/events.js';
 export * from '../core/contracts/extensions.js';
 export * from '../core/contracts/limitations.js';
+export * from '../core/contracts/performance.js';
+export * from '../core/contracts/hooks.js';
 //# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/sql-storage-adapter",
-  "version": "0.3.5",
+  "version": "0.4.2",
   "description": "Robust cross-platform SQL storage abstraction with automatic fallbacks and runtime detection",
   "type": "module",
   "main": "dist/index.js",
@@ -24,8 +24,8 @@
   ],
   "scripts": {
     "clean": "rimraf dist tsconfig.build.tsbuildinfo",
-    "build": "pnpm run clean && pnpm exec tsc -p tsconfig.build.json && node scripts/fix-esm-imports.mjs",
-    "prepublishOnly": "pnpm run build && pnpm run test",
+    "build": "npm run clean && npx tsc -p tsconfig.build.json && node scripts/fix-esm-imports.mjs",
+    "prepublishOnly": "npm run build && npm run test",
     "lint": "eslint \"src/**/*.{ts,tsx}\"",
     "lint:fix": "eslint \"src/**/*.{ts,tsx}\" --fix",
     "format": "prettier --write \"src/**/*.{ts,tsx,json,md}\"",
@@ -70,7 +70,7 @@
     "url": "https://github.com/framersai/sql-storage-adapter/issues",
     "email": "team@frame.dev"
   },
-  "homepage": "https://framersai.github.io/sql-storage-adapter",
+  "homepage": "https://framersai.github.io/sql-storage-adapter/",
   "sideEffects": false,
   "devDependencies": {
     "@aws-sdk/client-s3": "^3.709.0",