@framers/sql-storage-adapter 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Framers
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2025 Framers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -1,363 +1,146 @@
-# SQL Storage Adapter
-
-[![npm version](https://img.shields.io/npm/v/@framers/sql-storage-adapter.svg)](https://www.npmjs.com/package/@framers/sql-storage-adapter)
-[![CI](https://github.com/wearetheframers/sql-storage-adapter/actions/workflows/ci.yml/badge.svg)](https://github.com/wearetheframers/sql-storage-adapter/actions/workflows/ci.yml)
-[![codecov](https://codecov.io/gh/wearetheframers/sql-storage-adapter/branch/master/graph/badge.svg)](https://codecov.io/gh/wearetheframers/sql-storage-adapter)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
-
-> One SQL interface for Node.js, browsers, and mobile apps. Write your database code once, run it anywhere.
-
-**[Documentation](https://wearetheframers.github.io/sql-storage-adapter/)** | **[GitHub](https://github.com/wearetheframers/sql-storage-adapter)** | **[NPM](https://www.npmjs.com/package/@framers/sql-storage-adapter)**
-
-## Why?
-
-Build apps that work across platforms without rewriting database code:
-- 🖥️ **Desktop** (Electron) - fast local storage with better-sqlite3
-- 🌐 **Web** - in-browser SQL with sql.js (WebAssembly)
-- 📱 **Mobile** (Capacitor/React Native) - native SQLite
-- ☁️ **Server** - PostgreSQL or SQLite
-
-```typescript
-import { createDatabase } from '@framers/sql-storage-adapter';
-
-// Auto-picks the best adapter for your environment
-const db = await createDatabase();
-
-// Same code everywhere
-await db.run('INSERT INTO users (name) VALUES (?)', ['Alice']);
-const user = await db.get('SELECT * FROM users WHERE id = ?', [1]);
-```
-
-## Installation
-
-```bash
-npm install @framers/sql-storage-adapter
-
-# Install adapters you need:
-npm install better-sqlite3      # Desktop (Node.js/Electron)
-npm install pg                  # PostgreSQL (servers)
-npm install @capacitor-community/sqlite  # Mobile (Capacitor)
-# sql.js included - no extra install needed
-```
-
-## Quick Start
-
-```typescript
-import { createDatabase } from '@framers/sql-storage-adapter';
-
-// Create database (auto-detects best option)
-const db = await createDatabase();
-
-// Create table
-await db.exec(`
-  CREATE TABLE IF NOT EXISTS todos (
-    id INTEGER PRIMARY KEY,
-    task TEXT NOT NULL,
-    done INTEGER DEFAULT 0
-  )
-`);
-
-// Insert data
-await db.run('INSERT INTO todos (task) VALUES (?)', ['Buy groceries']);
-
-// Query data
-const todos = await db.all('SELECT * FROM todos WHERE done = 0');
-
-// Clean up
-await db.close();
-```
-
-## Core API
-
-```typescript
-// Execute SQL (no results)
-await db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
-
-// Run mutation (INSERT/UPDATE/DELETE)
-const result = await db.run('INSERT INTO users (name) VALUES (?)', ['Alice']);
-console.log(result.lastInsertRowid);  // Auto-increment ID
-
-// Get single row
-const user = await db.get<User>('SELECT * FROM users WHERE id = ?', [1]);
-
-// Get all rows
-const users = await db.all<User>('SELECT * FROM users');
-
-// Transactions (automatic commit/rollback)
-await db.transaction(async (tx) => {
-  await tx.run('INSERT INTO users (name) VALUES (?)', ['Bob']);
-  await tx.run('INSERT INTO posts (user_id, title) VALUES (?, ?)', [1, 'Hello']);
-});
-
-// Batch operations (if supported)
-if (db.capabilities.has('batch')) {
-  await db.batch([
-    { statement: 'INSERT INTO users (name) VALUES (?)', parameters: ['Alice'] },
-    { statement: 'INSERT INTO users (name) VALUES (?)', parameters: ['Bob'] }
-  ]);
-}
-
-// Close connection
-await db.close();
-```
-
-## Adapter Selection
-
-Auto-detection order:
-
-```
-🖥️ Node.js:     better-sqlite3 → sql.js
-🌐 Browser:     sql.js
-📱 Mobile:      capacitor-sqlite → sql.js
-☁️ Server:      postgres → better-sqlite3 → sql.js
-```
-
-Override with specific adapter:
-
-```typescript
-// Use PostgreSQL explicitly
-const db = await createDatabase({ 
-  url: 'postgresql://localhost/mydb' 
-});
-
-// Use SQLite explicitly
-const db = await createDatabase({ 
-  file: './app.db' 
-});
-
-// Custom priority
-const db = await createDatabase({
-  priority: ['postgres', 'better-sqlite3'],
-  postgres: { connectionString: process.env.DATABASE_URL },
-  filePath: './fallback.db'
-});
-```
-
-## Auto-Sync & Offline Support
-
-Build offline-first apps with automatic cloud sync:
-
-```typescript
-import { createSyncManager } from '@framers/sql-storage-adapter';
-
-const manager = await createSyncManager({
-  primary: './app.db',                     // Local SQLite
-  remote: process.env.DATABASE_URL,        // Cloud PostgreSQL
-  sync: {
-    mode: 'auto',                          // Auto-sync after writes
-    conflictStrategy: 'last-write-wins'
-  }
-});
-
-// Work offline
-await manager.db.run('INSERT INTO tasks (title) VALUES (?)', ['Buy milk']);
-
-// Sync manually when needed
-const result = await manager.sync();
-console.log(`Synced ${result.recordsSynced} records`);
-```
-
-**Sync Modes:**
-- `manual` - Call `sync()` explicitly (default)
-- `auto` - Syncs after writes (debounced)
-- `periodic` - Syncs every N seconds
-- `realtime` - Syncs immediately on every write
-- `on-reconnect` - Syncs when network returns
-
-**Conflict Strategies:**
-- `last-write-wins` - Newest timestamp wins (default)
-- `local-wins` - Local always wins
-- `remote-wins` - Server is authority
-- `merge` - Custom merge function
-- `keep-both` - Duplicate records
-
-📖 **[Complete Offline Sync Guide](./guides/OFFLINE_SYNC.md)** - 8 real-world examples with mobile optimization
-
-## Cloud Backups
-
-Automatic S3-compatible backups (AWS S3, Cloudflare R2, MinIO):
-
-```typescript
-import { S3Client } from '@aws-sdk/client-s3';
-import { createCloudBackupManager } from '@framers/sql-storage-adapter';
-
-const s3 = new S3Client({
-  region: 'us-east-1',
-  credentials: {
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!
-  }
-});
-
-const manager = createCloudBackupManager(db, s3, 'my-backups', {
-  interval: 3600000,  // Hourly backups
-  maxBackups: 24,     // Keep 24 backups
-  options: { compression: 'gzip' }
-});
-
-manager.start();  // Auto-backup every hour
-
-// Manual backup
-await manager.backupNow();
-
-// Restore
-await manager.restore('backups/my-database-2024-01-15.json.gz');
-```
-
-## Data Migration
-
-Export, import, and migrate between adapters:
-
-```typescript
-import { 
-  migrateLocalToSupabase,
-  exportAsJSON,
-  importFromJSON 
-} from '@framers/sql-storage-adapter';
-
-// Export to JSON
-const backup = await exportAsJSON(db, { 
-  tables: ['users', 'posts'],
-  includeSchema: true 
-});
-
-// Import from JSON
-await importFromJSON(db, backup, {
-  dropTables: true,
-  batchSize: 100
-});
-
-// Migrate SQLite → PostgreSQL
-const result = await migrateLocalToSupabase(sqliteDb, postgresDb, {
-  verify: true,
-  onConflict: 'replace'
-});
-
-console.log(`Migrated ${result.rowsImported} rows in ${result.duration}ms`);
-```
-
-## PostgreSQL Remote Connections
-
-Connect to hosted databases (AWS RDS, Heroku, Supabase, etc.):
-
-```typescript
-import { connectDatabase } from '@framers/sql-storage-adapter';
-
-// Auto-detect from DATABASE_URL
-const db = await connectDatabase(process.env.DATABASE_URL);
-
-// Or configure explicitly
-const db = await connectDatabase({
-  host: 'db.example.com',
-  database: 'myapp',
-  user: 'dbuser',
-  password: process.env.DB_PASSWORD,
-  ssl: true,
-  max: 20  // Connection pool size
-});
-
-// Same API as SQLite!
-const users = await db.all('SELECT * FROM users');
-```
-
-📖 **[PostgreSQL Remote Guide](./guides/POSTGRES_REMOTE_CONNECTION.md)** - Cloud provider examples & SSL config
-
-## Adapter Comparison
-
-| Adapter | Best For | Speed | Size | Concurrent |
-|---------|----------|-------|------|------------|
-| **PostgreSQL** | Production servers | ⚡⚡⚡ | N/A | ✅ Yes |
-| **better-sqlite3** | Desktop apps | ⚡⚡⚡ | 6 MB | ❌ No |
-| **SQL.js** | Browsers | ⚡ | 2.3 MB | ❌ No |
-| **Capacitor** | Mobile apps | ⚡⚡⚡ | ~1 MB | ❌ No |
-
-## TypeScript Support
-
-Full type safety with generics:
-
-```typescript
-interface User {
-  id: number;
-  name: string;
-  email: string;
-}
-
-// Type-safe queries
-const user = await db.get<User>('SELECT * FROM users WHERE id = ?', [1]);
-// user: User | null
-
-const users = await db.all<User>('SELECT * FROM users');
-// users: User[]
-
-// Runtime introspection
-const context = db.context;
-console.log('Adapter:', db.kind);
-console.log('Capabilities:', Array.from(db.capabilities));
-console.log('Max connections:', context.getLimitations().maxConnections);
-```
-
-## Event Monitoring
-
-Track queries and performance:
-
-```typescript
-db.events.on('query:error', (event) => {
-  console.error('Query failed:', event.statement, event.error);
-});
-
-db.events.on('performance:slow-query', (event) => {
-  if (event.duration > 1000) {
-    console.warn(`Slow query (${event.duration}ms):`, event.statement);
-  }
-});
-
-db.events.on('transaction:rollback', (event) => {
-  console.warn('Transaction rolled back:', event.error);
-});
-```
-
-## Examples
-
-Real-world usage in `examples/`:
-- `basic-usage.ts` - Getting started
-- `remote-postgres.ts` - Cloud database connections
-- `electron-app/` - Desktop app with better-sqlite3
-- `browser-extension/` - Chrome extension with SQL.js
-- `full-stack/` - Shared code frontend/backend
-- `offline-sync.ts` - Auto-sync patterns
-- `testing/` - Unit testing strategies
-
-## FAQ
-
-**Q: Which adapter should I use?**  
-Use `createDatabase()` - it auto-picks the best adapter for your environment.
-
-**Q: Can I switch adapters later?**  
-Yes. Use migration functions to move data between adapters.
-
-**Q: Is this production-ready?**  
-Yes. Built on battle-tested libraries (pg, better-sqlite3, sql.js). The adapter layer adds <1% overhead.
-
-**Q: What about schema migrations?**  
-Use any migration tool: [`node-pg-migrate`](https://github.com/salsita/node-pg-migrate), [`prisma`](https://www.prisma.io/), or raw SQL.
-
-**Q: How do I handle conflicts in sync?**  
-Use `conflictStrategy`: `last-write-wins` (default), `local-wins`, `remote-wins`, `merge`, or `keep-both`.
-
-**Q: Can I sync only on WiFi?**  
-Yes. Use `mode: 'manual'` and call `sync()` when `isOnWiFi === true`. See [Offline Sync Guide](./guides/OFFLINE_SYNC.md#1-mobile-app-with-wifi-only-sync).
-
-## Documentation
-
-- **[API Documentation](https://wearetheframers.github.io/sql-storage-adapter/)** - Complete TypeDoc reference
-- **[Offline Sync Guide](./guides/OFFLINE_SYNC.md)** - Comprehensive sync patterns
-- **[PostgreSQL Guide](./guides/POSTGRES_REMOTE_CONNECTION.md)** - Remote database setup
-- **[Architecture](./ARCHITECTURE.md)** - Design decisions
-
-## Contributing
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md)
-
-## License
-
-MIT © [The Framers](https://frame.dev)
+# SQL Storage Adapter
+
+<p align="center">
+  <a href="https://frame.dev" target="_blank" rel="noopener">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="./logos/frame-square-blue-dark-no-tagline.svg">
+      <source media="(prefers-color-scheme: light)" srcset="./logos/frame-square-blue-no-tagline.svg">
+      <img src="./logos/frame-square-blue-no-tagline.svg" alt="Frame.dev" width="200">
+    </picture>
+  </a>
+</p>
+
+[![npm version](https://img.shields.io/npm/v/@framers/sql-storage-adapter.svg?logo=npm&label=npm)](https://www.npmjs.com/package/@framers/sql-storage-adapter)
+[![CI](https://github.com/framersai/sql-storage-adapter/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/framersai/sql-storage-adapter/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/framersai/sql-storage-adapter/branch/master/graph/badge.svg)](https://codecov.io/gh/framersai/sql-storage-adapter)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/npm/l/@framers/sql-storage-adapter.svg)](./LICENSE)
+
+> Cross-platform SQL access for Node.js, web, and native runtimes with automatic adapter selection and consistent APIs.
+
+The SQL Storage Adapter provides a single, ergonomic interface over SQLite (native and WASM), PostgreSQL, Capacitor, and in-memory stores. It handles adapter discovery, capability detection, and advanced features like cloud backups so you can focus on your application logic.
+
+---
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Adapter Matrix](#adapter-matrix)
+- [Configuration & Resolution](#configuration--resolution)
+- [CI, Releases, and Badges](#ci-releases-and-badges)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- **Auto-detected adapters** – `createDatabase()` inspects environment signals and picks the best backend (native SQLite, PostgreSQL, Capacitor, sql.js, memory, etc.).
+- **Capability-aware API** – consistent CRUD, transactions, batching, and event hooks across adapters with runtime capability introspection.
+- **Cloud backups & migrations** – built-in backup manager with compression, retention policies, and restore helpers plus migration utilities.
+- **Portable packaging** – optional native dependencies; falls back to pure TypeScript/WASM adapters when native modules are unavailable.
+- **CI-first design** – Vitest coverage, Codecov integration, and GitHub Actions workflows for linting, testing, releasing, and npm publish/tag automation.
+
+## Installation
+
+```bash
+# Core package
+npm install @framers/sql-storage-adapter
+
+# Install only the adapters you plan to use
+npm install better-sqlite3            # Native SQLite for Node/Electron
+npm install pg                        # PostgreSQL
+npm install @capacitor-community/sqlite  # Capacitor / mobile
+# sql.js ships with the package (no extra install)
+```
+
+> Windows users: ensure the Visual Studio Build Tools (C++ workload) are installed before adding `better-sqlite3`. On Linux, install `python3`, `build-essential`, and `libssl-dev` prior to `npm install`.
+
+## Quick Start
+
+```typescript
+import { createDatabase } from '@framers/sql-storage-adapter';
+
+async function main() {
+  // Automatically selects the best adapter for the current runtime
+  const db = await createDatabase();
+
+  await db.exec(`
+    CREATE TABLE IF NOT EXISTS todos (
+      id INTEGER PRIMARY KEY,
+      task TEXT NOT NULL,
+      done INTEGER DEFAULT 0
+    )
+  `);
+
+  await db.run('INSERT INTO todos (task) VALUES (?)', ['Ship cross-platform builds']);
+  const items = await db.all<{ id: number; task: string; done: number }>('SELECT * FROM todos');
+  console.log(items);
+
+  await db.close();
+}
+
+main().catch((error) => {
+  console.error('Database bootstrap failed', error);
+  process.exit(1);
+});
+```
+
+## Adapter Matrix
+
+| Adapter | Package | Ideal for | Pros | Considerations |
+| --- | --- | --- | --- | --- |
+| `better-sqlite3` | `better-sqlite3` | Node/Electron, CLI, CI | Native performance, transactional semantics, WAL support | Needs native toolchain; version must match Node ABI |
+| `postgres` | `pg` | Hosted or on-prem PostgreSQL | Connection pooling, rich SQL features, cloud friendly | Requires `DATABASE_URL`/credentials |
+| `sqljs` | bundled | Browsers, serverless edge, native fallback | Pure WASM, no native deps | Write performance limited vs native, optional persistence |
+| `capacitor` | `@capacitor-community/sqlite` | Mobile (iOS/Android, Capacitor) | Native SQLite on mobile | Requires Capacitor runtime |
+| `memory` | built-in | Unit tests, storybooks, constrained sandboxes | Zero dependencies, instant startup | Non-durable, single-process only |
+
+## Configuration & Resolution
+
+- `resolveStorageAdapter` inspects:
+  - explicit options (`priority`, `type`, adapter configs),
+  - environment variables (`STORAGE_ADAPTER`, `DATABASE_URL`),
+  - runtime hints (Capacitor detection, browser globals).
+- Adapters are attempted in priority order until one opens successfully; a `StorageResolutionError` includes the full failure chain.
+- Provide `priority: ['memory', 'sqljs']` for browser bundles or tests where native modules shouldn’t load.
+- Use `createCloudBackupManager` for S3-compatible backups with gzip compression and retention limits.
+
+## CI, Releases, and Badges
+
+- GitHub Actions workflows:
+  - `ci.yml` runs lint, tests, and coverage on every branch.
+  - `release.yml` publishes new versions to npm, tags the commit (`vX.Y.Z`), and creates/updates the GitHub Release when `CHANGELOG.md` and `package.json` bump the version.
+- Check badge health whenever builds fail:
+  - CI badge should be green for `master`.
+  - Codecov badge updates after coverage reports upload.
+  - npm badge reflects the latest published version.
+- Manual verification commands:
+  ```bash
+  npm info @framers/sql-storage-adapter version
+  pnpm --filter sql-storage-adapter test
+  pnpm --filter sql-storage-adapter build
+  ```
+- See [RELEASING.md](./RELEASING.md) for the automated release flow, required secrets (`NPM_TOKEN`), and manual fallback steps.
+
+## Troubleshooting
+
+- **`better-sqlite3` cannot be required** – install native build tools before `npm install`, ensure Node version matches prebuilt binaries, or fall back to sql.js by setting `STORAGE_ADAPTER=sqljs`.
+- **Adapter resolution picks the wrong backend** – set `priority` or `STORAGE_ADAPTER` explicitly; register new adapters in `src/core/resolver.ts`.
+- **Cloud backup tests lock the database** – call `await db.close()` in test teardown; use the in-memory/sql.js fallback on runners without native SQLite.
+- **GitHub release missing** – confirm `release.yml` succeeded, `NPM_TOKEN` is configured, and the version bump is committed. Rerun the workflow if needed.
+- **Missing lock file in subtree mirror** – keep `pnpm-lock.yaml` committed so CI caches dependencies correctly when this package is mirrored out of a monorepo.
+
+## Contributing
+
+- Read [CONTRIBUTING.md](./CONTRIBUTING.md) for coding standards, lint/test commands, and pull request guidelines.
+- Architecture notes live in [ARCHITECTURE.md](./ARCHITECTURE.md); API docs can be regenerated with `pnpm --filter sql-storage-adapter run docs`.
+
+## License
+
+[MIT](./LICENSE)
+
+---
+
+<p align="center">
+  Built and maintained by <a href="https://frame.dev" target="_blank" rel="noopener">Frame.dev</a>
+</p>

package/dist/adapters/baseStorageAdapter.d.ts

@@ -27,7 +27,7 @@
  * }
  * ```
  */
-import type { StorageAdapter, StorageCapability, StorageOpenOptions, StorageParameters, StorageRunResult, BatchOperation, BatchResult, PreparedStatement } from '../types';
+import type { StorageAdapter, StorageCapability, StorageOpenOptions, StorageParameters, StorageRunResult, BatchOperation, BatchResult, PreparedStatement } from '../core/contracts';
 /**
  * Options for BaseStorageAdapter configuration.
  */

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

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

package/dist/adapters/betterSqliteAdapter.d.ts

@@ -1,4 +1,4 @@
-import type { StorageAdapter, StorageOpenOptions, StorageParameters, StorageRunResult, StorageCapability, BatchOperation, BatchResult } from '../types';
+import type { StorageAdapter, StorageOpenOptions, StorageParameters, StorageRunResult, StorageCapability, BatchOperation, BatchResult } from '../core/contracts';
 /**
  * Native SQLite adapter using better-sqlite3.
  *
@@ -23,6 +23,18 @@ import type { StorageAdapter, StorageOpenOptions, StorageParameters, StorageRunR
  * - Automatically enables WAL mode for better concurrency
  * - Handles database corruption with automatic recovery
  */
+/**
+ * Native SQLite adapter backed by the `better-sqlite3` module.
+ *
+ * Features:
+ * - Synchronous & high-performance local storage
+ * - WAL support, prepared statements, batched writes
+ * - Graceful degradation when the native module is absent
+ *
+ * Browser Safety:
+ * This class can be imported in browser bundles without immediate failure.
+ * A runtime error is only thrown if `open()` is invoked in a browser context.
+ */
 export declare class BetterSqliteAdapter implements StorageAdapter {
     private readonly defaultFilePath;
     readonly kind = "better-sqlite3";
@@ -37,6 +49,11 @@ export declare class BetterSqliteAdapter implements StorageAdapter {
      *                         Will be created if it doesn't exist.
      */
     constructor(defaultFilePath: string);
+    /**
+     * Open (or no-op if already open) the underlying native database.
+     *
+     * Throws a descriptive error if called in a browser environment.
+     */
     open(options?: StorageOpenOptions): Promise<void>;
     run(statement: string, parameters?: StorageParameters): Promise<StorageRunResult>;
     get<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T | null>;
@@ -60,5 +77,14 @@ export declare class BetterSqliteAdapter implements StorageAdapter {
 /**
  * Factory helper.
  */
+/**
+ * Factory helper for creating a BetterSqliteAdapter.
+ *
+ * Path Resolution:
+ * - Absolute paths are used as-is.
+ * - Relative paths are resolved against the current working directory instead
+ *   of the adapter file location (simpler & bundler neutral).
+ * - Special values like ':memory:' and 'file:' URIs are passed through.
+ */
 export declare const createBetterSqliteAdapter: (filePath: string) => StorageAdapter;
 //# sourceMappingURL=betterSqliteAdapter.d.ts.map

package/dist/adapters/betterSqliteAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"betterSqliteAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/betterSqliteAdapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AA6BxJ;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IAsB5C,OAAO,CAAC,QAAQ,CAAC,eAAe;IArB5C,SAAgB,IAAI,oBAAoB;IACxC,SAAgB,YAAY,EAAE,WAAW,CAAC,iBAAiB,CAAC,CAQzD;IAEH,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,EAAE,CAAqC;IAC/C,OAAO,CAAC,kBAAkB,CAA4C;IAEtE;;;;;OAKG;gBAC0B,eAAe,EAAE,MAAM;IAEvC,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBjD,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAOjF,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAOtF,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAOvE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnC,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAOnE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IASnC;;;;;;;;OAQG;IACU,KAAK,CAAC,UAAU,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IA+CtE,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,UAAU;CAKnB;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,GAAI,UAAU,MAAM,KAAG,cAU5D,CAAC"}
+{"version":3,"file":"betterSqliteAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/betterSqliteAdapter.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAiDjK;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;;;;;;;;;;;GAWG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IAsB5C,OAAO,CAAC,QAAQ,CAAC,eAAe;IArB5C,SAAgB,IAAI,oBAAoB;IACxC,SAAgB,YAAY,EAAE,WAAW,CAAC,iBAAiB,CAAC,CAQzD;IAEH,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,EAAE,CAAqC;IAC/C,OAAO,CAAC,kBAAkB,CAA4C;IAEtE;;;;;OAKG;gBAC0B,eAAe,EAAE,MAAM;IAEpD;;;;OAIG;IACU,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBjD,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAOjF,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAOtF,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAOvE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnC,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAOnE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IASnC;;;;;;;;OAQG;IACU,KAAK,CAAC,UAAU,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IA+CtE,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,UAAU;CAKnB;AAED;;GAEG;AACH;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,aAAc,MAAM,KAAG,cAQ5D,CAAC"}