doc: document sqlite parameter binding

doc/api/sqlite.md

@@ -91,13 +91,19 @@ more data types than SQLite, only a subset of JavaScript types are supported.
 Attempting to write an unsupported data type to SQLite will result in an
 exception.
 
-| Storage class | JavaScript to SQLite       | SQLite to JavaScript                  |
-| ------------- | -------------------------- | ------------------------------------- |
-| `NULL`        | {null}                     | {null}                                |
-| `INTEGER`     | {number} or {bigint}       | {number} or {bigint} _(configurable)_ |
-| `REAL`        | {number}                   | {number}                              |
-| `TEXT`        | {string}                   | {string}                              |
-| `BLOB`        | {TypedArray} or {DataView} | {Uint8Array}                          |
+| Storage class | JavaScript to SQLite                                            | SQLite to JavaScript                  |
+| ------------- | --------------------------------------------------------------- | ------------------------------------- |
+| `NULL`        | {null}                                                          | {null}                                |
+| `INTEGER`     | {number}, {bigint}, or {boolean}                                | {number} or {bigint} _(configurable)_ |
+| `REAL`        | {number}                                                        | {number}                              |
+| `TEXT`        | {string}                                                        | {string}                              |
+| `BLOB`        | {TypedArray}, {DataView}, {ArrayBuffer}, or {SharedArrayBuffer} | {Uint8Array}                          |
+
+Booleans are written as the `INTEGER` values `1` and `0`. Like any other
+`INTEGER` value, they are read back as {number} by default, or as {bigint}
+values (`1n` and `0n`) when reading BigInts is enabled. Writing a {bigint} that
+does not fit in a signed 64-bit integer throws an `ERR_INVALID_ARG_VALUE`
+error.
 
 APIs that read values from SQLite have a configuration option that determines
 whether `INTEGER` values are converted to `number` or `bigint` in JavaScript,
@@ -972,6 +978,49 @@ times with different bound values. Parameters also offer protection against
 [SQL injection][] attacks. For these reasons, prepared statements are preferred
 over hand-crafted SQL strings when handling user input.
 
+### Binding parameters
+
+The `all()`, `get()`, `iterate()`, and `run()` methods bind their arguments to
+the parameters of the prepared statement before executing it. Parameters are
+either anonymous or named.
+
+Anonymous parameters are written as `?` in SQL and are bound in order from the
+arguments passed to the method. The `?NNN` form assigns an explicit number to a
+placeholder, binding it to the argument at position `NNN`.
+
+```js
+db.prepare('SELECT ? AS a, ? AS b').get('x', 42);
+// { a: 'x', b: 42 }
+db.prepare('SELECT ?2 AS a, ?1 AS b').get('first', 'second');
+// { a: 'second', b: 'first' }
+```
+
+Named parameters begin with one of the prefix characters `$`, `:`, or `@` in
+SQL. They are bound from an object passed as the first argument. Repeating a
+name in the SQL binds the same value to every occurrence.
+
+```js
+db.prepare('SELECT $a AS a, $b AS b').get({ $a: 1, $b: 2 });
+// { a: 1, b: 2 }
+db.prepare('SELECT :a AS a').get({ ':a': 1 });
+// { a: 1 }
+db.prepare('SELECT @a AS a').get({ '@a': 1 });
+// { a: 1 }
+db.prepare('SELECT $k AS a, $k AS b').get({ k: 7 });
+// { a: 7, b: 7 }
+```
+
+The last example omits the prefix character from the object key. Bare names are
+allowed by default; see [`statement.setAllowBareNamedParameters()`][] for their
+caveats.
+
+Binding a key that does not name a parameter of the statement throws an
+`ERR_INVALID_STATE` error unless unknown named parameters are ignored. See
+[`statement.setAllowUnknownNamedParameters()`][].
+
+See [Type conversion between JavaScript and SQLite][] for the values that can be
+bound. Binding any other value throws an `ERR_INVALID_ARG_TYPE` error.
+
 ### `statement.all([namedParameters][, ...anonymousParameters])`
 
 <!-- YAML
