Minor touchups in JS docs and exception messages.

FossilOrigin-Name: 9e7fc9370dfca121244f7a2941e8de629b277f1799f8de08a43ff1d86f94b6f5

4 files changed, 42 insertions, 22 deletions

diff --git a/ext/wasm/api/sqlite3-api-oo1.js b/ext/wasm/api/sqlite3-api-oo1.js
index b225d80b9..8cd50a14b 100644
--- a/ext/wasm/api/sqlite3-api-oo1.js
+++ b/ext/wasm/api/sqlite3-api-oo1.js
@@ -112,10 +112,11 @@ globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){
      as a string, an ArrayBuffer, or a Uint8Array.
 
      This is a no-op in non-SEE builds. It throws on error and returns
-     without side effects if its key/textkey options are not of valid
-     types.
+     without side effects if none of the key/textkey/hexkey options
+     are set. It throws if more than one is set or if any are set to
+     values of an invalid type.
 
-     Returns true if it applies the key, else a falsy value.
+     Returns true if it applies the key, else an unspecified falsy value.
   */
   const dbCtorApplySEEKey = function(db,opt){
     if( !capi.sqlite3_key_v2 ) return;
@@ -123,7 +124,10 @@ globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){
     let key;
     const check = (opt.key ? 1 : 0) + (opt.hexkey ? 1 : 0) + (opt.textkey ? 1 : 0);
     if( !check ) return;
-    else if( check>1 ) toss3("Only ONE of (key, hexkey, textkey) may be provided.");
+    else if( check>1 ){
+      toss3(capi.SQLITE_MISUSE,
+            "Only ONE of (key, hexkey, textkey) may be provided.");
+    }
     if( opt.key ){
       /* It is not legal to bind an argument to PRAGMA key=?, so we
          convert it to a hexkey... */
@@ -136,7 +140,9 @@ globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){
         key = byteArrayToHex(key);
         keytype = 'hexkey';
       }else{
-        toss3("Invalid value for the 'key' option. Expecting a string, ArrayBuffer, or Uint8Array.");
+        toss3(capi.SQLITE_MISUSE,
+              "Invalid value for the 'key' option. Expecting a string,",
+              "ArrayBuffer, or Uint8Array.");
         return;
       }
     }else if( opt.textkey ){
@@ -150,7 +156,9 @@ globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){
       if(key instanceof Uint8Array){
         key = new TextDecoder('utf-8').decode(key);
       }else if('string'!==typeof key){
-        toss3("Invalid value for the 'textkey' option. Expecting a string, ArrayBuffer, or Uint8Array.");
+        toss3(capi.SQLITE_MISUSE,
+              "Invalid value for the 'textkey' option. Expecting a string,",
+              "ArrayBuffer, or Uint8Array.");
       }
     }else if( opt.hexkey ){
       keytype = 'hexkey';
@@ -158,7 +166,9 @@ globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){
       if((key instanceof ArrayBuffer) || (key instanceof Uint8Array)){
         key = byteArrayToHex(key);
       }else if('string'!==typeof key){
-        toss3("Invalid value for the 'hexkey' option. Expecting a string, ArrayBuffer, or Uint8Array.");
+        toss3(capi.SQLITE_MISUSE,
+              "Invalid value for the 'hexkey' option. Expecting a string,",
+              "ArrayBuffer, or Uint8Array.");
       }
       /* else assume it's valid hex codes */
     }else{
@@ -381,23 +391,33 @@ globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){
      - `vfs`: the VFS fname
 
 //#if enable-see
-     And, for SEE-capable builds, optionally ONE of the following:
+
+     SEE-capable builds optionally support ONE of the following
+     additional options:
 
      - `key`, `hexkey`, or `textkey`: encryption key as a string,
        ArrayBuffer, or Uint8Array. These flags function as documented
        for the SEE pragmas of the same names. Using a byte array for
        `hexkey` is equivalent to the same series of hex codes in
-       string form, so '666f6f' is equivalent to
-       Uint8Array([0x66,0x6f,0x6f]). A `textkey` byte array is assumed
-       to be UTF-8. A `key` string is transformed into a UTF-8 byte
-       array, and a `key` byte array is transformed into a `hexkey`
-       with the same bytes.
+       string form, so `'666f6f'` is equivalent to
+       `Uint8Array([0x66,0x6f,0x6f])`. A `textkey` byte array is
+       assumed to be UTF-8. A `key` string is transformed into a UTF-8
+       byte array, and a `key` byte array is transformed into a
+       `hexkey` with the same bytes.
 
      In non-SEE builds, these options are ignored. In SEE builds,
      `PRAGMA key/textkey/hexkey=X` is executed immediately after
      opening the db. If more than one of the options is provided,
      or any option has an invalid argument type, an exception is
      thrown.
+
+     Note that some DB subclasses may run post-initialization SQL
+     code, e.g. to set a busy-handler timeout or tweak the page cache
+     size. Such code is run _after_ the SEE key is applied. If no key
+     is supplied and the database is encrypted, execution of the
+     post-initialization SQL will fail, causing the constructor to
+     throw.
+
 //#endif enable-see
 
      The `filename` and `vfs` arguments may be either JS strings or
diff --git a/ext/wasm/api/sqlite3-api-prologue.js b/ext/wasm/api/sqlite3-api-prologue.js
index c3cc25f43..849dfe10f 100644
--- a/ext/wasm/api/sqlite3-api-prologue.js
+++ b/ext/wasm/api/sqlite3-api-prologue.js
@@ -245,7 +245,7 @@ globalThis.sqlite3ApiBootstrap = function sqlite3ApiBootstrap(
 
        The exception's message is created by concatenating its
        arguments with a space between each, except for the
-       two-args-with-an-objec form and that the first argument will
+       two-args-with-an-object form and that the first argument will
        get coerced to a string, as described above, if it's an
        integer.
 
diff --git a/manifest b/manifest
index 7b3f6096f..59bddf164 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C When\srunning\sthe\s'dist'\starget\sin\sext/wasm\sfor\san\sSEE-capable\sbuild,\sensure\sthat\sthe\sresulting\szip\sfile\sand\sdirectory\sname\sinclude\s'-see'.
-D 2024-04-23T05:38:49.383
+C Minor\stouchups\sin\sJS\sdocs\sand\sexception\smessages.
+D 2024-04-23T06:36:28.862
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -607,8 +607,8 @@ F ext/wasm/api/post-js-header.js 04dc12c3edd666b64a1b4ef3b6690c88dcc653f26451fd4
 F ext/wasm/api/pre-js.c-pp.js ad906703f7429590f2fbf5e6498513bf727a1a4f0ebfa057afb08161d7511219
 F ext/wasm/api/sqlite3-api-cleanup.js d235ad237df6954145404305040991c72ef8b1881715d2a650dda7b3c2576d0e
 F ext/wasm/api/sqlite3-api-glue.js c744f4b919e1254c898b467573858671a1c8797c2490d0eca2fdbadf2d0ac74b
-F ext/wasm/api/sqlite3-api-oo1.js 7a7828c2748d60664f155821fab2d091db23399e64f3470ea14f52080d3573f7
-F ext/wasm/api/sqlite3-api-prologue.js 93a72b07b2a5d964d2edc76a90b439ece49298bd7ba60a1c6ae5d4878213701e
+F ext/wasm/api/sqlite3-api-oo1.js 40f6834314b60e636f0046a9c49b8566a992dcf04be9ea593e680c23f6984b2b
+F ext/wasm/api/sqlite3-api-prologue.js 34457b25dcf0005c81d76f011f207026ec164f6ff0f69f024b608025ca808ea9
 F ext/wasm/api/sqlite3-api-worker1.js 8d9c0562831f62218170a3373468d8a0b7a6503b5985e309b69bf71187b525cf
 F ext/wasm/api/sqlite3-license-version-header.js 0c807a421f0187e778dc1078f10d2994b915123c1223fe752b60afdcd1263f89
 F ext/wasm/api/sqlite3-opfs-async-proxy.js 196ad83d36ca794e564044788c9d21b964679d63cad865f604da37c4afc9a285
@@ -2185,8 +2185,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 b4a6d32662acacb7767cfb9b8e040e6eb1f99322cb7d0cd44e6265e9ac2fb2e8
-R 7804df285b1889ac6d0dbfb4c36fb69b
+P 04c552b12e3b77b9dfd83838d35ce19a37ed024a8c18a2000ada10cf3d1eb6ad
+R ed22115253110bc0abaf81953307bf22
 U stephan
-Z 47a1361c4075358585b8d5f5c90006b4
+Z 8b53fb3b4d609195342a0ce669cacf2a
 # Remove this line to create a well-formed Fossil manifest.
diff --git a/manifest.uuid b/manifest.uuid
index a235332cd..0b66f11a1 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-04c552b12e3b77b9dfd83838d35ce19a37ed024a8c18a2000ada10cf3d1eb6ad
\ No newline at end of file
+9e7fc9370dfca121244f7a2941e8de629b277f1799f8de08a43ff1d86f94b6f5
\ No newline at end of file