Initial bits for a JS API variant in which the client operates in the main thread and sqlite3 in a Worker. This is far from complete.

FossilOrigin-Name: f6d6f969791f0d2367ae5418623b4794f6df657d9d7d9002fb5aec4206dcfd4c

5 files changed, 152 insertions, 7 deletions

diff --git a/ext/fiddle/sqlite3-api.js b/ext/fiddle/sqlite3-api.js
index d88ec9a8b..e625afc9b 100644
--- a/ext/fiddle/sqlite3-api.js
+++ b/ext/fiddle/sqlite3-api.js
@@ -85,7 +85,8 @@
 if(!Module.postRun) Module.postRun = [];
 /* ^^^^ the name Module is, in this setup, scope-local in the generated
    file sqlite3.js, with which this file gets combined at build-time. */
-Module.postRun.push(function(namespace){
+Module.postRun.push(function(namespace/*the module object, the target for
+                                        installed features*/){
     'use strict';
     /* For reference: sql.js does essentially everything we want and
        it solves much of the wasm-related voodoo, but we'll need a
@@ -470,7 +471,7 @@ Module.postRun.push(function(namespace){
            execMulti():
 
            - .multi: if true, this function acts as a proxy for
-             execMulti().
+             execMulti() and behaves identically to that function.
         */
         exec: function(/*(sql [,optionsObj]) or (optionsObj)*/){
             affirmDbOpen(this);
@@ -549,13 +550,15 @@ Module.postRun.push(function(namespace){
 
            ACHTUNG #1: The callback MUST NOT modify the Stmt
            object. Calling any of the Stmt.get() variants,
-           Stmt.getColumnName(), or simililar, is legal, but calling
+           Stmt.getColumnName(), or similar, is legal, but calling
            step() or finalize() is not. Routines which are illegal
            in this context will trigger an exception.
 
            ACHTUNG #2: The semantics of the `bind` and `callback`
            options may well change or those options may be removed
            altogether for this function (but retained for exec()).
+           Generally speaking, neither bind parameters nor a callback
+           are generically useful when executing multi-statement SQL.
         */
         execMulti: function(/*(sql [,obj]) || (obj)*/){
             affirmDbOpen(this);
@@ -1327,8 +1330,8 @@ Module.postRun.push(function(namespace){
         DB,
         Stmt,
         /**
-           Reports whether a given compile-time option, named by the
-           given argument. It has several distinct uses:
+           Reports info about compile-time options. It has several
+           distinct uses:
 
            If optName is an array then it is expected to be a list of
            compilation options and this function returns an object
@@ -1387,10 +1390,41 @@ Module.postRun.push(function(namespace){
                 'string'===typeof optName
             ) ? !!api.sqlite3_compileoption_used(optName) : false;
         }
-    };
+    }/*SQLite3 object*/;
 
     namespace.sqlite3 = {
         api: api,
         SQLite3
     };
+
+    if(self === self.window){
+        /* This is running in the main window thread, so we're done. */
+        return;
+    }
+    /******************************************************************
+     End of main window thread. What follows is only intended for use
+     in Worker threads.
+    ******************************************************************/
+
+    /*
+      TODO: we need an API which can proxy the DB API via a Worker
+      message interface. The primary quirky factor in such an API is
+      that clients cannot pass callback functions to it, so have to receive
+      all query results via asynchronous message-passing.
+
+      Certain important considerations here include:
+
+      - Support only one db connectior or multiple? The former is far
+        easier, but there's always going to be a user out there who
+        wants to juggle six database handles at once.
+
+      - Fetching multiple results: do we pass them on as a series of
+        messages, with start/end messages on either end, or do we
+        collect all results and bundle them back in a single message?
+        The former is, generically speaking, more memory-efficient but
+        the latter far easier to implement in this environment.
+     */
+    
+
+    setTimeout(()=>postMessage({type:'sqlite3-api',data:'loaded'}), 0);
 });
diff --git a/ext/fiddle/sqlite3-worker.js b/ext/fiddle/sqlite3-worker.js
new file mode 100644
index 000000000..6c1e9ca67
--- /dev/null
+++ b/ext/fiddle/sqlite3-worker.js
@@ -0,0 +1,35 @@
+/*
+  2022-05-23
+
+  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.
+
+  ***********************************************************************
+
+  UNDER CONSTRUCTION
+
+  This is a JS Worker file for the main sqlite3 api. It loads
+  sqlite3.js and offers access to the db via the Worker
+  message-passing interface.
+*/
+
+"use strict";
+(function(){
+    /** Posts a worker message as {type:type, data:data}. */
+    const wMsg = (type,data)=>self.postMessage({type, data});
+    self.onmessage = function(ev){
+        /*ev = ev.data;
+        switch(ev.type){
+            default: break;
+        };*/
+        console.warn("Unknown sqlite3-worker message type:",ev);
+    };
+    importScripts('sqlite3.js');
+    initSqlite3Module().then(function(){
+        wMsg('sqlite3-api','ready');
+    });
+})();
diff --git a/ext/fiddle/testing1.js b/ext/fiddle/testing1.js
index 9216db134..e4afad84e 100644
--- a/ext/fiddle/testing1.js
+++ b/ext/fiddle/testing1.js
@@ -10,7 +10,8 @@
 
   ***********************************************************************
 
-  A basic test script for sqlite3-api.js.
+  A basic test script for sqlite3-api.js. This file must be run in
+  main JS thread and sqlite3.js must have been loaded before it.
 */
 (function(){
     const T = self.SqliteTestUtil;
diff --git a/ext/fiddle/testing2.html b/ext/fiddle/testing2.html
new file mode 100644
index 000000000..b773c4aa4
--- /dev/null
+++ b/ext/fiddle/testing2.html
@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en-us">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+    <link rel="shortcut icon" href="data:image/x-icon;," type="image/x-icon">
+    <link rel="stylesheet" href="emscripten.css"/>
+    <link rel="stylesheet" href="testing.css"/>
+    <title>sqlite3-worker.js tests</title>
+    <style></style>
+  </head>
+  <body>
+    <header id='titlebar'><span>sqlite3-worker.js tests</span></header>
+    <!-- emscripten bits -->
+    <figure id="module-spinner">
+      <div class="spinner"></div>
+      <div class='center'><strong>Initializing app...</strong></div>
+      <div class='center'>
+        On a slow internet connection this may take a moment.  If this
+        message displays for "a long time", intialization may have
+        failed and the JavaScript console may contain clues as to why.
+      </div>
+    </figure>
+    <div class="emscripten" id="module-status">Downloading...</div>
+    <div class="emscripten">
+      <progress value="0" max="100" id="module-progress" hidden='1'></progress>  
+    </div><!-- /emscripten bits -->
+    <div>Everything on this page happens in the dev console.</div>
+    <script src="testing-common.js"></script>
+    <script src="testing2.js"></script>
+  </body>
+</html>
diff --git a/ext/fiddle/testing2.js b/ext/fiddle/testing2.js
new file mode 100644
index 000000000..c25885425
--- /dev/null
+++ b/ext/fiddle/testing2.js
@@ -0,0 +1,43 @@
+/*
+  2022-05-22
+
+  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 basic test script for sqlite3-worker.js.
+*/
+(function(){
+    /** Posts a worker message as {type:type, data:data}. */
+    const SW = new Worker("sqlite3-worker.js");
+    const wMsg = (type,data)=>SW.postMessage({type, data});
+    const log = console.log.bind(console);
+    const warn = console.warn.bind(console);
+    SW.onmessage = function(ev){
+        if(!ev.data || 'object'!==typeof ev.data){
+            warn("Unknown sqlite3-worker message type:",ev);
+            return;
+        }
+        ev = ev.data/*expecting a nested object*/;
+        switch(ev.type){
+            case 'sqlite3-api':
+                switch(ev.data){
+                    case 'loaded':
+                        log("Message:",ev); return;
+                    case 'ready':
+                        log("Message:",ev);
+                        self.sqlite3TestModule.setStatus(null);
+                        return;
+                    default: break;
+                }
+                break;
+        }
+        warn("Unknown sqlite3-api message type:",ev);
+    };
+    log("Init complete, but async bits may still be running.");
+})();