Add addOnDispose() method to Jaccwabyt and code-adjacent minor internal cleanups.

FossilOrigin-Name: 6a2723fe3f28dd94328d901e64e1e9ee9a1b2e9eeaed6c54038a5b83c914db78

ext/wasm/api/sqlite3-v-helper.js

@@ -350,10 +350,10 @@ self.sqlite3ApiBootstrap.initializers.push(function(sqlite3){
        methods which take a (sqlite3_vtab_cursor*) _except_ for
        xClose(), in which case use...
 
-     - wrapCursor(pCursor, true) will remove the m apping of pCursor to a
+     - wrapCursor(pCursor, true) will remove the mapping of pCursor to a
        capi.sqlite3_vtab_cursor object and return that object.  The
        caller must call dispose() on the returned object. This is
-       intended to be called form xClose() or in error handling of a
+       intended to be called from xClose() or in error handling of a
        failed xOpen().
  */
   vt.xWrapCursor = __xWrapFactory(capi.sqlite3_vtab_cursor);

ext/wasm/jaccwabyt/jaccwabyt.js

@@ -10,9 +10,12 @@
 
   ***********************************************************************
 
-  The Jaccwabyt API is documented in detail in an external file.
+  The Jaccwabyt API is documented in detail in an external file,
+  _possibly_ called jaccwabyt.md in the same directory as this file.
 
-  Project home: https://fossil.wanderinghorse.net/r/jaccwabyt
+  Project homes:
+  - https://fossil.wanderinghorse.net/r/jaccwabyt
+  - https://sqlite.org/src/dir/ext/wasm/jaccwabyt
 
 */
 'use strict';
@@ -219,15 +222,9 @@ self.Jaccwabyt = function StructBinderFactory(config){
   const __freeStruct = function(ctor, obj, m){
     if(!m) m = __instancePointerMap.get(obj);
     if(m) {
-      if(obj.ondispose instanceof Function){
-        try{obj.ondispose()}
-        catch(e){
-          /*do not rethrow: destructors must not throw*/
-          console.warn("ondispose() for",ctor.structName,'@',
-                       m,'threw. NOT propagating it.',e);
-        }
-      }else if(Array.isArray(obj.ondispose)){
-        obj.ondispose.forEach(function(x){
+      if(Array.isArray(obj.ondispose)){
+        let x;
+        while((x = obj.ondispose.shift())){
           try{
             if(x instanceof Function) x.call(obj);
             else if(x instanceof StructType) x.dispose();
@@ -238,7 +235,14 @@ self.Jaccwabyt = function StructBinderFactory(config){
             console.warn("ondispose() for",ctor.structName,'@',
                          m,'threw. NOT propagating it.',e);
           }
-        });
+        }
+      }else if(obj.ondispose instanceof Function){
+        try{obj.ondispose()}
+        catch(e){
+          /*do not rethrow: destructors must not throw*/
+          console.warn("ondispose() for",ctor.structName,'@',
+                       m,'threw. NOT propagating it.',e);
+        }
       }
       delete obj.ondispose;
       __instancePointerMap.delete(obj);
@@ -333,7 +337,9 @@ self.Jaccwabyt = function StructBinderFactory(config){
   /** Impl of X.memberKeys() for StructType and struct ctors. */
   const __structMemberKeys = rop(function(){
     const a = [];
-    Object.keys(this.structInfo.members).forEach((k)=>a.push(this.memberKey(k)));
+    for(const k of Object.keys(this.structInfo.members)){
+      a.push(this.memberKey(k));
+    }
     return a;
   });
 
@@ -399,15 +405,15 @@ self.Jaccwabyt = function StructBinderFactory(config){
      Adds value v to obj.ondispose, creating ondispose,
      or converting it to an array, if needed.
   */
-  const __addOnDispose = function(obj, v){
+  const __addOnDispose = function(obj, ...v){
     if(obj.ondispose){
-      if(obj.ondispose instanceof Function){
+      if(!Array.isArray(obj.ondispose)){
         obj.ondispose = [obj.ondispose];
-      }/*else assume it's an array*/
+      }
     }else{
       obj.ondispose = [];
     }
-    obj.ondispose.push(v);
+    obj.ondispose.push(...v);
   };
 
   /**
@@ -494,6 +500,13 @@ self.Jaccwabyt = function StructBinderFactory(config){
       return __setMemberCString(this, memberName, str);
     })
   });
+  // Function-type non-Property inherited members 
+  Object.assign(StructType.prototype,{
+    addOnDispose: function(...v){
+      __addOnDispose(this,...v);
+      return this;
+    }
+  });
 
   /**
      "Static" properties for StructType.

ext/wasm/jaccwabyt/jaccwabyt.md

@@ -4,7 +4,6 @@ Jaccwabyt 🐇
 **Jaccwabyt**: _JavaScript ⇄ C Struct Communication via WASM Byte
 Arrays_
 
-
 Welcome to Jaccwabyt, a JavaScript API which creates bindings for
 WASM-compiled C structs, defining them in such a way that changes to
 their state in JS are visible in C/WASM, and vice versa, permitting
@@ -27,8 +26,28 @@ are based solely on feature compatibility tables provided at
 **Formalities:**
 
 - Author: [Stephan Beal][sgb]
-- License: Public Domain
-- Project Home: <https://fossil.wanderinghorse.net/r/jaccwabyt>
+- Project Homes:
+  - <https://fossil.wanderinghorse.net/r/jaccwabyt>\  
+    Is the primary home but...
+  - <https://sqlite.org/src/dir/ext/wasm/jaccwabyt>\  
+    ... most development happens here.
+
+The license for both this documentation and the software it documents
+is the same as [sqlite3][], the project from which this spinoff
+project was spawned:
+
+-----
+
+> 2022-06-30:
+>
+> The author disclaims copyright to this source code.  In place of a
+> legal notice, here is a blessing:
+>
+>    May you do good and not evil.
+>    May you find forgiveness for yourself and forgive others.
+>    May you share freely, never taking more than you give.
+
+-----
 
 <a name='overview'></a>
 Table of Contents
@@ -571,6 +590,14 @@ only called by the [StructBinder][]-generated
 has the following "static" properties (^Which are accessible from
 individual instances via `theInstance.constructor`.):
 
+- `addOnDispose(...value)`\  
+  If this object has no `ondispose` property, this function creates it
+  as an array and pushes the given value(s) onto it. If the object has
+  a function-typed `ondispose` property, this call replaces it with an
+  array and moves that function into the array. In all other cases,
+  `ondispose` is assumed to be an array and the argument(s) is/are
+  appended to it. Returns `this`.
+
 - `allocCString(str)`  
   Identical to the [StructBinder][] method of the same name.
 

ext/wasm/tester1.c-pp.js

@@ -710,7 +710,7 @@ self.sqlite3InitModule = sqlite3InitModule;
     }/*WhWasmUtil*/)
 
   ////////////////////////////////////////////////////////////////////
-    .t('sqlite3.StructBinder (jaccwabyt)', function(sqlite3){
+    .t('sqlite3.StructBinder (jaccwabyt🐇)', function(sqlite3){
       const S = sqlite3, W = S.wasm;
       const MyStructDef = {
         sizeof: 16,
@@ -864,6 +864,18 @@ self.sqlite3InitModule = sqlite3InitModule;
       }finally{
         wts.dispose();
       }
+
+      if(1){ // ondispose of other struct instances
+        const s1 = new WTStruct, s2 = new WTStruct, s3 = new WTStruct;
+        T.assert(s1.lookupMember instanceof Function)
+          .assert(s1.addOnDispose instanceof Function);
+        s1.addOnDispose(s2,"testing variadic args");
+        T.assert(2===s1.ondispose.length);
+        s2.addOnDispose(s3);
+        s1.dispose();
+        T.assert(!s2.pointer,"Expecting s2 to be ondispose'd by s1.");
+        T.assert(!s3.pointer,"Expecting s3 to be ondispose'd by s2.");
+      }
     }/*StructBinder*/)
 
   ////////////////////////////////////////////////////////////////////
@@ -1549,6 +1561,7 @@ self.sqlite3InitModule = sqlite3InitModule;
                 .assert(args[0] === 'testvtab')
                 .assert(args[1] === 'main')
                 .assert(args[2] === 'testvtab');
+              console.debug("xConnect() args =",args);
               const rc = capi.sqlite3_declare_vtab(
                 pDb, "CREATE TABLE ignored(a,b)"
               );
@@ -1577,8 +1590,8 @@ self.sqlite3InitModule = sqlite3InitModule;
           xOpen: function(pVtab, ppCursor){
             try{
               const t = vth.xWrapVtab(pVtab), c = vth.xWrapCursor();
-              T.assert(t instanceof capi.sqlite3_vtab);
-              T.assert(c instanceof capi.sqlite3_vtab_cursor);
+              T.assert(t instanceof capi.sqlite3_vtab)
+                .assert(c instanceof capi.sqlite3_vtab_cursor);
               wasm.setPtrValue(ppCursor, c.pointer);
               c._rowId = 0;
               return 0;