@livestore/wa-sqlite 1.0.8-dev.2 → 1.0.8-dev.4

package/README.md

@@ -8,6 +8,10 @@ This fork adds synchronous APIs and session extensions needed for LiveStore's re
 - **Session extensions**: Enables change tracking and replication for collaborative features  
 - **Node.js compatibility**: Additional build targets for server-side testing
 
+## Future work
+
+- **Async build investigation**: Some VFS implementations (e.g., IndexedDB) require async APIs ([#131](https://github.com/livestorejs/livestore/issues/131)). We're investigating whether to support this through a unified hybrid build or separate builds.
+
 ### Changes include:
 
 - `src/sqlite-api.js`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livestore/wa-sqlite",
-  "version": "1.0.8-dev.2",
+  "version": "1.0.8-dev.4",
   "type": "module",
   "main": "src/sqlite-api.js",
   "types": "src/types/index.d.ts",
@@ -23,8 +23,8 @@
     "comlink": "^4.4.1",
     "jasmine-core": "^4.5.0",
     "monaco-editor": "^0.34.1",
-    "typedoc": "^0.25.7",
-    "typescript": "^5.3.3",
+    "typedoc": "^0.28.9",
+    "typescript": "^5.9.2",
     "web-test-runner-jasmine": "^0.0.6"
   },
   "dependenciesMeta": {

package/src/sqlite-api.js

@@ -260,18 +260,21 @@ export function Factory(Module) {
     return function(db, schema) {
       verifyDatabase(db);
       const piSize = tmpPtr[0];
-      let address = f(db, schema, piSize, 0);
+      let address = f(db, schema, piSize, 0); // 0 means no flags
       if (address === 0) {
         address = f(db, schema, piSize, SQLITE_SERIALIZE_NOCOPY);
         const size = Module.getValue(piSize, '*');
         const result = Module.HEAPU8.subarray(address, address + size);
         // NOTE Given that the memory is owned by SQLite, we must copy it.
+        // Warning: We're not super confident yet about this code path. There might be dragons.
         return new Uint8Array(result.slice());
       } else {
         const size = Module.getValue(piSize, '*');
         const result = Module.HEAPU8.subarray(address, address + size);
-        // Here we're getting a copy of the memory, so we can return it directly.
-        return new Uint8Array(result);
+        // Copy the data immediately, then free the SQLite buffer to prevent ref-count issues
+        const copy = new Uint8Array(result);
+        Module._sqlite3_free(address); 
+        return copy;
       }
     };
   })();
@@ -290,10 +293,15 @@ export function Factory(Module) {
         const errMsg = Module.ccall('sqlite3_errmsg', 'string', ['number'], [dest]);
         throw new SQLiteError(`backup failed: ${errMsg}`, SQLite.SQLITE_ERROR);
       }
-      fStep(backup, -1);
+      // TODO also allow run in chunks with some yielding mechanism
+      fStep(backup, -1); // -1 means do it in one go
       return fFinish(backup);
     };
   })();
