[Alpha WIP] Web Support

.github/workflows/test.yaml

@@ -55,9 +55,14 @@ jobs:
         run: dart pub get
 
       - name: Install SQLite
-        run: ./scripts/install_sqlite.sh ${{ matrix.sqlite_version }} ${{ matrix.sqlite_url }}
+        run: |
+          ./scripts/install_sqlite.sh ${{ matrix.sqlite_version }} ${{ matrix.sqlite_url }}
+          mkdir -p assets && curl -LJ https://github.com/simolus3/sqlite3.dart/releases/download/sqlite3-2.3.0/sqlite3.wasm -o assets/sqlite3.wasm
+
+      - name: Compile WebWorker
+        run: dart compile js -o assets/db_worker.js -O0 lib/src/web/worker/drift_worker.dart
 
       - name: Run Tests
         run: |
           export LD_LIBRARY_PATH=./sqlite-autoconf-${{ matrix.sqlite_version }}/.libs
-          dart test
+          dart test -p vm,chrome

.gitignore

@@ -6,7 +6,11 @@
 # https://dart.dev/guides/libraries/private-files#pubspeclock.
 pubspec.lock
 
+# Test assets
+assets
+
 .idea
+.vscode
 *.db
 *.db-*
 test-db

README.md

@@ -74,4 +74,29 @@ void main() async {
 
   await db.close();
 }
