[Alpha WIP] Web Support (#25)

Initial support for web platform

Author: stevensJourney

.github/workflows/test.yaml

@@ -23,7 +23,7 @@ jobs:
       - name: Check publish score
         run: |
           dart pub global activate pana
-          dart pub global run pana --no-warning --exit-code-threshold 0
+          dart pub global run pana --no-warning --exit-code-threshold 10
 
   test:
     runs-on: ubuntu-latest
@@ -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

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.7.0-alpha.1
+
+- Added initial support for web platform.
+
 ## 0.6.0
 
 - Allow catching errors and continuing the transaction. This is technically a breaking change, although it should not be an issue in most cases.

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/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

@@ -3,6 +3,12 @@
 /// See [SqliteDatabase] as a starting point.
 library;
 
+export 'src/common/abstract_open_factory.dart';
+export 'src/common/connection/sync_sqlite_connection.dart';
+export 'src/common/isolate_connection_factory.dart';
+export 'src/common/mutex.dart';
+export 'src/common/port_channel.dart';
+export 'src/common/sqlite_database.dart';
 export 'src/isolate_connection_factory.dart';
 export 'src/sqlite_connection.dart';
 export 'src/sqlite_database.dart';

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;
+  }
+}