Cleaner, more idiomatic init code and API

[josephrocca]

(Note: This is mainly in the interest of this project being more widely known and used, since it's easy to create my own wrappers and stuff now that I know what's going on. I just want the work done by the contributors here to be as valued as it should be. Thanks for all your efforts on this!)

Here's an example from the readme for initializing this lib:

import sqlite3InitModule from '@sqlite.org/sqlite-wasm';

const log = (...args) => console.log(...args);
const error = (...args) => console.error(...args);

const start = function (sqlite3) {
  log('Running SQLite3 version', sqlite3.version.libVersion);
  const db = new sqlite3.oo1.DB('/mydb.sqlite3', 'ct');
  // Your SQLite code here.
};

log('Loading and initializing SQLite3 module...');
sqlite3InitModule({
  print: log,
  printErr: error,
}).then((sqlite3) => {
  try {
    log('Done initializing. Running demo...');
    start(sqlite3);
  } catch (err) {
    error(err.name, err.message);
  }
});

This looks a bit scary and unusual in terms of code structure. I think this code example should be restructured to something like this:

import init from '@sqlite.org/sqlite-wasm';
const sqlite3 = await init({ print: console.log, printErr: console.error });
console.log('Running SQLite3 version', sqlite3.version.libVersion);

let db = new sqlite3.oo1.DB('/mydb.sqlite3', 'ct');
// Your SQLite code here.

And it'd also be worth mentioning after that code block that this import can be used directly in the browser to get up and running quickly:

import init from "https://cdn.jsdelivr.net/npm/@sqlite.org/sqlite-wasm@3.45.1-build1/index.mjs";

The PGlite repo is a great analogous example of how to create a developer-friendly readme, and it also highlights another point that I think is worth considering to make the sqlite team's work more broadly used:

import { PGlite } from "@electric-sql/pglite"

const db = new PGlite()
await db.query("select 'Hello world' as message;")
// -> [ { message: "Hello world" } ]

Is there anything fundamentally stopping this repo from having a wrapper that's similarly straightforward? The print/printErr can use console.log/error by default, and a wrapper can me made such that the first async interaction with the DB first waits for the DB to finish init (which it started doing during the sync constructor call).

[tomayac]

I don't disagree… Would you be willing to contribute a PR that showcases usage for all three options? Top-level await may be a problem, too.

[sgbeal]

Caveat:

init({ print: console.log, printErr: console.error });

that part is Emscripten-dependent and we very specifically do not document what flags Emscripten may or may not take. They may change at any time (and have changed in incompatible ways since the sqlite/wasm effort was started) and are 100% unsupported, so you'll never find any mention of them in any docs found on sqlite.org/wasm. We hope that someday Emscripten will have a competitor, and if that ever happens then any arguments passed to the library init function for such builds will almost certainly work differently.

[tomayac]

This is documented as Module.print and Module.printErr respectively.

[sgbeal]

My point is only that we do not/cannot guaranty that those flags will stay working that way for the rest of history. Emscripten does make incompatible changes from time to time, e.g. i just applied a patch for an incompatible change in v3.1.55 today. Those flags are part of 3rd-party code, part of a leaky abstraction which we unfortunately have no control over so we don't ever mention them in any of the "official" docs.

[josephrocca]

Would you be willing to contribute a PR that showcases usage for all three options?

I'm actually kind of stumped at what's even happening with in that sqlite3Worker1Promiser/promiser/_promiser code. Is it not feasible to packaging that all into the init function, so that the only difference is a useWorker option in the init options?

[josephrocca]

My point is only that we do not/cannot guaranty that those flags will stay working that way for the rest of history

It'd be pretty easy to just add print and printErr options as part of the init config, and route them to the new names, optionally with a deprecation warning that they'd be removed in 4.x (or whatever). Not a big deal at all imo. They're already documented in the readme so the ship has sailed on removing them in 3.x, even if emscripten did change something soon.

[tomayac]

Friendly ping. My comment from March 4 (#63 (comment)) still stands. Are you still interested in this? @josephrocca

[josephrocca]

No - feel free to use my example in place of the one I referenced, but as I said, imo the promiser in promiser code of the other code blocks is strange and indicates that the module itself needs to be adjusted to make the init code examples more simple.

The worker proxy enable/disable, and OPFS enable/disable should simply be flags in the awaitable init function.

Feel free to close this issue if that's not likely to happen without work on my part, since I unfortunately don't have time to contribute right now.

[sgbeal]

The worker proxy enable/disable, and OPFS enable/disable should simply be flags in the awaitable init function.

Unfortunately, we have no way of intercepting those arguments because of how Emscripten structures the generated code, or we would indeed have some form of configuration. There is a library-level configuration step, but it's necessarily hidden inside the Emscripten-related bootstrapping process.