Adding upstream version 3.45.1.upstream/3.45.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1469 insertions, 0 deletions

diff --git a/ext/wasm/api/sqlite3-vfs-opfs.c-pp.js b/ext/wasm/api/sqlite3-vfs-opfs.c-pp.js
new file mode 100644
index 0000000..af89f21
--- /dev/null
+++ b/ext/wasm/api/sqlite3-vfs-opfs.c-pp.js
@@ -0,0 +1,1469 @@
+//#ifnot target=node
+/*
+  2022-09-18
+
+  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.
+
+  ***********************************************************************
+
+  This file holds the synchronous half of an sqlite3_vfs
+  implementation which proxies, in a synchronous fashion, the
+  asynchronous Origin-Private FileSystem (OPFS) APIs using a second
+  Worker, implemented in sqlite3-opfs-async-proxy.js.  This file is
+  intended to be appended to the main sqlite3 JS deliverable somewhere
+  after sqlite3-api-oo1.js and before sqlite3-api-cleanup.js.
+*/
+'use strict';
+globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){
+/**
+   installOpfsVfs() returns a Promise which, on success, installs an
+   sqlite3_vfs named "opfs", suitable for use with all sqlite3 APIs
+   which accept a VFS. It is intended to be called via
+   sqlite3ApiBootstrap.initializers or an equivalent mechanism.
+
+   The installed VFS uses the Origin-Private FileSystem API for
+   all file storage. On error it is rejected with an exception
+   explaining the problem. Reasons for rejection include, but are
+   not limited to:
+
+   - The counterpart Worker (see below) could not be loaded.
+
+   - The environment does not support OPFS. That includes when
+     this function is called from the main window thread.
+
+  Significant notes and limitations:
+
+  - As of this writing, OPFS is still very much in flux and only
+    available in bleeding-edge versions of Chrome (v102+, noting that
+    that number will increase as the OPFS API matures).
+
+  - The OPFS features used here are only available in dedicated Worker
+    threads. This file tries to detect that case, resulting in a
+    rejected Promise if those features do not seem to be available.
+
+  - It requires the SharedArrayBuffer and Atomics classes, and the
+    former is only available if the HTTP server emits the so-called
+    COOP and COEP response headers. These features are required for
+    proxying OPFS's synchronous API via the synchronous interface
+    required by the sqlite3_vfs API.
+
+  - This function may only be called a single time. When called, this
+    function removes itself from the sqlite3 object.
+
+  All arguments to this function are for internal/development purposes
+  only. They do not constitute a public API and may change at any
+  time.
+
+  The argument may optionally be a plain object with the following
+  configuration options:
+
+  - proxyUri: as described above
+
+  - verbose (=2): an integer 0-3. 0 disables all logging, 1 enables
+    logging of errors. 2 enables logging of warnings and errors. 3
+    additionally enables debugging info.
+
+  - sanityChecks (=false): if true, some basic sanity tests are
+    run on the OPFS VFS API after it's initialized, before the
+    returned Promise resolves.
+
+  On success, the Promise resolves to the top-most sqlite3 namespace
+  object and that object gets a new object installed in its
+  `opfs` property, containing several OPFS-specific utilities.
+*/
+const installOpfsVfs = function callee(options){
+  if(!globalThis.SharedArrayBuffer
+    || !globalThis.Atomics){
+    return Promise.reject(
+      new Error("Cannot install OPFS: Missing SharedArrayBuffer and/or Atomics. "+
+                "The server must emit the COOP/COEP response headers to enable those. "+
+                "See https://sqlite.org/wasm/doc/trunk/persistence.md#coop-coep")
+    );
+  }else if('undefined'===typeof WorkerGlobalScope){
+    return Promise.reject(
+      new Error("The OPFS sqlite3_vfs cannot run in the main thread "+
+                "because it requires Atomics.wait().")
+    );
+  }else if(!globalThis.FileSystemHandle ||
+           !globalThis.FileSystemDirectoryHandle ||
+           !globalThis.FileSystemFileHandle ||
+           !globalThis.FileSystemFileHandle.prototype.createSyncAccessHandle ||
+           !navigator?.storage?.getDirectory){
+    return Promise.reject(
+      new Error("Missing required OPFS APIs.")
+    );
+  }
+  if(!options || 'object'!==typeof options){
+    options = Object.create(null);
+  }
+  const urlParams = new URL(globalThis.location.href).searchParams;
+  if(urlParams.has('opfs-disable')){
+    //sqlite3.config.warn('Explicitly not installing "opfs" VFS due to opfs-disable flag.');
+    return Promise.resolve(sqlite3);
+  }
+  if(undefined===options.verbose){
+    options.verbose = urlParams.has('opfs-verbose')
+      ? (+urlParams.get('opfs-verbose') || 2) : 1;
+  }
+  if(undefined===options.sanityChecks){
+    options.sanityChecks = urlParams.has('opfs-sanity-check');
+  }
+  if(undefined===options.proxyUri){
+    options.proxyUri = callee.defaultProxyUri;
+  }
+
+  //sqlite3.config.warn("OPFS options =",options,globalThis.location);
+
+  if('function' === typeof options.proxyUri){
+    options.proxyUri = options.proxyUri();
+  }
+  const thePromise = new Promise(function(promiseResolve_, promiseReject_){
+    const loggers = [
+      sqlite3.config.error,
+      sqlite3.config.warn,
+      sqlite3.config.log
+    ];
+    const logImpl = (level,...args)=>{
+      if(options.verbose>level) loggers[level]("OPFS syncer:",...args);
+    };
+    const log =    (...args)=>logImpl(2, ...args);
+    const warn =   (...args)=>logImpl(1, ...args);
+    const error =  (...args)=>logImpl(0, ...args);
+    const toss = sqlite3.util.toss;
+    const capi = sqlite3.capi;
+    const util = sqlite3.util;
+    const wasm = sqlite3.wasm;
+    const sqlite3_vfs = capi.sqlite3_vfs;
+    const sqlite3_file = capi.sqlite3_file;
+    const sqlite3_io_methods = capi.sqlite3_io_methods;
+    /**
+       Generic utilities for working with OPFS. This will get filled out
+       by the Promise setup and, on success, installed as sqlite3.opfs.
+
+       ACHTUNG: do not rely on these APIs in client code. They are
+       experimental and subject to change or removal as the
+       OPFS-specific sqlite3_vfs evolves.
+    */
+    const opfsUtil = Object.create(null);
+
+    /**
+       Returns true if _this_ thread has access to the OPFS APIs.
+    */
+    const thisThreadHasOPFS = ()=>{
+      return globalThis.FileSystemHandle &&
+        globalThis.FileSystemDirectoryHandle &&
+        globalThis.FileSystemFileHandle &&
+        globalThis.FileSystemFileHandle.prototype.createSyncAccessHandle &&
+        navigator?.storage?.getDirectory;
+    };
+
+    /**
+       Not part of the public API. Solely for internal/development
+       use.
+    */
+    opfsUtil.metrics = {
+      dump: function(){
+        let k, n = 0, t = 0, w = 0;
+        for(k in state.opIds){
+          const m = metrics[k];
+          n += m.count;
+          t += m.time;
+          w += m.wait;
+          m.avgTime = (m.count && m.time) ? (m.time / m.count) : 0;
+          m.avgWait = (m.count && m.wait) ? (m.wait / m.count) : 0;
+        }
+        sqlite3.config.log(globalThis.location.href,
+                    "metrics for",globalThis.location.href,":",metrics,
+                    "\nTotal of",n,"op(s) for",t,
+                    "ms (incl. "+w+" ms of waiting on the async side)");
+        sqlite3.config.log("Serialization metrics:",metrics.s11n);
+        W.postMessage({type:'opfs-async-metrics'});
+      },
+      reset: function(){
+        let k;
+        const r = (m)=>(m.count = m.time = m.wait = 0);
+        for(k in state.opIds){
+          r(metrics[k] = Object.create(null));
+        }
+        let s = metrics.s11n = Object.create(null);
+        s = s.serialize = Object.create(null);
+        s.count = s.time = 0;
+        s = metrics.s11n.deserialize = Object.create(null);
+        s.count = s.time = 0;
+      }
+    }/*metrics*/;
+    const opfsIoMethods = new sqlite3_io_methods();
+    const opfsVfs = new sqlite3_vfs()
+          .addOnDispose( ()=>opfsIoMethods.dispose());
+    let promiseWasRejected = undefined;
+    const promiseReject = (err)=>{
+      promiseWasRejected = true;
+      opfsVfs.dispose();
+      return promiseReject_(err);
+    };
+    const promiseResolve = ()=>{
+      promiseWasRejected = false;
+      return promiseResolve_(sqlite3);
+    };
+    const W =
+//#if target=es6-bundler-friendly
+    new Worker(new URL("sqlite3-opfs-async-proxy.js", import.meta.url));
+//#elif target=es6-module
+    new Worker(new URL(options.proxyUri, import.meta.url));
+//#else
+    new Worker(options.proxyUri);
+//#endif
+    setTimeout(()=>{
+      /* At attempt to work around a browser-specific quirk in which
+         the Worker load is failing in such a way that we neither
+         resolve nor reject it. This workaround gives that resolve/reject
+         a time limit and rejects if that timer expires. Discussion:
+         https://sqlite.org/forum/forumpost/a708c98dcb3ef */
+      if(undefined===promiseWasRejected){
+        promiseReject(
+          new Error("Timeout while waiting for OPFS async proxy worker.")
+        );
+      }
+    }, 4000);
+    W._originalOnError = W.onerror /* will be restored later */;
+    W.onerror = function(err){
+      // The error object doesn't contain any useful info when the
+      // failure is, e.g., that the remote script is 404.
+      error("Error initializing OPFS asyncer:",err);
+      promiseReject(new Error("Loading OPFS async Worker failed for unknown reasons."));
+    };
+    const pDVfs = capi.sqlite3_vfs_find(null)/*pointer to default VFS*/;
+    const dVfs = pDVfs
+          ? new sqlite3_vfs(pDVfs)
+          : null /* dVfs will be null when sqlite3 is built with
+                    SQLITE_OS_OTHER. */;
+    opfsIoMethods.$iVersion = 1;
+    opfsVfs.$iVersion = 2/*yes, two*/;
+    opfsVfs.$szOsFile = capi.sqlite3_file.structInfo.sizeof;
+    opfsVfs.$mxPathname = 1024/*sure, why not?*/;
+    opfsVfs.$zName = wasm.allocCString("opfs");
+    // All C-side memory of opfsVfs is zeroed out, but just to be explicit:
+    opfsVfs.$xDlOpen = opfsVfs.$xDlError = opfsVfs.$xDlSym = opfsVfs.$xDlClose = null;
+    opfsVfs.addOnDispose(
+      '$zName', opfsVfs.$zName,
+      'cleanup default VFS wrapper', ()=>(dVfs ? dVfs.dispose() : null)
+    );
+    /**
+       Pedantic sidebar about opfsVfs.ondispose: the entries in that array
+       are items to clean up when opfsVfs.dispose() is called, but in this
+       environment it will never be called. The VFS instance simply
+       hangs around until the WASM module instance is cleaned up. We
+       "could" _hypothetically_ clean it up by "importing" an
+       sqlite3_os_end() impl into the wasm build, but the shutdown order
+       of the wasm engine and the JS one are undefined so there is no
+       guaranty that the opfsVfs instance would be available in one
+       environment or the other when sqlite3_os_end() is called (_if_ it
+       gets called at all in a wasm build, which is undefined).
+    */
+    /**
+       State which we send to the async-api Worker or share with it.
+       This object must initially contain only cloneable or sharable
+       objects. After the worker's "inited" message arrives, other types
+       of data may be added to it.
+
+       For purposes of Atomics.wait() and Atomics.notify(), we use a
+       SharedArrayBuffer with one slot reserved for each of the API
+       proxy's methods. The sync side of the API uses Atomics.wait()
+       on the corresponding slot and the async side uses
+       Atomics.notify() on that slot.
+
+       The approach of using a single SAB to serialize comms for all
+       instances might(?) lead to deadlock situations in multi-db
+       cases. We should probably have one SAB here with a single slot
+       for locking a per-file initialization step and then allocate a
+       separate SAB like the above one for each file. That will
+       require a bit of acrobatics but should be feasible. The most
+       problematic part is that xOpen() would have to use
+       postMessage() to communicate its SharedArrayBuffer, and mixing
+       that approach with Atomics.wait/notify() gets a bit messy.
+    */
+    const state = Object.create(null);
+    state.verbose = options.verbose;
+    state.littleEndian = (()=>{
+      const buffer = new ArrayBuffer(2);
+      new DataView(buffer).setInt16(0, 256, true /* ==>littleEndian */);
+      // Int16Array uses the platform's endianness.
+      return new Int16Array(buffer)[0] === 256;
+    })();
+    /**
+       asyncIdleWaitTime is how long (ms) to wait, in the async proxy,
+       for each Atomics.wait() when waiting on inbound VFS API calls.
+       We need to wake up periodically to give the thread a chance to
+       do other things. If this is too high (e.g. 500ms) then even two
+       workers/tabs can easily run into locking errors. Some multiple
+       of this value is also used for determining how long to wait on
+       lock contention to free up.
+    */
+    state.asyncIdleWaitTime = 150;
+
+    /**
+       Whether the async counterpart should log exceptions to
+       the serialization channel. That produces a great deal of
+       noise for seemingly innocuous things like xAccess() checks
+       for missing files, so this option may have one of 3 values:
+
+       0 = no exception logging.
+
+       1 = only log exceptions for "significant" ops like xOpen(),
+       xRead(), and xWrite().
+
+       2 = log all exceptions.
+    */
+    state.asyncS11nExceptions = 1;
+    /* Size of file I/O buffer block. 64k = max sqlite3 page size, and
+       xRead/xWrite() will never deal in blocks larger than that. */
+    state.fileBufferSize = 1024 * 64;
+    state.sabS11nOffset = state.fileBufferSize;
+    /**
+       The size of the block in our SAB for serializing arguments and
+       result values. Needs to be large enough to hold serialized
+       values of any of the proxied APIs. Filenames are the largest
+       part but are limited to opfsVfs.$mxPathname bytes. We also
+       store exceptions there, so it needs to be long enough to hold
+       a reasonably long exception string.
+    */
+    state.sabS11nSize = opfsVfs.$mxPathname * 2;
+    /**
+       The SAB used for all data I/O between the synchronous and
+       async halves (file i/o and arg/result s11n).
+    */
+    state.sabIO = new SharedArrayBuffer(
+      state.fileBufferSize/* file i/o block */
+      + state.sabS11nSize/* argument/result serialization block */
+    );
+    state.opIds = Object.create(null);
+    const metrics = Object.create(null);
+    {
+      /* Indexes for use in our SharedArrayBuffer... */
+      let i = 0;
+      /* SAB slot used to communicate which operation is desired
+         between both workers. This worker writes to it and the other
+         listens for changes. */
+      state.opIds.whichOp = i++;
+      /* Slot for storing return values. This worker listens to that
+         slot and the other worker writes to it. */
+      state.opIds.rc = i++;
+      /* Each function gets an ID which this worker writes to
+         the whichOp slot. The async-api worker uses Atomic.wait()
+         on the whichOp slot to figure out which operation to run
+         next. */
+      state.opIds.xAccess = i++;
+      state.opIds.xClose = i++;
+      state.opIds.xDelete = i++;
+      state.opIds.xDeleteNoWait = i++;
+      state.opIds.xFileSize = i++;
+      state.opIds.xLock = i++;
+      state.opIds.xOpen = i++;
+      state.opIds.xRead = i++;
+      state.opIds.xSleep = i++;
+      state.opIds.xSync = i++;
+      state.opIds.xTruncate = i++;
+      state.opIds.xUnlock = i++;
+      state.opIds.xWrite = i++;
+      state.opIds.mkdir = i++;
+      state.opIds['opfs-async-metrics'] = i++;
+      state.opIds['opfs-async-shutdown'] = i++;
+      /* The retry slot is used by the async part for wait-and-retry
+         semantics. Though we could hypothetically use the xSleep slot
+         for that, doing so might lead to undesired side effects. */
+      state.opIds.retry = i++;
+      state.sabOP = new SharedArrayBuffer(
+        i * 4/* ==sizeof int32, noting that Atomics.wait() and friends
+                can only function on Int32Array views of an SAB. */);
+      opfsUtil.metrics.reset();
+    }
+    /**
+       SQLITE_xxx constants to export to the async worker
+       counterpart...
+    */
+    state.sq3Codes = Object.create(null);
+    [
+      'SQLITE_ACCESS_EXISTS',
+      'SQLITE_ACCESS_READWRITE',
+      'SQLITE_BUSY',
+      'SQLITE_ERROR',
+      'SQLITE_IOERR',
+      'SQLITE_IOERR_ACCESS',
+      'SQLITE_IOERR_CLOSE',
+      'SQLITE_IOERR_DELETE',
+      'SQLITE_IOERR_FSYNC',
+      'SQLITE_IOERR_LOCK',
+      'SQLITE_IOERR_READ',
+      'SQLITE_IOERR_SHORT_READ',
+      'SQLITE_IOERR_TRUNCATE',
+      'SQLITE_IOERR_UNLOCK',
+      'SQLITE_IOERR_WRITE',
+      'SQLITE_LOCK_EXCLUSIVE',
+      'SQLITE_LOCK_NONE',
+      'SQLITE_LOCK_PENDING',
+      'SQLITE_LOCK_RESERVED',
+      'SQLITE_LOCK_SHARED',
+      'SQLITE_LOCKED',
+      'SQLITE_MISUSE',
+      'SQLITE_NOTFOUND',
+      'SQLITE_OPEN_CREATE',
+      'SQLITE_OPEN_DELETEONCLOSE',
+      'SQLITE_OPEN_MAIN_DB',
+      'SQLITE_OPEN_READONLY'
+    ].forEach((k)=>{
+      if(undefined === (state.sq3Codes[k] = capi[k])){
+        toss("Maintenance required: not found:",k);
+      }
+    });
+    state.opfsFlags = Object.assign(Object.create(null),{
+      /**
+         Flag for use with xOpen(). "opfs-unlock-asap=1" enables
+         this. See defaultUnlockAsap, below.
+       */
+      OPFS_UNLOCK_ASAP: 0x01,
+      /**
+         If true, any async routine which implicitly acquires a sync
+         access handle (i.e. an OPFS lock) will release that locks at
+         the end of the call which acquires it. If false, such
+         "autolocks" are not released until the VFS is idle for some
+         brief amount of time.
+
+         The benefit of enabling this is much higher concurrency. The
+         down-side is much-reduced performance (as much as a 4x decrease
+         in speedtest1).
+      */
+      defaultUnlockAsap: false
+    });
+
+    /**
+       Runs the given operation (by name) in the async worker
+       counterpart, waits for its response, and returns the result
+       which the async worker writes to SAB[state.opIds.rc]. The
+       2nd and subsequent arguments must be the aruguments for the
+       async op.
+    */
+    const opRun = (op,...args)=>{
+      const opNdx = state.opIds[op] || toss("Invalid op ID:",op);
+      state.s11n.serialize(...args);
+      Atomics.store(state.sabOPView, state.opIds.rc, -1);
+      Atomics.store(state.sabOPView, state.opIds.whichOp, opNdx);
+      Atomics.notify(state.sabOPView, state.opIds.whichOp)
+      /* async thread will take over here */;
+      const t = performance.now();
+      Atomics.wait(state.sabOPView, state.opIds.rc, -1)
+      /* When this wait() call returns, the async half will have
+         completed the operation and reported its results. */;
+      const rc = Atomics.load(state.sabOPView, state.opIds.rc);
+      metrics[op].wait += performance.now() - t;
+      if(rc && state.asyncS11nExceptions){
+        const err = state.s11n.deserialize();
+        if(err) error(op+"() async error:",...err);
+      }
+      return rc;
+    };
+
+    /**
+       Not part of the public API. Only for test/development use.
+    */
+    opfsUtil.debug = {
+      asyncShutdown: ()=>{
+        warn("Shutting down OPFS async listener. The OPFS VFS will no longer work.");
+        opRun('opfs-async-shutdown');
+      },
+      asyncRestart: ()=>{
+        warn("Attempting to restart OPFS VFS async listener. Might work, might not.");
+        W.postMessage({type: 'opfs-async-restart'});
+      }
+    };
+
+    const initS11n = ()=>{
+      /**
+         !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+         ACHTUNG: this code is 100% duplicated in the other half of
+         this proxy! The documentation is maintained in the
+         "synchronous half".
+         !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+         This proxy de/serializes cross-thread function arguments and
+         output-pointer values via the state.sabIO SharedArrayBuffer,
+         using the region defined by (state.sabS11nOffset,
+         state.sabS11nOffset + state.sabS11nSize]. Only one dataset is
+         recorded at a time.
+
+         This is not a general-purpose format. It only supports the
+         range of operations, and data sizes, needed by the
+         sqlite3_vfs and sqlite3_io_methods operations. Serialized
+         data are transient and this serialization algorithm may
+         change at any time.
+
+         The data format can be succinctly summarized as:
+
+         Nt...Td...D
+
+         Where:
+
+         - N = number of entries (1 byte)
+
+         - t = type ID of first argument (1 byte)
+
+         - ...T = type IDs of the 2nd and subsequent arguments (1 byte
+         each).
+
+         - d = raw bytes of first argument (per-type size).
+
+         - ...D = raw bytes of the 2nd and subsequent arguments (per-type
+         size).
+
+         All types except strings have fixed sizes. Strings are stored
+         using their TextEncoder/TextDecoder representations. It would
+         arguably make more sense to store them as Int16Arrays of
+         their JS character values, but how best/fastest to get that
+         in and out of string form is an open point. Initial
+         experimentation with that approach did not gain us any speed.
+
+         Historical note: this impl was initially about 1% this size by
+         using using JSON.stringify/parse(), but using fit-to-purpose
+         serialization saves considerable runtime.
+      */
+      if(state.s11n) return state.s11n;
+      const textDecoder = new TextDecoder(),
+            textEncoder = new TextEncoder('utf-8'),
+            viewU8 = new Uint8Array(state.sabIO, state.sabS11nOffset, state.sabS11nSize),
+            viewDV = new DataView(state.sabIO, state.sabS11nOffset, state.sabS11nSize);
+      state.s11n = Object.create(null);
+      /* Only arguments and return values of these types may be
+         serialized. This covers the whole range of types needed by the
+         sqlite3_vfs API. */
+      const TypeIds = Object.create(null);
+      TypeIds.number  = { id: 1, size: 8, getter: 'getFloat64', setter: 'setFloat64' };
+      TypeIds.bigint  = { id: 2, size: 8, getter: 'getBigInt64', setter: 'setBigInt64' };
+      TypeIds.boolean = { id: 3, size: 4, getter: 'getInt32', setter: 'setInt32' };
+      TypeIds.string =  { id: 4 };
+
+      const getTypeId = (v)=>(
+        TypeIds[typeof v]
+          || toss("Maintenance required: this value type cannot be serialized.",v)
+      );
+      const getTypeIdById = (tid)=>{
+        switch(tid){
+            case TypeIds.number.id: return TypeIds.number;
+            case TypeIds.bigint.id: return TypeIds.bigint;
+            case TypeIds.boolean.id: return TypeIds.boolean;
+            case TypeIds.string.id: return TypeIds.string;
+            default: toss("Invalid type ID:",tid);
+        }
+      };
+
+      /**
+         Returns an array of the deserialized state stored by the most
+         recent serialize() operation (from from this thread or the
+         counterpart thread), or null if the serialization buffer is
+         empty.  If passed a truthy argument, the serialization buffer
+         is cleared after deserialization.
+      */
+      state.s11n.deserialize = function(clear=false){
+        ++metrics.s11n.deserialize.count;
+        const t = performance.now();
+        const argc = viewU8[0];
+        const rc = argc ? [] : null;
+        if(argc){
+          const typeIds = [];
+          let offset = 1, i, n, v;
+          for(i = 0; i < argc; ++i, ++offset){
+            typeIds.push(getTypeIdById(viewU8[offset]));
+          }
+          for(i = 0; i < argc; ++i){
+            const t = typeIds[i];
+            if(t.getter){
+              v = viewDV[t.getter](offset, state.littleEndian);
+              offset += t.size;
+            }else{/*String*/
+              n = viewDV.getInt32(offset, state.littleEndian);
+              offset += 4;
+              v = textDecoder.decode(viewU8.slice(offset, offset+n));
+              offset += n;
+            }
+            rc.push(v);
+          }
+        }
+        if(clear) viewU8[0] = 0;
+        //log("deserialize:",argc, rc);
+        metrics.s11n.deserialize.time += performance.now() - t;
+        return rc;
+      };
+
+      /**
+         Serializes all arguments to the shared buffer for consumption
+         by the counterpart thread.
+
+         This routine is only intended for serializing OPFS VFS
+         arguments and (in at least one special case) result values,
+         and the buffer is sized to be able to comfortably handle
+         those.
+
+         If passed no arguments then it zeroes out the serialization
+         state.
+      */
+      state.s11n.serialize = function(...args){
+        const t = performance.now();
+        ++metrics.s11n.serialize.count;
+        if(args.length){
+          //log("serialize():",args);
+          const typeIds = [];
+          let i = 0, offset = 1;
+          viewU8[0] = args.length & 0xff /* header = # of args */;
+          for(; i < args.length; ++i, ++offset){
+            /* Write the TypeIds.id value into the next args.length
+               bytes. */
+            typeIds.push(getTypeId(args[i]));
+            viewU8[offset] = typeIds[i].id;
+          }
+          for(i = 0; i < args.length; ++i) {
+            /* Deserialize the following bytes based on their
+               corresponding TypeIds.id from the header. */
+            const t = typeIds[i];
+            if(t.setter){
+              viewDV[t.setter](offset, args[i], state.littleEndian);
+              offset += t.size;
+            }else{/*String*/
+              const s = textEncoder.encode(args[i]);
+              viewDV.setInt32(offset, s.byteLength, state.littleEndian);
+              offset += 4;
+              viewU8.set(s, offset);
+              offset += s.byteLength;
+            }
+          }
+          //log("serialize() result:",viewU8.slice(0,offset));
+        }else{
+          viewU8[0] = 0;
+        }
+        metrics.s11n.serialize.time += performance.now() - t;
+      };
+      return state.s11n;
+    }/*initS11n()*/;
+
+    /**
+       Generates a random ASCII string len characters long, intended for
+       use as a temporary file name.
+    */
+    const randomFilename = function f(len=16){
+      if(!f._chars){
+        f._chars = "abcdefghijklmnopqrstuvwxyz"+
+          "ABCDEFGHIJKLMNOPQRSTUVWXYZ"+
+          "012346789";
+        f._n = f._chars.length;
+      }
+      const a = [];
+      let i = 0;
+      for( ; i < len; ++i){
+        const ndx = Math.random() * (f._n * 64) % f._n | 0;
+        a[i] = f._chars[ndx];
+      }
+      return a.join("");
+      /*
+        An alternative impl. with an unpredictable length
+        but much simpler:
+
+        Math.floor(Math.random() * Number.MAX_SAFE_INTEGER).toString(36)
+      */
+    };
+
+    /**
+       Map of sqlite3_file pointers to objects constructed by xOpen().
+    */
+    const __openFiles = Object.create(null);
+
+    const opTimer = Object.create(null);
+    opTimer.op = undefined;
+    opTimer.start = undefined;
+    const mTimeStart = (op)=>{
+      opTimer.start = performance.now();
+      opTimer.op = op;
+      ++metrics[op].count;
+    };
+    const mTimeEnd = ()=>(
+      metrics[opTimer.op].time += performance.now() - opTimer.start
+    );
+
+    /**
+       Impls for the sqlite3_io_methods methods. Maintenance reminder:
+       members are in alphabetical order to simplify finding them.
+    */
+    const ioSyncWrappers = {
+      xCheckReservedLock: function(pFile,pOut){
+        /**
+           As of late 2022, only a single lock can be held on an OPFS
+           file. We have no way of checking whether any _other_ db
+           connection has a lock except by trying to obtain and (on
+           success) release a sync-handle for it, but doing so would
+           involve an inherent race condition. For the time being,
+           pending a better solution, we simply report whether the
+           given pFile is open.
+        */
+        const f = __openFiles[pFile];
+        wasm.poke(pOut, f.lockType ? 1 : 0, 'i32');
+        return 0;
+      },
+      xClose: function(pFile){
+        mTimeStart('xClose');
+        let rc = 0;
+        const f = __openFiles[pFile];
+        if(f){
+          delete __openFiles[pFile];
+          rc = opRun('xClose', pFile);
+          if(f.sq3File) f.sq3File.dispose();
+        }
+        mTimeEnd();
+        return rc;
+      },
+      xDeviceCharacteristics: function(pFile){
+        //debug("xDeviceCharacteristics(",pFile,")");
+        return capi.SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN;
+      },
+      xFileControl: function(pFile, opId, pArg){
+        /*mTimeStart('xFileControl');
+          mTimeEnd();*/
+        return capi.SQLITE_NOTFOUND;
+      },
+      xFileSize: function(pFile,pSz64){
+        mTimeStart('xFileSize');
+        let rc = opRun('xFileSize', pFile);
+        if(0==rc){
+          try {
+            const sz = state.s11n.deserialize()[0];
+            wasm.poke(pSz64, sz, 'i64');
+          }catch(e){
+            error("Unexpected error reading xFileSize() result:",e);
+            rc = state.sq3Codes.SQLITE_IOERR;
+          }
+        }
+        mTimeEnd();
+        return rc;
+      },
+      xLock: function(pFile,lockType){
+        mTimeStart('xLock');
+        const f = __openFiles[pFile];
+        let rc = 0;
+        /* All OPFS locks are exclusive locks. If xLock() has
+           previously succeeded, do nothing except record the lock
+           type. If no lock is active, have the async counterpart
+           lock the file. */
+        if( !f.lockType ) {
+          rc = opRun('xLock', pFile, lockType);
+          if( 0===rc ) f.lockType = lockType;
+        }else{
+          f.lockType = lockType;
+        }
+        mTimeEnd();
+        return rc;
+      },
+      xRead: function(pFile,pDest,n,offset64){
+        mTimeStart('xRead');
+        const f = __openFiles[pFile];
+        let rc;
+        try {
+          rc = opRun('xRead',pFile, n, Number(offset64));
+          if(0===rc || capi.SQLITE_IOERR_SHORT_READ===rc){
+            /**
+               Results get written to the SharedArrayBuffer f.sabView.
+               Because the heap is _not_ a SharedArrayBuffer, we have
+               to copy the results. TypedArray.set() seems to be the
+               fastest way to copy this. */
+            wasm.heap8u().set(f.sabView.subarray(0, n), pDest);
+          }
+        }catch(e){
+          error("xRead(",arguments,") failed:",e,f);
+          rc = capi.SQLITE_IOERR_READ;
+        }
+        mTimeEnd();
+        return rc;
+      },
+      xSync: function(pFile,flags){
+        mTimeStart('xSync');
+        ++metrics.xSync.count;
+        const rc = opRun('xSync', pFile, flags);
+        mTimeEnd();
+        return rc;
+      },
+      xTruncate: function(pFile,sz64){
+        mTimeStart('xTruncate');
+        const rc = opRun('xTruncate', pFile, Number(sz64));
+        mTimeEnd();
+        return rc;
+      },
+      xUnlock: function(pFile,lockType){
+        mTimeStart('xUnlock');
+        const f = __openFiles[pFile];
+        let rc = 0;
+        if( capi.SQLITE_LOCK_NONE === lockType
+          && f.lockType ){
+          rc = opRun('xUnlock', pFile, lockType);
+        }
+        if( 0===rc ) f.lockType = lockType;
+        mTimeEnd();
+        return rc;
+      },
+      xWrite: function(pFile,pSrc,n,offset64){
+        mTimeStart('xWrite');
+        const f = __openFiles[pFile];
+        let rc;
+        try {
+          f.sabView.set(wasm.heap8u().subarray(pSrc, pSrc+n));
+          rc = opRun('xWrite', pFile, n, Number(offset64));
+        }catch(e){
+          error("xWrite(",arguments,") failed:",e,f);
+          rc = capi.SQLITE_IOERR_WRITE;
+        }
+        mTimeEnd();
+        return rc;
+      }
+    }/*ioSyncWrappers*/;
+
+    /**
+       Impls for the sqlite3_vfs methods. Maintenance reminder: members
+       are in alphabetical order to simplify finding them.
+    */
+    const vfsSyncWrappers = {
+      xAccess: function(pVfs,zName,flags,pOut){
+        mTimeStart('xAccess');
+        const rc = opRun('xAccess', wasm.cstrToJs(zName));
+        wasm.poke( pOut, (rc ? 0 : 1), 'i32' );
+        mTimeEnd();
+        return 0;
+      },
+      xCurrentTime: function(pVfs,pOut){
+        /* If it turns out that we need to adjust for timezone, see:
+           https://stackoverflow.com/a/11760121/1458521 */
+        wasm.poke(pOut, 2440587.5 + (new Date().getTime()/86400000),
+                  'double');
+        return 0;
+      },
+      xCurrentTimeInt64: function(pVfs,pOut){
+        wasm.poke(pOut, (2440587.5 * 86400000) + new Date().getTime(),
+                  'i64');
+        return 0;
+      },
+      xDelete: function(pVfs, zName, doSyncDir){
+        mTimeStart('xDelete');
+        const rc = opRun('xDelete', wasm.cstrToJs(zName), doSyncDir, false);
+        mTimeEnd();
+        return rc;
+      },
+      xFullPathname: function(pVfs,zName,nOut,pOut){
+        /* Until/unless we have some notion of "current dir"
+           in OPFS, simply copy zName to pOut... */
+        const i = wasm.cstrncpy(pOut, zName, nOut);
+        return i<nOut ? 0 : capi.SQLITE_CANTOPEN
+        /*CANTOPEN is required by the docs but SQLITE_RANGE would be a closer match*/;
+      },
+      xGetLastError: function(pVfs,nOut,pOut){
+        /* TODO: store exception.message values from the async
+           partner in a dedicated SharedArrayBuffer, noting that we'd have
+           to encode them... TextEncoder can do that for us. */
+        warn("OPFS xGetLastError() has nothing sensible to return.");
+        return 0;
+      },
+      //xSleep is optionally defined below
+      xOpen: function f(pVfs, zName, pFile, flags, pOutFlags){
+        mTimeStart('xOpen');
+        let opfsFlags = 0;
+        if(0===zName){
+          zName = randomFilename();
+        }else if('number'===typeof zName){
+          if(capi.sqlite3_uri_boolean(zName, "opfs-unlock-asap", 0)){
+            /* -----------------------^^^^^ MUST pass the untranslated
+               C-string here. */
+            opfsFlags |= state.opfsFlags.OPFS_UNLOCK_ASAP;
+          }
+          zName = wasm.cstrToJs(zName);
+        }
+        const fh = Object.create(null);
+        fh.fid = pFile;
+        fh.filename = zName;
+        fh.sab = new SharedArrayBuffer(state.fileBufferSize);
+        fh.flags = flags;
+        const rc = opRun('xOpen', pFile, zName, flags, opfsFlags);
+        if(!rc){
+          /* Recall that sqlite3_vfs::xClose() will be called, even on
+             error, unless pFile->pMethods is NULL. */
+          if(fh.readOnly){
+            wasm.poke(pOutFlags, capi.SQLITE_OPEN_READONLY, 'i32');
+          }
+          __openFiles[pFile] = fh;
+          fh.sabView = state.sabFileBufView;
+          fh.sq3File = new sqlite3_file(pFile);
+          fh.sq3File.$pMethods = opfsIoMethods.pointer;
+          fh.lockType = capi.SQLITE_LOCK_NONE;
+        }
+        mTimeEnd();
+        return rc;
+      }/*xOpen()*/
+    }/*vfsSyncWrappers*/;
+
+    if(dVfs){
+      opfsVfs.$xRandomness = dVfs.$xRandomness;
+      opfsVfs.$xSleep = dVfs.$xSleep;
+    }
+    if(!opfsVfs.$xRandomness){
+      /* If the default VFS has no xRandomness(), add a basic JS impl... */
+      vfsSyncWrappers.xRandomness = function(pVfs, nOut, pOut){
+        const heap = wasm.heap8u();
+        let i = 0;
+        for(; i < nOut; ++i) heap[pOut + i] = (Math.random()*255000) & 0xFF;
+        return i;
+      };
+    }
+    if(!opfsVfs.$xSleep){
+      /* If we can inherit an xSleep() impl from the default VFS then
+         assume it's sane and use it, otherwise install a JS-based
+         one. */
+      vfsSyncWrappers.xSleep = function(pVfs,ms){
+        Atomics.wait(state.sabOPView, state.opIds.xSleep, 0, ms);
+        return 0;
+      };
+    }
+
+    /**
+       Expects an OPFS file path. It gets resolved, such that ".."
+       components are properly expanded, and returned. If the 2nd arg
+       is true, the result is returned as an array of path elements,
+       else an absolute path string is returned.
+    */
+    opfsUtil.getResolvedPath = function(filename,splitIt){
+      const p = new URL(filename, "file://irrelevant").pathname;
+      return splitIt ? p.split('/').filter((v)=>!!v) : p;
+    };
+
+    /**
+       Takes the absolute path to a filesystem element. Returns an
+       array of [handleOfContainingDir, filename]. If the 2nd argument
+       is truthy then each directory element leading to the file is
+       created along the way. Throws if any creation or resolution
+       fails.
+    */
+    opfsUtil.getDirForFilename = async function f(absFilename, createDirs = false){
+      const path = opfsUtil.getResolvedPath(absFilename, true);
+      const filename = path.pop();
+      let dh = opfsUtil.rootDirectory;
+      for(const dirName of path){
+        if(dirName){
+          dh = await dh.getDirectoryHandle(dirName, {create: !!createDirs});
+        }
+      }
+      return [dh, filename];
+    };
+
+    /**
+       Creates the given directory name, recursively, in
+       the OPFS filesystem. Returns true if it succeeds or the
+       directory already exists, else false.
+    */
+    opfsUtil.mkdir = async function(absDirName){
+      try {
+        await opfsUtil.getDirForFilename(absDirName+"/filepart", true);
+        return true;
+      }catch(e){
+        //sqlite3.config.warn("mkdir(",absDirName,") failed:",e);
+        return false;
+      }
+    };
+    /**
+       Checks whether the given OPFS filesystem entry exists,
+       returning true if it does, false if it doesn't.
+    */
+    opfsUtil.entryExists = async function(fsEntryName){
+      try {
+        const [dh, fn] = await opfsUtil.getDirForFilename(fsEntryName);
+        await dh.getFileHandle(fn);
+        return true;
+      }catch(e){
+        return false;
+      }
+    };
+
+    /**
+       Generates a random ASCII string, intended for use as a
+       temporary file name. Its argument is the length of the string,
+       defaulting to 16.
+    */
+    opfsUtil.randomFilename = randomFilename;
+
+    /**
+       Re-registers the OPFS VFS. This is intended only for odd use
+       cases which have to call sqlite3_shutdown() as part of their
+       initialization process, which will unregister the VFS
+       registered by installOpfsVfs(). If passed a truthy value, the
+       OPFS VFS is registered as the default VFS, else it is not made
+       the default. Returns the result of the the
+       sqlite3_vfs_register() call.
+
+       Design note: the problem of having to re-register things after
+       a shutdown/initialize pair is more general. How to best plug
+       that in to the library is unclear. In particular, we cannot
+       hook in to any C-side calls to sqlite3_initialize(), so we
+       cannot add an after-initialize callback mechanism.
+    */
+    opfsUtil.registerVfs = (asDefault=false)=>{
+      return wasm.exports.sqlite3_vfs_register(
+        opfsVfs.pointer, asDefault ? 1 : 0
+      );
+    };
+
+    /**
+       Returns a promise which resolves to an object which represents
+       all files and directories in the OPFS tree. The top-most object
+       has two properties: `dirs` is an array of directory entries
+       (described below) and `files` is a list of file names for all
+       files in that directory.
+
+       Traversal starts at sqlite3.opfs.rootDirectory.
+
+       Each `dirs` entry is an object in this form:
+
+       ```
+       { name: directoryName,
+         dirs: [...subdirs],
+         files: [...file names]
+       }
+       ```
+
+       The `files` and `subdirs` entries are always set but may be
+       empty arrays.
+
+       The returned object has the same structure but its `name` is
+       an empty string. All returned objects are created with
+       Object.create(null), so have no prototype.
+
+       Design note: the entries do not contain more information,
+       e.g. file sizes, because getting such info is not only
+       expensive but is subject to locking-related errors.
+    */
+    opfsUtil.treeList = async function(){
+      const doDir = async function callee(dirHandle,tgt){
+        tgt.name = dirHandle.name;
+        tgt.dirs = [];
+        tgt.files = [];
+        for await (const handle of dirHandle.values()){
+          if('directory' === handle.kind){
+            const subDir = Object.create(null);
+            tgt.dirs.push(subDir);
+            await callee(handle, subDir);
+          }else{
+            tgt.files.push(handle.name);
+          }
+        }
+      };
+      const root = Object.create(null);
+      await doDir(opfsUtil.rootDirectory, root);
+      return root;
+    };
+
+    /**
+       Irrevocably deletes _all_ files in the current origin's OPFS.
+       Obviously, this must be used with great caution. It may throw
+       an exception if removal of anything fails (e.g. a file is
+       locked), but the precise conditions under which the underlying
+       APIs will throw are not documented (so we cannot tell you what
+       they are).
+    */
+    opfsUtil.rmfr = async function(){
+      const dir = opfsUtil.rootDirectory, opt = {recurse: true};
+      for await (const handle of dir.values()){
+        dir.removeEntry(handle.name, opt);
+      }
+    };
+
+    /**
+       Deletes the given OPFS filesystem entry.  As this environment
+       has no notion of "current directory", the given name must be an
+       absolute path. If the 2nd argument is truthy, deletion is
+       recursive (use with caution!).
+
+       The returned Promise resolves to true if the deletion was
+       successful, else false (but...). The OPFS API reports the
+       reason for the failure only in human-readable form, not
+       exceptions which can be type-checked to determine the
+       failure. Because of that...
+
+       If the final argument is truthy then this function will
+       propagate any exception on error, rather than returning false.
+    */
+    opfsUtil.unlink = async function(fsEntryName, recursive = false,
+                                     throwOnError = false){
+      try {
+        const [hDir, filenamePart] =
+              await opfsUtil.getDirForFilename(fsEntryName, false);
+        await hDir.removeEntry(filenamePart, {recursive});
+        return true;
+      }catch(e){
+        if(throwOnError){
+          throw new Error("unlink(",arguments[0],") failed: "+e.message,{
+            cause: e
+          });
+        }
+        return false;
+      }
+    };
+
+    /**
+       Traverses the OPFS filesystem, calling a callback for each one.
+       The argument may be either a callback function or an options object
+       with any of the following properties:
+
+       - `callback`: function which gets called for each filesystem
+         entry.  It gets passed 3 arguments: 1) the
+         FileSystemFileHandle or FileSystemDirectoryHandle of each
+         entry (noting that both are instanceof FileSystemHandle). 2)
+         the FileSystemDirectoryHandle of the parent directory. 3) the
+         current depth level, with 0 being at the top of the tree
+         relative to the starting directory. If the callback returns a
+         literal false, as opposed to any other falsy value, traversal
+         stops without an error. Any exceptions it throws are
+         propagated. Results are undefined if the callback manipulate
+         the filesystem (e.g. removing or adding entries) because the
+         how OPFS iterators behave in the face of such changes is
+         undocumented.
+
+       - `recursive` [bool=true]: specifies whether to recurse into
+         subdirectories or not. Whether recursion is depth-first or
+         breadth-first is unspecified!
+
+       - `directory` [FileSystemDirectoryEntry=sqlite3.opfs.rootDirectory]
+         specifies the starting directory.
+
+       If this function is passed a function, it is assumed to be the
+       callback.
+
+       Returns a promise because it has to (by virtue of being async)
+       but that promise has no specific meaning: the traversal it
+       performs is synchronous. The promise must be used to catch any
+       exceptions propagated by the callback, however.
+
+       TODO: add an option which specifies whether to traverse
+       depth-first or breadth-first. We currently do depth-first but
+       an incremental file browsing widget would benefit more from
+       breadth-first.
+    */
+    opfsUtil.traverse = async function(opt){
+      const defaultOpt = {
+        recursive: true,
+        directory: opfsUtil.rootDirectory
+      };
+      if('function'===typeof opt){
+        opt = {callback:opt};
+      }
+      opt = Object.assign(defaultOpt, opt||{});
+      const doDir = async function callee(dirHandle, depth){
+        for await (const handle of dirHandle.values()){
+          if(false === opt.callback(handle, dirHandle, depth)) return false;
+          else if(opt.recursive && 'directory' === handle.kind){
+            if(false === await callee(handle, depth + 1)) break;
+          }
+        }
+      };
+      doDir(opt.directory, 0);
+    };
+
+    /**
+       impl of importDb() when it's given a function as its second
+       argument.
+    */
+    const importDbChunked = async function(filename, callback){
+      const [hDir, fnamePart] = await opfsUtil.getDirForFilename(filename, true);
+      const hFile = await hDir.getFileHandle(fnamePart, {create:true});
+      let sah = await hFile.createSyncAccessHandle();
+      let nWrote = 0, chunk, checkedHeader = false, err = false;
+      try{
+        sah.truncate(0);
+        while( undefined !== (chunk = await callback()) ){
+          if(chunk instanceof ArrayBuffer) chunk = new Uint8Array(chunk);
+          if( 0===nWrote && chunk.byteLength>=15 ){
+            util.affirmDbHeader(chunk);
+            checkedHeader = true;
+          }
+          sah.write(chunk, {at: nWrote});
+          nWrote += chunk.byteLength;
+        }
+        if( nWrote < 512 || 0!==nWrote % 512 ){
+          toss("Input size",nWrote,"is not correct for an SQLite database.");
+        }
+        if( !checkedHeader ){
+          const header = new Uint8Array(20);
+          sah.read( header, {at: 0} );
+          util.affirmDbHeader( header );
+        }
+        sah.write(new Uint8Array([1,1]), {at: 18}/*force db out of WAL mode*/);
+        return nWrote;
+      }catch(e){
+        await sah.close();
+        sah = undefined;
+        await hDir.removeEntry( fnamePart ).catch(()=>{});
+        throw e;
+      }finally {
+        if( sah ) await sah.close();
+      }
+    };
+
+    /**
+       Asynchronously imports the given bytes (a byte array or
+       ArrayBuffer) into the given database file.
+
+       If passed a function for its second argument, its behaviour
+       changes to async and it imports its data in chunks fed to it by
+       the given callback function. It calls the callback (which may
+       be async) repeatedly, expecting either a Uint8Array or
+       ArrayBuffer (to denote new input) or undefined (to denote
+       EOF). For so long as the callback continues to return
+       non-undefined, it will append incoming data to the given
+       VFS-hosted database file. When called this way, the resolved
+       value of the returned Promise is the number of bytes written to
+       the target file.
+
+       It very specifically requires the input to be an SQLite3
+       database and throws if that's not the case.  It does so in
+       order to prevent this function from taking on a larger scope
+       than it is specifically intended to. i.e. we do not want it to
+       become a convenience for importing arbitrary files into OPFS.
+
+       This routine rewrites the database header bytes in the output
+       file (not the input array) to force disabling of WAL mode.
+
+       On error this throws and the state of the input file is
+       undefined (it depends on where the exception was triggered).
+
+       On success, resolves to the number of bytes written.
+    */
+    opfsUtil.importDb = async function(filename, bytes){
+      if( bytes instanceof Function ){
+        return importDbChunked(filename, bytes);
+      }
+      if(bytes instanceof ArrayBuffer) bytes = new Uint8Array(bytes);
+      util.affirmIsDb(bytes);
+      const n = bytes.byteLength;
+      const [hDir, fnamePart] = await opfsUtil.getDirForFilename(filename, true);
+      let sah, err, nWrote = 0;
+      try {
+        const hFile = await hDir.getFileHandle(fnamePart, {create:true});
+        sah = await hFile.createSyncAccessHandle();
+        sah.truncate(0);
+        nWrote = sah.write(bytes, {at: 0});
+        if(nWrote != n){
+          toss("Expected to write "+n+" bytes but wrote "+nWrote+".");
+        }
+        sah.write(new Uint8Array([1,1]), {at: 18}) /* force db out of WAL mode */;
+        return nWrote;
+      }catch(e){
+        if( sah ){ await sah.close(); sah = undefined; }
+        await hDir.removeEntry( fnamePart ).catch(()=>{});
+        throw e;
+      }finally{
+        if( sah ) await sah.close();
+      }
+    };
+
+    if(sqlite3.oo1){
+      const OpfsDb = function(...args){
+        const opt = sqlite3.oo1.DB.dbCtorHelper.normalizeArgs(...args);
+        opt.vfs = opfsVfs.$zName;
+        sqlite3.oo1.DB.dbCtorHelper.call(this, opt);
+      };
+      OpfsDb.prototype = Object.create(sqlite3.oo1.DB.prototype);
+      sqlite3.oo1.OpfsDb = OpfsDb;
+      OpfsDb.importDb = opfsUtil.importDb;
+      sqlite3.oo1.DB.dbCtorHelper.setVfsPostOpenSql(
+        opfsVfs.pointer,
+        function(oo1Db, sqlite3){
+          /* Set a relatively high default busy-timeout handler to
+             help OPFS dbs deal with multi-tab/multi-worker
+             contention. */
+          sqlite3.capi.sqlite3_busy_timeout(oo1Db, 10000);
+          sqlite3.capi.sqlite3_exec(oo1Db, [
+            /* As of July 2023, the PERSIST journal mode on OPFS is
+               somewhat slower than DELETE or TRUNCATE (it was faster
+               before Chrome version 108 or 109). TRUNCATE and DELETE
+               have very similar performance on OPFS.
+
+               Roy Hashimoto notes that TRUNCATE and PERSIST modes may
+               decrease OPFS concurrency because multiple connections
+               can open the journal file in those modes:
+
+               https://github.com/rhashimoto/wa-sqlite/issues/68
+
+               Given that, and the fact that testing has not revealed
+               any appreciable difference between performance of
+               TRUNCATE and DELETE modes on OPFS, we currently (as of
+               2023-07-13) default to DELETE mode.
+            */
+            "pragma journal_mode=DELETE;",
+            /*
+              This vfs benefits hugely from cache on moderate/large
+              speedtest1 --size 50 and --size 100 workloads. We
+              currently rely on setting a non-default cache size when
+              building sqlite3.wasm. If that policy changes, the cache
+              can be set here.
+            */
+            "pragma cache_size=-16384;"
+          ], 0, 0, 0);
+        }
+      );
+    }/*extend sqlite3.oo1*/
+
+    const sanityCheck = function(){
+      const scope = wasm.scopedAllocPush();
+      const sq3File = new sqlite3_file();
+      try{
+        const fid = sq3File.pointer;
+        const openFlags = capi.SQLITE_OPEN_CREATE
+              | capi.SQLITE_OPEN_READWRITE
+        //| capi.SQLITE_OPEN_DELETEONCLOSE
+              | capi.SQLITE_OPEN_MAIN_DB;
+        const pOut = wasm.scopedAlloc(8);
+        const dbFile = "/sanity/check/file"+randomFilename(8);
+        const zDbFile = wasm.scopedAllocCString(dbFile);
+        let rc;
+        state.s11n.serialize("This is ä string.");
+        rc = state.s11n.deserialize();
+        log("deserialize() says:",rc);
+        if("This is ä string."!==rc[0]) toss("String d13n error.");
+        vfsSyncWrappers.xAccess(opfsVfs.pointer, zDbFile, 0, pOut);
+        rc = wasm.peek(pOut,'i32');
+        log("xAccess(",dbFile,") exists ?=",rc);
+        rc = vfsSyncWrappers.xOpen(opfsVfs.pointer, zDbFile,
+                                   fid, openFlags, pOut);
+        log("open rc =",rc,"state.sabOPView[xOpen] =",
+            state.sabOPView[state.opIds.xOpen]);
+        if(0!==rc){
+          error("open failed with code",rc);
+          return;
+        }
+        vfsSyncWrappers.xAccess(opfsVfs.pointer, zDbFile, 0, pOut);
+        rc = wasm.peek(pOut,'i32');
+        if(!rc) toss("xAccess() failed to detect file.");
+        rc = ioSyncWrappers.xSync(sq3File.pointer, 0);
+        if(rc) toss('sync failed w/ rc',rc);
+        rc = ioSyncWrappers.xTruncate(sq3File.pointer, 1024);
+        if(rc) toss('truncate failed w/ rc',rc);
+        wasm.poke(pOut,0,'i64');
+        rc = ioSyncWrappers.xFileSize(sq3File.pointer, pOut);
+        if(rc) toss('xFileSize failed w/ rc',rc);
+        log("xFileSize says:",wasm.peek(pOut, 'i64'));
+        rc = ioSyncWrappers.xWrite(sq3File.pointer, zDbFile, 10, 1);
+        if(rc) toss("xWrite() failed!");
+        const readBuf = wasm.scopedAlloc(16);
+        rc = ioSyncWrappers.xRead(sq3File.pointer, readBuf, 6, 2);
+        wasm.poke(readBuf+6,0);
+        let jRead = wasm.cstrToJs(readBuf);
+        log("xRead() got:",jRead);
+        if("sanity"!==jRead) toss("Unexpected xRead() value.");
+        if(vfsSyncWrappers.xSleep){
+          log("xSleep()ing before close()ing...");
+          vfsSyncWrappers.xSleep(opfsVfs.pointer,2000);
+          log("waking up from xSleep()");
+        }
+        rc = ioSyncWrappers.xClose(fid);
+        log("xClose rc =",rc,"sabOPView =",state.sabOPView);
+        log("Deleting file:",dbFile);
+        vfsSyncWrappers.xDelete(opfsVfs.pointer, zDbFile, 0x1234);
+        vfsSyncWrappers.xAccess(opfsVfs.pointer, zDbFile, 0, pOut);
+        rc = wasm.peek(pOut,'i32');
+        if(rc) toss("Expecting 0 from xAccess(",dbFile,") after xDelete().");
+        warn("End of OPFS sanity checks.");
+      }finally{
+        sq3File.dispose();
+        wasm.scopedAllocPop(scope);
+      }
+    }/*sanityCheck()*/;
+
+    W.onmessage = function({data}){
+      //log("Worker.onmessage:",data);
+      switch(data.type){
+          case 'opfs-unavailable':
+            /* Async proxy has determined that OPFS is unavailable. There's
+               nothing more for us to do here. */
+            promiseReject(new Error(data.payload.join(' ')));
+            break;
+          case 'opfs-async-loaded':
+            /* Arrives as soon as the asyc proxy finishes loading.
+               Pass our config and shared state on to the async
+               worker. */
+            W.postMessage({type: 'opfs-async-init',args: state});
+            break;
+          case 'opfs-async-inited': {
+            /* Indicates that the async partner has received the 'init'
+               and has finished initializing, so the real work can
+               begin... */
+            if(true===promiseWasRejected){
+              break /* promise was already rejected via timer */;
+            }
+            try {
+              sqlite3.vfs.installVfs({
+                io: {struct: opfsIoMethods, methods: ioSyncWrappers},
+                vfs: {struct: opfsVfs, methods: vfsSyncWrappers}
+              });
+              state.sabOPView = new Int32Array(state.sabOP);
+              state.sabFileBufView = new Uint8Array(state.sabIO, 0, state.fileBufferSize);
+              state.sabS11nView = new Uint8Array(state.sabIO, state.sabS11nOffset, state.sabS11nSize);
+              initS11n();
+              if(options.sanityChecks){
+                warn("Running sanity checks because of opfs-sanity-check URL arg...");
+                sanityCheck();
+              }
+              if(thisThreadHasOPFS()){
+                navigator.storage.getDirectory().then((d)=>{
+                  W.onerror = W._originalOnError;
+                  delete W._originalOnError;
+                  sqlite3.opfs = opfsUtil;
+                  opfsUtil.rootDirectory = d;
+                  log("End of OPFS sqlite3_vfs setup.", opfsVfs);
+                  promiseResolve();
+                }).catch(promiseReject);
+              }else{
+                promiseResolve();
+              }
+            }catch(e){
+              error(e);
+              promiseReject(e);
+            }
+            break;
+          }
+          default: {
+            const errMsg = (
+              "Unexpected message from the OPFS async worker: " +
+              JSON.stringify(data)
+            );
+            error(errMsg);
+            promiseReject(new Error(errMsg));
+            break;
+          }
+      }/*switch(data.type)*/
+    }/*W.onmessage()*/;
+  })/*thePromise*/;
+  return thePromise;
+}/*installOpfsVfs()*/;
+installOpfsVfs.defaultProxyUri =
+  "sqlite3-opfs-async-proxy.js";
+globalThis.sqlite3ApiBootstrap.initializersAsync.push(async (sqlite3)=>{
+  try{
+    let proxyJs = installOpfsVfs.defaultProxyUri;
+    if(sqlite3.scriptInfo.sqlite3Dir){
+      installOpfsVfs.defaultProxyUri =
+        sqlite3.scriptInfo.sqlite3Dir + proxyJs;
+      //sqlite3.config.warn("installOpfsVfs.defaultProxyUri =",installOpfsVfs.defaultProxyUri);
+    }
+    return installOpfsVfs().catch((e)=>{
+      sqlite3.config.warn("Ignoring inability to install OPFS sqlite3_vfs:",e.message);
+    });
+  }catch(e){
+    sqlite3.config.error("installOpfsVfs() exception:",e);
+    return Promise.reject(e);
+  }
+});
+}/*sqlite3ApiBootstrap.initializers.push()*/);
+//#else
+/* The OPFS VFS parts are elided from builds targeting node.js. */
+//#endif target=node