git-sqlite-vfs 0.0.11 → 0.0.12

package/README.md

@@ -34,19 +34,33 @@ The custom SQLite merge driver scopes to the designated database directory via `
 
 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';
 
 // Load the native extension process-wide and set the VFS directory
 await bootstrapGitVFS({ dir: '.my-db' });
 
-// Initialize the database connection using a 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'
 });
 
@@ -66,11 +80,24 @@ const allUsers = await db.select().from(users);
 console.log(allUsers);
 ```
 
+### 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, configure SQLite to use `FULL` auto-vacuuming and `DELETE` journaling.
+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.
+
+When you use `createVFSClient()`, it automatically executes these PRAGMAs for you upon connection initialization.
 
-Execute these PRAGMA statements during connection initialization:
+If you create your client manually without `createVFSClient`, you must run them yourself:
 
 ```sql
 PRAGMA auto_vacuum = FULL;

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.11",
+  "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": "",