1782 lines
74 KiB
JavaScript
1782 lines
74 KiB
JavaScript
/*
|
|
2022-05-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 is intended to be appended to the emcc-generated
|
|
sqlite3.js via emcc:
|
|
|
|
emcc ... -sMODULARIZE -sEXPORT_NAME=initSqlite3Module --post-js=THIS_FILE
|
|
|
|
It is loaded by importing the emcc-generated sqlite3.js, then:
|
|
|
|
initSqlite3Module({module object}).then(
|
|
function(theModule){
|
|
theModule.sqlite3 == an object containing this file's
|
|
deliverables:
|
|
{
|
|
api: bindings for much of the core sqlite3 APIs,
|
|
SQLite3: high-level OO API wrapper
|
|
}
|
|
});
|
|
|
|
It is up to the caller to provide a module object compatible with
|
|
emcc, but it can be a plain empty object. The object passed to
|
|
initSqlite3Module() will get populated by the emscripten-generated
|
|
bits and, in part, by the code from this file. Specifically, this file
|
|
installs the `theModule.sqlite3` part shown above.
|
|
|
|
The resulting sqlite3.api object wraps the standard sqlite3 C API in
|
|
a way as close to its native form as JS allows for. The
|
|
sqlite3.SQLite3 object provides a higher-level wrapper more
|
|
appropriate for general client-side use in JS.
|
|
|
|
Because using certain parts of the low-level API properly requires
|
|
some degree of WASM-related magic, it is not recommended that that
|
|
API be used as-is in client-level code. Rather, client code should
|
|
use the higher-level OO API or write a custom wrapper on top of the
|
|
lower-level API. In short, most of the C-style API is used in an
|
|
intuitive manner from JS but any C-style APIs which take
|
|
pointers-to-pointer arguments require WASM-specific interfaces
|
|
installed by emcscripten-generated code. Those which take or return
|
|
only integers, doubles, strings, or "plain" pointers to db or
|
|
statement objects can be used in "as normal," noting that "pointers"
|
|
in wasm are simply 32-bit integers.
|
|
|
|
# Goals and Non-goals of this API
|
|
|
|
Goals:
|
|
|
|
- Except where noted in the non-goals, provide a more-or-less
|
|
complete wrapper to the sqlite3 C API, insofar as WASM feature
|
|
parity with C allows for. In fact, provide at least 3...
|
|
|
|
- (1) The aforementioned C-style API. (2) An OO-style API on
|
|
top of that, designed to run in the same thread (main window or
|
|
Web Worker) as the C API. (3) A less-capable wrapper which can
|
|
work across the main window/worker boundary, where the sqlite3 API
|
|
is one of those and this wrapper is in the other. That
|
|
constellation places some considerable limitations on how the API
|
|
can be interacted with, but keeping the DB operations out of the
|
|
UI thread is generally desirable.
|
|
|
|
- Insofar as possible, support client-side storage using JS
|
|
filesystem APIs. As of this writing, such things are still very
|
|
much TODO.
|
|
|
|
Non-goals:
|
|
|
|
- As WASM is a web-centric technology and UTF-8 is the King of
|
|
Encodings in that realm, there are no current plans to support the
|
|
UTF16-related APIs. They would add a complication to the bindings
|
|
for no appreciable benefit.
|
|
|
|
- Supporting old or niche-market platforms. WASM is built for a
|
|
modern web and requires modern platforms.
|
|
|
|
*/
|
|
if(!Module.postRun) Module.postRun = [];
|
|
/* ^^^^ the name Module is, in this setup, scope-local in the generated
|
|
file sqlite3.js, with which this file gets combined at build-time. */
|
|
Module.postRun.push(function(namespace/*the module object, the target for
|
|
installed features*/){
|
|
'use strict';
|
|
/* For reference: sql.js does essentially everything we want and
|
|
it solves much of the wasm-related voodoo, but we'll need a
|
|
different structure because we want the db connection to run in
|
|
a worker thread and feed data back into the main
|
|
thread. Regardless of those differences, it makes a great point
|
|
of reference:
|
|
|
|
https://github.com/sql-js/sql.js
|
|
|
|
Some of the specific design goals here:
|
|
|
|
- Bind a low-level sqlite3 API which is close to the native one
|
|
in terms of usage.
|
|
|
|
- Create a higher-level one, more akin to sql.js and
|
|
node.js-style implementations. This one would speak directly
|
|
to the low-level API. This API could be used by clients who
|
|
import the low-level API directly into their main thread
|
|
(which we don't want to recommend but also don't want to
|
|
outright forbid).
|
|
|
|
- Create a second higher-level one which speaks to the
|
|
low-level API via worker messages. This one would be intended
|
|
for use in the main thread, talking to the low-level UI via
|
|
worker messages. Because workers have only a single message
|
|
channel, some acrobatics will be needed here to feed async
|
|
work results back into client-side callbacks (as those
|
|
callbacks cannot simply be passed to the worker). Exactly
|
|
what those acrobatics should look like is not yet entirely
|
|
clear and much experimentation is pending.
|
|
*/
|
|
|
|
const SQM = namespace/*the sqlite module object */;
|
|
|
|
/**
|
|
Set up the main sqlite3 binding API here, mimicking the C API as
|
|
closely as we can.
|
|
|
|
Attribution: though not a direct copy/paste, much of what
|
|
follows is strongly influenced by the sql.js implementation.
|
|
*/
|
|
const api = {
|
|
/* It is important that the following integer values match
|
|
those from the C code. Ideally we could fetch them from the
|
|
C API, e.g., in the form of a JSON object, but getting that
|
|
JSON string constructed within our current confines is
|
|
currently not worth the effort.
|
|
|
|
Reminder to self: we could probably do so by adding the
|
|
proverbial level of indirection, calling in to C to get it,
|
|
and having that C func call an
|
|
emscripten-installed/JS-implemented library function which
|
|
builds the result object:
|
|
|
|
const obj = {};
|
|
sqlite3__get_enum(function(key,val){
|
|
obj[key] = val;
|
|
});
|
|
|
|
but whether or not we can pass a function that way, via a
|
|
(void*) is as yet unknown.
|
|
*/
|
|
/* Minimum subset of sqlite result codes we'll need. */
|
|
SQLITE_OK: 0,
|
|
SQLITE_ROW: 100,
|
|
SQLITE_DONE: 101,
|
|
/* sqlite data types */
|
|
SQLITE_INTEGER: 1,
|
|
SQLITE_FLOAT: 2,
|
|
SQLITE_TEXT: 3,
|
|
SQLITE_BLOB: 4,
|
|
SQLITE_NULL: 5,
|
|
/* create_function() flags */
|
|
SQLITE_DETERMINISTIC: 0x000000800,
|
|
SQLITE_DIRECTONLY: 0x000080000,
|
|
SQLITE_INNOCUOUS: 0x000200000,
|
|
/* sqlite encodings, used for creating UDFs, noting that we
|
|
will only support UTF8. */
|
|
SQLITE_UTF8: 1
|
|
};
|
|
const cwrap = SQM.cwrap;
|
|
[/* C-side functions to bind. Each entry is an array with 3 or 4
|
|
elements:
|
|
|
|
["c-side name",
|
|
"result type" (cwrap() syntax),
|
|
[arg types in cwrap() syntax]
|
|
]
|
|
|
|
If it has 4 elements, the first one is an alternate name to
|
|
use for the JS-side binding. That's required when overloading
|
|
a binding for two different uses.
|
|
*/
|
|
["sqlite3_bind_blob","number",["number", "number", "number", "number", "number"]],
|
|
["sqlite3_bind_double","number",["number", "number", "number"]],
|
|
["sqlite3_bind_int","number",["number", "number", "number"]],
|
|
/*Noting that JS/wasm combo does not currently support 64-bit integers:
|
|
["sqlite3_bind_int64","number",["number", "number", "number"]],*/
|
|
["sqlite3_bind_null","void",["number"]],
|
|
["sqlite3_bind_parameter_count", "number", ["number"]],
|
|
["sqlite3_bind_parameter_index","number",["number", "string"]],
|
|
["sqlite3_bind_text","number",["number", "number", "number", "number", "number"]],
|
|
["sqlite3_changes", "number", ["number"]],
|
|
["sqlite3_clear_bindings","number",["number"]],
|
|
["sqlite3_close_v2", "number", ["number"]],
|
|
["sqlite3_column_blob","number", ["number", "number"]],
|
|
["sqlite3_column_bytes","number",["number", "number"]],
|
|
["sqlite3_column_count", "number", ["number"]],
|
|
["sqlite3_column_count","number",["number"]],
|
|
["sqlite3_column_double","number",["number", "number"]],
|
|
["sqlite3_column_int","number",["number", "number"]],
|
|
/*Noting that JS/wasm combo does not currently support 64-bit integers:
|
|
["sqlite3_column_int64","number",["number", "number"]],*/
|
|
["sqlite3_column_name","string",["number", "number"]],
|
|
["sqlite3_column_text","string",["number", "number"]],
|
|
["sqlite3_column_type","number",["number", "number"]],
|
|
["sqlite3_compileoption_get", "string", ["number"]],
|
|
["sqlite3_compileoption_used", "number", ["string"]],
|
|
["sqlite3_create_function_v2", "number",
|
|
["number", "string", "number", "number","number",
|
|
"number", "number", "number", "number"]],
|
|
["sqlite3_data_count", "number", ["number"]],
|
|
["sqlite3_db_filename", "string", ["number", "string"]],
|
|
["sqlite3_errmsg", "string", ["number"]],
|
|
["sqlite3_exec", "number", ["number", "string", "number", "number", "number"]],
|
|
["sqlite3_finalize", "number", ["number"]],
|
|
["sqlite3_interrupt", "void", ["number"]],
|
|
["sqlite3_libversion", "string", []],
|
|
["sqlite3_open", "number", ["string", "number"]],
|
|
//["sqlite3_open_v2", "number", ["string", "number", "number", "string"]],
|
|
//^^^^ TODO: add the flags needed for the 3rd arg
|
|
["sqlite3_prepare_v2", "number", ["number", "string", "number", "number", "number"]],
|
|
["sqlite3_prepare_v2_sqlptr", "sqlite3_prepare_v2",
|
|
/* Impl which requires that the 2nd argument be a pointer to
|
|
the SQL string, instead of being converted to a
|
|
string. This is used for cases where we require a non-NULL
|
|
value for the final argument (exec()'ing multiple
|
|
statements from one input string). */
|
|
"number", ["number", "number", "number", "number", "number"]],
|
|
["sqlite3_reset", "number", ["number"]],
|
|
["sqlite3_result_blob",null,["number", "number", "number", "number"]],
|
|
["sqlite3_result_double",null,["number", "number"]],
|
|
["sqlite3_result_error",null,["number", "string", "number"]],
|
|
["sqlite3_result_int",null,["number", "number"]],
|
|
["sqlite3_result_null",null,["number"]],
|
|
["sqlite3_result_text",null,["number", "string", "number", "number"]],
|
|
["sqlite3_sourceid", "string", []],
|
|
["sqlite3_sql", "string", ["number"]],
|
|
["sqlite3_step", "number", ["number"]],
|
|
["sqlite3_value_blob", "number", ["number"]],
|
|
["sqlite3_value_bytes","number",["number"]],
|
|
["sqlite3_value_double","number",["number"]],
|
|
["sqlite3_value_text", "string", ["number"]],
|
|
["sqlite3_value_type", "number", ["number"]]
|
|
//["sqlite3_normalized_sql", "string", ["number"]]
|
|
].forEach(function(a){
|
|
const k = (4==a.length) ? a.shift() : a[0];
|
|
api[k] = cwrap.apply(this, a);
|
|
});
|
|
|
|
/* 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. */
|
|
|
|
/** Memory for use in some pointer-to-pointer-passing routines. */
|
|
const pPtrArg = stackAlloc(4);
|
|
/** Throws a new error, concatenating all args with a space between
|
|
each. */
|
|
const toss = function(){
|
|
throw new Error(Array.prototype.join.call(arguments, ' '));
|
|
};
|
|
|
|
/**
|
|
The DB class wraps a sqlite3 db handle.
|
|
|
|
It accepts the following argument signatures:
|
|
|
|
- ()
|
|
- (undefined) (same effect as ())
|
|
- (filename[,buffer])
|
|
- (buffer)
|
|
|
|
Where a buffer indicates a Uint8Array holding an sqlite3 db
|
|
image.
|
|
|
|
If the filename is provided, only the last component of the
|
|
path is used - any path prefix is stripped and certain
|
|
"special" characters are replaced with `_`. If no name is
|
|
provided, a random name is generated. The resulting filename is
|
|
the one used for accessing the db file within root directory of
|
|
the emscripten-supplied virtual filesystem, and is set (with no
|
|
path part) as the DB object's `filename` property.
|
|
|
|
Note that the special sqlite3 db names ":memory:" and ""
|
|
(temporary db) have no special meanings here. We can apparently
|
|
only export images of DBs which are stored in the
|
|
pseudo-filesystem provided by the JS APIs. Since exporting and
|
|
importing images is an important usability feature for this
|
|
class, ":memory:" DBs are not supported (until/unless we can
|
|
find a way to export those as well). The naming semantics will
|
|
certainly evolve as this API does.
|
|
*/
|
|
const DB = function(arg){
|
|
let buffer, fn;
|
|
if(arg instanceof Uint8Array){
|
|
buffer = arg;
|
|
arg = undefined;
|
|
}else if(arguments.length){ /*(filename[,buffer])*/
|
|
if('string'===typeof arg){
|
|
const p = arg.split('/').pop().replace(':','_');
|
|
if(p) fn = p;
|
|
if(arguments.length>1){
|
|
buffer = arguments[1];
|
|
}
|
|
}else if(undefined!==arg){
|
|
toss("Invalid arguments to DB constructor.",
|
|
"Expecting (), (undefined), (name,buffer),",
|
|
"or (buffer), where buffer an sqlite3 db ",
|
|
"as a Uint8Array.");
|
|
}
|
|
}
|
|
if(!fn){
|
|
fn = "db-"+((Math.random() * 10000000) | 0)+
|
|
"-"+((Math.random() * 10000000) | 0)+".sqlite3";
|
|
}
|
|
if(buffer){
|
|
if(!(buffer instanceof Uint8Array)){
|
|
toss("Expecting Uint8Array image of db contents.");
|
|
}
|
|
FS.createDataFile("/", fn, buffer, true, true);
|
|
}
|
|
setValue(pPtrArg, 0, "i32");
|
|
this.checkRc(api.sqlite3_open(fn, pPtrArg));
|
|
this._pDb = getValue(pPtrArg, "i32");
|
|
this.filename = fn;
|
|
this._statements = {/*map of open Stmt _pointers_ to Stmt*/};
|
|
this._udfs = {/*map of UDF names to wasm function _pointers_*/};
|
|
};
|
|
|
|
/**
|
|
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;
|
|
|
|
/**
|
|
This class wraps sqlite3_stmt. Calling this constructor
|
|
directly will trigger an exception. Use DB.prepare() to create
|
|
new instances.
|
|
*/
|
|
const Stmt = function(){
|
|
if(BindTypes!==arguments[2]){
|
|
toss("Do not call the Stmt constructor directly. Use DB.prepare().");
|
|
}
|
|
this.db = arguments[0];
|
|
this._pStmt = arguments[1];
|
|
this.columnCount = api.sqlite3_column_count(this._pStmt);
|
|
this.parameterCount = api.sqlite3_bind_parameter_count(this._pStmt);
|
|
this._allocs = [/*list of alloc'd memory blocks for bind() values*/]
|
|
};
|
|
|
|
/** Throws if the given DB has been closed, else it is returned. */
|
|
const affirmDbOpen = function(db){
|
|
if(!db._pDb) toss("DB has been closed.");
|
|
return db;
|
|
};
|
|
|
|
/** Returns true if n is a 32-bit (signed) integer,
|
|
else false. */
|
|
const isInt32 = function(n){
|
|
return (n===n|0 && n<0xFFFFFFFF) ? true : undefined;
|
|
};
|
|
|
|
/**
|
|
Expects to be passed (arguments) from DB.exec() and
|
|
DB.execMulti(). Does the argument processing/validation, throws
|
|
on error, and returns a new object on success:
|
|
|
|
{ sql: the SQL, obt: optionsObj, cbArg: function}
|
|
|
|
cbArg is only set if the opt.callback is 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(args){
|
|
const out = {};
|
|
switch(args.length){
|
|
case 1:
|
|
if('string'===typeof args[0]){
|
|
out.sql = args[0];
|
|
out.opt = {};
|
|
}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: toss("Invalid argument count for exec().");
|
|
};
|
|
if('string'!==typeof out.sql) toss("Missing SQL argument.");
|
|
if(out.opt.callback || out.opt.resultRows){
|
|
switch((undefined===out.opt.rowMode)
|
|
? 'stmt' : out.opt.rowMode) {
|
|
case 'object': out.cbArg = (stmt)=>stmt.get({}); break;
|
|
case 'array': out.cbArg = (stmt)=>stmt.get([]); break;
|
|
case 'stmt': out.cbArg = (stmt)=>stmt; break;
|
|
default: toss("Invalid rowMode:",out.opt.rowMode);
|
|
}
|
|
}
|
|
return out;
|
|
};
|
|
|
|
/** 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)=>
|
|
opts.hasOwnProperty(p) ? opts[p] : dflt;
|
|
|
|
DB.prototype = {
|
|
/**
|
|
Expects to be given an sqlite3 API result code. If it is
|
|
falsy, this function returns this object, else it throws an
|
|
exception with an error message from sqlite3_errmsg(),
|
|
using this object's db handle. 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.
|
|
*/
|
|
checkRc: function(sqliteResultCode){
|
|
if(!sqliteResultCode) return this;
|
|
toss("sqlite result code",sqliteResultCode+":",
|
|
api.sqlite3_errmsg(this._pDb) || "Unknown db error.");
|
|
},
|
|
/**
|
|
Finalizes all open statements and closes this database
|
|
connection. This is a no-op if the db has already been
|
|
closed. If the db is open and alsoUnlink is truthy then the
|
|
this.filename entry in the pseudo-filesystem will also be
|
|
removed (and any error in that attempt is silently
|
|
ignored).
|
|
*/
|
|
close: function(alsoUnlink){
|
|
if(this._pDb){
|
|
let s;
|
|
const that = this;
|
|
Object.keys(this._statements).forEach(function(k,s){
|
|
delete that._statements[k];
|
|
if(s && s._pStmt) s.finalize();
|
|
});
|
|
Object.values(this._udfs).forEach(SQM.removeFunction);
|
|
delete this._udfs;
|
|
delete this._statements;
|
|
api.sqlite3_close_v2(this._pDb);
|
|
delete this._pDb;
|
|
if(this.filename){
|
|
if(alsoUnlink){
|
|
try{SQM.FS.unlink('/'+this.filename);}
|
|
catch(e){/*ignored*/}
|
|
}
|
|
delete this.filename;
|
|
}
|
|
}
|
|
},
|
|
/**
|
|
Similar to this.filename but will return NULL for
|
|
special names like ":memory:". Not of much use until
|
|
we have filesystem support. Throws if the DB has
|
|
been closed. If passed an argument it then it will return
|
|
the filename of the ATTACHEd db with that name, else it assumes
|
|
a name of `main`.
|
|
*/
|
|
fileName: function(dbName){
|
|
return api.sqlite3_db_filename(affirmDbOpen(this)._pDb, dbName||"main");
|
|
},
|
|
/**
|
|
Compiles the given SQL and returns a prepared Stmt. This is
|
|
the only way to create new Stmt objects. Throws on error.
|
|
*/
|
|
prepare: function(sql){
|
|
affirmDbOpen(this);
|
|
setValue(pPtrArg,0,"i32");
|
|
this.checkRc(api.sqlite3_prepare_v2(this._pDb, sql, -1, pPtrArg, null));
|
|
const pStmt = getValue(pPtrArg, "i32");
|
|
if(!pStmt) toss("Empty SQL is not permitted.");
|
|
const stmt = new Stmt(this, pStmt, BindTypes);
|
|
this._statements[pStmt] = stmt;
|
|
return stmt;
|
|
},
|
|
/**
|
|
This function works like execMulti(), and takes most of the
|
|
same arguments, but is more efficient (performs much less
|
|
work) when the input SQL is only a single statement. If
|
|
passed a multi-statement SQL, it only processes the first
|
|
one.
|
|
|
|
This function supports the following additional options not
|
|
supported by execMulti():
|
|
|
|
- .multi: if true, this function acts as a proxy for
|
|
execMulti() and behaves identically to that function.
|
|
|
|
- .resultRows: if this is an array, each row of the result
|
|
set (if any) is appended to it in the format specified
|
|
for the `rowMode` property, with the exception that the
|
|
only legal values for `rowMode` in this case are 'array'
|
|
or 'object', neither of which is the default. 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.
|
|
|
|
- .columnNames: if this is an array and the query has
|
|
result columns, the array is passed to
|
|
Stmt.getColumnNames() to append the column names to it
|
|
(regardless of whether the query produces any result
|
|
rows). If the query has no result columns, this value is
|
|
unchanged.
|
|
|
|
The following options to execMulti() are _not_ supported by
|
|
this method (they are simply ignored):
|
|
|
|
- .saveSql
|
|
*/
|
|
exec: function(/*(sql [,optionsObj]) or (optionsObj)*/){
|
|
affirmDbOpen(this);
|
|
const arg = parseExecArgs(arguments);
|
|
if(!arg.sql) return this;
|
|
else if(arg.opt.multi){
|
|
return this.execMulti(arg, undefined, BindTypes);
|
|
}
|
|
const opt = arg.opt;
|
|
let stmt, rowTarget;
|
|
try {
|
|
if(Array.isArray(opt.resultRows)){
|
|
if(opt.rowMode!=='array' && opt.rowMode!=='object'){
|
|
toss("Invalid rowMode for resultRows array: must",
|
|
"be one of 'array' or 'object'.");
|
|
}
|
|
rowTarget = opt.resultRows;
|
|
}
|
|
stmt = this.prepare(arg.sql);
|
|
if(stmt.columnCount && Array.isArray(opt.columnNames)){
|
|
stmt.getColumnNames(opt.columnNames);
|
|
}
|
|
if(opt.bind) stmt.bind(opt.bind);
|
|
if(opt.callback || rowTarget){
|
|
while(stmt.step()){
|
|
const row = arg.cbArg(stmt);
|
|
if(rowTarget) rowTarget.push(row);
|
|
if(opt.callback){
|
|
stmt._isLocked = true;
|
|
opt.callback(row, stmt);
|
|
stmt._isLocked = false;
|
|
}
|
|
}
|
|
}else{
|
|
stmt.step();
|
|
}
|
|
}finally{
|
|
if(stmt){
|
|
delete stmt._isLocked;
|
|
stmt.finalize();
|
|
}
|
|
}
|
|
return this;
|
|
|
|
}/*exec()*/,
|
|
/**
|
|
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. Returns this
|
|
object. 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).
|
|
|
|
- .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.)
|
|
|
|
- .callback = a function which gets called for each row of
|
|
the FIRST statement in the SQL (if it has any result
|
|
rows). The second argument passed to the callback is
|
|
always the current Stmt object (so that the caller
|
|
may collect column names, or similar). The first
|
|
argument passed to the callback defaults to the current
|
|
Stmt object but may be changed with ...
|
|
|
|
- .rowMode = a string describing what type of argument
|
|
should be passed as the first argument to the callback. A
|
|
value of 'object' causes the results of `stmt.get({})` to
|
|
be passed to the object. A value of 'array' causes the
|
|
results of `stmt.get([])` to be passed to the callback.
|
|
A value of 'stmt' is equivalent to the default, passing
|
|
the current Stmt to the callback (noting that it's always
|
|
passed as the 2nd argument). Any other value triggers an
|
|
exception.
|
|
|
|
- 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.
|
|
|
|
See also the exec() method, which is a close cousin of this
|
|
one.
|
|
|
|
ACHTUNG #1: 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. Routines which are illegal
|
|
in this context will trigger an exception.
|
|
|
|
ACHTUNG #2: The semantics of the `bind` and `callback`
|
|
options may well change or those options may be removed
|
|
altogether for this function (but retained for exec()).
|
|
Generally speaking, neither bind parameters nor a callback
|
|
are generically useful when executing multi-statement SQL.
|
|
*/
|
|
execMulti: function(/*(sql [,obj]) || (obj)*/){
|
|
affirmDbOpen(this);
|
|
const arg = (BindTypes===arguments[2]
|
|
/* ^^^ Being passed on from exec() */
|
|
? arguments[0] : parseExecArgs(arguments));
|
|
if(!arg.sql) return this;
|
|
const opt = arg.opt;
|
|
const stack = stackSave();
|
|
let stmt;
|
|
let bind = opt.bind;
|
|
let rowMode = (
|
|
(opt.callback && opt.rowMode)
|
|
? opt.rowMode : false);
|
|
try{
|
|
let pSql = SQM.allocateUTF8OnStack(arg.sql)
|
|
const pzTail = stackAlloc(4);
|
|
while(getValue(pSql, "i8")){
|
|
setValue(pPtrArg, 0, "i32");
|
|
setValue(pzTail, 0, "i32");
|
|
this.checkRc(api.sqlite3_prepare_v2_sqlptr(
|
|
this._pDb, pSql, -1, pPtrArg, pzTail
|
|
));
|
|
const pStmt = getValue(pPtrArg, "i32");
|
|
pSql = getValue(pzTail, "i32");
|
|
if(!pStmt) continue;
|
|
if(opt.saveSql){
|
|
opt.saveSql.push(api.sqlite3_sql(pStmt).trim());
|
|
}
|
|
stmt = new Stmt(this, pStmt, BindTypes);
|
|
if(bind && stmt.parameterCount){
|
|
stmt.bind(bind);
|
|
bind = null;
|
|
}
|
|
if(opt.callback && null!==rowMode){
|
|
while(stmt.step()){
|
|
stmt._isLocked = true;
|
|
callback(arg.cbArg(stmt), stmt);
|
|
stmt._isLocked = false;
|
|
}
|
|
rowMode = null;
|
|
}else{
|
|
// Do we need to while(stmt.step()){} here?
|
|
stmt.step();
|
|
}
|
|
stmt.finalize();
|
|
stmt = null;
|
|
}
|
|
}finally{
|
|
if(stmt){
|
|
delete stmt._isLocked;
|
|
stmt.finalize();
|
|
}
|
|
stackRestore(stack);
|
|
}
|
|
return this;
|
|
}/*execMulti()*/,
|
|
/**
|
|
Creates a new scalar 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. In the final
|
|
case, the function's name must be the 'name' property.
|
|
|
|
This can only be used to create scalar functions, not
|
|
aggregate or window functions. UDFs cannot be removed from
|
|
a DB handle after they're added.
|
|
|
|
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. Some freedom is afforded
|
|
to numeric conversions due to friction between the JS and C
|
|
worlds: integers which are larger than 32 bits will be
|
|
treated as doubles, as JS does not support 64-bit integers
|
|
and it is (as of this writing) illegal to use WASM
|
|
functions which take or return 64-bit integers from JS.
|
|
|
|
The optional 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 the
|
|
callback's length property (i.e. the number of declared
|
|
parameters it has). A value of -1 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 following properties correspond to flags documented at:
|
|
|
|
https://sqlite.org/c3ref/create_function.html
|
|
|
|
- .deterministic = SQLITE_DETERMINISTIC
|
|
- .directOnly = SQLITE_DIRECTONLY
|
|
- .innocuous = SQLITE_INNOCUOUS
|
|
|
|
|
|
Maintenance reminder: the ability to add new
|
|
WASM-accessible functions to the runtime requires that the
|
|
WASM build is compiled with emcc's `-sALLOW_TABLE_GROWTH`
|
|
flag.
|
|
*/
|
|
createFunction: function f(name, callback,opt){
|
|
switch(arguments.length){
|
|
case 1: /* (optionsObject) */
|
|
opt = name;
|
|
name = opt.name;
|
|
callback = opt.callback;
|
|
break;
|
|
case 2: /* (name, callback|optionsObject) */
|
|
if(!(callback instanceof Function)){
|
|
opt = callback;
|
|
callback = opt.callback;
|
|
}
|
|
break;
|
|
default: break;
|
|
}
|
|
if(!opt) opt = {};
|
|
if(!(callback instanceof Function)){
|
|
toss("Invalid arguments: expecting a callback function.");
|
|
}else if('string' !== typeof name){
|
|
toss("Invalid arguments: missing function name.");
|
|
}
|
|
if(!f._extractArgs){
|
|
/* Static init */
|
|
f._extractArgs = function(argc, pArgv){
|
|
let i, pVal, valType, arg;
|
|
const tgt = [];
|
|
for(i = 0; i < argc; ++i){
|
|
pVal = getValue(pArgv + (4 * i), "i32");
|
|
valType = api.sqlite3_value_type(pVal);
|
|
switch(valType){
|
|
case api.SQLITE_INTEGER:
|
|
case api.SQLITE_FLOAT:
|
|
arg = api.sqlite3_value_double(pVal);
|
|
break;
|
|
case SQLITE_TEXT:
|
|
arg = api.sqlite3_value_text(pVal);
|
|
break;
|
|
case SQLITE_BLOB:{
|
|
const n = api.sqlite3_value_bytes(ptr);
|
|
const pBlob = api.sqlite3_value_blob(ptr);
|
|
arg = new Uint8Array(n);
|
|
let i;
|
|
for(i = 0; i < n; ++i) arg[i] = HEAP8[pBlob+i];
|
|
break;
|
|
}
|
|
default:
|
|
arg = null; break;
|
|
}
|
|
tgt.push(arg);
|
|
}
|
|
return tgt;
|
|
}/*_extractArgs()*/;
|
|
f._setResult = function(pCx, val){
|
|
switch(typeof val) {
|
|
case 'boolean':
|
|
api.sqlite3_result_int(pCx, val ? 1 : 0);
|
|
break;
|
|
case 'number': {
|
|
(isInt32(val)
|
|
? api.sqlite3_result_int
|
|
: api.sqlite3_result_double)(pCx, val);
|
|
break;
|
|
}
|
|
case 'string':
|
|
api.sqlite3_result_text(pCx, val, -1,
|
|
-1/*==SQLITE_TRANSIENT*/);
|
|
break;
|
|
case 'object':
|
|
if(null===val) {
|
|
api.sqlite3_result_null(pCx);
|
|
break;
|
|
}else if(undefined!==val.length){
|
|
const pBlob =
|
|
SQM.allocate(val, SQM.ALLOC_NORMAL);
|
|
api.sqlite3_result_blob(pCx, pBlob, val.length, -1/*==SQLITE_TRANSIENT*/);
|
|
SQM._free(blobptr);
|
|
break;
|
|
}
|
|
// else fall through
|
|
default:
|
|
toss("Don't not how to handle this UDF result value:",val);
|
|
};
|
|
}/*_setResult()*/;
|
|
}/*static init*/
|
|
const wrapper = function(pCx, argc, pArgv){
|
|
try{
|
|
f._setResult(pCx, callback.apply(null, f._extractArgs(argc, pArgv)));
|
|
}catch(e){
|
|
api.sqlite3_result_error(pCx, e.message, -1);
|
|
}
|
|
};
|
|
const pUdf = SQM.addFunction(wrapper, "viii");
|
|
let fFlags = 0;
|
|
if(getOwnOption(opt, 'deterministic')) fFlags |= api.SQLITE_DETERMINISTIC;
|
|
if(getOwnOption(opt, 'directOnly')) fFlags |= api.SQLITE_DIRECTONLY;
|
|
if(getOwnOption(opt, 'innocuous')) fFlags |= api.SQLITE_INNOCUOUS;
|
|
name = name.toLowerCase();
|
|
try {
|
|
this.checkRc(api.sqlite3_create_function_v2(
|
|
this._pDb, name,
|
|
(opt.hasOwnProperty('arity') ? +opt.arity : callback.length),
|
|
api.SQLITE_UTF8 | fFlags, null/*pApp*/, pUdf,
|
|
null/*xStep*/, null/*xFinal*/, null/*xDestroy*/));
|
|
}catch(e){
|
|
SQM.removeFunction(pUdf);
|
|
throw e;
|
|
}
|
|
if(this._udfs.hasOwnProperty(name)){
|
|
SQM.removeFunction(this._udfs[name]);
|
|
}
|
|
this._udfs[name] = pUdf;
|
|
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. Throws on error (e.g. malformed
|
|
SQL).
|
|
*/
|
|
selectValue: function(sql,bind){
|
|
let stmt, rc;
|
|
try {
|
|
stmt = this.prepare(sql).bind(bind);
|
|
if(stmt.step()) rc = stmt.get(0);
|
|
}finally{
|
|
if(stmt) stmt.finalize();
|
|
}
|
|
return rc;
|
|
},
|
|
|
|
/**
|
|
Exports a copy of this db's file as a Uint8Array and
|
|
returns it. It is technically not legal to call this while
|
|
any prepared statement are currently active because,
|
|
depending on the platform, it might not be legal to read
|
|
the db while a statement is locking it. Throws if this db
|
|
is not open or has any opened statements.
|
|
|
|
The resulting buffer can be passed to this class's
|
|
constructor to restore the DB.
|
|
|
|
Maintenance reminder: the corresponding sql.js impl of this
|
|
feature closes the current db, finalizing any active
|
|
statements and (seemingly unnecessarily) destroys any UDFs,
|
|
copies the file, and then re-opens it (without restoring
|
|
the UDFs). Those gymnastics are not necessary on the tested
|
|
platform but might be necessary on others. Because of that
|
|
eventuality, this interface currently enforces that no
|
|
statements are active when this is run. It will throw if
|
|
any are.
|
|
*/
|
|
exportBinaryImage: function(){
|
|
affirmDbOpen(this);
|
|
if(Object.keys(this._statements).length){
|
|
toss("Cannot export with prepared statements active!",
|
|
"finalize() all statements and try again.");
|
|
}
|
|
return FS.readFile(this.filename, {encoding:"binary"});
|
|
}
|
|
}/*DB.prototype*/;
|
|
|
|
|
|
/** Throws if the given Stmt has been finalized, else stmt is
|
|
returned. */
|
|
const affirmStmtOpen = function(stmt){
|
|
if(!stmt._pStmt) toss("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;
|
|
default:
|
|
if(v instanceof Uint8Array) return BindTypes.blob;
|
|
return undefined;
|
|
}
|
|
};
|
|
|
|
/**
|
|
If isSupportedBindType(v) returns a truthy value, this
|
|
function returns that value, else it throws.
|
|
*/
|
|
const affirmSupportedBindType = function(v){
|
|
return isSupportedBindType(v) || toss("Unsupport bind() argument type.");
|
|
};
|
|
|
|
/**
|
|
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 : api.sqlite3_bind_parameter_index(stmt._pStmt, key);
|
|
if(0===n || (n===key && (n!==(n|0)/*floating point*/))){
|
|
toss("Invalid bind() parameter name: "+key);
|
|
}
|
|
else if(n<1 || n>stmt.parameterCount) toss("Bind index",key,"is out of range.");
|
|
return n;
|
|
};
|
|
|
|
/** 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.
|
|
*/
|
|
const affirmColIndex = function(stmt,ndx){
|
|
if((ndx !== (ndx|0)) || ndx<0 || ndx>=stmt.columnCount){
|
|
toss("Column index",ndx,"is out of range.");
|
|
}
|
|
return stmt;
|
|
};
|
|
|
|
/**
|
|
If stmt._isLocked 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 affirmUnlocked = function(stmt,currentOpName){
|
|
if(stmt._isLocked){
|
|
toss("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){
|
|
affirmUnlocked(stmt, 'bind()');
|
|
if(!f._){
|
|
f._ = {
|
|
string: function(stmt, ndx, val, asBlob){
|
|
const bytes = intArrayFromString(val,true);
|
|
const pStr = SQM.allocate(bytes, ALLOC_NORMAL);
|
|
stmt._allocs.push(pStr);
|
|
const func = asBlob ? api.sqlite3_bind_blob : api.sqlite3_bind_text;
|
|
return func(stmt._pStmt, ndx, pStr, bytes.length, 0);
|
|
}
|
|
};
|
|
}
|
|
affirmSupportedBindType(val);
|
|
ndx = affirmParamIndex(stmt,ndx);
|
|
let rc = 0;
|
|
switch((null===val || undefined===val) ? BindTypes.null : bindType){
|
|
case BindTypes.null:
|
|
rc = api.sqlite3_bind_null(stmt._pStmt, ndx);
|
|
break;
|
|
case BindTypes.string:{
|
|
rc = f._.string(stmt, ndx, val, false);
|
|
break;
|
|
}
|
|
case BindTypes.number: {
|
|
const m = (isInt32(val)
|
|
? api.sqlite3_bind_int
|
|
/*It's illegal to bind a 64-bit int
|
|
from here*/
|
|
: api.sqlite3_bind_double);
|
|
rc = m(stmt._pStmt, ndx, val);
|
|
break;
|
|
}
|
|
case BindTypes.boolean:
|
|
rc = api.sqlite3_bind_int(stmt._pStmt, ndx, val ? 1 : 0);
|
|
break;
|
|
case BindTypes.blob: {
|
|
if('string'===typeof val){
|
|
rc = f._.string(stmt, ndx, val, true);
|
|
}else{
|
|
const len = val.length;
|
|
if(undefined===len){
|
|
toss("Binding a value as a blob requires",
|
|
"that it have a length member.");
|
|
}
|
|
const pBlob = SQM.allocate(val, ALLOC_NORMAL);
|
|
stmt._allocs.push(pBlob);
|
|
rc = api.sqlite3_bind_blob(stmt._pStmt, ndx, pBlob, len, 0);
|
|
}
|
|
}
|
|
default: toss("Unsupported bind() argument type.");
|
|
}
|
|
if(rc) stmt.db.checkRc(rc);
|
|
return stmt;
|
|
};
|
|
|
|
/** Frees any memory explicitly allocated for the given
|
|
Stmt object. Returns stmt. */
|
|
const freeBindMemory = function(stmt){
|
|
let m;
|
|
while(undefined !== (m = stmt._allocs.pop())){
|
|
SQM._free(m);
|
|
}
|
|
return stmt;
|
|
};
|
|
|
|
Stmt.prototype = {
|
|
/**
|
|
"Finalizes" this statement. This is a no-op if the
|
|
statement has already been finalizes. Returns
|
|
undefined. Most methods in this class will throw if called
|
|
after this is.
|
|
*/
|
|
finalize: function(){
|
|
if(this._pStmt){
|
|
affirmUnlocked(this,'finalize()');
|
|
freeBindMemory(this);
|
|
delete this.db._statements[this._pStmt];
|
|
api.sqlite3_finalize(this._pStmt);
|
|
delete this.columnCount;
|
|
delete this.parameterCount;
|
|
delete this._pStmt;
|
|
delete this.db;
|
|
delete this._isLocked;
|
|
}
|
|
},
|
|
/** Clears all bound values. Returns this object.
|
|
Throws if this statement has been finalized. */
|
|
clearBindings: function(){
|
|
freeBindMemory(
|
|
affirmUnlocked(affirmStmtOpen(this), 'clearBindings()')
|
|
);
|
|
api.sqlite3_clear_bindings(this._pStmt);
|
|
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 passed a truthy argument then this.clearBindings() is
|
|
also called, otherwise any existing bindings, along with
|
|
any memory allocated for them, are retained.
|
|
*/
|
|
reset: function(alsoClearBinds){
|
|
affirmUnlocked(this,'reset()');
|
|
if(alsoClearBinds) this.clearBindings();
|
|
api.sqlite3_reset(affirmStmtOpen(this)._pStmt);
|
|
this._mayGet = false;
|
|
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. (It is,
|
|
as of this writing, illegal to call (from JS) a WASM
|
|
function which either takes or returns an int64.)
|
|
Booleans are bound as integer 0 or 1. It is not expected
|
|
the distinction of binding doubles which have no
|
|
fractional parts is integers is significant for the
|
|
majority of clients due to sqlite3's data typing
|
|
model. This API does not currently support the BigInt
|
|
type.
|
|
|
|
- Strings are bound as strings (use bindAsBlob() to force
|
|
blob binding).
|
|
|
|
- Uint8Array 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.
|
|
|
|
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: toss("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){
|
|
toss("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){
|
|
toss("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('object'===typeof arg/*null was checked above*/){
|
|
/* bind by name */
|
|
if(1!==arguments.length){
|
|
toss("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);
|
|
}
|
|
toss("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,
|
|
Uint8Array, or null/undefined (both treated as null).
|
|
|
|
If passed a single argument, a bind index of 1 is assumed.
|
|
*/
|
|
bindAsBlob: function(ndx,arg){
|
|
affirmStmtOpen(this);
|
|
if(1===arguments.length){
|
|
ndx = 1;
|
|
arg = arguments[0];
|
|
}
|
|
const t = affirmSupportedBindType(arg);
|
|
if(BindTypes.string !== t && BindTypes.blob !== t
|
|
&& BindTypes.null !== t){
|
|
toss("Invalid value type for bindAsBlob()");
|
|
}
|
|
this._mayGet = false;
|
|
return bindOne(this, ndx, BindTypes.blob, arg);
|
|
},
|
|
/**
|
|
Steps the statement one time. If the result indicates that
|
|
a row of data is available, true is returned. If no row of
|
|
data is available, false is returned. Throws on error.
|
|
*/
|
|
step: function(){
|
|
affirmUnlocked(this, 'step()');
|
|
const rc = api.sqlite3_step(affirmStmtOpen(this)._pStmt);
|
|
switch(rc){
|
|
case api.SQLITE_DONE: return this._mayGet = false;
|
|
case api.SQLITE_ROW: return this._mayGet = true;
|
|
default:
|
|
this._mayGet = false;
|
|
console.warn("sqlite3_step() rc=",rc,"SQL =",
|
|
api.sqlite3_sql(this._pStmt));
|
|
this.db.checkRc(rc);
|
|
};
|
|
},
|
|
/**
|
|
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 arugment, 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.
|
|
|
|
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){
|
|
toss("Stmt.step() has not (recently) returned true.");
|
|
}
|
|
if(Array.isArray(ndx)){
|
|
let i = 0;
|
|
while(i<this.columnCount){
|
|
ndx[i] = this.get(i++);
|
|
}
|
|
return ndx;
|
|
}else if(ndx && 'object'===typeof ndx){
|
|
let i = 0;
|
|
while(i<this.columnCount){
|
|
ndx[api.sqlite3_column_name(this._pStmt,i)] = this.get(i++);
|
|
}
|
|
return ndx;
|
|
}
|
|
affirmColIndex(this, ndx);
|
|
switch(undefined===asType
|
|
? api.sqlite3_column_type(this._pStmt, ndx)
|
|
: asType){
|
|
case api.SQLITE_NULL: return null;
|
|
case api.SQLITE_INTEGER:{
|
|
return 0 | api.sqlite3_column_double(this._pStmt, ndx);
|
|
/* ^^^^^^^^ strips any fractional part and handles
|
|
handles >32bits */
|
|
}
|
|
case api.SQLITE_FLOAT:
|
|
return api.sqlite3_column_double(this._pStmt, ndx);
|
|
case api.SQLITE_TEXT:
|
|
return api.sqlite3_column_text(this._pStmt, ndx);
|
|
case api.SQLITE_BLOB: {
|
|
const n = api.sqlite3_column_bytes(this._pStmt, ndx);
|
|
const ptr = api.sqlite3_column_blob(this._pStmt, ndx);
|
|
const rc = new Uint8Array(n);
|
|
for(let i = 0; i < n; ++i) rc[i] = HEAP8[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: toss("Don't know how to translate",
|
|
"type of result column #"+ndx+".");
|
|
}
|
|
abort("Not reached.");
|
|
},
|
|
/** Equivalent to get(ndx) but coerces the result to an
|
|
integer. */
|
|
getInt: function(ndx){return this.get(ndx,api.SQLITE_INTEGER)},
|
|
/** Equivalent to get(ndx) but coerces the result to a
|
|
float. */
|
|
getFloat: function(ndx){return this.get(ndx,api.SQLITE_FLOAT)},
|
|
/** Equivalent to get(ndx) but coerces the result to a
|
|
string. */
|
|
getString: function(ndx){return this.get(ndx,api.SQLITE_TEXT)},
|
|
/** Equivalent to get(ndx) but coerces the result to a
|
|
Uint8Array. */
|
|
getBlob: function(ndx){return this.get(ndx,api.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, api.SQLITE_STRING);
|
|
return null===s ? s : JSON.parse(s);
|
|
},
|
|
/**
|
|
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 api.sqlite3_column_name(
|
|
affirmColIndex(affirmStmtOpen(this),ndx)._pStmt, 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 member
|
|
holds the number of columns.
|
|
*/
|
|
getColumnNames: function(tgt){
|
|
affirmColIndex(affirmStmtOpen(this),0);
|
|
if(!tgt) tgt = [];
|
|
for(let i = 0; i < this.columnCount; ++i){
|
|
tgt.push(api.sqlite3_column_name(this._pStmt, 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
|
|
? api.sqlite3_bind_parameter_index(this._pStmt, name)
|
|
: undefined);
|
|
}
|
|
}/*Stmt.prototype*/;
|
|
|
|
/** OO binding's namespace. */
|
|
const SQLite3 = {
|
|
version: {
|
|
lib: api.sqlite3_libversion(),
|
|
ooApi: "0.0.1"
|
|
},
|
|
DB,
|
|
Stmt,
|
|
/**
|
|
Reports info about compile-time options. It has several
|
|
distinct uses:
|
|
|
|
If optName is an array then it is expected to be a list of
|
|
compilation options and this function returns an object
|
|
which maps each such option to true or false, indicating
|
|
whether or not the given option was included in this
|
|
build. That object is returned.
|
|
|
|
If optName is an object, its keys are expected to be
|
|
compilation options and this function sets each entry to
|
|
true or false. That object is returned.
|
|
|
|
If passed no arguments then it returns an object mapping
|
|
all known compilation options to their compile-time values,
|
|
or boolean true if they are defined with no value.
|
|
|
|
In all other cases it returns true if the given option was
|
|
active when when compiling the sqlite3 module, else false.
|
|
|
|
Compile-time option names may optionally include their
|
|
"SQLITE_" prefix. When it returns an object of all options,
|
|
the prefix is elided.
|
|
*/
|
|
compileOptionUsed: function f(optName){
|
|
if(!arguments.length){
|
|
if(!f._opt){
|
|
f._rx = /^([^=]+)=(.+)/;
|
|
f._rxInt = /^-?\d+$/;
|
|
f._opt = function(opt, rv){
|
|
const m = f._rx.exec(opt);
|
|
rv[0] = (m ? m[1] : opt);
|
|
rv[1] = m ? (f._rxInt.test(m[2]) ? +m[2] : m[2]) : true;
|
|
};
|
|
}
|
|
const rc = {}, ov = [0,0];
|
|
let i = 0, k;
|
|
while((k = api.sqlite3_compileoption_get(i++))){
|
|
f._opt(k,ov);
|
|
rc[ov[0]] = ov[1];
|
|
}
|
|
return rc;
|
|
}
|
|
else if(Array.isArray(optName)){
|
|
const rc = {};
|
|
optName.forEach((v)=>{
|
|
rc[v] = api.sqlite3_compileoption_used(v);
|
|
});
|
|
return rc;
|
|
}
|
|
else if('object' === typeof optName){
|
|
Object.keys(optName).forEach((k)=> {
|
|
optName[k] = api.sqlite3_compileoption_used(k);
|
|
});
|
|
return optName;
|
|
}
|
|
return (
|
|
'string'===typeof optName
|
|
) ? !!api.sqlite3_compileoption_used(optName) : false;
|
|
}
|
|
}/*SQLite3 object*/;
|
|
|
|
namespace.sqlite3 = {
|
|
api: api,
|
|
SQLite3
|
|
};
|
|
|
|
if(self === self.window){
|
|
/* This is running in the main window thread, so we're done. */
|
|
setTimeout(()=>postMessage({type:'sqlite3-api',data:'loaded'}), 0);
|
|
return;
|
|
}
|
|
/******************************************************************
|
|
End of main window thread. What follows is only intended for use
|
|
in Worker threads.
|
|
******************************************************************/
|
|
|
|
/*
|
|
UNDER CONSTRUCTION
|
|
|
|
We need an API which can proxy the DB API via a Worker message
|
|
interface. The primary quirky factor in such an API is that we
|
|
cannot pass callback functions between the window thread and a
|
|
worker thread, so we have to receive all db results via
|
|
asynchronous message-passing.
|
|
|
|
Certain important considerations here include:
|
|
|
|
- Support only one db connection or multiple? The former is far
|
|
easier, but there's always going to be a user out there who
|
|
wants to juggle six database handles at once. Do we add that
|
|
complexity or tell such users to write their own code using
|
|
the provided lower-level APIs?
|
|
|
|
- Fetching multiple results: do we pass them on as a series of
|
|
messages, with start/end messages on either end, or do we
|
|
collect all results and bundle them back in a single message?
|
|
The former is, generically speaking, more memory-efficient but
|
|
the latter far easier to implement in this environment. The
|
|
latter is untennable for large data sets. Despite a web page
|
|
hypothetically being a relatively limited environment, there
|
|
will always be those users who feel that they should/need to
|
|
be able to work with multi-hundred-meg (or larger) blobs, and
|
|
passing around arrays of those may quickly exhaust the JS
|
|
engine's memory.
|
|
|
|
TODOs include, but are not limited to:
|
|
|
|
- The ability to manage multiple DB handles. This can
|
|
potentially be done via a simple mapping of DB.filename or
|
|
DB._pDb (`sqlite3*` handle) to DB objects. The open()
|
|
interface would need to provide an ID (probably DB._pDb) back
|
|
to the user which can optionally be passed as an argument to
|
|
the other APIs (they'd default to the first-opened DB, for
|
|
ease of use). Client-side usability of this feature would
|
|
benefit from making another wrapper class (or a singleton)
|
|
available to the main thread, with that object proxying all(?)
|
|
communication with the worker.
|
|
|
|
- Revisit how virtual files are managed. We currently delete DBs
|
|
from the virtual filesystem when we close them, for the sake
|
|
of saving memory (the VFS lives in RAM). Supporting multiple
|
|
DBs may require that we give up that habit. Similarly, fully
|
|
supporting ATTACH, where a user can upload multiple DBs and
|
|
ATTACH them, also requires the that we manage the VFS entries
|
|
better. As of this writing, ATTACH will fail fatally in the
|
|
fiddle app (but not the lower-level APIs) because it runs in
|
|
safe mode, where ATTACH is disabled.
|
|
*/
|
|
|
|
/**
|
|
Helper for managing Worker-level state.
|
|
*/
|
|
const wState = {
|
|
db: undefined,
|
|
open: function(arg){
|
|
if(!arg && this.db) return this.db;
|
|
else if(this.db) this.db.close();
|
|
return this.db = (Array.isArray(arg) ? new DB(...arg) : new DB(arg));
|
|
},
|
|
close: function(alsoUnlink){
|
|
if(this.db){
|
|
this.db.close(alsoUnlink);
|
|
this.db = undefined;
|
|
}
|
|
},
|
|
affirmOpen: function(){
|
|
return this.db || toss("DB is not opened.");
|
|
},
|
|
post: function(type,data,xferList){
|
|
if(xferList){
|
|
self.postMessage({type, data},xferList);
|
|
xferList.length = 0;
|
|
}else{
|
|
self.postMessage({type, data});
|
|
}
|
|
}
|
|
};
|
|
|
|
/**
|
|
A level of "organizational abstraction" for the Worker
|
|
API. Each method in this object must map directly to a Worker
|
|
message type key. The onmessage() dispatcher attempts to
|
|
dispatch all inbound messages to a method of this object,
|
|
passing it the event.data part of the inbound event object. All
|
|
methods must return a plain Object containing any response
|
|
state, which the dispatcher may amend. All methods must throw
|
|
on error.
|
|
*/
|
|
const wMsgHandler = {
|
|
xfer: [/*Temp holder for "transferable" postMessage() state.*/],
|
|
/**
|
|
Proxy for DB.exec() which expects a single argument of type
|
|
string (SQL to execute) or an options object in the form
|
|
expected by exec(). The notable differences from exec()
|
|
include:
|
|
|
|
- The default value for options.rowMode is 'array' because
|
|
the normal default cannot cross the window/Worker boundary.
|
|
|
|
- A function-type options.callback property cannot cross
|
|
the window/Worker boundary, so is not useful here. If
|
|
options.callback is a string then it is assumed to be a
|
|
message type key, in which case a callback function will be
|
|
applied which posts each row result via:
|
|
|
|
postMessage({type: thatKeyType, data: theRow})
|
|
|
|
And, at the end of the result set (whether or not any
|
|
result rows were produced), it will post an identical
|
|
message with data:null to alert the caller than the result
|
|
set is completed.
|
|
|
|
The callback proxy must not recurse into this interface, or
|
|
results are undefined. (It hypothetically cannot recurse
|
|
because an exec() call will be tying up the Worker thread,
|
|
causing any recursion attempt to wait until the first
|
|
exec() is completed.)
|
|
|
|
The response is the input options object (or a synthesized
|
|
one if passed only a string), noting that
|
|
options.resultRows and options.columnNames may be populated
|
|
by the call to exec().
|
|
|
|
This opens/creates the Worker's db if needed.
|
|
*/
|
|
exec: function(ev){
|
|
const opt = (
|
|
'string'===typeof ev.data
|
|
) ? {sql: ev.data} : (ev.data || {});
|
|
if(!opt.rowMode){
|
|
/* Since the default rowMode of 'stmt' is not useful
|
|
for the Worker interface, we'll default to
|
|
something else. */
|
|
opt.rowMode = 'array';
|
|
}else if('stmt'===opt.rowMode){
|
|
toss("Invalid rowMode for exec(): stmt mode",
|
|
"does not work in the Worker API.");
|
|
}
|
|
const db = wState.open();
|
|
if(opt.callback || opt.resultRows instanceof Array){
|
|
// Part of a copy-avoidance optimization for blobs
|
|
db._blobXfer = this.xfer;
|
|
}
|
|
const callbackMsgType = opt.callback;
|
|
if('string' === typeof callbackMsgType){
|
|
const that = this;
|
|
opt.callback =
|
|
(row)=>wState.post(callbackMsgType,row,this.xfer);
|
|
}
|
|
try {
|
|
db.exec(opt);
|
|
if(opt.callback instanceof Function){
|
|
opt.callback = callbackMsgType;
|
|
wState.post(callbackMsgType, null);
|
|
}
|
|
}finally{
|
|
delete db._blobXfer;
|
|
if('string'===typeof callbackMsgType){
|
|
opt.callback = callbackMsgType;
|
|
}
|
|
}
|
|
return opt;
|
|
}/*exec()*/,
|
|
/**
|
|
Proxy for DB.exportBinaryImage(). Throws if the db has not
|
|
been opened. Response is an object:
|
|
|
|
{
|
|
buffer: Uint8Array (db file contents),
|
|
filename: the current db filename,
|
|
mimetype: string
|
|
}
|
|
*/
|
|
export: function(ev){
|
|
const db = wState.affirmOpen();
|
|
const response = {
|
|
buffer: db.exportBinaryImage(),
|
|
filename: db.filename,
|
|
mimetype: 'application/x-sqlite3'
|
|
};
|
|
this.xfer.push(response.buffer.buffer);
|
|
return response;
|
|
}/*export()*/,
|
|
/**
|
|
Proxy for the DB constructor. Expects to be passed a single
|
|
object or a falsy value to use defaults. The object may
|
|
have a filename property to name the db file (see the DB
|
|
constructor for peculiarities and transformations) and/or a
|
|
buffer property (a Uint8Array holding a complete database
|
|
file's contents). The response is an object:
|
|
|
|
{
|
|
filename: db filename (possibly differing from the input)
|
|
}
|
|
|
|
If the Worker's db is currently opened, this call closes it
|
|
before proceeding.
|
|
*/
|
|
open: function(ev){
|
|
wState.close(/*true???*/);
|
|
const args = [], data = (ev.data || {});
|
|
if(data.filename) args.push(data.filename);
|
|
if(data.buffer){
|
|
args.push(data.buffer);
|
|
this.xfer.push(data.buffer.buffer);
|
|
}
|
|
const db = wState.open(args);
|
|
return {filename: db.filename};
|
|
},
|
|
/**
|
|
Proxy for DB.close(). If ev.data may either be a boolean or
|
|
an object with an `unlink` property. If that value is
|
|
truthy then the db file (if the db is currently open) will
|
|
be unlinked from the virtual filesystem, else it will be
|
|
kept intact. The response object is:
|
|
|
|
{filename: db filename _if_ the db is is opened when this
|
|
is called, else the undefined value
|
|
}
|
|
*/
|
|
close: function(ev){
|
|
const response = {
|
|
filename: wState.db && wState.db.filename
|
|
};
|
|
if(wState.db){
|
|
wState.close(!!(ev.data && 'object'===typeof ev.data)
|
|
? ev.data.unlink : ev.data);
|
|
}
|
|
return response;
|
|
}
|
|
}/*wMsgHandler*/;
|
|
|
|
/**
|
|
UNDER CONSTRUCTION!
|
|
|
|
A subset of the DB API is accessible via Worker messages in the form:
|
|
|
|
{ type: apiCommand,
|
|
data: apiArguments }
|
|
|
|
As a rule, these commands respond with a postMessage() of their
|
|
own in the same form, but will, if needed, transform the `data`
|
|
member to an object and may add state to it. The responses
|
|
always have an object-format `data` part. If the inbound `data`
|
|
is an object which has a `messageId` property, that property is
|
|
always mirrored in the result object, for use in client-side
|
|
dispatching of these asynchronous results. Exceptions thrown
|
|
during processing result in an `error`-type event with a
|
|
payload in the form:
|
|
|
|
{
|
|
message: error string,
|
|
errorClass: class name of the error type,
|
|
input: ev.data,
|
|
[messageId: if set in the inbound message]
|
|
}
|
|
|
|
The individual APIs are documented in the wMsgHandler object.
|
|
*/
|
|
self.onmessage = function(ev){
|
|
ev = ev.data;
|
|
let response, evType = ev.type;
|
|
try {
|
|
if(wMsgHandler.hasOwnProperty(evType) &&
|
|
wMsgHandler[evType] instanceof Function){
|
|
response = wMsgHandler[evType](ev);
|
|
}else{
|
|
toss("Unknown db worker message type:",ev.type);
|
|
}
|
|
}catch(err){
|
|
evType = 'error';
|
|
response = {
|
|
message: err.message,
|
|
errorClass: err.name,
|
|
input: ev
|
|
};
|
|
}
|
|
if(!response.messageId && ev.data
|
|
&& 'object'===typeof ev.data && ev.data.messageId){
|
|
response.messageId = ev.data.messageId;
|
|
}
|
|
wState.post(evType, response, wMsgHandler.xfer);
|
|
};
|
|
|
|
setTimeout(()=>postMessage({type:'sqlite3-api',data:'loaded'}), 0);
|
|
});
|