-```
+```
+
+# Web
+
+Web support is provided by the [Drift](https://github.com/powersync-ja/drift/pull/1) library. Detailed instructions for compatibility and setup are listed in the link.
+
+Web support requires Sqlite3 WASM and Drift worker Javascript files to be accessible via configurable URIs.
+
+Default URIs are shown in the example below. URIs only need to be specified if they differ from default values.
+
+Watched queries and table change notifications are only supported when using a custom Drift worker which is compiled by linking
+https://github.com/powersync-ja/drift/pull/1. 
+
+Setup
+
+``` Dart 
+import 'package:sqlite_async/sqlite_async.dart';
+
+final db = SqliteDatabase(
+    path: 'test.db',
+    options: SqliteOptions(
+        webSqliteOptions: WebSqliteOptions(
+            wasmUri: 'sqlite3.wasm', workerUri: 'db_worker.js')));
+
+```
+

example/custom_functions_example.dart

@@ -1,21 +1,22 @@
+import 'dart:async';
 import 'dart:io';
 import 'dart:isolate';
 
+import 'package:sqlite3/common.dart';
 import 'package:sqlite_async/sqlite_async.dart';
-import 'package:sqlite3/sqlite3.dart' as sqlite;
 
 /// Since the functions need to be created on every SQLite connection,
 /// we do this in a SqliteOpenFactory.
 class TestOpenFactory extends DefaultSqliteOpenFactory {
   TestOpenFactory({required super.path, super.sqliteOptions});
 
   @override
-  sqlite.Database open(SqliteOpenOptions options) {
-    final db = super.open(options);
+  FutureOr<CommonDatabase> open(SqliteOpenOptions options) async {
+    final db = await super.open(options);
 
     db.createFunction(
       functionName: 'sleep',
-      argumentCount: const sqlite.AllowedArgumentCount(1),
+      argumentCount: const AllowedArgumentCount(1),
       function: (args) {
         final millis = args[0] as int;
         sleep(Duration(milliseconds: millis));
@@ -25,7 +26,7 @@ class TestOpenFactory extends DefaultSqliteOpenFactory {
 
     db.createFunction(
       functionName: 'isolate_name',
-      argumentCount: const sqlite.AllowedArgumentCount(0),
+      argumentCount: const AllowedArgumentCount(0),
       function: (args) {
         return Isolate.current.debugName;
       },

example/linux_cli_example.dart

@@ -1,8 +1,9 @@
+import 'dart:async';
 import 'dart:ffi';
 
+import 'package:sqlite3/common.dart';
 import 'package:sqlite_async/sqlite_async.dart';
 import 'package:sqlite3/open.dart' as sqlite_open;
-import 'package:sqlite3/sqlite3.dart' as sqlite;
 
 const defaultSqlitePath = 'libsqlite3.so.0';
 
@@ -16,7 +17,7 @@ class TestOpenFactory extends DefaultSqliteOpenFactory {
       this.sqlitePath = defaultSqlitePath});
 
   @override
-  sqlite.Database open(SqliteOpenOptions options) {
+  FutureOr<CommonDatabase> open(SqliteOpenOptions options) async {
     // For details, see:
     // https://pub.dev/packages/sqlite3#manually-providing-sqlite3-libraries
     sqlite_open.open.overrideFor(sqlite_open.OperatingSystem.linux, () {

lib/definitions.dart

@@ -0,0 +1,8 @@
+export 'package:sqlite_async/src/update_notification.dart';
+export 'package:sqlite_async/src/sqlite_connection.dart';
+export 'package:sqlite_async/src/sqlite_queries.dart';
+export 'package:sqlite_async/src/sqlite_open_factory.dart';
+export 'package:sqlite_async/src/sqlite_options.dart';
+export 'package:sqlite_async/src/common/abstract_isolate_connection_factory.dart';
+export 'package:sqlite_async/src/common/abstract_open_factory.dart';
+export 'package:sqlite_async/src/common/abstract_sqlite_database.dart';

lib/drift.dart

@@ -0,0 +1,6 @@
+/// Re-exports [Drift](https://pub.dev/packages/drift) to expose drift without
+/// adding it as a direct dependency.
+library;
+
+export 'package:drift/wasm.dart';
+export 'package:sqlite_async/src/web/worker/worker_utils.dart';

lib/sqlite3_common.dart

@@ -0,0 +1,2 @@
+// Exports common Sqlite3 exports which are available on web and ffi environments
+export 'package:sqlite3/common.dart';

lib/sqlite_async.dart

@@ -8,7 +8,8 @@ export 'src/sqlite_connection.dart';
 export 'src/sqlite_database.dart';
 export 'src/sqlite_migrations.dart';
 export 'src/sqlite_open_factory.dart';
-export 'src/sqlite_options.dart';
 export 'src/sqlite_queries.dart';
 export 'src/update_notification.dart';
 export 'src/utils.dart';
+export 'definitions.dart';
+export 'src/common/connection/sync_sqlite_connection.dart';

lib/src/common/abstract_isolate_connection_factory.dart

@@ -0,0 +1,34 @@
+import 'dart:async';
+import 'package:sqlite_async/mutex.dart';
+import 'package:sqlite_async/sqlite3_common.dart' as sqlite;
+import 'package:sqlite_async/src/sqlite_connection.dart';
+
+import 'abstract_open_factory.dart';
+import 'port_channel.dart';
+
+/// A connection factory that can be passed to different isolates.
+abstract class AbstractIsolateConnectionFactory<
+    Database extends sqlite.CommonDatabase> {
+  AbstractDefaultSqliteOpenFactory<Database> get openFactory;
+
+  AbstractMutex get mutex;
+
+  SerializedPortClient get upstreamPort;
+
+  /// Open a new SqliteConnection.
+  ///
+  /// This opens a single connection in a background execution isolate.
+  SqliteConnection open({String? debugName, bool readOnly = false});
+
+  /// Opens a synchronous sqlite.Database directly in the current isolate.
+  ///
+  /// This gives direct access to the database, but:
+  ///  1. No app-level locking is performed automatically. Transactions may fail
+  ///     with SQLITE_BUSY if another isolate is using the database at the same time.
+  ///  2. Other connections are not notified of any updates to tables made within
+  ///     this connection.
+  FutureOr<Database> openRawDatabase({bool readOnly = false}) async {
+    return openFactory
+        .open(SqliteOpenOptions(primaryConnection: false, readOnly: readOnly));
+  }
+}

lib/src/common/abstract_mutex.dart

@@ -0,0 +1,26 @@
+abstract class AbstractMutex {
+  /// timeout is a timeout for acquiring the lock, not for the callback
+  Future<T> lock<T>(Future<T> Function() callback, {Duration? timeout});
+
+  /// Use [open] to get a [AbstractMutex] instance.
+  /// This is mainly used for shared mutexes
+  AbstractMutex open() {
+    return this;
+  }
+
+  /// Release resources used by the Mutex.
+  ///
+  /// Subsequent calls to [lock] may fail, or may never call the callback.
+  Future<void> close();
+}
+
+class LockError extends Error {
+  final String message;
+
+  LockError(this.message);
+
+  @override
+  String toString() {
+    return 'LockError: $message';
+  }
+}

lib/src/common/abstract_open_factory.dart

@@ -0,0 +1,69 @@
+import 'dart:async';
+import 'package:meta/meta.dart';
+
+import 'package:sqlite_async/sqlite3_common.dart' as sqlite;
+import 'package:sqlite_async/src/sqlite_options.dart';
+
+/// Factory to create new SQLite database connections.
+///
+/// Since connections are opened in dedicated background isolates, this class
+/// must be safe to pass to different isolates.
+abstract class SqliteOpenFactory<Database extends sqlite.CommonDatabase> {
+  String get path;
+
+  FutureOr<Database> open(SqliteOpenOptions options);
+}
+
+class SqliteOpenOptions {
+  /// Whether this is the primary write connection for the database.
+  final bool primaryConnection;
+
+  /// Whether this connection is read-only.
+  final bool readOnly;
+
+  const SqliteOpenOptions(
+      {required this.primaryConnection, required this.readOnly});
+
+  sqlite.OpenMode get openMode {
+    if (primaryConnection) {
+      return sqlite.OpenMode.readWriteCreate;
+    } else if (readOnly) {
+      return sqlite.OpenMode.readOnly;
+    } else {
+      return sqlite.OpenMode.readWrite;
+    }
+  }
+}
+
+/// The default database factory.
+///
+/// This takes care of opening the database, and running PRAGMA statements
+/// to configure the connection.
+///
+/// Override the [open] method to customize the process.
+abstract class AbstractDefaultSqliteOpenFactory<
+        Database extends sqlite.CommonDatabase>
+    implements SqliteOpenFactory<Database> {
+  @override
+  final String path;
+  final SqliteOptions sqliteOptions;
+
+  const AbstractDefaultSqliteOpenFactory(
+      {required this.path,
+      this.sqliteOptions = const SqliteOptions.defaults()});
+
+  List<String> pragmaStatements(SqliteOpenOptions options);
+
+  @protected
+  FutureOr<Database> openDB(SqliteOpenOptions options);
+
+  @override
+  FutureOr<Database> open(SqliteOpenOptions options) async {
+    var db = await openDB(options);
+
+    for (var statement in pragmaStatements(options)) {
+      db.execute(statement);
+    }
+    return db;
+  }
+}

lib/src/common/abstract_sqlite_database.dart

@@ -0,0 +1,48 @@
+import 'dart:async';
+
+import 'package:sqlite_async/src/common/abstract_isolate_connection_factory.dart';
+import 'package:sqlite_async/src/common/abstract_open_factory.dart';
+import 'package:sqlite_async/src/sqlite_queries.dart';
+import 'package:sqlite_async/src/update_notification.dart';
+import 'package:sqlite_async/src/sqlite_connection.dart';
+
+/// A SQLite database instance.
+///
+/// Use one instance per database file. If multiple instances are used, update
+/// notifications may not trigger, and calls may fail with "SQLITE_BUSY" errors.
+abstract class AbstractSqliteDatabase extends SqliteConnection
+    with SqliteQueries {
+  /// The maximum number of concurrent read transactions if not explicitly specified.
+  static const int defaultMaxReaders = 5;
+
+  /// Maximum number of concurrent read transactions.
+  int get maxReaders;
+
+  /// Factory that opens a raw database connection in each isolate.
+  ///
+  /// This must be safe to pass to different isolates.
+  ///
+  /// Use a custom class for this to customize the open process.
+  AbstractDefaultSqliteOpenFactory get openFactory;
+
+  /// Use this stream to subscribe to notifications of updates to tables.
+  @override
+  Stream<UpdateNotification> get updates;
+
+  final StreamController<UpdateNotification> updatesController =
+      StreamController.broadcast();
+
+  Future<void> get isInitialized;
+
+  /// Wait for initialization to complete.
+  ///
+  /// While initializing is automatic, this helps to catch and report initialization errors.
+  Future<void> initialize() async {
+    await isInitialized;
+  }
+
+  /// A connection factory that can be passed to different isolates.
+  ///
+  /// Use this to access the database in background isolates.
+  AbstractIsolateConnectionFactory isolateConnectionFactory();
+}