@xnetjs/sqlite 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Smothers
+
+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

@@ -0,0 +1,220 @@
+# @xnetjs/sqlite
+
+Unified SQLite adapter for xNet across all platforms (Electron, Web, Expo).
+
+## Installation
+
+```bash
+pnpm add @xnetjs/sqlite
+```
+
+## Features
+
+- **Unified interface** -- Same `SQLiteAdapter` API across all platforms
+- **Platform adapters** -- better-sqlite3 (Electron), sqlite-wasm (Web), expo-sqlite (Expo)
+- **Schema management** -- Version tracking and migrations
+- **Full-text search** -- FTS5 integration helpers
+- **Diagnostics** -- Query analysis and database stats
+
+## Usage
+
+### Memory Adapter (Testing)
+
+```typescript
+import { createMemorySQLiteAdapter } from '@xnetjs/sqlite/memory'
+
+const db = await createMemorySQLiteAdapter()
+
+// Query data
+const rows = await db.query('SELECT * FROM nodes WHERE schema_id = ?', ['xnet://Page/1.0'])
+
+// Insert data
+await db.run('INSERT INTO nodes (id, schema_id, ...) VALUES (?, ?, ...)', [id, schemaId, ...])
+
+// Transactions
+await db.transaction(async () => {
+  await db.run(...)
+  await db.run(...)
+})
+
+await db.close()
+```
+
+### Electron (better-sqlite3)
+
+```typescript
+import { createElectronSQLiteAdapter } from '@xnetjs/sqlite/electron'
+
+const db = await createElectronSQLiteAdapter({
+  path: 'xnet.db',
+  // Optional WAL mode (default: true)
+  walMode: true
+})
+```
+
+### Web (sqlite-wasm + OPFS)
+
+```typescript
+import { createWebSQLiteAdapter } from '@xnetjs/sqlite/web'
+
+const db = await createWebSQLiteAdapter({
+  path: 'xnet.db'
+})
+```
+
+### Expo (expo-sqlite)
+
+```typescript
+import { createExpoSQLiteAdapter } from '@xnetjs/sqlite/expo'
+
+const db = await createExpoSQLiteAdapter({
+  path: 'xnet.db'
+})
+```
+
+## API
+
+### SQLiteAdapter Interface
+
+```typescript
+interface SQLiteAdapter {
+  // Query execution
+  query<T>(sql: string, params?: unknown[]): Promise<T[]>
+  queryOne<T>(sql: string, params?: unknown[]): Promise<T | null>
+  run(sql: string, params?: unknown[]): Promise<RunResult>
+  exec(sql: string): Promise<void>
+
+  // Transactions
+  transaction<T>(fn: () => Promise<T>): Promise<T>
+  beginTransaction(): Promise<void>
+  commit(): Promise<void>
+  rollback(): Promise<void>
+
+  // Prepared statements
+  prepare(sql: string): Promise<PreparedStatement>
+
+  // Schema
+  getSchemaVersion(): Promise<number>
+  setSchemaVersion(version: number): Promise<void>
+  applySchema(version: number, sql: string): Promise<boolean>
+
+  // Lifecycle
+  isOpen(): boolean
+  close(): Promise<void>
+
+  // Utilities
+  getDatabaseSize(): Promise<number>
+  vacuum(): Promise<void>
+  checkpoint(): Promise<number>
+}
+```
+
+### FTS5 Helpers
+
+```typescript
+import { updateNodeFTS, searchNodes, rebuildFTS } from '@xnetjs/sqlite'
+
+// Update FTS index for a node
+await updateNodeFTS(db, nodeId, title, content)
+
+// Search nodes
+const results = await searchNodes(db, 'search query', { limit: 10 })
+
+// Rebuild entire FTS index
+await rebuildFTS(db, (current, total) => {
+  console.log(`Progress: ${current}/${total}`)
+})
+```
+
+### Diagnostics
+
+```typescript
+import { getDatabaseStats, explainQuery, timeQuery } from '@xnetjs/sqlite'
+
+// Get database statistics
+const stats = await getDatabaseStats(db)
+console.log(`Tables: ${stats.tableCount}, Size: ${stats.totalSizeBytes} bytes`)
+
+// Analyze a query
+const plan = await explainQuery(db, 'SELECT * FROM nodes WHERE schema_id = ?', ['xnet://Page/1.0'])
+console.log(plan)
+
+// Time a query
+const { result, durationMs } = await timeQuery(db, async () => {
+  return db.query('SELECT * FROM nodes')
+})
+console.log(`Query took ${durationMs}ms`)
+```
+
+## Schema
+
+The package includes a unified schema (`SCHEMA_DDL`) with the following tables:
+
+### Core Tables
+
+- `nodes` - Entity registry
+- `node_properties` - Property storage with LWW
+- `changes` - Event log
+
+### Yjs Tables
+
+- `yjs_state` - Document state
+- `yjs_updates` - Incremental updates
+- `yjs_snapshots` - Time travel
+
+### Storage Tables
+
+- `blobs` - Content-addressed binary storage
+- `documents` - Generic document storage
+- `updates` - @xnetjs/storage compatibility
+- `snapshots` - @xnetjs/storage compatibility
+
+### Metadata Tables
+
+- `_schema_version` - Schema tracking
+- `sync_state` - Sync metadata
+
+### FTS5 Virtual Table
+
+- `nodes_fts` - Full-text search index
+
+## Platform Support
+
+| Platform | Adapter                 | SQLite Engine    | FTS5 |
+| -------- | ----------------------- | ---------------- | ---- |
+| Electron | `ElectronSQLiteAdapter` | better-sqlite3   | Yes  |
+| Web      | `WebSQLiteAdapter`      | @sqlite.org/wasm | Yes  |
+| Expo     | `ExpoSQLiteAdapter`     | expo-sqlite      | Yes  |
+| Test     | `MemorySQLiteAdapter`   | sql.js           | No\* |
+
+\* sql.js does not include FTS5 extension. FTS-related tests are skipped.
+
+## Browser Support (Web)
+
+The Web adapter requires:
+
+- Cross-Origin-Opener-Policy: same-origin
+- Cross-Origin-Embedder-Policy: require-corp
+- Chrome 102+, Firefox 111+, Safari 16.4+, Edge 102+
+
+```typescript
+import { checkBrowserSupport } from '@xnetjs/sqlite'
+
+const support = await checkBrowserSupport()
+if (!support.supported) {
+  console.warn('SQLite not supported:', support.reason)
+}
+```
+
+## Testing
+
+```bash
+pnpm --filter @xnetjs/sqlite test
+```
+
+## Dependencies
+
+- `sql.js` - WebAssembly SQLite (for memory adapter)
+- `better-sqlite3` - Native SQLite for Node.js (Electron)
+- `@sqlite.org/sqlite-wasm` - Official SQLite WASM (Web)
+- `expo-sqlite` - Expo SQLite (React Native)

