ext/wasm/api/sqlite3-worker1-promiser.js

   1 /*
   2   2022-08-24
   3
   4   The author disclaims copyright to this source code.  In place of a
   5   legal notice, here is a blessing:
   6
   7   *   May you do good and not evil.
   8   *   May you find forgiveness for yourself and forgive others.
   9   *   May you share freely, never taking more than you give.
  10
  11   ***********************************************************************
  12
  13   This file implements a Promise-based proxy for the sqlite3 Worker
  14   API #1. It is intended to be included either from the main thread or
  15   a Worker, but only if (A) the environment supports nested Workers
  16   and (B) it's _not_ a Worker which loads the sqlite3 WASM/JS
  17   module. This file's features will load that module and provide a
  18   slightly simpler client-side interface than the slightly-lower-level
  19   Worker API does.
  20
  21   This script necessarily exposes one global symbol, but clients may
  22   freely `delete` that symbol after calling it.
  23 */
  24 'use strict';
  25 /**
  26    Configures an sqlite3 Worker API #1 Worker such that it can be
  27    manipulated via a Promise-based interface and returns a factory
  28    function which returns Promises for communicating with the worker.
  29    This proxy has an _almost_ identical interface to the normal
  30    worker API, with any exceptions documented below.
  31
  32    It requires a configuration object with the following properties:
  33
  34    - `worker` (required): a Worker instance which loads
  35    `sqlite3-worker1.js` or a functional equivalent. Note that the
  36    promiser factory replaces the worker.onmessage property. This
  37    config option may alternately be a function, in which case this
  38    function re-assigns this property with the result of calling that
  39    function, enabling delayed instantiation of a Worker.
  40
  41    - `onready` (optional, but...): this callback is called with no
  42    arguments when the worker fires its initial
  43    'sqlite3-api'/'worker1-ready' message, which it does when
  44    sqlite3.initWorker1API() completes its initialization. This is
  45    the simplest way to tell the worker to kick off work at the
  46    earliest opportunity.
  47
  48    - `onunhandled` (optional): a callback which gets passed the
  49    message event object for any worker.onmessage() events which
  50    are not handled by this proxy. Ideally that "should" never
  51    happen, as this proxy aims to handle all known message types.
  52
  53    - `generateMessageId` (optional): a function which, when passed an
  54    about-to-be-posted message object, generates a _unique_ message ID
  55    for the message, which this API then assigns as the messageId
  56    property of the message. It _must_ generate unique IDs on each call
  57    so that dispatching can work. If not defined, a default generator
  58    is used (which should be sufficient for most or all cases).
  59
  60    - `debug` (optional): a console.debug()-style function for logging
  61    information about messages.
  62
  63    This function returns a stateful factory function with the
  64    following interfaces:
  65
  66    - Promise function(messageType, messageArgs)
  67    - Promise function({message object})
  68
  69    The first form expects the "type" and "args" values for a Worker
  70    message. The second expects an object in the form {type:...,
  71    args:...}  plus any other properties the client cares to set. This
  72    function will always set the `messageId` property on the object,
  73    even if it's already set, and will set the `dbId` property to the
  74    current database ID if it is _not_ set in the message object.
  75
  76    The function throws on error.
  77
  78    The function installs a temporary message listener, posts a
  79    message to the configured Worker, and handles the message's
  80    response via the temporary message listener. The then() callback
  81    of the returned Promise is passed the `message.data` property from
  82    the resulting message, i.e. the payload from the worker, stripped
  83    of the lower-level event state which the onmessage() handler
  84    receives.
  85
  86    Example usage:
  87
  88    ```
  89    const config = {...};
  90    const sq3Promiser = sqlite3Worker1Promiser(config);
  91    sq3Promiser('open', {filename:"/foo.db"}).then(function(msg){
  92      console.log("open response",msg); // => {type:'open', result: {filename:'/foo.db'}, ...}
  93    });
  94    sq3Promiser({type:'close'}).then((msg)=>{
  95      console.log("close response",msg); // => {type:'close', result: {filename:'/foo.db'}, ...}
  96    });
  97    ```
  98
  99    Differences from Worker API #1:
 100
 101    - exec's {callback: STRING} option does not work via this
 102    interface (it triggers an exception), but {callback: function}
 103    does and works exactly like the STRING form does in the Worker:
 104    the callback is called one time for each row of the result set,
 105    passed the same worker message format as the worker API emits:
 106
 107      {type:typeString,
 108       row:VALUE,
 109       rowNumber:1-based-#,
 110       columnNames: array}
 111
 112    Where `typeString` is an internally-synthesized message type string
 113    used temporarily for worker message dispatching. It can be ignored
 114    by all client code except that which tests this API. The `row`
 115    property contains the row result in the form implied by the
 116    `rowMode` option (defaulting to `'array'`). The `rowNumber` is a
 117    1-based integer value incremented by 1 on each call into th
 118    callback.
 119
 120    At the end of the result set, the same event is fired with
 121    (row=undefined, rowNumber=null) to indicate that
 122    the end of the result set has been reached. Note that the rows
 123    arrive via worker-posted messages, with all the implications
 124    of that.
 125 */
 126 self.sqlite3Worker1Promiser = function callee(config = callee.defaultConfig){
 127   // Inspired by: https://stackoverflow.com/a/52439530
 128   if(1===arguments.length && 'function'===typeof arguments[0]){
 129     const f = config;
 130     config = Object.assign(Object.create(null), callee.defaultConfig);
 131     config.onready = f;
 132   }else{
 133     config = Object.assign(Object.create(null), callee.defaultConfig, config);
 134   }
 135   const handlerMap = Object.create(null);
 136   const noop = function(){};
 137   const err = config.onerror
 138         || noop /* config.onerror is intentionally undocumented
 139                    pending finding a less ambiguous name */;
 140   const debug = config.debug || noop;
 141   const idTypeMap = config.generateMessageId ? undefined : Object.create(null);
 142   const genMsgId = config.generateMessageId || function(msg){
 143     return msg.type+'#'+(idTypeMap[msg.type] = (idTypeMap[msg.type]||0) + 1);
 144   };
 145   const toss = (...args)=>{throw new Error(args.join(' '))};
 146   if(!config.worker) config.worker = callee.defaultConfig.worker;
 147   if('function'===typeof config.worker) config.worker = config.worker();
 148   let dbId;
 149   config.worker.onmessage = function(ev){
 150     ev = ev.data;
 151     debug('worker1.onmessage',ev);
 152     let msgHandler = handlerMap[ev.messageId];
 153     if(!msgHandler){
 154       if(ev && 'sqlite3-api'===ev.type && 'worker1-ready'===ev.result) {
 155         /*fired one time when the Worker1 API initializes*/
 156         if(config.onready) config.onready();
 157         return;
 158       }
 159       msgHandler = handlerMap[ev.type] /* check for exec per-row callback */;
 160       if(msgHandler && msgHandler.onrow){
 161         msgHandler.onrow(ev);
 162         return;
 163       }
 164       if(config.onunhandled) config.onunhandled(arguments[0]);
 165       else err("sqlite3Worker1Promiser() unhandled worker message:",ev);
 166       return;
 167     }
 168     delete handlerMap[ev.messageId];
 169     switch(ev.type){
 170         case 'error':
 171           msgHandler.reject(ev);
 172           return;
 173         case 'open':
 174           if(!dbId) dbId = ev.dbId;
 175           break;
 176         case 'close':
 177           if(ev.dbId===dbId) dbId = undefined;
 178           break;
 179         default:
 180           break;
 181     }
 182     try {msgHandler.resolve(ev)}
 183     catch(e){msgHandler.reject(e)}
 184   }/*worker.onmessage()*/;
 185   return function(/*(msgType, msgArgs) || (msgEnvelope)*/){
 186     let msg;
 187     if(1===arguments.length){
 188       msg = arguments[0];
 189     }else if(2===arguments.length){
 190       msg = {
 191         type: arguments[0],
 192         args: arguments[1]
 193       };
 194     }else{
 195       toss("Invalid arugments for sqlite3Worker1Promiser()-created factory.");
 196     }
 197     if(!msg.dbId) msg.dbId = dbId;
 198     msg.messageId = genMsgId(msg);
 199     msg.departureTime = performance.now();
 200     const proxy = Object.create(null);
 201     proxy.message = msg;
 202     let rowCallbackId /* message handler ID for exec on-row callback proxy */;
 203     if('exec'===msg.type && msg.args){
 204       if('function'===typeof msg.args.callback){
 205         rowCallbackId = msg.messageId+':row';
 206         proxy.onrow = msg.args.callback;
 207         msg.args.callback = rowCallbackId;
 208         handlerMap[rowCallbackId] = proxy;
 209       }else if('string' === typeof msg.args.callback){
 210         toss("exec callback may not be a string when using the Promise interface.");
 211         /**
 212            Design note: the reason for this limitation is that this
 213            API takes over worker.onmessage() and the client has no way
 214            of adding their own message-type handlers to it. Per-row
 215            callbacks are implemented as short-lived message.type
 216            mappings for worker.onmessage().
 217
 218            We "could" work around this by providing a new
 219            config.fallbackMessageHandler (or some such) which contains
 220            a map of event type names to callbacks. Seems like overkill
 221            for now, seeing as the client can pass callback functions
 222            to this interface (whereas the string-form "callback" is
 223            needed for the over-the-Worker interface).
 224         */
 225       }
 226     }
 227     //debug("requestWork", msg);
 228     let p = new Promise(function(resolve, reject){
 229       proxy.resolve = resolve;
 230       proxy.reject = reject;
 231       handlerMap[msg.messageId] = proxy;
 232       debug("Posting",msg.type,"message to Worker dbId="+(dbId||'default')+':',msg);
 233       config.worker.postMessage(msg);
 234     });
 235     if(rowCallbackId) p = p.finally(()=>delete handlerMap[rowCallbackId]);
 236     return p;
 237   };
 238 }/*sqlite3Worker1Promiser()*/;
 239 self.sqlite3Worker1Promiser.defaultConfig = {
 240   worker: function(){
 241     let theJs = "sqlite3-worker1.js";
 242     if(this.currentScript){
 243       const src = this.currentScript.src.split('/');
 244       src.pop();
 245       theJs = src.join('/')+'/' + theJs;
 246       //console.warn("promiser currentScript, theJs =",this.currentScript,theJs);
 247     }else{
 248       //console.warn("promiser self.location =",self.location);
 249       const urlParams = new URL(self.location.href).searchParams;
 250       if(urlParams.has('sqlite3.dir')){
 251         theJs = urlParams.get('sqlite3.dir') + '/' + theJs;
 252       }
 253     }
 254     return new Worker(theJs + self.location.search);
 255   }.bind({
 256     currentScript: self?.document?.currentScript
 257   }),
 258   onerror: (...args)=>console.error('worker1 promiser error',...args)
 259 };