+  
+
+  // TODO implement this at some point
+  // sqlite3.backup_step = (function() {
 
   sqlite3.clear_bindings = (function() {
     const fname = 'sqlite3_clear_bindings';

package/src/types/index.d.ts

@@ -11,11 +11,11 @@
  *  Javascript types that SQLite can use
  * 
  * C integer and floating-point types both map to/from Javascript `number`.
- * Blob data can be provided to SQLite as `Uint8Array` or `number[]` (with
+ * Blob data can be provided to SQLite as `Uint8Array<ArrayBuffer>` or `number[]` (with
  * each element converted to a byte); SQLite always returns blob data as
- * `Uint8Array`
+ * `Uint8Array<ArrayBuffer>`
  */
-type SQLiteCompatibleType = number|string|Uint8Array|Array<number>|bigint|null;
+type SQLiteCompatibleType = number|string|Uint8Array<ArrayBuffer>|Array<number>|bigint|null;
 
 /**
  * SQLite Virtual File System object
@@ -244,7 +244,7 @@ interface SQLiteAPI {
    * @param value 
    * @returns `SQLITE_OK` (throws exception on error)
    */
-  bind_blob(stmt: number, i: number, value: Uint8Array|Array<number>): number;
+  bind_blob(stmt: number, i: number, value: Uint8Array<ArrayBuffer>|Array<number>): number;
 
   /**
    * Bind number to prepared statement parameter
@@ -346,7 +346,7 @@ interface SQLiteAPI {
   deserialize(
     db: number,
     zSchema: string,
-    pData: Uint8Array,
+    pData: Uint8Array<ArrayBuffer>,
     szDb: number,
     szBuf: number,
     mFlags: number
@@ -364,7 +364,7 @@ interface SQLiteAPI {
     db: number,
     zSchema: string,
     // mFlags: number
-  ): Uint8Array;
+  ): Uint8Array<ArrayBuffer>;
 
   // sqlite3_backup *sqlite3_backup_init(
   //   sqlite3 *pDest,                        /* Destination database handle */
@@ -440,7 +440,7 @@ interface SQLiteAPI {
    * @param i column index
    * @returns column value
    */
-  column_blob(stmt: number, i: number): Uint8Array;
+  column_blob(stmt: number, i: number): Uint8Array<ArrayBuffer>;
 
   /**
    * Get storage size for column text or blob
@@ -699,7 +699,7 @@ interface SQLiteAPI {
    * @param context context pointer
    * @param value 
    */
-  result_blob(context: number, value: Uint8Array|number[]): void;
+  result_blob(context: number, value: Uint8Array<ArrayBuffer>|number[]): void;
 
   /**
    * Set the result of a function or vtable column
@@ -869,7 +869,7 @@ interface SQLiteAPI {
    * @param pValue `sqlite3_value` pointer
    * @returns value
    */
-  value_blob(pValue: number): Uint8Array;
+  value_blob(pValue: number): Uint8Array<ArrayBuffer>;
 
   /**
    * Get blob or text size for value
@@ -961,18 +961,18 @@ interface SQLiteAPI {
    * Get the changeset for a session.
    * 
    * @param pSession session pointer
-   * @returns {result: number, size: number, changeset: Uint8Array}
+   * @returns {result: number, size: number, changeset: Uint8Array<ArrayBuffer>}
    */
   session_changeset(pSession: number): {
     result: number;
     size: number;
-    changeset: Uint8Array | null;
+    changeset: Uint8Array<ArrayBuffer> | null;
   };
 
   session_changeset_inverted(pSession: number): {
     result: number;
     size: number;
-    changeset: Uint8Array;
+    changeset: Uint8Array<ArrayBuffer>;
   };
 
   /**
@@ -988,7 +988,7 @@ interface SQLiteAPI {
    * @param changeset changeset blob to import from
    * @returns changeset iterator pointer
    */
-  changeset_start(changesetBlob: Uint8Array): number;
+  changeset_start(changesetBlob: Uint8Array<ArrayBuffer>): number;
 
   /**
    * Finalize a changeset iterator.
@@ -1004,7 +1004,7 @@ interface SQLiteAPI {
    * @param input changeset to invert
    * @returns inverted changeset
    */
-  changeset_invert(input: Uint8Array): Uint8Array;
+  changeset_invert(input: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
 
   /**
    * Apply a changeset to a database.
@@ -1013,7 +1013,7 @@ interface SQLiteAPI {
    * @param changeset changeset to apply
    * @returns `SQLITE_OK` (throws exception on error)
    */
-  changeset_apply(db: number, changeset: Uint8Array, options?: {
+  changeset_apply(db: number, changeset: Uint8Array<ArrayBuffer>, options?: {
     onConflict?: (conflictType: number) => 0 | 1 | 2
   }): number;
 
@@ -1309,23 +1309,23 @@ declare module '@livestore/wa-sqlite/src/VFS.js' {
     xClose(fileId: number): number;
     /**
      * @param {number} fileId
-     * @param {Uint8Array} pData
+     * @param {Uint8Array<ArrayBuffer>} pData
      * @param {number} iOffset
      * @returns {number}
      */
     xRead(fileId: number, pData: {
         size: number;
-        value: Uint8Array;
+        value: Uint8Array<ArrayBuffer>;
     }, iOffset: number): number;
     /**
      * @param {number} fileId
-     * @param {Uint8Array} pData
+     * @param {Uint8Array<ArrayBuffer>} pData
      * @param {number} iOffset
      * @returns {number}
      */
     xWrite(fileId: number, pData: {
         size: number;
-        value: Uint8Array;
+        value: Uint8Array<ArrayBuffer>;
     }, iOffset: number): number;
     /**
      * @param {number} fileId