git-sqlite-vfs 0.0.10 → 0.0.12

package/README.md

@@ -1,85 +1,110 @@
 # git-sqlite-vfs
 
-A Git-versioned SQLite Database powered by a custom Virtual File System (VFS).
+A Git-versioned SQLite database utilizing a custom Virtual File System (VFS).
 
-By integrating native SQLite, Drizzle ORM, and libSQL with Git's version control capabilities, `git-sqlite-vfs` allows you to version, diff, and merge your application's database in a manner similar to source code. It is compatible with both **Node.js** and **Deno**.
+By integrating SQLite, Drizzle ORM, and libSQL with Git, `git-sqlite-vfs` enables versioning, diffing, and merging of SQLite databases. It is compatible with Node.js and Deno.
 
 ## Architecture
 
-Standard SQLite databases are stored as a single flat file. This structure presents challenges for version control, as a minor insertion can result in widespread byte shifts across the file, reducing the effectiveness of delta-compression and making binary merge conflicts difficult to resolve.
+Standard SQLite databases are stored as a single file. This limits version control compatibility, as minor insertions cause cascading byte shifts, negating delta-compression and creating unresolvable binary merge conflicts.
 
-This package provides a loadable SQLite C Extension that overrides the default VFS behavior. It shards the database into 4KB deterministic binary pages within a specified directory (e.g. `.my-db`).
+This package provides a loadable SQLite C extension that overrides the default VFS behavior. It shards the database into deterministic 4KB binary pages within a specified directory (e.g. `.my-db`).
 
-During a Git merge, a provided `git-merge-sqlitevfs` driver integrates with Git's conflict resolution pipeline to reconcile binary B-Tree page conflicts, maintaining data integrity.
+During a Git merge, a custom `git-merge-sqlitevfs` driver integrates with Git's conflict resolution pipeline to reconcile B-Tree page conflicts.
 
 ## Installation
 
-Install the package alongside your libSQL and Drizzle ORM dependencies:
-
 ```bash
 npm install git-sqlite-vfs @libsql/client drizzle-orm
 ```
 
 ## Git Configuration
 
-To enable Git versioning and binary merging, the repository must be configured to use the custom merge driver. This is done **automatically** when you call `bootstrapGitVFS()`:
+The repository must be configured to use the custom merge driver. This configuration occurs automatically when `bootstrapGitVFS()` is called:
 
-1. It registers `git-merge-sqlitevfs` as a custom Git merge driver in the local `.git/config`.
-2. It adds or appends to a `.gitattributes` file in the repository root to route all files matching your configured directory (e.g., `.my-db/*`) through the custom merge driver.
-3. It creates or updates a `.gitignore` to ignore SQLite transient files (`*-journal`, `*-wal`, `*-shm`).
+1. Registers `git-merge-sqlitevfs` as a custom Git merge driver in the local `.git/config`.
+2. Updates `.gitattributes` in the repository root to route files matching the configured directory (e.g., `.my-db/*`) through the custom merge driver.
+3. Updates `.gitignore` to ignore SQLite transient files (`*-journal`, `*-wal`, `*-shm`).
 
-### Safe alongside Source Code
+### Source Code Compatibility
 
-The custom SQLite merge driver **will not interfere with the merging of standard source code or text files**. By utilizing the `.gitattributes` file, Git explicitly scopes the custom driver strictly to the files within your designated database directory (e.g., `.my-db/* merge=sqlitevfs`). All other files in your repository will continue to use Git's default text-based merge algorithms.
+The custom SQLite merge driver scopes to the designated database directory via `.gitattributes`. Other repository files continue using Git's default text-based merge algorithms.
 
 ## Usage
 