package/dist/adapter-I7yAV6iu.d.ts

@@ -0,0 +1,166 @@
+import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult } from './types-C_aHfRDF.js';
+
+/**
+ * @xnetjs/sqlite - SQLite adapter interface definitions
+ */
+
+/**
+ * Unified SQLite adapter interface.
+ *
+ * All platform-specific implementations must implement this interface.
+ * The interface uses async methods to support both sync (better-sqlite3)
+ * and async (sqlite-wasm, expo-sqlite) implementations.
+ */
+interface SQLiteAdapter {
+    /**
+     * Open the database connection.
+     * Creates the database file if it doesn't exist.
+     */
+    open(config: SQLiteConfig): Promise<void>;
+    /**
+     * Close the database connection.
+     * Flushes any pending writes and releases resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Check if the database is currently open.
+     */
+    isOpen(): boolean;
+    /**
+     * Execute a single SQL statement that returns rows.
+     * Use for SELECT queries.
+     *
+     * @param sql - SQL query string
+     * @param params - Bound parameters
+     * @returns Array of result rows
+     *
+     * @example
+     * const nodes = await db.query<NodeRow>(
+     *   'SELECT * FROM nodes WHERE schemaId = ?',
+     *   ['xnet://Page/1.0']
+     * )
+     */
+    query<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T[]>;
+    /**
+     * Execute a single SQL statement that returns one row.
+     * Use for SELECT queries expecting 0 or 1 result.
+     *
+     * @param sql - SQL query string
+     * @param params - Bound parameters
+     * @returns Single row or null if not found
+     */
+    queryOne<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T | null>;
+    /**
+     * Execute a single SQL statement that modifies data.
+     * Use for INSERT, UPDATE, DELETE queries.
+     *
+     * @param sql - SQL statement
+     * @param params - Bound parameters
+     * @returns Run result with changes count and last insert ID
+     */
+    run(sql: string, params?: SQLValue[]): Promise<RunResult>;
+    /**
+     * Execute raw SQL that may contain multiple statements.
+     * Use for schema creation and migrations.
+     * Does not support parameter binding.
+     *
+     * @param sql - SQL statements (may be multiple, separated by semicolons)
+     */
+    exec(sql: string): Promise<void>;
+    /**
+     * Execute a function within a transaction.
+     * Automatically commits on success, rolls back on error.
+     *
+     * @param fn - Function to execute within transaction
+     * @returns Result of the function
+     *
+     * @example
+     * await db.transaction(async () => {
+     *   await db.run('INSERT INTO nodes ...')
+     *   await db.run('INSERT INTO changes ...')
+     * })
+     */
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Begin a manual transaction.
+     * Must be followed by commit() or rollback().
+     */
+    beginTransaction(): Promise<void>;
+    /**
+     * Commit the current transaction.
+     */
+    commit(): Promise<void>;
+    /**
+     * Rollback the current transaction.
+     */
+    rollback(): Promise<void>;
+    /**
+     * Prepare a statement for repeated execution.
+     * Useful for bulk operations.
+     *
+     * @param sql - SQL statement with placeholders
+     * @returns Prepared statement handle
+     */
+    prepare(sql: string): Promise<PreparedStatement>;
+    /**
+     * Get the current schema version.
+     * Returns 0 if no schema has been applied.
+     */
+    getSchemaVersion(): Promise<number>;
+    /**
+     * Set the schema version after applying migrations.
+     */
+    setSchemaVersion(version: number): Promise<void>;
+    /**
+     * Apply schema SQL if version is outdated.
+     * Handles version checking and updating atomically.
+     *
+     * @param version - Target schema version
+     * @param sql - Schema SQL to execute
+     * @returns true if schema was applied, false if already up-to-date
+     */
+    applySchema(version: number, sql: string): Promise<boolean>;
+    /**
+     * Get database file size in bytes.
+     * Returns 0 for in-memory databases.
+     */
+    getDatabaseSize(): Promise<number>;
+    /**
+     * Vacuum the database to reclaim space.
+     */
+    vacuum(): Promise<void>;
+    /**
+     * Checkpoint WAL file (for WAL mode databases).
+     * Returns the number of frames checkpointed.
+     */
+    checkpoint(): Promise<number>;
+    /**
+     * Get the current storage mode of the database.
+     * Returns 'opfs' if using OPFS-backed persistent storage,
+     * or 'memory' if using in-memory fallback.
+     */
+    getStorageMode(): Promise<'opfs' | 'memory'> | 'opfs' | 'memory';
+}
+/**
+ * Prepared statement for repeated execution.
+ */
+interface PreparedStatement {
+    /**
+     * Execute the statement with parameters and return rows.
+     */
+    query<T extends SQLRow = SQLRow>(params?: SQLValue[]): Promise<T[]>;
+    /**
+     * Execute the statement with parameters and return one row.
+     */
+    queryOne<T extends SQLRow = SQLRow>(params?: SQLValue[]): Promise<T | null>;
+    /**
+     * Execute the statement with parameters for modification.
+     */
+    run(params?: SQLValue[]): Promise<RunResult>;
+    /**
+     * Release the prepared statement.
+     */
+    finalize(): Promise<void>;
+}
+
+export type { PreparedStatement as P, SQLiteAdapter as S };

