2171 lines
83 KiB
JavaScript
2171 lines
83 KiB
JavaScript
//#ifnot omit-oo1
|
|
/*
|
|
2022-07-22
|
|
|
|
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 contains the so-called OO #1 API wrapper for the sqlite3
|
|
WASM build. It requires that sqlite3-api-glue.js has already run
|
|
and it installs its deliverable as globalThis.sqlite3.oo1.
|
|
*/
|
|
globalThis.sqlite3ApiBootstrap.initializers.push(function(sqlite3){
|
|
const toss = (...args)=>{throw new Error(args.join(' '))};
|
|
const toss3 = (...args)=>{throw new sqlite3.SQLite3Error(...args)};
|
|
|
|
const capi = sqlite3.capi, wasm = sqlite3.wasm, util = sqlite3.util;
|
|
/* What follows is colloquially known as "OO API #1". It is a
|
|
binding of the sqlite3 API which is designed to be run within
|
|
the same thread (main or worker) as the one in which the
|
|
sqlite3 WASM binding was initialized. This wrapper cannot use
|
|
the sqlite3 binding if, e.g., the wrapper is in the main thread
|
|
and the sqlite3 API is in a worker. */
|
|
|
|
/**
|
|
In order to keep clients from manipulating, perhaps
|
|
inadvertently, the underlying pointer values of DB and Stmt
|
|
instances, we'll gate access to them via the `pointer` property
|
|
accessor and store their real values in this map. Keys = DB/Stmt
|
|
objects, values = pointer values. This also unifies how those are
|
|
accessed, for potential use downstream via custom
|
|
wasm.xWrap() function signatures which know how to extract
|
|
it.
|
|
*/
|
|
const __ptrMap = new WeakMap();
|
|
/**
|
|
Map of DB instances to objects, each object being a map of Stmt
|
|
wasm pointers to Stmt objects.
|
|
*/
|
|
const __stmtMap = new WeakMap();
|
|
|
|
/** If object opts has _its own_ property named p then that
|
|
property's value is returned, else dflt is returned. */
|
|
const getOwnOption = (opts, p, dflt)=>{
|
|
const d = Object.getOwnPropertyDescriptor(opts,p);
|
|
return d ? d.value : dflt;
|
|
};
|
|
|
|
// Documented in DB.checkRc()
|
|
const checkSqlite3Rc = function(dbPtr, sqliteResultCode){
|
|
if(sqliteResultCode){
|
|
if(dbPtr instanceof DB) dbPtr = dbPtr.pointer;
|
|
toss3(
|
|
sqliteResultCode,
|
|
"sqlite3 result code",sqliteResultCode+":",
|
|
(dbPtr
|
|
? capi.sqlite3_errmsg(dbPtr)
|
|
: capi.sqlite3_errstr(sqliteResultCode))
|
|
);
|
|
}
|
|
return arguments[0];
|
|
};
|
|
|
|
/**
|
|
sqlite3_trace_v2() callback which gets installed by the DB ctor
|
|
if its open-flags contain "t".
|
|
*/
|
|
const __dbTraceToConsole =
|
|
wasm.installFunction('i(ippp)', function(t,c,p,x){
|
|
if(capi.SQLITE_TRACE_STMT===t){
|
|
// x == SQL, p == sqlite3_stmt*
|
|
console.log("SQL TRACE #"+(++this.counter)+' via sqlite3@'+c+':',
|
|
wasm.cstrToJs(x));
|
|
}
|
|
}.bind({counter: 0}));
|
|
|
|
/**
|
|
A map of sqlite3_vfs pointers to SQL code or a callback function
|
|
to run when the DB constructor opens a database with the given
|
|
VFS. In the latter case, the call signature is
|
|
(theDbObject,sqlite3Namespace) and the callback is expected to
|
|
throw on error.
|
|
*/
|
|
const __vfsPostOpenCallback = Object.create(null);
|
|
|
|
//#if enable-see
|
|
/**
|
|
Converts ArrayBuffer or Uint8Array ba into a string of hex
|
|
digits.
|
|
*/
|
|
const byteArrayToHex = function(ba){
|
|
if( ba instanceof ArrayBuffer ){
|
|
ba = new Uint8Array(ba);
|
|
}
|
|
const li = [];
|
|
const digits = "0123456789abcdef";
|
|
for( const d of ba ){
|
|
li.push( digits[(d & 0xf0) >> 4], digits[d & 0x0f] );
|
|
}
|
|
return li.join('');
|
|
};
|
|
|
|
/**
|
|
Internal helper to apply an SEE key to a just-opened
|
|
database. Requires that db be-a DB object which has just been
|
|
opened, opt be the options object processed by its ctor, and opt
|
|
must have either the key, hexkey, or textkey properties, either
|
|
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 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 an unspecified falsy
|
|
value. Note that applying the key does not imply that the key is
|
|
correct, only that it was passed on to the db.
|
|
*/
|
|
const dbCtorApplySEEKey = function(db,opt){
|
|
if( !capi.sqlite3_key_v2 ) return;
|
|
let keytype;
|
|
let key;
|
|
const check = (opt.key ? 1 : 0) + (opt.hexkey ? 1 : 0) + (opt.textkey ? 1 : 0);
|
|
if( !check ) return;
|
|
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... */
|
|
keytype = 'key';
|
|
key = opt.key;
|
|
if('string'===typeof key){
|
|
key = new TextEncoder('utf-8').encode(key);
|
|
}
|
|
if((key instanceof ArrayBuffer) || (key instanceof Uint8Array)){
|
|
key = byteArrayToHex(key);
|
|
keytype = 'hexkey';
|
|
}else{
|
|
toss3(capi.SQLITE_MISUSE,
|
|
"Invalid value for the 'key' option. Expecting a string,",
|
|
"ArrayBuffer, or Uint8Array.");
|
|
return;
|
|
}
|
|
}else if( opt.textkey ){
|
|
/* For textkey we need it to be in string form, so convert it to
|
|
a string if it's a byte array... */
|
|
keytype = 'textkey';
|
|
key = opt.textkey;
|
|
if(key instanceof ArrayBuffer){
|
|
key = new Uint8Array(key);
|
|
}
|
|
if(key instanceof Uint8Array){
|
|
key = new TextDecoder('utf-8').decode(key);
|
|
}else if('string'!==typeof key){
|
|
toss3(capi.SQLITE_MISUSE,
|
|
"Invalid value for the 'textkey' option. Expecting a string,",
|
|
"ArrayBuffer, or Uint8Array.");
|
|
}
|
|
}else if( opt.hexkey ){
|
|
keytype = 'hexkey';
|
|
key = opt.hexkey;
|
|
if((key instanceof ArrayBuffer) || (key instanceof Uint8Array)){
|
|
key = byteArrayToHex(key);
|
|
}else if('string'!==typeof key){
|
|
toss3(capi.SQLITE_MISUSE,
|
|
"Invalid value for the 'hexkey' option. Expecting a string,",
|
|
"ArrayBuffer, or Uint8Array.");
|
|
}
|
|
/* else assume it's valid hex codes */
|
|
}else{
|
|
return;
|
|
}
|
|
let stmt;
|
|
try{
|
|
stmt = db.prepare("PRAGMA "+keytype+"="+util.sqlite3__wasm_qfmt_token(key, 1));
|
|
stmt.step();
|
|
return true;
|
|
}finally{
|
|
if(stmt) stmt.finalize();
|
|
}
|
|
};
|
|
//#endif enable-see
|
|
|
|
/**
|
|
A proxy for DB class constructors. It must be called with the
|
|
being-construct DB object as its "this". See the DB constructor
|
|
for the argument docs. This is split into a separate function
|
|
in order to enable simple creation of special-case DB constructors,
|
|
e.g. JsStorageDb and OpfsDb.
|
|
|
|
Expects to be passed a configuration object with the following
|
|
properties:
|
|
|
|
- `.filename`: the db filename. It may be a special name like ":memory:"
|
|
or "".
|
|
|
|
- `.flags`: as documented in the DB constructor.
|
|
|
|
- `.vfs`: as documented in the DB constructor.
|
|
|
|
It also accepts those as the first 3 arguments.
|
|
*/
|
|
const dbCtorHelper = function ctor(...args){
|
|
if(!ctor._name2vfs){
|
|
/**
|
|
Map special filenames which we handle here (instead of in C)
|
|
to some helpful metadata...
|
|
|
|
As of 2022-09-20, the C API supports the names :localStorage:
|
|
and :sessionStorage: for kvvfs. However, C code cannot
|
|
determine (without embedded JS code, e.g. via Emscripten's
|
|
EM_JS()) whether the kvvfs is legal in the current browser
|
|
context (namely the main UI thread). In order to help client
|
|
code fail early on, instead of it being delayed until they
|
|
try to read or write a kvvfs-backed db, we'll check for those
|
|
names here and throw if they're not legal in the current
|
|
context.
|
|
*/
|
|
ctor._name2vfs = Object.create(null);
|
|
const isWorkerThread = ('function'===typeof importScripts/*===running in worker thread*/)
|
|
? (n)=>toss3("The VFS for",n,"is only available in the main window thread.")
|
|
: false;
|
|
ctor._name2vfs[':localStorage:'] = {
|
|
vfs: 'kvvfs', filename: isWorkerThread || (()=>'local')
|
|
};
|
|
ctor._name2vfs[':sessionStorage:'] = {
|
|
vfs: 'kvvfs', filename: isWorkerThread || (()=>'session')
|
|
};
|
|
}
|
|
const opt = ctor.normalizeArgs(...args);
|
|
let fn = opt.filename, vfsName = opt.vfs, flagsStr = opt.flags;
|
|
if(('string'!==typeof fn && 'number'!==typeof fn)
|
|
|| 'string'!==typeof flagsStr
|
|
|| (vfsName && ('string'!==typeof vfsName && 'number'!==typeof vfsName))){
|
|
sqlite3.config.error("Invalid DB ctor args",opt,arguments);
|
|
toss3("Invalid arguments for DB constructor.");
|
|
}
|
|
let fnJs = ('number'===typeof fn) ? wasm.cstrToJs(fn) : fn;
|
|
const vfsCheck = ctor._name2vfs[fnJs];
|
|
if(vfsCheck){
|
|
vfsName = vfsCheck.vfs;
|
|
fn = fnJs = vfsCheck.filename(fnJs);
|
|
}
|
|
let pDb, oflags = 0;
|
|
if( flagsStr.indexOf('c')>=0 ){
|
|
oflags |= capi.SQLITE_OPEN_CREATE | capi.SQLITE_OPEN_READWRITE;
|
|
}
|
|
if( flagsStr.indexOf('w')>=0 ) oflags |= capi.SQLITE_OPEN_READWRITE;
|
|
if( 0===oflags ) oflags |= capi.SQLITE_OPEN_READONLY;
|
|
oflags |= capi.SQLITE_OPEN_EXRESCODE;
|
|
const stack = wasm.pstack.pointer;
|
|
try {
|
|
const pPtr = wasm.pstack.allocPtr() /* output (sqlite3**) arg */;
|
|
let rc = capi.sqlite3_open_v2(fn, pPtr, oflags, vfsName || 0);
|
|
pDb = wasm.peekPtr(pPtr);
|
|
checkSqlite3Rc(pDb, rc);
|
|
capi.sqlite3_extended_result_codes(pDb, 1);
|
|
if(flagsStr.indexOf('t')>=0){
|
|
capi.sqlite3_trace_v2(pDb, capi.SQLITE_TRACE_STMT,
|
|
__dbTraceToConsole, pDb);
|
|
}
|
|
}catch( e ){
|
|
if( pDb ) capi.sqlite3_close_v2(pDb);
|
|
throw e;
|
|
}finally{
|
|
wasm.pstack.restore(stack);
|
|
}
|
|
this.filename = fnJs;
|
|
__ptrMap.set(this, pDb);
|
|
__stmtMap.set(this, Object.create(null));
|
|
try{
|
|
//#if enable-see
|
|
dbCtorApplySEEKey(this,opt);
|
|
//#endif
|
|
// Check for per-VFS post-open SQL/callback...
|
|
const pVfs = capi.sqlite3_js_db_vfs(pDb)
|
|
|| toss3("Internal error: cannot get VFS for new db handle.");
|
|
const postInitSql = __vfsPostOpenCallback[pVfs];
|
|
if(postInitSql){
|
|
/**
|
|
Reminder: if this db is encrypted and the client did _not_ pass
|
|
in the key, any init code will fail, causing the ctor to throw.
|
|
We don't actually know whether the db is encrypted, so we cannot
|
|
sensibly apply any heuristics which skip the init code only for
|
|
encrypted databases for which no key has yet been supplied.
|
|
*/
|
|
if(postInitSql instanceof Function){
|
|
postInitSql(this, sqlite3);
|
|
}else{
|
|
checkSqlite3Rc(
|
|
pDb, capi.sqlite3_exec(pDb, postInitSql, 0, 0, 0)
|
|
);
|
|
}
|
|
}
|
|
}catch(e){
|
|
this.close();
|
|
throw e;
|
|
}
|
|
};
|
|
|
|
/**
|
|
Sets a callback which should be called after a db is opened with
|
|
the given sqlite3_vfs pointer. The 2nd argument must be a
|
|
function, which gets called with
|
|
(theOo1DbObject,sqlite3Namespace) at the end of the DB()
|
|
constructor. The function must throw on error, in which case the
|
|
db is closed and the exception is propagated. This function is
|
|
intended only for use by DB subclasses or sqlite3_vfs
|
|
implementations.
|
|
|
|
Prior to 2024-07-22, it was legal to pass SQL code as the second
|
|
argument, but that can interfere with a client's ability to run
|
|
pragmas which must be run before anything else, namely (pragma
|
|
locking_mode=exclusive) for use with WAL mode. That capability
|
|
had only ever been used as an internal detail of the two OPFS
|
|
VFSes, and they no longer use it that way.
|
|
*/
|
|
dbCtorHelper.setVfsPostOpenCallback = function(pVfs, callback){
|
|
if( !(callback instanceof Function)){
|
|
toss3("dbCtorHelper.setVfsPostOpenCallback() should not be used with "+
|
|
"a non-function argument.",arguments);
|
|
}
|
|
__vfsPostOpenCallback[pVfs] = callback;
|
|
};
|
|
|
|
/**
|
|
A helper for DB constructors. It accepts either a single
|
|
config-style object or up to 3 arguments (filename, dbOpenFlags,
|
|
dbVfsName). It returns a new object containing:
|
|
|
|
{ filename: ..., flags: ..., vfs: ... }
|
|
|
|
If passed an object, any additional properties it has are copied
|
|
as-is into the new object.
|
|
*/
|
|
dbCtorHelper.normalizeArgs = function(filename=':memory:',flags = 'c',vfs = null){
|
|
const arg = {};
|
|
if(1===arguments.length && arguments[0] && 'object'===typeof arguments[0]){
|
|
Object.assign(arg, arguments[0]);
|
|
if(undefined===arg.flags) arg.flags = 'c';
|
|
if(undefined===arg.vfs) arg.vfs = null;
|
|
if(undefined===arg.filename) arg.filename = ':memory:';
|
|
}else{
|
|
arg.filename = filename;
|
|
arg.flags = flags;
|
|
arg.vfs = vfs;
|
|
}
|
|
return arg;
|
|
};
|
|
/**
|
|
The DB class provides a high-level OO wrapper around an sqlite3
|
|
db handle.
|
|
|
|
The given db filename must be resolvable using whatever
|
|
filesystem layer (virtual or otherwise) is set up for the default
|
|
sqlite3 VFS.
|
|
|
|
Note that the special sqlite3 db names ":memory:" and ""
|
|
(temporary db) have their normal special meanings here and need
|
|
not resolve to real filenames, but "" uses an on-storage
|
|
temporary database and requires that the VFS support that.
|
|
|
|
The second argument specifies the open/create mode for the
|
|
database. It must be string containing a sequence of letters (in
|
|
any order, but case sensitive) specifying the mode:
|
|
|
|
- "c": create if it does not exist, else fail if it does not
|
|
exist. Implies the "w" flag.
|
|
|
|
- "w": write. Implies "r": a db cannot be write-only.
|
|
|
|
- "r": read-only if neither "w" nor "c" are provided, else it
|
|
is ignored.
|
|
|
|
- "t": enable tracing of SQL executed on this database handle,
|
|
sending it to `console.log()`. To disable it later, call
|
|
`sqlite3.capi.sqlite3_trace_v2(thisDb.pointer, 0, 0, 0)`.
|
|
|
|
If "w" is not provided, the db is implicitly read-only, noting
|
|
that "rc" is meaningless
|
|
|
|
Any other letters are currently ignored. The default is
|
|
"c". These modes are ignored for the special ":memory:" and ""
|
|
names and _may_ be ignored altogether for certain VFSes.
|
|
|
|
The final argument is analogous to the final argument of
|
|
sqlite3_open_v2(): the name of an sqlite3 VFS. Pass a falsy value,
|
|
or none at all, to use the default. If passed a value, it must
|
|
be the string name of a VFS.
|
|
|
|
The constructor optionally (and preferably) takes its arguments
|
|
in the form of a single configuration object with the following
|
|
properties:
|
|
|
|
- `filename`: database file name
|
|
- `flags`: open-mode flags
|
|
- `vfs`: the VFS fname
|
|
|
|
//#if enable-see
|
|
|
|
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.
|
|
|
|
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
|
|
C-strings allocated via WASM. `flags` is required to be a JS
|
|
string (because it's specific to this API, which is specific
|
|
to JS).
|
|
|
|
For purposes of passing a DB instance to C-style sqlite3
|
|
functions, the DB object's read-only `pointer` property holds its
|
|
`sqlite3*` pointer value. That property can also be used to check
|
|
whether this DB instance is still open: it will evaluate to
|
|
`undefined` after the DB object's close() method is called.
|
|
|
|
In the main window thread, the filenames `":localStorage:"` and
|
|
`":sessionStorage:"` are special: they cause the db to use either
|
|
localStorage or sessionStorage for storing the database using
|
|
the kvvfs. If one of these names are used, they trump
|
|
any vfs name set in the arguments.
|
|
*/
|
|
const DB = function(...args){
|
|
dbCtorHelper.apply(this, args);
|
|
};
|
|
DB.dbCtorHelper = dbCtorHelper;
|
|
|
|
/**
|
|
Internal-use enum for mapping JS types to DB-bindable types.
|
|
These do not (and need not) line up with the SQLITE_type
|
|
values. All values in this enum must be truthy and distinct
|
|
but they need not be numbers.
|
|
*/
|
|
const BindTypes = {
|
|
null: 1,
|
|
number: 2,
|
|
string: 3,
|
|
boolean: 4,
|
|
blob: 5
|
|
};
|
|
BindTypes['undefined'] == BindTypes.null;
|
|
if(wasm.bigIntEnabled){
|
|
BindTypes.bigint = BindTypes.number;
|
|
}
|
|
|
|
/**
|
|
This class wraps sqlite3_stmt. Calling this constructor
|
|
directly will trigger an exception. Use DB.prepare() to create
|
|
new instances.
|
|
|
|
For purposes of passing a Stmt instance to C-style sqlite3
|
|
functions, its read-only `pointer` property holds its `sqlite3_stmt*`
|
|
pointer value.
|
|
|
|
Other non-function properties include:
|
|
|
|
- `db`: the DB object which created the statement.
|
|
|
|
- `columnCount`: the number of result columns in the query, or 0
|
|
for queries which cannot return results. This property is a proxy
|
|
for sqlite3_column_count() and its use in loops should be avoided
|
|
because of the call overhead associated with that. The
|
|
`columnCount` is not cached when the Stmt is created because a
|
|
schema change made via a separate db connection between this
|
|
statement's preparation and when it is stepped may invalidate it.
|
|
|
|
- `parameterCount`: the number of bindable parameters in the query.
|
|
|
|
As a general rule, most methods of this class will throw if
|
|
called on an instance which has been finalized. For brevity's
|
|
sake, the method docs do not all repeat this warning.
|
|
*/
|
|
const Stmt = function(){
|
|
if(BindTypes!==arguments[2]){
|
|
toss3(capi.SQLITE_MISUSE, "Do not call the Stmt constructor directly. Use DB.prepare().");
|
|
}
|
|
this.db = arguments[0];
|
|
__ptrMap.set(this, arguments[1]);
|
|
this.parameterCount = capi.sqlite3_bind_parameter_count(this.pointer);
|
|
};
|
|
|
|
/** Throws if the given DB has been closed, else it is returned. */
|
|
const affirmDbOpen = function(db){
|
|
if(!db.pointer) toss3("DB has been closed.");
|
|
return db;
|
|
};
|
|
|
|
/** Throws if ndx is not an integer or if it is out of range
|
|
for stmt.columnCount, else returns stmt.
|
|
|
|
Reminder: this will also fail after the statement is finalized
|
|
but the resulting error will be about an out-of-bounds column
|
|
index rather than a statement-is-finalized error.
|
|
*/
|
|
const affirmColIndex = function(stmt,ndx){
|
|
if((ndx !== (ndx|0)) || ndx<0 || ndx>=stmt.columnCount){
|
|
toss3("Column index",ndx,"is out of range.");
|
|
}
|
|
return stmt;
|
|
};
|
|
|
|
/**
|
|
Expects to be passed the `arguments` object from DB.exec(). Does
|
|
the argument processing/validation, throws on error, and returns
|
|
a new object on success:
|
|
|
|
{ sql: the SQL, opt: optionsObj, cbArg: function}
|
|
|
|
The opt object is a normalized copy of any passed to this
|
|
function. The sql will be converted to a string if it is provided
|
|
in one of the supported non-string formats.
|
|
|
|
cbArg is only set if the opt.callback or opt.resultRows are set,
|
|
in which case it's a function which expects to be passed the
|
|
current Stmt and returns the callback argument of the type
|
|
indicated by the input arguments.
|
|
*/
|
|
const parseExecArgs = function(db, args){
|
|
const out = Object.create(null);
|
|
out.opt = Object.create(null);
|
|
switch(args.length){
|
|
case 1:
|
|
if('string'===typeof args[0] || util.isSQLableTypedArray(args[0])){
|
|
out.sql = args[0];
|
|
}else if(Array.isArray(args[0])){
|
|
out.sql = args[0];
|
|
}else if(args[0] && 'object'===typeof args[0]){
|
|
out.opt = args[0];
|
|
out.sql = out.opt.sql;
|
|
}
|
|
break;
|
|
case 2:
|
|
out.sql = args[0];
|
|
out.opt = args[1];
|
|
break;
|
|
default: toss3("Invalid argument count for exec().");
|
|
};
|
|
out.sql = util.flexibleString(out.sql);
|
|
if('string'!==typeof out.sql){
|
|
toss3("Missing SQL argument or unsupported SQL value type.");
|
|
}
|
|
const opt = out.opt;
|
|
switch(opt.returnValue){
|
|
case 'resultRows':
|
|
if(!opt.resultRows) opt.resultRows = [];
|
|
out.returnVal = ()=>opt.resultRows;
|
|
break;
|
|
case 'saveSql':
|
|
if(!opt.saveSql) opt.saveSql = [];
|
|
out.returnVal = ()=>opt.saveSql;
|
|
break;
|
|
case undefined:
|
|
case 'this':
|
|
out.returnVal = ()=>db;
|
|
break;
|
|
default:
|
|
toss3("Invalid returnValue value:",opt.returnValue);
|
|
}
|
|
if(!opt.callback && !opt.returnValue && undefined!==opt.rowMode){
|
|
if(!opt.resultRows) opt.resultRows = [];
|
|
out.returnVal = ()=>opt.resultRows;
|
|
}
|
|
if(opt.callback || opt.resultRows){
|
|
switch((undefined===opt.rowMode) ? 'array' : opt.rowMode) {
|
|
case 'object':
|
|
out.cbArg = (stmt,cache)=>{
|
|
if( !cache.columnNames ) cache.columnNames = stmt.getColumnNames([]);
|
|
/* https://sqlite.org/forum/forumpost/3632183d2470617d:
|
|
conversion of rows to objects (key/val pairs) is
|
|
somewhat expensive for large data sets because of the
|
|
native-to-JS conversion of the column names. If we
|
|
instead cache the names and build objects from that
|
|
list of strings, it can run twice as fast. The
|
|
difference is not noticeable for small data sets but
|
|
becomes human-perceivable when enough rows are
|
|
involved. */
|
|
const row = stmt.get([]);
|
|
const rv = Object.create(null);
|
|
for( const i in cache.columnNames ) rv[cache.columnNames[i]] = row[i];
|
|
return rv;
|
|
};
|
|
break;
|
|
case 'array': out.cbArg = (stmt)=>stmt.get([]); break;
|
|
case 'stmt':
|
|
if(Array.isArray(opt.resultRows)){
|
|
toss3("exec(): invalid rowMode for a resultRows array: must",
|
|
"be one of 'array', 'object',",
|
|
"a result column number, or column name reference.");
|
|
}
|
|
out.cbArg = (stmt)=>stmt;
|
|
break;
|
|
default:
|
|
if(util.isInt32(opt.rowMode)){
|
|
out.cbArg = (stmt)=>stmt.get(opt.rowMode);
|
|
break;
|
|
}else if('string'===typeof opt.rowMode
|
|
&& opt.rowMode.length>1
|
|
&& '$'===opt.rowMode[0]){
|
|
/* "$X": fetch column named "X" (case-sensitive!). Prior
|
|
to 2022-12-14 ":X" and "@X" were also permitted, but
|
|
having so many options is unnecessary and likely to
|
|
cause confusion. */
|
|
const $colName = opt.rowMode.substr(1);
|
|
out.cbArg = (stmt)=>{
|
|
const rc = stmt.get(Object.create(null))[$colName];
|
|
return (undefined===rc)
|
|
? toss3(capi.SQLITE_NOTFOUND,
|
|
"exec(): unknown result column:",$colName)
|
|
: rc;
|
|
};
|
|
break;
|
|
}
|
|
toss3("Invalid rowMode:",opt.rowMode);
|
|
}
|
|
}
|
|
return out;
|
|
};
|
|
|
|
/**
|
|
Internal impl of the DB.selectValue(), selectArray(), and
|
|
selectObject() methods.
|
|
*/
|
|
const __selectFirstRow = (db, sql, bind, ...getArgs)=>{
|
|
const stmt = db.prepare(sql);
|
|
try {
|
|
const rc = stmt.bind(bind).step() ? stmt.get(...getArgs) : undefined;
|
|
stmt.reset(/*for INSERT...RETURNING locking case*/);
|
|
return rc;
|
|
}finally{
|
|
stmt.finalize();
|
|
}
|
|
};
|
|
|
|
/**
|
|
Internal impl of the DB.selectArrays() and selectObjects()
|
|
methods.
|
|
*/
|
|
const __selectAll =
|
|
(db, sql, bind, rowMode)=>db.exec({
|
|
sql, bind, rowMode, returnValue: 'resultRows'
|
|
});
|
|
|
|
/**
|
|
Expects to be given a DB instance or an `sqlite3*` pointer (may
|
|
be null) and an sqlite3 API result code. If the result code is
|
|
not falsy, this function throws an SQLite3Error with an error
|
|
message from sqlite3_errmsg(), using db (or, if db is-a DB,
|
|
db.pointer) as the db handle, or sqlite3_errstr() if db is
|
|
falsy. Note that if it's passed a non-error code like SQLITE_ROW
|
|
or SQLITE_DONE, it will still throw but the error string might be
|
|
"Not an error." The various non-0 non-error codes need to be
|
|
checked for in client code where they are expected.
|
|
|
|
The thrown exception's `resultCode` property will be the value of
|
|
the second argument to this function.
|
|
|
|
If it does not throw, it returns its first argument.
|
|
*/
|
|
DB.checkRc = (db,resultCode)=>checkSqlite3Rc(db,resultCode);
|
|
|
|
DB.prototype = {
|
|
/** Returns true if this db handle is open, else false. */
|
|
isOpen: function(){
|
|
return !!this.pointer;
|
|
},
|
|
/** Throws if this given DB has been closed, else returns `this`. */
|
|
affirmOpen: function(){
|
|
return affirmDbOpen(this);
|
|
},
|
|
/**
|
|
Finalizes all open statements and closes this database
|
|
connection. This is a no-op if the db has already been
|
|
closed. After calling close(), `this.pointer` will resolve to
|
|
`undefined`, so that can be used to check whether the db
|
|
instance is still opened.
|
|
|
|
If this.onclose.before is a function then it is called before
|
|
any close-related cleanup.
|
|
|
|
If this.onclose.after is a function then it is called after the
|
|
db is closed but before auxiliary state like this.filename is
|
|
cleared.
|
|
|
|
Both onclose handlers are passed this object, with the onclose
|
|
object as their "this," noting that the db will have been
|
|
closed when onclose.after is called. If this db is not opened
|
|
when close() is called, neither of the handlers are called. Any
|
|
exceptions the handlers throw are ignored because "destructors
|
|
must not throw."
|
|
|
|
Note that garbage collection of a db handle, if it happens at
|
|
all, will never trigger close(), so onclose handlers are not a
|
|
reliable way to implement close-time cleanup or maintenance of
|
|
a db.
|
|
*/
|
|
close: function(){
|
|
if(this.pointer){
|
|
if(this.onclose && (this.onclose.before instanceof Function)){
|
|
try{this.onclose.before(this)}
|
|
catch(e){/*ignore*/}
|
|
}
|
|
const pDb = this.pointer;
|
|
Object.keys(__stmtMap.get(this)).forEach((k,s)=>{
|
|
if(s && s.pointer){
|
|
try{s.finalize()}
|
|
catch(e){/*ignore*/}
|
|
}
|
|
});
|
|
__ptrMap.delete(this);
|
|
__stmtMap.delete(this);
|
|
capi.sqlite3_close_v2(pDb);
|
|
if(this.onclose && (this.onclose.after instanceof Function)){
|
|
try{this.onclose.after(this)}
|
|
catch(e){/*ignore*/}
|
|
}
|
|
delete this.filename;
|
|
}
|
|
},
|
|
/**
|
|
Returns the number of changes, as per sqlite3_changes()
|
|
(if the first argument is false) or sqlite3_total_changes()
|
|
(if it's true). If the 2nd argument is true, it uses
|
|
sqlite3_changes64() or sqlite3_total_changes64(), which
|
|
will trigger an exception if this build does not have
|
|
BigInt support enabled.
|
|
*/
|
|
changes: function(total=false,sixtyFour=false){
|
|
const p = affirmDbOpen(this).pointer;
|
|
if(total){
|
|
return sixtyFour
|
|
? capi.sqlite3_total_changes64(p)
|
|
: capi.sqlite3_total_changes(p);
|
|
}else{
|
|
return sixtyFour
|
|
? capi.sqlite3_changes64(p)
|
|
: capi.sqlite3_changes(p);
|
|
}
|
|
},
|
|
/**
|
|
Similar to the this.filename but returns the
|
|
sqlite3_db_filename() value for the given database name,
|
|
defaulting to "main". The argument may be either a JS string
|
|
or a pointer to a WASM-allocated C-string.
|
|
*/
|
|
dbFilename: function(dbName='main'){
|
|
return capi.sqlite3_db_filename(affirmDbOpen(this).pointer, dbName);
|
|
},
|
|
/**
|
|
Returns the name of the given 0-based db number, as documented
|
|
for sqlite3_db_name().
|
|
*/
|
|
dbName: function(dbNumber=0){
|
|
return capi.sqlite3_db_name(affirmDbOpen(this).pointer, dbNumber);
|
|
},
|
|
/**
|
|
Returns the name of the sqlite3_vfs used by the given database
|
|
of this connection (defaulting to 'main'). The argument may be
|
|
either a JS string or a WASM C-string. Returns undefined if the
|
|
given db name is invalid. Throws if this object has been
|
|
close()d.
|
|
*/
|
|
dbVfsName: function(dbName=0){
|
|
let rc;
|
|
const pVfs = capi.sqlite3_js_db_vfs(
|
|
affirmDbOpen(this).pointer, dbName
|
|
);
|
|
if(pVfs){
|
|
const v = new capi.sqlite3_vfs(pVfs);
|
|
try{ rc = wasm.cstrToJs(v.$zName) }
|
|
finally { v.dispose() }
|
|
}
|
|
return rc;
|
|
},
|
|
/**
|
|
Compiles the given SQL and returns a prepared Stmt. This is
|
|
the only way to create new Stmt objects. Throws on error.
|
|
|
|
The given SQL must be a string, a Uint8Array holding SQL, a
|
|
WASM pointer to memory holding the NUL-terminated SQL string,
|
|
or an array of strings. In the latter case, the array is
|
|
concatenated together, with no separators, to form the SQL
|
|
string (arrays are often a convenient way to formulate long
|
|
statements). If the SQL contains no statements, an
|
|
SQLite3Error is thrown.
|
|
|
|
Design note: the C API permits empty SQL, reporting it as a 0
|
|
result code and a NULL stmt pointer. Supporting that case here
|
|
would cause extra work for all clients: any use of the Stmt API
|
|
on such a statement will necessarily throw, so clients would be
|
|
required to check `stmt.pointer` after calling `prepare()` in
|
|
order to determine whether the Stmt instance is empty or not.
|
|
Long-time practice (with other sqlite3 script bindings)
|
|
suggests that the empty-prepare case is sufficiently rare that
|
|
supporting it here would simply hurt overall usability.
|
|
*/
|
|
prepare: function(sql){
|
|
affirmDbOpen(this);
|
|
const stack = wasm.pstack.pointer;
|
|
let ppStmt, pStmt;
|
|
try{
|
|
ppStmt = wasm.pstack.alloc(8)/* output (sqlite3_stmt**) arg */;
|
|
DB.checkRc(this, capi.sqlite3_prepare_v2(this.pointer, sql, -1, ppStmt, null));
|
|
pStmt = wasm.peekPtr(ppStmt);
|
|
}
|
|
finally {
|
|
wasm.pstack.restore(stack);
|
|
}
|
|
if(!pStmt) toss3("Cannot prepare empty SQL.");
|
|
const stmt = new Stmt(this, pStmt, BindTypes);
|
|
__stmtMap.get(this)[pStmt] = stmt;
|
|
return stmt;
|
|
},
|
|
/**
|
|
Executes one or more SQL statements in the form of a single
|
|
string. Its arguments must be either (sql,optionsObject) or
|
|
(optionsObject). In the latter case, optionsObject.sql must
|
|
contain the SQL to execute. By default it returns this object
|
|
but that can be changed via the `returnValue` option as
|
|
described below. Throws on error.
|
|
|
|
If no SQL is provided, or a non-string is provided, an
|
|
exception is triggered. Empty SQL, on the other hand, is
|
|
simply a no-op.
|
|
|
|
The optional options object may contain any of the following
|
|
properties:
|
|
|
|
- `sql` = the SQL to run (unless it's provided as the first
|
|
argument). This must be of type string, Uint8Array, or an array
|
|
of strings. In the latter case they're concatenated together
|
|
as-is, _with no separator_ between elements, before evaluation.
|
|
The array form is often simpler for long hand-written queries.
|
|
|
|
- `bind` = a single value valid as an argument for
|
|
Stmt.bind(). This is _only_ applied to the _first_ non-empty
|
|
statement in the SQL which has any bindable parameters. (Empty
|
|
statements are skipped entirely.)
|
|
|
|
- `saveSql` = an optional array. If set, the SQL of each
|
|
executed statement is appended to this array before the
|
|
statement is executed (but after it is prepared - we don't have
|
|
the string until after that). Empty SQL statements are elided
|
|
but can have odd effects in the output. e.g. SQL of: `"select
|
|
1; -- empty\n; select 2"` will result in an array containing
|
|
`["select 1;", "--empty \n; select 2"]`. That's simply how
|
|
sqlite3 records the SQL for the 2nd statement.
|
|
|
|
==================================================================
|
|
The following options apply _only_ to the _first_ statement
|
|
which has a non-zero result column count, regardless of whether
|
|
the statement actually produces any result rows.
|
|
==================================================================
|
|
|
|
- `columnNames`: if this is an array, the column names of the
|
|
result set are stored in this array before the callback (if
|
|
any) is triggered (regardless of whether the query produces any
|
|
result rows). If no statement has result columns, this value is
|
|
unchanged. Achtung: an SQL result may have multiple columns
|
|
with identical names.
|
|
|
|
- `callback` = a function which gets called for each row of the
|
|
result set, but only if that statement has any result rows. The
|
|
callback's "this" is the options object, noting that this
|
|
function synthesizes one if the caller does not pass one to
|
|
exec(). The second argument passed to the callback is always
|
|
the current Stmt object, as it's needed if the caller wants to
|
|
fetch the column names or some such (noting that they could
|
|
also be fetched via `this.columnNames`, if the client provides
|
|
the `columnNames` option). If the callback returns a literal
|
|
`false` (as opposed to any other falsy value, e.g. an implicit
|
|
`undefined` return), any ongoing statement-`step()` iteration
|
|
stops without an error. The return value of the callback is
|
|
otherwise ignored.
|
|
|
|
ACHTUNG: The callback MUST NOT modify the Stmt object. Calling
|
|
any of the Stmt.get() variants, Stmt.getColumnName(), or
|
|
similar, is legal, but calling step() or finalize() is
|
|
not. Member methods which are illegal in this context will
|
|
trigger an exception, but clients must also refrain from using
|
|
any lower-level (C-style) APIs which might modify the
|
|
statement.
|
|
|
|
The first argument passed to the callback defaults to an array of
|
|
values from the current result row but may be changed with ...
|
|
|
|
- `rowMode` = specifies the type of he callback's first argument.
|
|
It may be any of...
|
|
|
|
A) A string describing what type of argument should be passed
|
|
as the first argument to the callback:
|
|
|
|
A.1) `'array'` (the default) causes the results of
|
|
`stmt.get([])` to be passed to the `callback` and/or appended
|
|
to `resultRows`.
|
|
|
|
A.2) `'object'` causes the results of
|
|
`stmt.get(Object.create(null))` to be passed to the
|
|
`callback` and/or appended to `resultRows`. Achtung: an SQL
|
|
result may have multiple columns with identical names. In
|
|
that case, the right-most column will be the one set in this
|
|
object!
|
|
|
|
A.3) `'stmt'` causes the current Stmt to be passed to the
|
|
callback, but this mode will trigger an exception if
|
|
`resultRows` is an array because appending the transient
|
|
statement to the array would be downright unhelpful.
|
|
|
|
B) An integer, indicating a zero-based column in the result
|
|
row. Only that one single value will be passed on.
|
|
|
|
C) A string with a minimum length of 2 and leading character of
|
|
'$' will fetch the row as an object, extract that one field,
|
|
and pass that field's value to the callback. Note that these
|
|
keys are case-sensitive so must match the case used in the
|
|
SQL. e.g. `"select a A from t"` with a `rowMode` of `'$A'`
|
|
would work but `'$a'` would not. A reference to a column not in
|
|
the result set will trigger an exception on the first row (as
|
|
the check is not performed until rows are fetched). Note also
|
|
that `$` is a legal identifier character in JS so need not be
|
|
quoted.
|
|
|
|
Any other `rowMode` value triggers an exception.
|
|
|
|
- `resultRows`: if this is an array, it functions similarly to
|
|
the `callback` option: each row of the result set (if any),
|
|
with the exception that the `rowMode` 'stmt' is not legal. It
|
|
is legal to use both `resultRows` and `callback`, but
|
|
`resultRows` is likely much simpler to use for small data sets
|
|
and can be used over a WebWorker-style message interface.
|
|
exec() throws if `resultRows` is set and `rowMode` is 'stmt'.
|
|
|
|
- `returnValue`: is a string specifying what this function
|
|
should return:
|
|
|
|
A) The default value is (usually) `"this"`, meaning that the
|
|
DB object itself should be returned. The exception is if
|
|
the caller passes neither of `callback` nor `returnValue`
|
|
but does pass an explicit `rowMode` then the default
|
|
`returnValue` is `"resultRows"`, described below.
|
|
|
|
B) `"resultRows"` means to return the value of the
|
|
`resultRows` option. If `resultRows` is not set, this
|
|
function behaves as if it were set to an empty array.
|
|
|
|
C) `"saveSql"` means to return the value of the
|
|
`saveSql` option. If `saveSql` is not set, this
|
|
function behaves as if it were set to an empty array.
|
|
|
|
Potential TODOs:
|
|
|
|
- `bind`: permit an array of arrays/objects to bind. The first
|
|
sub-array would act on the first statement which has bindable
|
|
parameters (as it does now). The 2nd would act on the next such
|
|
statement, etc.
|
|
|
|
- `callback` and `resultRows`: permit an array entries with
|
|
semantics similar to those described for `bind` above.
|
|
|
|
*/
|
|
exec: function(/*(sql [,obj]) || (obj)*/){
|
|
affirmDbOpen(this);
|
|
const arg = parseExecArgs(this, arguments);
|
|
if(!arg.sql){
|
|
return toss3("exec() requires an SQL string.");
|
|
}
|
|
const opt = arg.opt;
|
|
const callback = opt.callback;
|
|
const resultRows =
|
|
Array.isArray(opt.resultRows) ? opt.resultRows : undefined;
|
|
let stmt;
|
|
let bind = opt.bind;
|
|
let evalFirstResult = !!(
|
|
arg.cbArg || opt.columnNames || resultRows
|
|
) /* true to step through the first result-returning statement */;
|
|
const stack = wasm.scopedAllocPush();
|
|
const saveSql = Array.isArray(opt.saveSql) ? opt.saveSql : undefined;
|
|
try{
|
|
const isTA = util.isSQLableTypedArray(arg.sql)
|
|
/* Optimization: if the SQL is a TypedArray we can save some string
|
|
conversion costs. */;
|
|
/* Allocate the two output pointers (ppStmt, pzTail) and heap
|
|
space for the SQL (pSql). When prepare_v2() returns, pzTail
|
|
will point to somewhere in pSql. */
|
|
let sqlByteLen = isTA ? arg.sql.byteLength : wasm.jstrlen(arg.sql);
|
|
const ppStmt = wasm.scopedAlloc(
|
|
/* output (sqlite3_stmt**) arg and pzTail */
|
|
(2 * wasm.ptrSizeof) + (sqlByteLen + 1/* SQL + NUL */)
|
|
);
|
|
const pzTail = ppStmt + wasm.ptrSizeof /* final arg to sqlite3_prepare_v2() */;
|
|
let pSql = pzTail + wasm.ptrSizeof;
|
|
const pSqlEnd = pSql + sqlByteLen;
|
|
if(isTA) wasm.heap8().set(arg.sql, pSql);
|
|
else wasm.jstrcpy(arg.sql, wasm.heap8(), pSql, sqlByteLen, false);
|
|
wasm.poke(pSql + sqlByteLen, 0/*NUL terminator*/);
|
|
while(pSql && wasm.peek(pSql, 'i8')
|
|
/* Maintenance reminder:^^^ _must_ be 'i8' or else we
|
|
will very likely cause an endless loop. What that's
|
|
doing is checking for a terminating NUL byte. If we
|
|
use i32 or similar then we read 4 bytes, read stuff
|
|
around the NUL terminator, and get stuck in and
|
|
endless loop at the end of the SQL, endlessly
|
|
re-preparing an empty statement. */ ){
|
|
wasm.pokePtr([ppStmt, pzTail], 0);
|
|
DB.checkRc(this, capi.sqlite3_prepare_v3(
|
|
this.pointer, pSql, sqlByteLen, 0, ppStmt, pzTail
|
|
));
|
|
const pStmt = wasm.peekPtr(ppStmt);
|
|
pSql = wasm.peekPtr(pzTail);
|
|
sqlByteLen = pSqlEnd - pSql;
|
|
if(!pStmt) continue;
|
|
if(saveSql) saveSql.push(capi.sqlite3_sql(pStmt).trim());
|
|
stmt = new Stmt(this, pStmt, BindTypes);
|
|
if(bind && stmt.parameterCount){
|
|
stmt.bind(bind);
|
|
bind = null;
|
|
}
|
|
if(evalFirstResult && stmt.columnCount){
|
|
/* Only forward SELECT-style results for the FIRST query
|
|
in the SQL which potentially has them. */
|
|
let gotColNames = Array.isArray(
|
|
opt.columnNames
|
|
/* As reported in
|
|
https://sqlite.org/forum/forumpost/7774b773937cbe0a
|
|
we need to delay fetching of the column names until
|
|
after the first step() (if we step() at all) because
|
|
a schema change between the prepare() and step(), via
|
|
another connection, may invalidate the column count
|
|
and names. */) ? 0 : 1;
|
|
evalFirstResult = false;
|
|
if(arg.cbArg || resultRows){
|
|
const cbArgCache = Object.create(null)
|
|
/* 2nd arg for arg.cbArg, used by (at least) row-to-object
|
|
converter */;
|
|
for(; stmt.step(); stmt._lockedByExec = false){
|
|
if(0===gotColNames++){
|
|
stmt.getColumnNames(cbArgCache.columnNames = (opt.columnNames || []));
|
|
}
|
|
stmt._lockedByExec = true;
|
|
const row = arg.cbArg(stmt,cbArgCache);
|
|
if(resultRows) resultRows.push(row);
|
|
if(callback && false === callback.call(opt, row, stmt)){
|
|
break;
|
|
}
|
|
}
|
|
stmt._lockedByExec = false;
|
|
}
|
|
if(0===gotColNames){
|
|
/* opt.columnNames was provided but we visited no result rows */
|
|
stmt.getColumnNames(opt.columnNames);
|
|
}
|
|
}else{
|
|
stmt.step();
|
|
}
|
|
stmt.reset(
|
|
/* In order to trigger an exception in the
|
|
INSERT...RETURNING locking scenario:
|
|
https://sqlite.org/forum/forumpost/36f7a2e7494897df
|
|
*/).finalize();
|
|
stmt = null;
|
|
}/*prepare() loop*/
|
|
}/*catch(e){
|
|
sqlite3.config.warn("DB.exec() is propagating exception",opt,e);
|
|
throw e;
|
|
}*/finally{
|
|
wasm.scopedAllocPop(stack);
|
|
if(stmt){
|
|
delete stmt._lockedByExec;
|
|
stmt.finalize();
|
|
}
|
|
}
|
|
return arg.returnVal();
|
|
}/*exec()*/,
|
|
|
|
/**
|
|
Creates a new UDF (User-Defined Function) which is accessible
|
|
via SQL code. This function may be called in any of the
|
|
following forms:
|
|
|
|
- (name, function)
|
|
- (name, function, optionsObject)
|
|
- (name, optionsObject)
|
|
- (optionsObject)
|
|
|
|
In the final two cases, the function must be defined as the
|
|
`callback` property of the options object (optionally called
|
|
`xFunc` to align with the C API documentation). In the final
|
|
case, the function's name must be the 'name' property.
|
|
|
|
The first two call forms can only be used for creating scalar
|
|
functions. Creating an aggregate or window function requires
|
|
the options-object form (see below for details).
|
|
|
|
UDFs can be removed as documented for
|
|
sqlite3_create_function_v2() and
|
|
sqlite3_create_window_function(), but doing so will "leak" the
|
|
JS-created WASM binding of those functions (meaning that their
|
|
entries in the WASM indirect function table still
|
|
exist). Eliminating that potential leak is a pending TODO.
|
|
|
|
On success, returns this object. Throws on error.
|
|
|
|
When called from SQL arguments to the UDF, and its result,
|
|
will be converted between JS and SQL with as much fidelity as
|
|
is feasible, triggering an exception if a type conversion
|
|
cannot be determined. The docs for sqlite3_create_function_v2()
|
|
describe the conversions in more detail.
|
|
|
|
The values set in the options object differ for scalar and
|
|
aggregate functions:
|
|
|
|
- Scalar: set the `xFunc` function-type property to the UDF
|
|
function.
|
|
|
|
- Aggregate: set the `xStep` and `xFinal` function-type
|
|
properties to the "step" and "final" callbacks for the
|
|
aggregate. Do not set the `xFunc` property.
|
|
|
|
- Window: set the `xStep`, `xFinal`, `xValue`, and `xInverse`
|
|
function-type properties. Do not set the `xFunc` property.
|
|
|
|
The options object may optionally have an `xDestroy`
|
|
function-type property, as per sqlite3_create_function_v2().
|
|
Its argument will be the WASM-pointer-type value of the `pApp`
|
|
property, and this function will throw if `pApp` is defined but
|
|
is not null, undefined, or a numeric (WASM pointer)
|
|
value. i.e. `pApp`, if set, must be value suitable for use as a
|
|
WASM pointer argument, noting that `null` or `undefined` will
|
|
translate to 0 for that purpose.
|
|
|
|
The options object may contain flags to modify how
|
|
the function is defined:
|
|
|
|
- `arity`: the number of arguments which SQL calls to this
|
|
function expect or require. The default value is `xFunc.length`
|
|
or `xStep.length` (i.e. the number of declared parameters it
|
|
has) **MINUS 1** (see below for why). As a special case, if the
|
|
`length` is 0, its arity is also 0 instead of -1. A negative
|
|
arity value means that the function is variadic and may accept
|
|
any number of arguments, up to sqlite3's compile-time
|
|
limits. sqlite3 will enforce the argument count if is zero or
|
|
greater. The callback always receives a pointer to an
|
|
`sqlite3_context` object as its first argument. Any arguments
|
|
after that are from SQL code. The leading context argument does
|
|
_not_ count towards the function's arity. See the docs for
|
|
sqlite3.capi.sqlite3_create_function_v2() for why that argument
|
|
is needed in the interface.
|
|
|
|
The following options-object properties correspond to flags
|
|
documented at:
|
|
|
|
https://sqlite.org/c3ref/create_function.html
|
|
|
|
- `deterministic` = sqlite3.capi.SQLITE_DETERMINISTIC
|
|
- `directOnly` = sqlite3.capi.SQLITE_DIRECTONLY
|
|
- `innocuous` = sqlite3.capi.SQLITE_INNOCUOUS
|
|
|
|
Sidebar: the ability to add new WASM-accessible functions to
|
|
the runtime requires that the WASM build is compiled with the
|
|
equivalent functionality as that provided by Emscripten's
|
|
`-sALLOW_TABLE_GROWTH` flag.
|
|
*/
|
|
createFunction: function f(name, xFunc, opt){
|
|
const isFunc = (f)=>(f instanceof Function);
|
|
switch(arguments.length){
|
|
case 1: /* (optionsObject) */
|
|
opt = name;
|
|
name = opt.name;
|
|
xFunc = opt.xFunc || 0;
|
|
break;
|
|
case 2: /* (name, callback|optionsObject) */
|
|
if(!isFunc(xFunc)){
|
|
opt = xFunc;
|
|
xFunc = opt.xFunc || 0;
|
|
}
|
|
break;
|
|
case 3: /* name, xFunc, opt */
|
|
break;
|
|
default: break;
|
|
}
|
|
if(!opt) opt = {};
|
|
if('string' !== typeof name){
|
|
toss3("Invalid arguments: missing function name.");
|
|
}
|
|
let xStep = opt.xStep || 0;
|
|
let xFinal = opt.xFinal || 0;
|
|
const xValue = opt.xValue || 0;
|
|
const xInverse = opt.xInverse || 0;
|
|
let isWindow = undefined;
|
|
if(isFunc(xFunc)){
|
|
isWindow = false;
|
|
if(isFunc(xStep) || isFunc(xFinal)){
|
|
toss3("Ambiguous arguments: scalar or aggregate?");
|
|
}
|
|
xStep = xFinal = null;
|
|
}else if(isFunc(xStep)){
|
|
if(!isFunc(xFinal)){
|
|
toss3("Missing xFinal() callback for aggregate or window UDF.");
|
|
}
|
|
xFunc = null;
|
|
}else if(isFunc(xFinal)){
|
|
toss3("Missing xStep() callback for aggregate or window UDF.");
|
|
}else{
|
|
toss3("Missing function-type properties.");
|
|
}
|
|
if(false === isWindow){
|
|
if(isFunc(xValue) || isFunc(xInverse)){
|
|
toss3("xValue and xInverse are not permitted for non-window UDFs.");
|
|
}
|
|
}else if(isFunc(xValue)){
|
|
if(!isFunc(xInverse)){
|
|
toss3("xInverse must be provided if xValue is.");
|
|
}
|
|
isWindow = true;
|
|
}else if(isFunc(xInverse)){
|
|
toss3("xValue must be provided if xInverse is.");
|
|
}
|
|
const pApp = opt.pApp;
|
|
if(undefined!==pApp &&
|
|
null!==pApp &&
|
|
(('number'!==typeof pApp) || !util.isInt32(pApp))){
|
|
toss3("Invalid value for pApp property. Must be a legal WASM pointer value.");
|
|
}
|
|
const xDestroy = opt.xDestroy || 0;
|
|
if(xDestroy && !isFunc(xDestroy)){
|
|
toss3("xDestroy property must be a function.");
|
|
}
|
|
let fFlags = 0 /*flags for sqlite3_create_function_v2()*/;
|
|
if(getOwnOption(opt, 'deterministic')) fFlags |= capi.SQLITE_DETERMINISTIC;
|
|
if(getOwnOption(opt, 'directOnly')) fFlags |= capi.SQLITE_DIRECTONLY;
|
|
if(getOwnOption(opt, 'innocuous')) fFlags |= capi.SQLITE_INNOCUOUS;
|
|
name = name.toLowerCase();
|
|
const xArity = xFunc || xStep;
|
|
const arity = getOwnOption(opt, 'arity');
|
|
const arityArg = ('number'===typeof arity
|
|
? arity
|
|
: (xArity.length ? xArity.length-1/*for pCtx arg*/ : 0));
|
|
let rc;
|
|
if( isWindow ){
|
|
rc = capi.sqlite3_create_window_function(
|
|
this.pointer, name, arityArg,
|
|
capi.SQLITE_UTF8 | fFlags, pApp || 0,
|
|
xStep, xFinal, xValue, xInverse, xDestroy);
|
|
}else{
|
|
rc = capi.sqlite3_create_function_v2(
|
|
this.pointer, name, arityArg,
|
|
capi.SQLITE_UTF8 | fFlags, pApp || 0,
|
|
xFunc, xStep, xFinal, xDestroy);
|
|
}
|
|
DB.checkRc(this, rc);
|
|
return this;
|
|
}/*createFunction()*/,
|
|
/**
|
|
Prepares the given SQL, step()s it one time, and returns
|
|
the value of the first result column. If it has no results,
|
|
undefined is returned.
|
|
|
|
If passed a second argument, it is treated like an argument
|
|
to Stmt.bind(), so may be any type supported by that
|
|
function. Passing the undefined value is the same as passing
|
|
no value, which is useful when...
|
|
|
|
If passed a 3rd argument, it is expected to be one of the
|
|
SQLITE_{typename} constants. Passing the undefined value is
|
|
the same as not passing a value.
|
|
|
|
Throws on error (e.g. malformed SQL).
|
|
*/
|
|
selectValue: function(sql,bind,asType){
|
|
return __selectFirstRow(this, sql, bind, 0, asType);
|
|
},
|
|
|
|
/**
|
|
Runs the given query and returns an array of the values from
|
|
the first result column of each row of the result set. The 2nd
|
|
argument is an optional value for use in a single-argument call
|
|
to Stmt.bind(). The 3rd argument may be any value suitable for
|
|
use as the 2nd argument to Stmt.get(). If a 3rd argument is
|
|
desired but no bind data are needed, pass `undefined` for the 2nd
|
|
argument.
|
|
|
|
If there are no result rows, an empty array is returned.
|
|
*/
|
|
selectValues: function(sql,bind,asType){
|
|
const stmt = this.prepare(sql), rc = [];
|
|
try {
|
|
stmt.bind(bind);
|
|
while(stmt.step()) rc.push(stmt.get(0,asType));
|
|
stmt.reset(/*for INSERT...RETURNING locking case*/);
|
|
}finally{
|
|
stmt.finalize();
|
|
}
|
|
return rc;
|
|
},
|
|
|
|
/**
|
|
Prepares the given SQL, step()s it one time, and returns an
|
|
array containing the values of the first result row. If it has
|
|
no results, `undefined` is returned.
|
|
|
|
If passed a second argument other than `undefined`, it is
|
|
treated like an argument to Stmt.bind(), so may be any type
|
|
supported by that function.
|
|
|
|
Throws on error (e.g. malformed SQL).
|
|
*/
|
|
selectArray: function(sql,bind){
|
|
return __selectFirstRow(this, sql, bind, []);
|
|
},
|
|
|
|
/**
|
|
Prepares the given SQL, step()s it one time, and returns an
|
|
object containing the key/value pairs of the first result
|
|
row. If it has no results, `undefined` is returned.
|
|
|
|
Note that the order of returned object's keys is not guaranteed
|
|
to be the same as the order of the fields in the query string.
|
|
|
|
If passed a second argument other than `undefined`, it is
|
|
treated like an argument to Stmt.bind(), so may be any type
|
|
supported by that function.
|
|
|
|
Throws on error (e.g. malformed SQL).
|
|
*/
|
|
selectObject: function(sql,bind){
|
|
return __selectFirstRow(this, sql, bind, {});
|
|
},
|
|
|
|
/**
|
|
Runs the given SQL and returns an array of all results, with
|
|
each row represented as an array, as per the 'array' `rowMode`
|
|
option to `exec()`. An empty result set resolves
|
|
to an empty array. The second argument, if any, is treated as
|
|
the 'bind' option to a call to exec().
|
|
*/
|
|
selectArrays: function(sql,bind){
|
|
return __selectAll(this, sql, bind, 'array');
|
|
},
|
|
|
|
/**
|
|
Works identically to selectArrays() except that each value
|
|
in the returned array is an object, as per the 'object' `rowMode`
|
|
option to `exec()`.
|
|
*/
|
|
selectObjects: function(sql,bind){
|
|
return __selectAll(this, sql, bind, 'object');
|
|
},
|
|
|
|
/**
|
|
Returns the number of currently-opened Stmt handles for this db
|
|
handle, or 0 if this DB instance is closed. Note that only
|
|
handles prepared via this.prepare() are counted, and not
|
|
handles prepared using capi.sqlite3_prepare_v3() (or
|
|
equivalent).
|
|
*/
|
|
openStatementCount: function(){
|
|
return this.pointer ? Object.keys(__stmtMap.get(this)).length : 0;
|
|
},
|
|
|
|
/**
|
|
Starts a transaction, calls the given callback, and then either
|
|
rolls back or commits the savepoint, depending on whether the
|
|
callback throws. The callback is passed this db object as its
|
|
only argument. On success, returns the result of the
|
|
callback. Throws on error.
|
|
|
|
Note that transactions may not be nested, so this will throw if
|
|
it is called recursively. For nested transactions, use the
|
|
savepoint() method or manually manage SAVEPOINTs using exec().
|
|
|
|
If called with 2 arguments, the first must be a keyword which
|
|
is legal immediately after a BEGIN statement, e.g. one of
|
|
"DEFERRED", "IMMEDIATE", or "EXCLUSIVE". Though the exact list
|
|
of supported keywords is not hard-coded here, in order to be
|
|
future-compatible, if the argument does not look like a single
|
|
keyword then an exception is triggered with a description of
|
|
the problem.
|
|
*/
|
|
transaction: function(/* [beginQualifier,] */callback){
|
|
let opener = 'BEGIN';
|
|
if(arguments.length>1){
|
|
if(/[^a-zA-Z]/.test(arguments[0])){
|
|
toss3(capi.SQLITE_MISUSE, "Invalid argument for BEGIN qualifier.");
|
|
}
|
|
opener += ' '+arguments[0];
|
|
callback = arguments[1];
|
|
}
|
|
affirmDbOpen(this).exec(opener);
|
|
try {
|
|
const rc = callback(this);
|
|
this.exec("COMMIT");
|
|
return rc;
|
|
}catch(e){
|
|
this.exec("ROLLBACK");
|
|
throw e;
|
|
}
|
|
},
|
|
|
|
/**
|
|
This works similarly to transaction() but uses sqlite3's SAVEPOINT
|
|
feature. This function starts a savepoint (with an unspecified name)
|
|
and calls the given callback function, passing it this db object.
|
|
If the callback returns, the savepoint is released (committed). If
|
|
the callback throws, the savepoint is rolled back. If it does not
|
|
throw, it returns the result of the callback.
|
|
*/
|
|
savepoint: function(callback){
|
|
affirmDbOpen(this).exec("SAVEPOINT oo1");
|
|
try {
|
|
const rc = callback(this);
|
|
this.exec("RELEASE oo1");
|
|
return rc;
|
|
}catch(e){
|
|
this.exec("ROLLBACK to SAVEPOINT oo1; RELEASE SAVEPOINT oo1");
|
|
throw e;
|
|
}
|
|
},
|
|
|
|
/**
|
|
A convenience form of DB.checkRc(this,resultCode). If it does
|
|
not throw, it returns this object.
|
|
*/
|
|
checkRc: function(resultCode){
|
|
return checkSqlite3Rc(this, resultCode);
|
|
}
|
|
}/*DB.prototype*/;
|
|
|
|
|
|
/** Throws if the given Stmt has been finalized, else stmt is
|
|
returned. */
|
|
const affirmStmtOpen = function(stmt){
|
|
if(!stmt.pointer) toss3("Stmt has been closed.");
|
|
return stmt;
|
|
};
|
|
|
|
/** Returns an opaque truthy value from the BindTypes
|
|
enum if v's type is a valid bindable type, else
|
|
returns a falsy value. As a special case, a value of
|
|
undefined is treated as a bind type of null. */
|
|
const isSupportedBindType = function(v){
|
|
let t = BindTypes[(null===v||undefined===v) ? 'null' : typeof v];
|
|
switch(t){
|
|
case BindTypes.boolean:
|
|
case BindTypes.null:
|
|
case BindTypes.number:
|
|
case BindTypes.string:
|
|
return t;
|
|
case BindTypes.bigint:
|
|
if(wasm.bigIntEnabled) return t;
|
|
/* else fall through */
|
|
default:
|
|
return util.isBindableTypedArray(v) ? BindTypes.blob : undefined;
|
|
}
|
|
};
|
|
|
|
/**
|
|
If isSupportedBindType(v) returns a truthy value, this
|
|
function returns that value, else it throws.
|
|
*/
|
|
const affirmSupportedBindType = function(v){
|
|
//sqlite3.config.log('affirmSupportedBindType',v);
|
|
return isSupportedBindType(v) || toss3("Unsupported bind() argument type:",typeof v);
|
|
};
|
|
|
|
/**
|
|
If key is a number and within range of stmt's bound parameter
|
|
count, key is returned.
|
|
|
|
If key is not a number then it is checked against named
|
|
parameters. If a match is found, its index is returned.
|
|
|
|
Else it throws.
|
|
*/
|
|
const affirmParamIndex = function(stmt,key){
|
|
const n = ('number'===typeof key)
|
|
? key : capi.sqlite3_bind_parameter_index(stmt.pointer, key);
|
|
if(0===n || !util.isInt32(n)){
|
|
toss3("Invalid bind() parameter name: "+key);
|
|
}
|
|
else if(n<1 || n>stmt.parameterCount) toss3("Bind index",key,"is out of range.");
|
|
return n;
|
|
};
|
|
|
|
/**
|
|
If stmt._lockedByExec is truthy, this throws an exception
|
|
complaining that the 2nd argument (an operation name,
|
|
e.g. "bind()") is not legal while the statement is "locked".
|
|
Locking happens before an exec()-like callback is passed a
|
|
statement, to ensure that the callback does not mutate or
|
|
finalize the statement. If it does not throw, it returns stmt.
|
|
*/
|
|
const affirmNotLockedByExec = function(stmt,currentOpName){
|
|
if(stmt._lockedByExec){
|
|
toss3("Operation is illegal when statement is locked:",currentOpName);
|
|
}
|
|
return stmt;
|
|
};
|
|
|
|
/**
|
|
Binds a single bound parameter value on the given stmt at the
|
|
given index (numeric or named) using the given bindType (see
|
|
the BindTypes enum) and value. Throws on error. Returns stmt on
|
|
success.
|
|
*/
|
|
const bindOne = function f(stmt,ndx,bindType,val){
|
|
affirmNotLockedByExec(affirmStmtOpen(stmt), 'bind()');
|
|
if(!f._){
|
|
f._tooBigInt = (v)=>toss3(
|
|
"BigInt value is too big to store without precision loss:", v
|
|
);
|
|
f._ = {
|
|
string: function(stmt, ndx, val, asBlob){
|
|
const [pStr, n] = wasm.allocCString(val, true);
|
|
const f = asBlob ? capi.sqlite3_bind_blob : capi.sqlite3_bind_text;
|
|
return f(stmt.pointer, ndx, pStr, n, capi.SQLITE_WASM_DEALLOC);
|
|
}
|
|
};
|
|
}/* static init */
|
|
affirmSupportedBindType(val);
|
|
ndx = affirmParamIndex(stmt,ndx);
|
|
let rc = 0;
|
|
switch((null===val || undefined===val) ? BindTypes.null : bindType){
|
|
case BindTypes.null:
|
|
rc = capi.sqlite3_bind_null(stmt.pointer, ndx);
|
|
break;
|
|
case BindTypes.string:
|
|
rc = f._.string(stmt, ndx, val, false);
|
|
break;
|
|
case BindTypes.number: {
|
|
let m;
|
|
if(util.isInt32(val)) m = capi.sqlite3_bind_int;
|
|
else if('bigint'===typeof val){
|
|
if(!util.bigIntFits64(val)){
|
|
f._tooBigInt(val);
|
|
}else if(wasm.bigIntEnabled){
|
|
m = capi.sqlite3_bind_int64;
|
|
}else if(util.bigIntFitsDouble(val)){
|
|
val = Number(val);
|
|
m = capi.sqlite3_bind_double;
|
|
}else{
|
|
f._tooBigInt(val);
|
|
}
|
|
}else{ // !int32, !bigint
|
|
val = Number(val);
|
|
if(wasm.bigIntEnabled && Number.isInteger(val)){
|
|
m = capi.sqlite3_bind_int64;
|
|
}else{
|
|
m = capi.sqlite3_bind_double;
|
|
}
|
|
}
|
|
rc = m(stmt.pointer, ndx, val);
|
|
break;
|
|
}
|
|
case BindTypes.boolean:
|
|
rc = capi.sqlite3_bind_int(stmt.pointer, ndx, val ? 1 : 0);
|
|
break;
|
|
case BindTypes.blob: {
|
|
if('string'===typeof val){
|
|
rc = f._.string(stmt, ndx, val, true);
|
|
break;
|
|
}else if(val instanceof ArrayBuffer){
|
|
val = new Uint8Array(val);
|
|
}else if(!util.isBindableTypedArray(val)){
|
|
toss3("Binding a value as a blob requires",
|
|
"that it be a string, Uint8Array, Int8Array, or ArrayBuffer.");
|
|
}
|
|
const pBlob = wasm.alloc(val.byteLength || 1);
|
|
wasm.heap8().set(val.byteLength ? val : [0], pBlob)
|
|
rc = capi.sqlite3_bind_blob(stmt.pointer, ndx, pBlob, val.byteLength,
|
|
capi.SQLITE_WASM_DEALLOC);
|
|
break;
|
|
}
|
|
default:
|
|
sqlite3.config.warn("Unsupported bind() argument type:",val);
|
|
toss3("Unsupported bind() argument type: "+(typeof val));
|
|
}
|
|
if(rc) DB.checkRc(stmt.db.pointer, rc);
|
|
stmt._mayGet = false;
|
|
return stmt;
|
|
};
|
|
|
|
Stmt.prototype = {
|
|
/**
|
|
"Finalizes" this statement. This is a no-op if the statement
|
|
has already been finalized. Returns the result of
|
|
sqlite3_finalize() (0 on success, non-0 on error), or the
|
|
undefined value if the statement has already been
|
|
finalized. Regardless of success or failure, most methods in
|
|
this class will throw if called after this is.
|
|
|
|
This method always throws if called when it is illegal to do
|
|
so. Namely, when triggered via a per-row callback handler of a
|
|
DB.exec() call.
|
|
*/
|
|
finalize: function(){
|
|
if(this.pointer){
|
|
affirmNotLockedByExec(this,'finalize()');
|
|
const rc = capi.sqlite3_finalize(this.pointer);
|
|
delete __stmtMap.get(this.db)[this.pointer];
|
|
__ptrMap.delete(this);
|
|
delete this._mayGet;
|
|
delete this.parameterCount;
|
|
delete this._lockedByExec;
|
|
delete this.db;
|
|
return rc;
|
|
}
|
|
},
|
|
/**
|
|
Clears all bound values. Returns this object. Throws if this
|
|
statement has been finalized or if modification of the
|
|
statement is currently illegal (e.g. in the per-row callback of
|
|
a DB.exec() call).
|
|
*/
|
|
clearBindings: function(){
|
|
affirmNotLockedByExec(affirmStmtOpen(this), 'clearBindings()')
|
|
capi.sqlite3_clear_bindings(this.pointer);
|
|
this._mayGet = false;
|
|
return this;
|
|
},
|
|
/**
|
|
Resets this statement so that it may be step()ed again from the
|
|
beginning. Returns this object. Throws if this statement has
|
|
been finalized, if it may not legally be reset because it is
|
|
currently being used from a DB.exec() callback, or if the
|
|
underlying call to sqlite3_reset() returns non-0.
|
|
|
|
If passed a truthy argument then this.clearBindings() is
|
|
also called, otherwise any existing bindings, along with
|
|
any memory allocated for them, are retained.
|
|
|
|
In versions 3.42.0 and earlier, this function did not throw if
|
|
sqlite3_reset() returns non-0, but it was discovered that
|
|
throwing (or significant extra client-side code) is necessary
|
|
in order to avoid certain silent failure scenarios, as
|
|
discussed at:
|
|
|
|
https://sqlite.org/forum/forumpost/36f7a2e7494897df
|
|
*/
|
|
reset: function(alsoClearBinds){
|
|
affirmNotLockedByExec(this,'reset()');
|
|
if(alsoClearBinds) this.clearBindings();
|
|
const rc = capi.sqlite3_reset(affirmStmtOpen(this).pointer);
|
|
this._mayGet = false;
|
|
checkSqlite3Rc(this.db, rc);
|
|
return this;
|
|
},
|
|
/**
|
|
Binds one or more values to its bindable parameters. It
|
|
accepts 1 or 2 arguments:
|
|
|
|
If passed a single argument, it must be either an array, an
|
|
object, or a value of a bindable type (see below).
|
|
|
|
If passed 2 arguments, the first one is the 1-based bind
|
|
index or bindable parameter name and the second one must be
|
|
a value of a bindable type.
|
|
|
|
Bindable value types:
|
|
|
|
- null is bound as NULL.
|
|
|
|
- undefined as a standalone value is a no-op intended to
|
|
simplify certain client-side use cases: passing undefined as
|
|
a value to this function will not actually bind anything and
|
|
this function will skip confirmation that binding is even
|
|
legal. (Those semantics simplify certain client-side uses.)
|
|
Conversely, a value of undefined as an array or object
|
|
property when binding an array/object (see below) is treated
|
|
the same as null.
|
|
|
|
- Numbers are bound as either doubles or integers: doubles if
|
|
they are larger than 32 bits, else double or int32, depending
|
|
on whether they have a fractional part. Booleans are bound as
|
|
integer 0 or 1. It is not expected the distinction of binding
|
|
doubles which have no fractional parts and integers is
|
|
significant for the majority of clients due to sqlite3's data
|
|
typing model. If BigInt support is enabled then this routine
|
|
will bind BigInt values as 64-bit integers if they'll fit in
|
|
64 bits. If that support disabled, it will store the BigInt
|
|
as an int32 or a double if it can do so without loss of
|
|
precision. If the BigInt is _too BigInt_ then it will throw.
|
|
|
|
- Strings are bound as strings (use bindAsBlob() to force
|
|
blob binding).
|
|
|
|
- Uint8Array, Int8Array, and ArrayBuffer instances are bound as
|
|
blobs.
|
|
|
|
If passed an array, each element of the array is bound at
|
|
the parameter index equal to the array index plus 1
|
|
(because arrays are 0-based but binding is 1-based).
|
|
|
|
If passed an object, each object key is treated as a
|
|
bindable parameter name. The object keys _must_ match any
|
|
bindable parameter names, including any `$`, `@`, or `:`
|
|
prefix. Because `$` is a legal identifier chararacter in
|
|
JavaScript, that is the suggested prefix for bindable
|
|
parameters: `stmt.bind({$a: 1, $b: 2})`.
|
|
|
|
It returns this object on success and throws on
|
|
error. Errors include:
|
|
|
|
- Any bind index is out of range, a named bind parameter
|
|
does not match, or this statement has no bindable
|
|
parameters.
|
|
|
|
- Any value to bind is of an unsupported type.
|
|
|
|
- Passed no arguments or more than two.
|
|
|
|
- The statement has been finalized.
|
|
*/
|
|
bind: function(/*[ndx,] arg*/){
|
|
affirmStmtOpen(this);
|
|
let ndx, arg;
|
|
switch(arguments.length){
|
|
case 1: ndx = 1; arg = arguments[0]; break;
|
|
case 2: ndx = arguments[0]; arg = arguments[1]; break;
|
|
default: toss3("Invalid bind() arguments.");
|
|
}
|
|
if(undefined===arg){
|
|
/* It might seem intuitive to bind undefined as NULL
|
|
but this approach simplifies certain client-side
|
|
uses when passing on arguments between 2+ levels of
|
|
functions. */
|
|
return this;
|
|
}else if(!this.parameterCount){
|
|
toss3("This statement has no bindable parameters.");
|
|
}
|
|
this._mayGet = false;
|
|
if(null===arg){
|
|
/* bind NULL */
|
|
return bindOne(this, ndx, BindTypes.null, arg);
|
|
}
|
|
else if(Array.isArray(arg)){
|
|
/* bind each entry by index */
|
|
if(1!==arguments.length){
|
|
toss3("When binding an array, an index argument is not permitted.");
|
|
}
|
|
arg.forEach((v,i)=>bindOne(this, i+1, affirmSupportedBindType(v), v));
|
|
return this;
|
|
}else if(arg instanceof ArrayBuffer){
|
|
arg = new Uint8Array(arg);
|
|
}
|
|
if('object'===typeof arg/*null was checked above*/
|
|
&& !util.isBindableTypedArray(arg)){
|
|
/* Treat each property of arg as a named bound parameter. */
|
|
if(1!==arguments.length){
|
|
toss3("When binding an object, an index argument is not permitted.");
|
|
}
|
|
Object.keys(arg)
|
|
.forEach(k=>bindOne(this, k,
|
|
affirmSupportedBindType(arg[k]),
|
|
arg[k]));
|
|
return this;
|
|
}else{
|
|
return bindOne(this, ndx, affirmSupportedBindType(arg), arg);
|
|
}
|
|
toss3("Should not reach this point.");
|
|
},
|
|
/**
|
|
Special case of bind() which binds the given value using the
|
|
BLOB binding mechanism instead of the default selected one for
|
|
the value. The ndx may be a numbered or named bind index. The
|
|
value must be of type string, null/undefined (both get treated
|
|
as null), or a TypedArray of a type supported by the bind()
|
|
API. This API cannot bind numbers as blobs.
|
|
|
|
If passed a single argument, a bind index of 1 is assumed and
|
|
the first argument is the value.
|
|
*/
|
|
bindAsBlob: function(ndx,arg){
|
|
affirmStmtOpen(this);
|
|
if(1===arguments.length){
|
|
arg = ndx;
|
|
ndx = 1;
|
|
}
|
|
const t = affirmSupportedBindType(arg);
|
|
if(BindTypes.string !== t && BindTypes.blob !== t
|
|
&& BindTypes.null !== t){
|
|
toss3("Invalid value type for bindAsBlob()");
|
|
}
|
|
return bindOne(this, ndx, BindTypes.blob, arg);
|
|
},
|
|
/**
|
|
Steps the statement one time. If the result indicates that a
|
|
row of data is available, a truthy value is returned. If no
|
|
row of data is available, a falsy value is returned. Throws on
|
|
error.
|
|
*/
|
|
step: function(){
|
|
affirmNotLockedByExec(this, 'step()');
|
|
const rc = capi.sqlite3_step(affirmStmtOpen(this).pointer);
|
|
switch(rc){
|
|
case capi.SQLITE_DONE: return this._mayGet = false;
|
|
case capi.SQLITE_ROW: return this._mayGet = true;
|
|
default:
|
|
this._mayGet = false;
|
|
sqlite3.config.warn("sqlite3_step() rc=",rc,
|
|
capi.sqlite3_js_rc_str(rc),
|
|
"SQL =", capi.sqlite3_sql(this.pointer));
|
|
DB.checkRc(this.db.pointer, rc);
|
|
}
|
|
},
|
|
/**
|
|
Functions exactly like step() except that...
|
|
|
|
1) On success, it calls this.reset() and returns this object.
|
|
|
|
2) On error, it throws and does not call reset().
|
|
|
|
This is intended to simplify constructs like:
|
|
|
|
```
|
|
for(...) {
|
|
stmt.bind(...).stepReset();
|
|
}
|
|
```
|
|
|
|
Note that the reset() call makes it illegal to call this.get()
|
|
after the step.
|
|
*/
|
|
stepReset: function(){
|
|
this.step();
|
|
return this.reset();
|
|
},
|
|
/**
|
|
Functions like step() except that it calls finalize() on this
|
|
statement immediately after stepping, even if the step() call
|
|
throws.
|
|
|
|
On success, it returns true if the step indicated that a row of
|
|
data was available, else it returns a falsy value.
|
|
|
|
This is intended to simplify use cases such as:
|
|
|
|
```
|
|
aDb.prepare("insert into foo(a) values(?)").bind(123).stepFinalize();
|
|
```
|
|
*/
|
|
stepFinalize: function(){
|
|
try{
|
|
const rc = this.step();
|
|
this.reset(/*for INSERT...RETURNING locking case*/);
|
|
return rc;
|
|
}finally{
|
|
try{this.finalize()}
|
|
catch(e){/*ignored*/}
|
|
}
|
|
},
|
|
|
|
/**
|
|
Fetches the value from the given 0-based column index of
|
|
the current data row, throwing if index is out of range.
|
|
|
|
Requires that step() has just returned a truthy value, else
|
|
an exception is thrown.
|
|
|
|
By default it will determine the data type of the result
|
|
automatically. If passed a second argument, it must be one
|
|
of the enumeration values for sqlite3 types, which are
|
|
defined as members of the sqlite3 module: SQLITE_INTEGER,
|
|
SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB. Any other value,
|
|
except for undefined, will trigger an exception. Passing
|
|
undefined is the same as not passing a value. It is legal
|
|
to, e.g., fetch an integer value as a string, in which case
|
|
sqlite3 will convert the value to a string.
|
|
|
|
If ndx is an array, this function behaves a differently: it
|
|
assigns the indexes of the array, from 0 to the number of
|
|
result columns, to the values of the corresponding column,
|
|
and returns that array.
|
|
|
|
If ndx is a plain object, this function behaves even
|
|
differentlier: it assigns the properties of the object to
|
|
the values of their corresponding result columns and returns
|
|
that object.
|
|
|
|
Blobs are returned as Uint8Array instances.
|
|
|
|
Potential TODO: add type ID SQLITE_JSON, which fetches the
|
|
result as a string and passes it (if it's not null) to
|
|
JSON.parse(), returning the result of that. Until then,
|
|
getJSON() can be used for that.
|
|
*/
|
|
get: function(ndx,asType){
|
|
if(!affirmStmtOpen(this)._mayGet){
|
|
toss3("Stmt.step() has not (recently) returned true.");
|
|
}
|
|
if(Array.isArray(ndx)){
|
|
let i = 0;
|
|
const n = this.columnCount;
|
|
while(i<n){
|
|
ndx[i] = this.get(i++);
|
|
}
|
|
return ndx;
|
|
}else if(ndx && 'object'===typeof ndx){
|
|
let i = 0;
|
|
const n = this.columnCount;
|
|
while(i<n){
|
|
ndx[capi.sqlite3_column_name(this.pointer,i)] = this.get(i++);
|
|
}
|
|
return ndx;
|
|
}
|
|
affirmColIndex(this, ndx);
|
|
switch(undefined===asType
|
|
? capi.sqlite3_column_type(this.pointer, ndx)
|
|
: asType){
|
|
case capi.SQLITE_NULL: return null;
|
|
case capi.SQLITE_INTEGER:{
|
|
if(wasm.bigIntEnabled){
|
|
const rc = capi.sqlite3_column_int64(this.pointer, ndx);
|
|
if(rc>=Number.MIN_SAFE_INTEGER && rc<=Number.MAX_SAFE_INTEGER){
|
|
/* Coerce "normal" number ranges to normal number values,
|
|
and only return BigInt-type values for numbers out of this
|
|
range. */
|
|
return Number(rc).valueOf();
|
|
}
|
|
return rc;
|
|
}else{
|
|
const rc = capi.sqlite3_column_double(this.pointer, ndx);
|
|
if(rc>Number.MAX_SAFE_INTEGER || rc<Number.MIN_SAFE_INTEGER){
|
|
/* Throwing here is arguable but, since we're explicitly
|
|
extracting an SQLITE_INTEGER-type value, it seems fair to throw
|
|
if the extracted number is out of range for that type.
|
|
This policy may be laxened to simply pass on the number and
|
|
hope for the best, as the C API would do. */
|
|
toss3("Integer is out of range for JS integer range: "+rc);
|
|
}
|
|
//sqlite3.config.log("get integer rc=",rc,isInt32(rc));
|
|
return util.isInt32(rc) ? (rc | 0) : rc;
|
|
}
|
|
}
|
|
case capi.SQLITE_FLOAT:
|
|
return capi.sqlite3_column_double(this.pointer, ndx);
|
|
case capi.SQLITE_TEXT:
|
|
return capi.sqlite3_column_text(this.pointer, ndx);
|
|
case capi.SQLITE_BLOB: {
|
|
const n = capi.sqlite3_column_bytes(this.pointer, ndx),
|
|
ptr = capi.sqlite3_column_blob(this.pointer, ndx),
|
|
rc = new Uint8Array(n);
|
|
//heap = n ? wasm.heap8() : false;
|
|
if(n) rc.set(wasm.heap8u().slice(ptr, ptr+n), 0);
|
|
//for(let i = 0; i < n; ++i) rc[i] = heap[ptr + i];
|
|
if(n && this.db._blobXfer instanceof Array){
|
|
/* This is an optimization soley for the
|
|
Worker-based API. These values will be
|
|
transfered to the main thread directly
|
|
instead of being copied. */
|
|
this.db._blobXfer.push(rc.buffer);
|
|
}
|
|
return rc;
|
|
}
|
|
default: toss3("Don't know how to translate",
|
|
"type of result column #"+ndx+".");
|
|
}
|
|
toss3("Not reached.");
|
|
},
|
|
/** Equivalent to get(ndx) but coerces the result to an
|
|
integer. */
|
|
getInt: function(ndx){return this.get(ndx,capi.SQLITE_INTEGER)},
|
|
/** Equivalent to get(ndx) but coerces the result to a
|
|
float. */
|
|
getFloat: function(ndx){return this.get(ndx,capi.SQLITE_FLOAT)},
|
|
/** Equivalent to get(ndx) but coerces the result to a
|
|
string. */
|
|
getString: function(ndx){return this.get(ndx,capi.SQLITE_TEXT)},
|
|
/** Equivalent to get(ndx) but coerces the result to a
|
|
Uint8Array. */
|
|
getBlob: function(ndx){return this.get(ndx,capi.SQLITE_BLOB)},
|
|
/**
|
|
A convenience wrapper around get() which fetches the value
|
|
as a string and then, if it is not null, passes it to
|
|
JSON.parse(), returning that result. Throws if parsing
|
|
fails. If the result is null, null is returned. An empty
|
|
string, on the other hand, will trigger an exception.
|
|
*/
|
|
getJSON: function(ndx){
|
|
const s = this.get(ndx, capi.SQLITE_STRING);
|
|
return null===s ? s : JSON.parse(s);
|
|
},
|
|
// Design note: the only reason most of these getters have a 'get'
|
|
// prefix is for consistency with getVALUE_TYPE(). The latter
|
|
// arguably really need that prefix for API readability and the
|
|
// rest arguably don't, but consistency is a powerful thing.
|
|
/**
|
|
Returns the result column name of the given index, or
|
|
throws if index is out of bounds or this statement has been
|
|
finalized. This can be used without having run step()
|
|
first.
|
|
*/
|
|
getColumnName: function(ndx){
|
|
return capi.sqlite3_column_name(
|
|
affirmColIndex(affirmStmtOpen(this),ndx).pointer, ndx
|
|
);
|
|
},
|
|
/**
|
|
If this statement potentially has result columns, this function
|
|
returns an array of all such names. If passed an array, it is
|
|
used as the target and all names are appended to it. Returns
|
|
the target array. Throws if this statement cannot have result
|
|
columns. This object's columnCount property holds the number of
|
|
columns.
|
|
*/
|
|
getColumnNames: function(tgt=[]){
|
|
affirmColIndex(affirmStmtOpen(this),0);
|
|
const n = this.columnCount;
|
|
for(let i = 0; i < n; ++i){
|
|
tgt.push(capi.sqlite3_column_name(this.pointer, i));
|
|
}
|
|
return tgt;
|
|
},
|
|
/**
|
|
If this statement has named bindable parameters and the
|
|
given name matches one, its 1-based bind index is
|
|
returned. If no match is found, 0 is returned. If it has no
|
|
bindable parameters, the undefined value is returned.
|
|
*/
|
|
getParamIndex: function(name){
|
|
return (affirmStmtOpen(this).parameterCount
|
|
? capi.sqlite3_bind_parameter_index(this.pointer, name)
|
|
: undefined);
|
|
},
|
|
/**
|
|
If this statement has named bindable parameters and the given
|
|
index refers to one, its name is returned, else null is
|
|
returned. If this statement has no bound parameters, undefined
|
|
is returned.
|
|
|
|
Added in 3.47.
|
|
*/
|
|
getParamName: function(ndx){
|
|
return (affirmStmtOpen(this).parameterCount
|
|
? capi.sqlite3_bind_parameter_name(this.pointer, ndx)
|
|
: undefined);
|
|
},
|
|
|
|
/**
|
|
Behaves like sqlite3_stmt_busy() but throws if this statement
|
|
is closed and returns a value of type boolean instead of integer.
|
|
|
|
Added in 3.47.
|
|
*/
|
|
isBusy: function(){
|
|
return 0!==capi.sqlite3_stmt_busy(affirmStmtOpen(this));
|
|
},
|
|
|
|
/**
|
|
Behaves like sqlite3_stmt_readonly() but throws if this statement
|
|
is closed and returns a value of type boolean instead of integer.
|
|
|
|
Added in 3.47.
|
|
*/
|
|
isReadOnly: function(){
|
|
return 0!==capi.sqlite3_stmt_readonly(affirmStmtOpen(this));
|
|
}
|
|
}/*Stmt.prototype*/;
|
|
|
|
{/* Add the `pointer` property to DB and Stmt. */
|
|
const prop = {
|
|
enumerable: true,
|
|
get: function(){return __ptrMap.get(this)},
|
|
set: ()=>toss3("The pointer property is read-only.")
|
|
}
|
|
Object.defineProperty(Stmt.prototype, 'pointer', prop);
|
|
Object.defineProperty(DB.prototype, 'pointer', prop);
|
|
}
|
|
/**
|
|
Stmt.columnCount is an interceptor for sqlite3_column_count().
|
|
|
|
This requires an unfortunate performance hit compared to caching
|
|
columnCount when the Stmt is created/prepared (as was done in
|
|
SQLite <=3.42.0), but is necessary in order to handle certain
|
|
corner cases, as described in
|
|
https://sqlite.org/forum/forumpost/7774b773937cbe0a.
|
|
*/
|
|
Object.defineProperty(Stmt.prototype, 'columnCount', {
|
|
enumerable: false,
|
|
get: function(){return capi.sqlite3_column_count(this.pointer)},
|
|
set: ()=>toss3("The columnCount property is read-only.")
|
|
});
|
|
|
|
/** The OO API's public namespace. */
|
|
sqlite3.oo1 = {
|
|
DB,
|
|
Stmt
|
|
}/*oo1 object*/;
|
|
|
|
if(util.isUIThread()){
|
|
/**
|
|
Functionally equivalent to DB(storageName,'c','kvvfs') except
|
|
that it throws if the given storage name is not one of 'local'
|
|
or 'session'.
|
|
|
|
As of version 3.46, the argument may optionally be an options
|
|
object in the form:
|
|
|
|
{
|
|
filename: 'session'|'local',
|
|
... etc. (all options supported by the DB ctor)
|
|
}
|
|
|
|
noting that the 'vfs' option supported by main DB
|
|
constructor is ignored here: the vfs is always 'kvvfs'.
|
|
*/
|
|
sqlite3.oo1.JsStorageDb = function(storageName='session'){
|
|
const opt = dbCtorHelper.normalizeArgs(...arguments);
|
|
storageName = opt.filename;
|
|
if('session'!==storageName && 'local'!==storageName){
|
|
toss3("JsStorageDb db name must be one of 'session' or 'local'.");
|
|
}
|
|
opt.vfs = 'kvvfs';
|
|
dbCtorHelper.call(this, opt);
|
|
};
|
|
const jdb = sqlite3.oo1.JsStorageDb;
|
|
jdb.prototype = Object.create(DB.prototype);
|
|
/** Equivalent to sqlite3_js_kvvfs_clear(). */
|
|
jdb.clearStorage = capi.sqlite3_js_kvvfs_clear;
|
|
/**
|
|
Clears this database instance's storage or throws if this
|
|
instance has been closed. Returns the number of
|
|
database blocks which were cleaned up.
|
|
*/
|
|
jdb.prototype.clearStorage = function(){
|
|
return jdb.clearStorage(affirmDbOpen(this).filename);
|
|
};
|
|
/** Equivalent to sqlite3_js_kvvfs_size(). */
|
|
jdb.storageSize = capi.sqlite3_js_kvvfs_size;
|
|
/**
|
|
Returns the _approximate_ number of bytes this database takes
|
|
up in its storage or throws if this instance has been closed.
|
|
*/
|
|
jdb.prototype.storageSize = function(){
|
|
return jdb.storageSize(affirmDbOpen(this).filename);
|
|
};
|
|
}/*main-window-only bits*/
|
|
|
|
});
|
|
//#else
|
|
/* Built with the omit-oo1 flag. */
|
|
//#endif ifnot omit-oo1
|