@@ -986,16 +1035,17 @@ changes:
 
 * `namedParameters` {Object} An optional object used to bind named parameters.
   The keys of this object are used to configure the mapping.
-* `...anonymousParameters` {null|number|bigint|string|Buffer|TypedArray|DataView} Zero or
-  more values to bind to anonymous parameters.
+* `...anonymousParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
+  Zero or more values to bind to anonymous parameters.
 * Returns: {Array} An array of objects. Each object corresponds to a row
   returned by executing the prepared statement. The keys and values of each
   object correspond to the column names and values of the row.
 
 This method executes a prepared statement and returns all results as an array of
 objects. If the prepared statement does not return any results, this method
 returns an empty array. The prepared statement [parameters are bound][] using
-the values in `namedParameters` and `anonymousParameters`.
+the values in `namedParameters` and `anonymousParameters`. See
+[Binding parameters][].
 
 ### `statement.close()`
 
@@ -1063,8 +1113,8 @@ changes:
 
 * `namedParameters` {Object} An optional object used to bind named parameters.
   The keys of this object are used to configure the mapping.
-* `...anonymousParameters` {null|number|bigint|string|Buffer|TypedArray|DataView} Zero or
-  more values to bind to anonymous parameters.
+* `...anonymousParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
+  Zero or more values to bind to anonymous parameters.
 * Returns: {Object|undefined} An object corresponding to the first row returned
   by executing the prepared statement. The keys and values of the object
   correspond to the column names and values of the row. If no rows were returned
@@ -1073,7 +1123,8 @@ changes:
 This method executes a prepared statement and returns the first result as an
 object. If the prepared statement does not return any results, this method
 returns `undefined`. The prepared statement [parameters are bound][] using the
-values in `namedParameters` and `anonymousParameters`.
+values in `namedParameters` and `anonymousParameters`. See
+[Binding parameters][].
 
 ### `statement.iterate([namedParameters][, ...anonymousParameters])`
 
@@ -1091,16 +1142,17 @@ changes:
 
 * `namedParameters` {Object} An optional object used to bind named parameters.
   The keys of this object are used to configure the mapping.
-* `...anonymousParameters` {null|number|bigint|string|Buffer|TypedArray|DataView} Zero or
-  more values to bind to anonymous parameters.
+* `...anonymousParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
+  Zero or more values to bind to anonymous parameters.
 * Returns: {Iterator} An iterable iterator of objects. Each object corresponds to a row
   returned by executing the prepared statement. The keys and values of each
   object correspond to the column names and values of the row.
 
 This method executes a prepared statement and returns an iterator of
 objects. If the prepared statement does not return any results, this method
 returns an empty iterator. The prepared statement [parameters are bound][] using
-the values in `namedParameters` and `anonymousParameters`.
+the values in `namedParameters` and `anonymousParameters`. See
+[Binding parameters][].
 
 ### `statement.run([namedParameters][, ...anonymousParameters])`
 
@@ -1116,8 +1168,8 @@ changes:
 
 * `namedParameters` {Object} An optional object used to bind named parameters.
   The keys of this object are used to configure the mapping.
-* `...anonymousParameters` {null|number|bigint|string|Buffer|TypedArray|DataView} Zero or
-  more values to bind to anonymous parameters.
+* `...anonymousParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
+  Zero or more values to bind to anonymous parameters.
 * Returns: {Object}
   * `changes` {number|bigint} The number of rows modified, inserted, or deleted
     by the most recently completed `INSERT`, `UPDATE`, or `DELETE` statement.
@@ -1131,7 +1183,8 @@ changes:
 
 This method executes a prepared statement and returns an object summarizing the
 resulting changes. The prepared statement [parameters are bound][] using the
-values in `namedParameters` and `anonymousParameters`.
+values in `namedParameters` and `anonymousParameters`. See
+[Binding parameters][].
 
 ### `statement.setAllowBareNamedParameters(enabled)`
 