package/dist/adapters/electron.d.ts

@@ -0,0 +1,106 @@
+import { S as SQLiteAdapter, P as PreparedStatement } from '../adapter-I7yAV6iu.js';
+import { b as SQLiteConfig, a as SQLRow, S as SQLValue, R as RunResult } from '../types-C_aHfRDF.js';
+import Database from 'better-sqlite3';
+export { a as SCHEMA_DDL, S as SCHEMA_VERSION } from '../schema-CjkXTqxn.js';
+
+/**
+ * @xnetjs/sqlite - Electron SQLite adapter using better-sqlite3
+ *
+ * better-sqlite3 provides synchronous SQLite access for Node.js/Electron.
+ * The async interface is maintained for compatibility with other adapters.
+ */
+
+/**
+ * SQLite adapter for Electron using better-sqlite3.
+ *
+ * better-sqlite3 is synchronous, which is ideal for Electron's utility process.
+ * The async interface is maintained for compatibility with other adapters.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new ElectronSQLiteAdapter()
+ * await adapter.open({ path: '/path/to/xnet.db' })
+ *
+ * const nodes = await adapter.query('SELECT * FROM nodes')
+ * ```
+ */
+declare class ElectronSQLiteAdapter implements SQLiteAdapter {
+    private db;
+    private config;
+    private inTransaction;
+    private statementCache;
+    open(config: SQLiteConfig): Promise<void>;
+    close(): Promise<void>;
+    isOpen(): boolean;
+    query<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T[]>;
+    queryOne<T extends SQLRow = SQLRow>(sql: string, params?: SQLValue[]): Promise<T | null>;
+    run(sql: string, params?: SQLValue[]): Promise<RunResult>;
+    exec(sql: string): Promise<void>;
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Synchronous transaction for performance-critical batch operations.
+     * Prefer this over async transaction when the body is synchronous.
+     */
+    transactionSync<T>(fn: () => T): T;
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    prepare(sql: string): Promise<PreparedStatement>;
+    getSchemaVersion(): Promise<number>;
+    setSchemaVersion(version: number): Promise<void>;
+    applySchema(version: number, sql: string): Promise<boolean>;
+    getDatabaseSize(): Promise<number>;
+    vacuum(): Promise<void>;
+    checkpoint(): Promise<number>;
+    getStorageMode(): 'opfs' | 'memory';
+    /**
+     * Get a statement from cache or prepare it.
+     * Statement caching significantly improves performance for repeated queries.
+     */
+    private getOrPrepare;
+    private ensureOpen;
+    private wrapError;
+    /**
+     * Get the underlying better-sqlite3 database instance.
+     * Use for advanced operations not covered by the interface.
+     */
+    getRawDatabase(): Database.Database;
+    /**
+     * Create a batch writer for efficient bulk inserts.
+     */
+    createBatchWriter(options?: {
+        maxBatchSize?: number;
+    }): ElectronBatchWriter;
+}
+/**
+ * Batch writer for efficient bulk operations.
+ * Batches multiple writes and executes them in a single transaction.
+ */
+declare class ElectronBatchWriter {
+    private adapter;
+    private pendingOps;
+    private maxBatchSize;
+    private flushTimer;
+    private flushPromise;
+    constructor(adapter: ElectronSQLiteAdapter, options?: {
+        maxBatchSize?: number;
+    });
+    /**
+     * Queue an operation for batch execution.
+     */
+    queue(sql: string, params: SQLValue[]): void;
+    /**
+     * Flush all pending operations.
+     */
+    flush(): Promise<void>;
+    /**
+     * Close the batch writer, flushing any pending operations.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Create an ElectronSQLiteAdapter with schema applied.
+ */
+declare function createElectronSQLiteAdapter(config: SQLiteConfig): Promise<ElectronSQLiteAdapter>;
+
+export { ElectronBatchWriter, ElectronSQLiteAdapter, createElectronSQLiteAdapter };