diff --git a/client-sdk-references/javascript-web.mdx b/client-sdk-references/javascript-web.mdx index d4c42081..fdb0bf2d 100644 --- a/client-sdk-references/javascript-web.mdx +++ b/client-sdk-references/javascript-web.mdx @@ -285,26 +285,113 @@ See [Usage Examples](/client-sdk-references/javascript-web/usage-examples) for f ## Developer Notes -### Connecting via WebSocket or HTTP Stream +### Connection Methods -This SDK connects to a PowerSync instance and streams sync commands via WebSockets (enabled by default since @powersync/web@1.6.0) or HTTP streaming. +This SDK supports two methods for streaming sync commands: -The WebSocket implementation uses reactive socket streams from the cross-platform [RSocket](https://github.com/powersync-ja/powersync-js/pull/rsocket.io) library. This allows the client to request commands from the server after processing existing events, alleviating any back-pressure build-up of commands. Sync commands are transmitted as BSON (binary) documents. +1. **WebSocket (Default)** + - The implementation leverages RSocket for handling reactive socket streams. + - Back-pressure is effectively managed through client-controlled command requests. + - Sync commands are transmitted efficiently as BSON (binary) documents. + - This method is **recommended** since it will support the future [BLOB column support](https://roadmap.powersync.com/c/88-support-for-blob-column-types) feature. -#### Benefits of using the WebSocket Method +2. **HTTP Streaming (Legacy)** + - This is the original implementation method. + - This method will not support the future BLOB column feature. -* BLOB column support will be added on top of the WebSocket implementation (the HTTP streaming method will not support this). +By default, the `PowerSyncDatabase.connect()` method uses WebSocket. You can optionally specify the `connectionMethod` to override this: -#### Selecting Connection Method +```js +// WebSocket (default) +powerSync.connect(connector); + +// HTTP Streaming +powerSync.connect(connector, { connectionMethod: SyncStreamConnectionMethod.HTTP }); +``` + +### SQLite Virtual File Systems + +This SDK supports multiple Virtual File Systems (VFS), responsible for storing the local SQLite database: + +#### 1. IDBBatchAtomicVFS (Default) +- This system utilizes IndexedDB as its underlying storage mechanism. +- Multiple tabs are fully supported across most modern browsers. +- Users may experience stability issues when using Safari. -The `PowerSyncDatabase` client's `connect` method supports a `connectionMethod` option. This is not required, as the WebSocket method is used by default. +#### 2. OPFS-based Alternatives +PowerSync supports two OPFS (Origin Private File System) implementations that generally offer improved performance: + +##### OPFSCoopSyncVFS (Recommended) +- This implementation provides comprehensive multi-tab support across all major browsers. +- It offers the most reliable compatibility with Safari and Safari iOS. +- Example configuration: ```js -// For WebSocket -powerSync.connect(connector) +import { PowerSyncDatabase, WASQLiteOpenFactory, WASQLiteVFS } from '@powersync/web'; -// For HTTP Streaming -powerSync.connect(connector, { connectionMethod: SyncStreamConnectionMethod.HTTP }); +export const db = new PowerSyncDatabase({ + schema: AppSchema, + database: new WASQLiteOpenFactory({ + dbFilename: 'exampleVFS.db', + vfs: WASQLiteVFS.OPFSCoopSyncVFS, + flags: { + enableMultiTabs: typeof SharedWorker !== 'undefined' + } + }), + flags: { + enableMultiTabs: typeof SharedWorker !== 'undefined' + } +}); +``` + +##### AccessHandlePoolVFS +- This implementation delivers optimal performance for single-tab applications. +- The system is not designed to handle multiple tab scenarios. +- The configuration is similar to `OPFSCoopSyncVFS`, but requires using `WASQLiteVFS.AccessHandlePoolVFS`. + +#### VFS Compatibility Matrix + +| VFS Type | Multi-Tab Support (Standard Browsers) | Multi-Tab Support (Safari/iOS) | Notes | +|----------|---------------------------|---------------------|--------| +| IDBBatchAtomicVFS | ✅ | ❌ | Default, some Safari stability issues | +| OPFSCoopSyncVFS | ✅ | ✅ | Recommended for multi-tab support | +| AccessHandlePoolVFS | ❌ | ❌ | Best for single-tab applications | + +**Note**: There are known issues with OPFS when using Safari's incognito mode. + +### Managing OPFS Storage + +Unlike IndexedDB, OPFS storage cannot be managed through browser developer tools. The following utility functions can help you manage OPFS storage programmatically: + +```js +// Clear all OPFS storage +async function purgeVFS() { + await powerSync.disconnect(); + await powerSync.close(); + + const root = await navigator.storage.getDirectory(); + await new Promise(resolve => setTimeout(resolve, 1)); // Allow .db-wal to become deletable + + for await (const [name, entry] of root.entries!()) { + try { + if (entry.kind === 'file') { + await root.removeEntry(name); + } else if (entry.kind === 'directory') { + await root.removeEntry(name, { recursive: true }); + } + } catch (err) { + console.error(`Failed to delete ${entry.kind}: ${name}`, err); + } + } +} + +// List OPFS entries +async function listVfsEntries() { + const root = await navigator.storage.getDirectory(); + for await (const [name, entry] of root.entries()) { + console.log(`${entry.kind}: ${name}`); + } +} ``` ## ORM Support diff --git a/client-sdk-references/react-native-and-expo.mdx b/client-sdk-references/react-native-and-expo.mdx index ea1441fe..95f1112c 100644 --- a/client-sdk-references/react-native-and-expo.mdx +++ b/client-sdk-references/react-native-and-expo.mdx @@ -370,27 +370,27 @@ See [Usage Examples](/client-sdk-references/react-native-and-expo/usage-examples ## Developer Notes -### Connecting via WebSockets or HTTP Streams +### Connection Methods -This SDK connects to a PowerSync instance and streams sync commands via WebSockets (enabled by default since @powersync/react-native@1.11.0) or HTTP streams. +This SDK supports two methods for streaming sync commands: -The WebSocket implementation (available since version 1.4.6 of the SDK) uses reactive socket streams using the cross-platform [RSocket](https://github.com/powersync-ja/powersync-js/pull/rsocket.io) library. This allows the client to request commands from the server after processing existing events, alleviating any back-pressure build-up of commands. Sync commands are transmitted as BSON (binary) documents. +1. **WebSocket (Default)** + - The implementation leverages RSocket for handling reactive socket streams. + - Back-pressure is effectively managed through client-controlled command requests. + - Sync commands are transmitted efficiently as BSON (binary) documents. + - This method is **recommended** since it will support the future [BLOB column support](https://roadmap.powersync.com/c/88-support-for-blob-column-types) feature. -#### Benefits of using the WebSocket Method +2. **HTTP Streaming (Legacy)** + - This is the original implementation method. + - This method will not support the future BLOB column feature. -* BLOB column support will be added on top of the WebSocket implementation (the HTTP streaming method will not support this). -* If you are using Expo \