Merge branch 'docs' into prioritized-sync

Author: kobiebotha

.github/workflows/check.yaml

@@ -0,0 +1,23 @@
+name: Check Documentation
+
+on:
+  push:
+    branches:
+      - '**'
+    tags-ignore:
+      - '**'
+
+jobs:
+  check:
+    name: Check Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+
+      # This checks internal links, but does not validate external links
+      - name: Check for broken links
+        run: npx mintlify broken-links 

.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+.vscode/
+.idea

architecture/client-architecture.mdx

@@ -31,14 +31,14 @@ The local SQLite database embedded in the PowerSync SDK is automatically kept in
 
 Client-side data modifications, namely updates, deletes and inserts, are persisted in the embedded SQLite database as well as stored in an upload queue. The upload queue is a blocking [FIFO](https://en.wikipedia.org/wiki/FIFO%5F%28computing%5Fand%5Felectronics%29) queue that gets processed when network connectivity is available.
 
-Each entry in the queue is processed by writing the entry to your existing backend application API, using a function [defined by you](/usage/installation/client-side-setup/integrating-with-your-backend) (the developer). This is to ensure that existing backend business logic is honored when uploading data changes. For more information, see the section on [integrating with your backend](/usage/installation/client-side-setup/integrating-with-your-backend).
+Each entry in the queue is processed by writing the entry to your existing backend application API, using a function [defined by you](/installation/client-side-setup/integrating-with-your-backend) (the developer). This is to ensure that existing backend business logic is honored when uploading data changes. For more information, see the section on [integrating with your backend](/installation/client-side-setup/integrating-with-your-backend).
 
 <Frame>
   <img src="/images/powersync-docs-architecture-diagram-008 (3).png"/>
 </Frame>
 
 ### Schema
-On the client, the application [defines a schema](/usage/installation/client-side-setup/define-your-schema) with tables, columns and indexes.
+On the client, the application [defines a schema](/installation/client-side-setup/define-your-schema) with tables, columns and indexes.
 
 These are then usable as if they were actual SQLite tables, while in reality these are created as SQLite views.
 

architecture/powersync-service.mdx

@@ -18,7 +18,7 @@ Replication is initially performed by taking a snapshot of all tables defined in
 
 ## Authentication
 
-The service authenticates users using [JWTs](/usage/installation/authentication-setup), before allowing access to data.
+The service authenticates users using [JWTs](/installation/authentication-setup), before allowing access to data.
 
 ## Streaming Sync
 

client-sdk-references/flutter.mdx

@@ -41,7 +41,7 @@ See the [SDK's README](https://pub.dev/packages/powersync#getting-started) for i
 Before implementing the PowerSync SDK in your project, make sure you have completed these steps:
 
 * Signed up for a PowerSync Cloud account ([here](https://accounts.journeyapps.com/portal/get-started?powersync=true)) or [self-host PowerSync](/self-hosting/getting-started).
-* [Configured your backend database](/usage/installation/database-setup) and connected it to your PowerSync instance.
+* [Configured your backend database](/installation/database-setup) and connected it to your PowerSync instance.
 * [Installed](/client-sdk-references/flutter#installation) the PowerSync Flutter SDK.
 
 ### 1\. Define the Schema
@@ -130,14 +130,14 @@ The PowerSync backend connector provides the connection between your application
 
 It is used to:
 
-1. [Retrieve an auth token](/usage/installation/authentication-setup) to connect to the PowerSync instance.
-2. [Apply local changes](/usage/installation/app-backend-setup/writing-client-changes) on your backend application server (and from there, to Postgres)
+1. [Retrieve an auth token](/installation/authentication-setup) to connect to the PowerSync instance.
+2. [Apply local changes](/installation/app-backend-setup/writing-client-changes) on your backend application server (and from there, to Postgres)
 
 Accordingly, the connector must implement two methods:
 
-1. [PowerSyncBackendConnector.fetchCredentials](https://pub.dev/documentation/powersync/latest/powersync/PowerSyncBackendConnector/fetchCredentials.html) \- This is called every couple of minutes and is used to obtain credentials for your app backend API. -> See [Authentication Setup](/usage/installation/authentication-setup) for instructions on how the credentials should be generated.
+1. [PowerSyncBackendConnector.fetchCredentials](https://pub.dev/documentation/powersync/latest/powersync/PowerSyncBackendConnector/fetchCredentials.html) \- This is called every couple of minutes and is used to obtain credentials for your app backend API. -> See [Authentication Setup](/installation/authentication-setup) for instructions on how the credentials should be generated.
 2. [PowerSyncBackendConnector.uploadData](https://pub.dev/documentation/powersync/latest/powersync/PowerSyncBackendConnector/uploadData.html) \- Use this to upload client-side changes to your app backend.
-\-> See [Writing Client Changes](/usage/installation/app-backend-setup/writing-client-changes) for considerations on the app backend implementation.
+\-> See [Writing Client Changes](/installation/app-backend-setup/writing-client-changes) for considerations on the app backend implementation.
 
 **Example**:
 
@@ -156,14 +156,14 @@ class MyBackendConnector extends PowerSyncBackendConnector {
   Future<PowerSyncCredentials?> fetchCredentials() async {
     // Implement fetchCredentials to obtain a JWT from your authentication service
     // If you're using Supabase or Firebase, you can re-use the JWT from those clients, see
-    // - https://docs.powersync.com/usage/installation/authentication-setup/supabase-auth
-    // - https://docs.powersync.com/usage/installation/authentication-setup/firebase-auth
+    // - https://docs.powersync.com/installation/authentication-setup/supabase-auth
+    // - https://docs.powersync.com/installation/authentication-setup/firebase-auth
 
     // See example implementation here: https://pub.dev/documentation/powersync/latest/powersync/DevConnector/fetchCredentials.html
 
     return {
         endpoint: '[Your PowerSync instance URL or self-hosted endpoint]',
-        // Use a development token (see Authentication Setup https://docs.powersync.com/usage/installation/authentication-setup/development-tokens) to get up and running quickly
+        // Use a development token (see Authentication Setup https://docs.powersync.com/installation/authentication-setup/development-tokens) to get up and running quickly
         token: 'An authentication token'
     };
   }

client-sdk-references/flutter/flutter-orm-support.mdx

@@ -1,7 +1,10 @@
 ---
 title: "Flutter ORM Support (Alpha)"
+sidebarTitle: "ORM Support (Alpha)"
 ---
 
+An introduction to using ORMs with PowerSync is available on our blog [here](https://www.powersync.com/blog/using-orms-with-powersync).
+
 ORM support is available via the following package (currently in an alpha release):
 
 <Card
@@ -39,10 +42,3 @@ Every write transaction (or write statement) will lock the database for other wr
 **External modifications**
 
 Often, ORMs only detect notifications made using the same library. In order to support streaming queries, PowerSync requires the ORM to allow external modifications to trigger the same change notifications, meaning streaming queries are unlikely to work out-of-the-box.
-
-<Check>
-**Further reading**
-
-See [Using ORMs with PowerSync](https://www.powersync.com/blog/using-orms-with-powersync) on our blog.
-
-</Check>

client-sdk-references/flutter/flutter-web-support.mdx

@@ -1,14 +1,19 @@
 ---
-title: "Flutter Web Support (Alpha)"
+title: "Flutter Web Support (Beta)"
+sidebarTitle: "Web Support (Beta)"
 ---
 
-Web support for Flutter in version `^1.6.0` is currently in its alpha stage.
+<Note>
+Web support for Flutter in version `^1.9.0` is currently in a **beta** release. It is functionally ready for production use, provided that you've tested your use cases. 
+
+Please see the [Limitations](#limitations) detailed below.
+</Note>
 
 ## Demo app
 
-The easiest way to test out the alpha is to run the [Supabase Todo-List](https://github.com/powersync-ja/powersync.dart/blob/master/demos/supabase-todolist) demo app:
+The easiest way to test Flutter Web support is to run the [Supabase Todo-List](https://github.com/powersync-ja/powersync.dart/tree/main/demos/supabase-todolist) demo app:
 
-1. Checkout [the powersync.dart repo's](https://github.com/powersync-ja/powersync.dart/tree/master) `master` branch.
+1. Clone the [powersync.dart](https://github.com/powersync-ja/powersync.dart/tree/main) repo.
    1. **Note**: If you are an existing user updating to the latest code after a git pull, run `melos exec 'flutter pub upgrade'` in the repo's root and make sure it succeeds.
 2. Run `melos prepare` in the repo's root
 3. cd into the `demos/supabase-todolist` folder
@@ -17,25 +22,56 @@ The easiest way to test out the alpha is to run the [Supabase Todo-List](https:/
 
 ## Installing PowerSync in your own project
 
-Install the latest alpha version of the package, for example:
+Install the [latest version](https://pub.dev/packages/powersync/versions) of the package, for example:
 
 ```bash
-flutter pub add powersync:'^1.6.2'
+flutter pub add powersync:'^1.9.0'
 ```
 
-The latest version can be found [here](https://pub.dev/packages/powersync/versions).
-
-## Additional config
+### Additional config
 
-Web support requires `sqlite3.wasm` and `powersync_db.worker.js` assets to be served from the web application. They can be downloaded to the `web` directory by running the following command in your application's root folder.
+#### Assets
+Web support requires `sqlite3.wasm` and worker (`powersync_db.worker.js` and `powersync_sync.worker.js`) assets to be served from the web application. They can be downloaded to the web directory by running the following command in your application's root folder.
 
 ```bash
 dart run powersync:setup_web
 ```
 
 The same code is used for initializing native and web `PowerSyncDatabase` clients.
 
-## Imports
+#### OPFS for improved performance
+
+This SDK supports different storage modes of the SQLite database with varying levels of performance and compatibility:
+
+- **IndexedDB**: Highly compatible with different browsers, but performance is slow.
+- **OPFS** (Origin-Private File System): Significantly faster but requires additional configuration.
+
+OPFS is the preferred mode when it is available. Otherwise database storage falls back to IndexedDB.
+
+Enabling OPFS requires adding two headers to the HTTP server response when a client requests the Flutter web application:
+
+- `Cross-Origin-Opener-Policy`: Needs to be set to `same-origin`.
+- `Cross-Origin-Embedder-Policy`: Needs to be set to `require-corp`.
+
+When running the app locally, you can use the following command to include the required headers:
+
+```bash
+flutter run -d chrome --web-header "Cross-Origin-Opener-Policy=same-origin" --web-header "Cross-Origin-Embedder-Policy=require-corp"
+```
+
+When serving a Flutter Web app in production, the [Flutter docs](https://docs.flutter.dev/deployment/web#building-the-app-for-release) recommend building the web app with `flutter build web`, then serving the content with an HTTP server. The server should be configured to use the above headers.
+
+<Tip>
+**Further reading**:
+
+[Drift](https://drift.simonbinder.eu/) uses the same packages as our [`sqlite_async`](https://github.com/powersync-ja/sqlite_async.dart) package under the hood, and has excellent documentation for how the web filesystem is selected. See [here](https://drift.simonbinder.eu/platforms/web/) for web compatibility notes and [here](https://drift.simonbinder.eu/platforms/web/#additional-headers) for additional notes on the required web headers.
+</Tip>
+
+## Limitations
+
+The API for Web is essentially the same as for native platforms, however, some features within `PowerSyncDatabase` clients are not available.
+
+### Imports
 
 Flutter Web does not support importing directly from `sqlite3.dart` as it uses `dart:ffi`.
 
@@ -53,14 +89,8 @@ import 'package/powersync/sqlite3_common.dart'
 
 in code which needs to run on the Web platform. Isolated native-specific code can still import from `sqlite3.dart`.
 
-## Database connections
+### Database connections
 
 Web database connections do not support concurrency. A single database connection is used. `readLock` and `writeLock` contexts do not implement checks for preventing writable queries in read connections and vice-versa.
 
 Direct access to the synchronous `CommonDatabase` (`sqlite.Database` equivalent for web) connection is not available. `computeWithDatabase` is not available on web.
-
-## Limitations
-
-The API for web is essentially the same as for native platforms. Some features within `PowerSyncDatabase` clients are not available.
-
-Full multiple tab support is not yet available. Some sync status indicators will not be available in each tab. Multiple requests from tabs to connect/disconnect might result in undefined behaviour.

client-sdk-references/flutter/unit-testing.mdx

@@ -0,0 +1,76 @@
+---
+title: "Unit Testing"
+description: "Guidelines for unit testing with PowerSync"
+---
+
+For unit-testing your projects using PowerSync
+(e.g. testing whether your queries run as expected) you will need the `powersync-sqlite-core` binary in your project's root directory.
+
+1. Download the PowerSync SQLite binary
+   - Go to the [Releases](https://github.com/powersync-ja/powersync-sqlite-core/releases) for `powersync-sqlite-core`.
+   - Download the binary compatible with your OS.
+2. Rename the binary
+   - Rename the binary by removing the architecture suffix.
+   - Example: `powersync_x64.dll` to `powersync.dll`
+   - Example: `libpowersync_aarch64.dylib` to `libpowersync.dylib`
+   - Example: `libpowersync_x64.so` to `libpowersync.so`
+3. Place the binary in your project
+   - Move the renamed binary to the root directory of your project.
+
+This snippet below is only included as a guide to unit testing in Flutter with PowerSync. For more information refer to the [official Flutter unit testing documentation](https://docs.flutter.dev/cookbook/testing/unit/introduction).
+
+```dart
+import 'dart:io';
+import 'package:powersync/powersync.dart';
+import 'package:path/path.dart';
+
+const schema = Schema([
+    Table('customers', [Column.text('name'), Column.text('email')])
+]);
+
+late PowerSyncDatabase testDB;
+
+String getTestDatabasePath() async {
+    const dbFilename = 'powersync-test.db';
+    final dir = Directory.current.absolute.path;
+    return join(dir, dbFilename);
+}
+
+Future<void> openTestDatabase() async {
+    testDB = PowerSyncDatabase(
+      schema: schema,
+      path: await getTestDatabasePath(),
+      logger: testLogger,
+    );
+
+    await testDB.initialize();
+}
+
+test('INSERT', () async {
+    await testDB.execute(
+          'INSERT INTO customers(name, email) VALUES(?, ?)', ['John Doe', '[email protected]']);
+
+    final results = await testDB.getAll('SELECT * FROM customers');
+
+    expect(results.length, 1);
+    expect(results, ['John Doe', '[email protected]']);
+});
+```
+
+#### If you have trouble with loading the extension, confirm the following
+
+Ensure that your SQLite3 binary install on your system has extension loading enabled. You can confirm this by doing the following
+
+- Run `sqlite3` in your command-line interface.
+- In the sqlite3 prompt run `PRAGMA compile_options;`
+- Check the output for the option `ENABLE_LOAD_EXTENSION`.
+- If you see `ENABLE_LOAD_EXTENSION`, it means extension loading is enabled.
+
+If the above steps don't work, you can also confirm if extension loading is enabled by trying to load the extension in your command-line interface.
+
+- Run `sqlite3` in your command-line interface.
+- Run `.load /path/to/file/libpowersync.dylib` (macOS) or `.load /path/to/file/libpowersync.so` (Linux) or `.load /path/to/file/powersync.dll` (Windows).
+- If this runs without error, then extension loading is enabled. If it fails with an error message about extension loading being disabled, then it’s not enabled in your SQLite installation.
+
+If it is not enabled, you will have to download a compiled SQLite binary with extension loading enabled (e.g. using Homebrew) or [compile SQLite](https://www.sqlite.org/howtocompile.html) with extension loading enabled and
+include it in your project's folder alongside the extension.

client-sdk-references/introduction.mdx

@@ -10,12 +10,12 @@ Select your client framework for the full SDK reference, getting started instruc
   </Card>
   <Card title="React Native & Expo" icon="react" href="/client-sdk-references/react-native-and-expo">
   </Card>
-  <Card title="JS/Web" icon="js" href="/client-sdk-references/js-web">
+  <Card title="JavaScript/Web" icon="js" href="/client-sdk-references/javascript-web">
   </Card>
   <Card title="Kotlin Multiplatform" icon="flag" href="/client-sdk-references/kotlin-multiplatform">
   Currently in a beta release.
   </Card>
   <Card title="Swift" icon="swift" href="/client-sdk-references/swift">
   Currently in an alpha release.
   </Card>
-</CardGroup>
+</CardGroup>