JS documentation cleanups. No code changes.

FossilOrigin-Name: 18e89a436daa18a8c972caf06b298da43c97a6ea3e2e5229dccb6920c27bfdb9

ext/wasm/api/sqlite3-api-prologue.js

@@ -11,76 +11,18 @@
   ***********************************************************************
 
   This file is intended to be combined at build-time with other
-  related code, most notably a header and footer which wraps this whole
+  related code, most notably a header and footer which wraps this
-  file into an Emscripten Module.postRun() handler which has a parameter
+  whole file into an Emscripten Module.postRun() handler which has a
-  named "Module" (the Emscripten Module object). The exact requirements,
+  parameter named "Module" (the Emscripten Module object). The sqlite3
-  conventions, and build process are very much under construction and
+  JS API has no hard requirements on Emscripten, and does not expose
-  will be (re)documented once they've stopped fluctuating so much.
+  any Emscripten APIs to clients. It is structured such that its build
+  can be tweaked to include it in arbitrary WASM environments which
+  supply the necessary underlying features (e.g. a POSIX file I/O
+  layer).
 
-  Project home page: https://sqlite.org
+  Main project home page: https://sqlite.org
 
   Documentation home page: https://sqlite.org/wasm
-
-  Specific goals of this subproject:
-
-  - Except where noted in the non-goals, provide a more-or-less
-    feature-complete wrapper to the sqlite3 C API, insofar as WASM
-    feature parity with C allows for. In fact, provide at least 4
-    APIs...
-
-    1) 1-to-1 bindings as exported from WASM, with no automatic
-       type conversions between JS and C.
-       
-    2) A binding of (1) which provides certain JS/C type conversions
-       to greatly simplify its use.
-
-    3) A higher-level API, more akin to sql.js and node.js-style
-       implementations. This one speaks directly to the low-level
-       API. This API must be used from the same thread as the
-       low-level API.
-
-    4) A second higher-level API which speaks to the previous APIs via
-       worker messages. This one is intended for use in the main
-       thread, with the lower-level APIs installed in a Worker thread,
-       and talking to them via Worker messages. Because Workers are
-       asynchronouns and have only a single message channel, some
-       acrobatics are needed here to feed async work results back to
-       the client (as we cannot simply pass around callbacks between
-       the main and Worker threads).
-
-  - Insofar as possible, support client-side storage using JS
-    filesystem APIs. As of this writing, such things are still very
-    much under development.
-
-  Specific non-goals of this project:
-
-  - As WASM is a web-centric technology and UTF-8 is the King of
-    Encodings in that realm, there are no currently plans to support
-    the UTF16-related sqlite3 APIs. They would add a complication to
-    the bindings for no appreciable benefit. Though web-related
-    implementation details take priority, and the JavaScript
-    components of the API specifically focus on browser clients, the
-    lower-level WASM module "should" work in non-web WASM
-    environments.
-
-  - Supporting old or niche-market platforms. WASM is built for a
-    modern web and requires modern platforms.
-
-  - Though scalar User-Defined Functions (UDFs) may be created in
-    JavaScript, there are currently no plans to add support for
-    aggregate and window functions.
-
-  Attribution:
-
-  This project is endebted to the work of sql.js:
-
-  https://github.com/sql-js/sql.js
-
-  sql.js was an essential stepping stone in this code's development as
-  it demonstrated how to handle some of the WASM-related voodoo (like
-  handling pointers-to-pointers and adding JS implementations of
-  C-bound callback functions). These APIs have a considerably
-  different shape than sql.js's, however.
 */
 
 /**
@@ -90,6 +32,10 @@
    for the current environment, and then optionally be removed from
    the global object using `delete self.sqlite3ApiBootstrap`.
 
+   This function is not intended for client-level use. It is intended
+   for use in creating bundles configured for specific WASM
+   environments.
+
    This function expects a configuration object, intended to abstract
    away details specific to any given WASM environment, primarily so
    that it can be used without any _direct_ dependency on
@@ -126,11 +72,11 @@
      environment. Defaults to `"free"`.
 
    - `wasmfsOpfsDir`[^1]: if the environment supports persistent
-     storage, this directory names the "mount point" for that
+     storage using OPFS-over-WASMFS , this directory names the "mount
-     directory. It must be prefixed by `/` and may contain only a
+     point" for that directory. It must be prefixed by `/` and may
-     single directory-name part. Using the root directory name is not
+     contain only a single directory-name part. Using the root
-     supported by any current persistent backend.  This setting is
+     directory name is not supported by any current persistent
-     only used in WASMFS-enabled builds.
+     backend.  This setting is only used in WASMFS-enabled builds.
 
 
    [^1] = This property may optionally be a function, in which case this
@@ -191,11 +137,7 @@ self.sqlite3ApiBootstrap = function sqlite3ApiBootstrap(
   const capi = Object.create(null);
   /**
      Holds state which are specific to the WASM-related
-     infrastructure and glue code. It is not expected that client
+     infrastructure and glue code.
-     code will normally need these, but they're exposed here in case
-     it does. These APIs are _not_ to be considered an
-     official/stable part of the sqlite3 WASM API. They may change
-     as the developers' experience suggests appropriate changes.
 
      Note that a number of members of this object are injected
      dynamically after the api object is fully constructed, so
@@ -228,7 +170,7 @@ self.sqlite3ApiBootstrap = function sqlite3ApiBootstrap(
        result of sqlite3.capi.sqlite3_js_rc_str() or (if that returns
        falsy) a synthesized string which contains that integer.
 
-       - If passed 2 arguments and the 2nd is a object, it bevaves
+       - If passed 2 arguments and the 2nd is a object, it behaves
        like the Error(string,object) constructor except that the first
        argument is subject to the is-integer semantics from the
        previous point.
@@ -686,9 +628,7 @@ self.sqlite3ApiBootstrap = function sqlite3ApiBootstrap(
     /**
        The WASM IR (Intermediate Representation) value for
        pointer-type values. It MUST refer to a value type of the
-       size described by this.ptrSizeof _or_ it may be any value
+       size described by this.ptrSizeof.
-       which ends in '*', which Emscripten's glue code internally
-       translates to i32.
     */
     ptrIR: config.wasmPtrIR || "i32",
     /**

manifest

@@ -1,5 +1,5 @@
-C Update\smultiplex3.test\sto\saccount\sfor\sthe\sfact\sthat\sthe\smultiplexor\sxDelete\smethod\smay\sreturn\san\serror\seven\sif\sit\smanages\sto\sdelete\sthe\sfirst\schunk\sof\sa\sfile.
+C JS\sdocumentation\scleanups.\sNo\scode\schanges.
-D 2022-11-24T15:32:00.589
+D 2022-11-24T16:03:49.104
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -503,7 +503,7 @@ F ext/wasm/api/sqlite3-api-cleanup.js ecdc69dbfccfe26146f04799fcfd4a6f5790d46e7e
 F ext/wasm/api/sqlite3-api-glue.js 056f44b82c126358a0175e08a892d56fadfce177b0d7a0012502a6acf67ea6d5
 F ext/wasm/api/sqlite3-api-oo1.js dec6c14994317ad0011714890426cdc211f4eab451c9766ea88c7ac4f535287e
 F ext/wasm/api/sqlite3-api-opfs.js 38d368e33f470f9ba196f1a2b0c9ce076c930c70df233c345a246f1ad4c26d3b
-F ext/wasm/api/sqlite3-api-prologue.js 58caf45e4cc0deec9bdddb051ce17408686f2bc21ea7b3ee0b4c4deaba532605
+F ext/wasm/api/sqlite3-api-prologue.js 7fce4c6a138ec3d7c285b7c125cee809e6b668d2cb0d2328a1b790b7037765bd
 F ext/wasm/api/sqlite3-api-worker1.js e94ba98e44afccfa482874cd9acb325883ade50ed1f9f9526beb9de1711f182f
 F ext/wasm/api/sqlite3-license-version-header.js a661182fc93fc2cf212dfd0b987f8e138a3ac98f850b1112e29b5fbdaecc87c3
 F ext/wasm/api/sqlite3-opfs-async-proxy.js 1ec10873f1d59d305f6f3b435c50a1b75d693d5fb739b226f3da46fcbb11261a
@@ -2059,8 +2059,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P f7eaa6ba2147bfd6dbdc2444d0f919d846aa7f9b68cccab17ef585ffdacf3d60
+P 1a7f3254735054ed8ca32d5ec7c8cde9195a64702638bdc50392007e396fead2
-R f39101951334943bf67c026388719509
+R abd9b2d5004cf0e1068a5fc8037a67b4
-U dan
+U stephan
-Z db7c150da52ab80c381cc3a21444c8d8
+Z 59d8b0c4ff23bb85893a1a0d379c6144
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-1a7f3254735054ed8ca32d5ec7c8cde9195a64702638bdc50392007e396fead2
+18e89a436daa18a8c972caf06b298da43c97a6ea3e2e5229dccb6920c27bfdb9