-The VFS works in both Node.js and Deno environments. By calling the `bootstrapGitVFS()` method prior to initializing `@libsql/client`, the extension is loaded process-wide.
+The VFS operates in Node.js and Deno environments. Calling `bootstrapGitVFS()` prior to initializing `@libsql/client` loads the extension process-wide.
+
+To ensure the VFS correctly intercepts database connections and executes required PRAGMAs, use `createVFSClient` to initialize your connection instead of `@libsql/client`'s `createClient`.
+
+### Native Binding Isolation (libsql version mismatch)
+
+`git-sqlite-vfs` internally loads the `libsql` native C extension. If your project uses a different version of `@libsql/client` (and thus a different `libsql` binding), Node/Deno may spawn two isolated native C instances in memory, causing the VFS registration to fail silently.
+
+To prevent this, you can inject your own `libsql` instance directly into the VFS via `options.libsql`:
+
+```typescript
+import * as myLibsql from 'libsql';
+import { bootstrapGitVFS } from 'git-sqlite-vfs';
+
+await bootstrapGitVFS({ dir: '.my-db', libsql: myLibsql });
+```
 
 ### Example with `@libsql/client` and Drizzle ORM
 
 ```typescript
-import { createClient } from '@libsql/client'; // In Deno: 'npm:@libsql/client/node'
+import { bootstrapGitVFS, createVFSClient } from 'git-sqlite-vfs';
 import { drizzle } from 'drizzle-orm/libsql';
 import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core';
-import { bootstrapGitVFS } from 'git-sqlite-vfs';
 
-// 1. Load the native extension process-wide and set the VFS directory
+// Load the native extension process-wide and set the VFS directory
 await bootstrapGitVFS({ dir: '.my-db' });
 
-// 2. Initialize the database connection using a standard file: URL
-const client = createClient({
+// Initialize the database connection (automates required PRAGMAs and natively supports Deno)
+const client = await createVFSClient({
     url: 'file:.my-db/local.db'
 });
 
-// 3. Wrap with Drizzle ORM
+// Wrap with Drizzle ORM
 const db = drizzle(client);
 
-// 4. Define the schema
+// Define the schema
 const users = sqliteTable('users', {
     id: integer('id').primaryKey(),
     name: text('name')
 });
 
-// 5. Execute queries. File I/O is intercepted by the Git VFS.
+// Execute queries
 await db.insert(users).values({ id: 1, name: 'Alice' });
 const allUsers = await db.select().from(users);
 
 console.log(allUsers);
 ```
 
-## Preventing Repository Bloat
+### Usage with Deno
+
+By default, Deno resolves `npm:@libsql/client` to its browser-compatible implementation, which bypasses native C extensions entirely. This means the VFS never runs. 
+
+To work around this, lock the dependency directly to the Node environment. `createVFSClient` will gracefully default to the Node native bindings under the hood (`npm:@libsql/client/node`).
+
+If you still need to bypass `createVFSClient`, import using the `/node` path directly:
+```typescript
+import { createClient } from 'npm:@libsql/client@0.14.0/node';
+```
+
+## Database Compaction
+
+SQLite often zeroes out deleted data pages rather than shrinking the file size, causing unneeded `.bin` pages to remain. To allow the Git VFS to remove these unused shards, it requires `FULL` auto-vacuuming and `DELETE` journaling to actively split and compact out-of-bounds shards.
 
-Because SQLite often zeroes out deleted data pages rather than shrinking the database file size, "zombie" `.bin` pages may accumulate in the repository over time. To allow the Git VFS to automatically garbage-collect these unused chunks, configure SQLite to use `FULL` auto-vacuuming and `DELETE` journaling.
+When you use `createVFSClient()`, it automatically executes these PRAGMAs for you upon connection initialization.
 
-Execute these PRAGMA statements when initializing the database connection:
+If you create your client manually without `createVFSClient`, you must run them yourself:
 
 ```sql
 PRAGMA auto_vacuum = FULL;
 PRAGMA journal_mode = DELETE;
 ```
 
-Alternatively, you can run `VACUUM;` periodically. When SQLite explicitly reduces the database file size, the underlying VFS `xTruncate` implementation will remove the out-of-bounds `.bin` shards, keeping the repository history compressed.
+Alternatively, executing `VACUUM;` periodically reduces the database file size, and the VFS `xTruncate` implementation will remove out-of-bounds `.bin` shards.
 
 ## Compatibility
 

