Static + Dynamic PowerSync Builds

[stevensJourney]

Overview

This supersedes the following PRs:

• [POC] Dynamic Extension Loading #16
• [Chore] Update fork #13

Update

This PR updates our fork with the latest changes from upstream. Our PowerSync core Git submodule had build issues when just pulling in the latest changes. Build issues have been resolved by removing the use of Git submodules in this repository.

Noteable updates

• Upstream now supports table change notifications. Our old implementation has been removed.
• Upstream has removed prepare_v2 from SQLiteAPI. Our SDK now has to use a different method for batchExecute.
• WA SQLite is now on version 1.0.4. This PR includes a major version bump to @journeyapps/[email protected]

PowerSync Core

The PowerSync core is no longer provided from a Git submodule. The libpowersync-wasm.a binary is now downloaded from the powersync-sqlite-core releases during compilation. The PowerSync core is statically linked in the dist/wa-sqlite.wasm and dist/wa-sqlite-async.wasm distributables.

The PowerSync specific source has been separated from the SQLite source.

The PowerSync extension can be loaded in the static build with

const { default: moduleFactory } = await import('@journeyapps/dist/wa-sqlite.mjs');
  const module = await moduleFactory();

  module.ccall('setup_powersync', 'int', []);
  const sqlite3 = SQLite.Factory(module);

Dynamic extension loading

See here and here for reference.

We now provide dist/wa-sqlite-dynamic-main.wasm and dist/wa-sqlite-async-dynamic-main.wasm distributables which support dynamic extension loading. These distributables are compiled as Emscripten main modules.

The PowerSync side module WASM files are configured to be downloaded in a postinstall script.

The PowerSync extension can be loaded with:

const { default: moduleFactory } = await import('@journeyapps/dist/wa-sqlite-dynamic-main.mjs');
  const module = await moduleFactory({
    // locateFile(path) {
    //   // (OPTIONAL) locateFile can be specified to change WASM module resolution.
    //   // The returned url is passed to fetch, and can be a relative path
    //   // or absolute URL.
    //   // This applies to both the main wasm file, and the extension.
    //   return `../dist/${path}`;
    // },
  });

  const sqlite3 = SQLite.Factory(module);
  // Load the extension library into this scope
  let extScope = {};
  await module.loadDynamicLibrary(
     'libpowersync.wasm',
      { loadAsync: true },
      extScope
    );

    // This calls sqlite3_auto_extension(sqlite3_powersync_init).
    // For generic extensions, we'd need to call sqlite3_auto_extension directly.
    extScope.powersync_init_static();

Runtime errors could occur if the main module does not export all the required symbols which side modules require. We currently don't have a full list of all the common/required symbols for our PowerSync side module. This list could also change if other SQLite extensions are loaded. In order to ensure stability, the main module is currently compiled with the option MAIN_MODULE=1. This has the unfortunate affect of a large file-size (3.7mb).