@@ -1142,14 +1195,15 @@ added: v22.5.0
 * `enabled` {boolean} Enables or disables support for binding named parameters
   without the prefix character.
 
-The names of SQLite parameters begin with a prefix character. By default,
-`node:sqlite` requires that this prefix character is present when binding
-parameters. However, with the exception of dollar sign character, these
-prefix characters also require extra quoting when used in object keys.
+The names of SQLite parameters begin with a prefix character. However, with the
+exception of the dollar sign character, these prefix characters also require
+extra quoting when used in object keys.
 
-To improve ergonomics, this method can be used to also allow bare named
-parameters, which do not require the prefix character in JavaScript code. There
-are several caveats to be aware of when enabling bare named parameters:
+To improve ergonomics, `node:sqlite` allows bare named parameters, which do not
+require the prefix character in JavaScript code, by default. This method can be
+used to disable that behavior, requiring the prefix character when binding.
+There are several caveats to be aware of when bare named parameters are
+allowed:
 
 * The prefix character is still required in SQL.
 * The prefix character is still allowed in JavaScript. In fact, prefixed names
@@ -1247,7 +1301,7 @@ added: v24.9.0
 
 * `stringElements` {string\[]} Template literal elements containing the SQL
   query.
-* `...boundParameters` {null|number|bigint|string|Buffer|TypedArray|DataView}
+* `...boundParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
   Parameter values to be bound to placeholders in the template string.
 * Returns: {Array} An array of objects representing the rows returned by the query.
 
@@ -1265,7 +1319,7 @@ added: v24.9.0
 
 * `stringElements` {string\[]} Template literal elements containing the SQL
   query.
-* `...boundParameters` {null|number|bigint|string|Buffer|TypedArray|DataView}
+* `...boundParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
   Parameter values to be bound to placeholders in the template string.
 * Returns: {Object | undefined} An object representing the first row returned by
   the query, or `undefined` if no rows are returned.
@@ -1283,7 +1337,7 @@ added: v24.9.0
 
 * `stringElements` {string\[]} Template literal elements containing the SQL
   query.
-* `...boundParameters` {null|number|bigint|string|Buffer|TypedArray|DataView}
+* `...boundParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
   Parameter values to be bound to placeholders in the template string.
 * Returns: {Iterator} An iterator that yields objects representing the rows returned by the query.
 
@@ -1300,7 +1354,7 @@ added: v24.9.0
 
 * `stringElements` {string\[]} Template literal elements containing the SQL
   query.
-* `...boundParameters` {null|number|bigint|string|Buffer|TypedArray|DataView}
+* `...boundParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
   Parameter values to be bound to placeholders in the template string.
 * Returns: {Object} An object containing information about the execution, including `changes` and `lastInsertRowid`.
 
@@ -1666,6 +1720,7 @@ callback function to indicate what type of operation is being authorized.
   </tr>
 </table>
 
+[Binding parameters]: #binding-parameters
 [Changesets and Patchsets]: https://www.sqlite.org/sessionintro.html#changesets_and_patchsets
 [Constants Passed To The Conflict Handler]: https://www.sqlite.org/session/c_changeset_conflict.html
 [Constants Returned From The Conflict Handler]: https://www.sqlite.org/session/c_changeset_abort.html
@@ -1714,6 +1769,8 @@ callback function to indicate what type of operation is being authorized.
 [`sqlite3session_create()`]: https://www.sqlite.org/session/sqlite3session_create.html
 [`sqlite3session_delete()`]: https://www.sqlite.org/session/sqlite3session_delete.html
 [`sqlite3session_patchset()`]: https://www.sqlite.org/session/sqlite3session_patchset.html
+[`statement.setAllowBareNamedParameters()`]: #statementsetallowbarenamedparametersenabled
+[`statement.setAllowUnknownNamedParameters()`]: #statementsetallowunknownnamedparametersenabled
 [busy timeout]: https://sqlite.org/c3ref/busy_timeout.html
 [connection]: https://www.sqlite.org/c3ref/sqlite3.html
 [data types]: https://www.sqlite.org/datatype3.html