package/index.d.ts

@@ -2,10 +2,18 @@ export const GITVFS_EXTENSION_PATH: string;
 
 export interface BootstrapOptions {
     dir?: string;
+    libsql?: any;
 }
 
 export function bootstrapGitVFS(options?: BootstrapOptions): Promise<void>;
 
+export interface CreateVFSClientOptions {
+    clientOptions: any;
+    createClient?: any;
+}
+
+export function createVFSClient(options: CreateVFSClientOptions | any): Promise<any>;
+
 export interface ConfigureGitOptions {
     repoDir: string;
     vfsDir: string;

package/index.js

@@ -33,16 +33,18 @@ export async function bootstrapGitVFS(options = {}) {
 
     let currentExtPath = extensionPath;
     if (!fs.existsSync(currentExtPath)) {
-        const writableDir = path.join(process.cwd(), '.git-sqlite-vfs-bin');
+        const writableDir = path.join(__dirname, '.git-sqlite-vfs-bin');
         await downloadOrBuild(writableDir);
         currentExtPath = path.join(writableDir, `gitvfs.${ext}`);
     }
 
     // Dynamically import libsql so that we load the extension into its isolated native memory space.
     let Database;
-    if (typeof Deno !== 'undefined') {
+    if (options.libsql) {
+        Database = options.libsql.default || options.libsql.Database || options.libsql;
+    } else if (typeof Deno !== 'undefined') {
         // Deno environment
-        const lib = await import('libsql');
+        const lib = await import('npm:libsql');
         Database = lib.default || lib.Database || lib;
     } else {
         // Node.js environment
@@ -63,6 +65,28 @@ export async function bootstrapGitVFS(options = {}) {
     }
 }
 
+export async function createVFSClient(options) {
+    let createClientFn = options.createClient;
+    if (!createClientFn) {
+        if (typeof Deno !== 'undefined') {
+            // Gracefully default to Node native bindings in Deno to prevent bypassing the VFS
+            const mod = await import('npm:@libsql/client/node');
+            createClientFn = mod.createClient;
+        } else {
+            const mod = await import('@libsql/client');
+            createClientFn = mod.createClient;
+        }
+    }
+
+    const client = createClientFn(options.clientOptions || options);
+    
+    // Execute required PRAGMAs for the VFS to actively split and compact out-of-bounds shards
+    await client.execute('PRAGMA auto_vacuum = FULL;');
+    await client.execute('PRAGMA journal_mode = DELETE;');
+
+    return client;
+}
+
 export async function configureGitIntegration({ repoDir, vfsDir }) {
     let driverDir = path.resolve(__dirname, 'c', 'output');
     let driverPath = path.join(driverDir, 'git-merge-sqlitevfs');
@@ -71,7 +95,7 @@ export async function configureGitIntegration({ repoDir, vfsDir }) {
     }
 
     if (!fs.existsSync(driverPath)) {
-        driverDir = path.join(process.cwd(), '.git-sqlite-vfs-bin');
+        driverDir = path.join(__dirname, '.git-sqlite-vfs-bin');
         await downloadOrBuild(driverDir);
         driverPath = path.join(driverDir, 'git-merge-sqlitevfs');
         if (platform === 'win32' && !fs.existsSync(driverPath) && fs.existsSync(driverPath + '.exe')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-sqlite-vfs",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "A Git-Versioned SQLite Database via a Custom Virtual File System (VFS)",
   "main": "index.js",
   "types": "index.d.ts",
@@ -29,8 +29,10 @@
     "test:deno": "npm run build && rm -rf .db test.db .test-db .git .gitattributes .gitignore && git init --initial-branch=master && deno test -A test/*.deno.test.ts"
   },
   "dependencies": {
+    "drizzle-orm": "^0.33.0"
+  },
+  "peerDependencies": {
     "@libsql/client": "^0.14.0",
-    "drizzle-orm": "^0.33.0",
     "libsql": "^0.4.5"
   },
   "author": "",