FORGE-2185: react-ditto v5 migration follow-ups

- useQuery: add optional subscriptionQuery param, and stop a failed
  subscription registration from overwriting the hook error state so a
  healthy observer is not masked (v5 DQL_RESTRICT_SUBSCRIPTION rejects
  ORDER BY/LIMIT/OFFSET in subscriptions)
- remove the trivially-passing "fails to load wasm" provider tests: init()
  is a process-global singleton so a bad wasm path is never exercised after
  the first init, and provider error-surfacing is already covered by the
  setup-failure tests
- README: document the useRemotePeers/useConnectionStatus presence hooks and
  the v5 subscription constraint

Author: aaronleopold

README.md

@@ -195,6 +195,29 @@ export default function App() {
 }
 ```
 
+### Subscriptions under Ditto v5
+
+Ditto v5 enables `DQL_RESTRICT_SUBSCRIPTION` by default, so a sync subscription
+whose query contains `ORDER BY`, `LIMIT`, or `OFFSET` is rejected
+("Unsupported feature: Limit or Order by"). Because `useQuery` observes and
+subscribes with the same query, an observed query carrying those clauses will
+fail to register a subscription.
+
+When that happens the store observer still works and keeps returning local data,
+and the failure is reported through `onError` (it does **not** populate the
+hook's `error`, which is reserved for query/observer failures). To keep sync
+working, pass a `subscriptionQuery` without the restricted clauses:
+
+```tsx
+const { items } = useQuery<Task>('SELECT * FROM tasks ORDER BY createdAt LIMIT 20', {
+  // Observe the ordered/limited result set, but subscribe to the full set.
+  subscriptionQuery: 'SELECT * FROM tasks',
+})
+```
+
+`subscriptionQuery` is ignored when `localOnly` is `true` (no subscription is
+created).
+
 ## Mutating and on-demand queries with `useExecuteQuery`
 
 `useExecuteQuery` returns an execution function that runs a DQL query on demand.
@@ -222,6 +245,42 @@ Query arguments can be supplied when setting up the hook and/or when calling the
 execution function; when both are provided they are shallow-merged, with the
 execution function's arguments taking precedence.
 
+## Presence
+
+Two hooks expose Ditto's presence information so you can react to the peers and
+transports currently connected.
+
+`useRemotePeers` returns the list of connected remote peers, updating as peers
+join and leave:
+
+```tsx
+import { useRemotePeers } from '@dittolive/react-ditto'
+
+export default function PeerCount() {
+  const { remotePeers } = useRemotePeers()
+
+  return <p>{remotePeers.length} peer(s) connected</p>
+}
+```
+
+`useConnectionStatus` returns a boolean for whether a connection is active over
+a given transport. Pass the transport via `forTransport` (a `ConnectionType`:
+`'Bluetooth'`, `'P2PWiFi'`, `'AccessPoint'`, or `'WebSocket'`):
+
+```tsx
+import { useConnectionStatus } from '@dittolive/react-ditto'
+
+export default function BluetoothIndicator() {
+  const isConnected = useConnectionStatus({ forTransport: 'Bluetooth' })
+
+  return <p>Bluetooth: {isConnected ? 'connected' : 'disconnected'}</p>
+}
+```
+
+Both hooks accept an optional `path` to target a specific Ditto instance when
+several are registered with the `DittoProvider`; omit it to use the first
+registered instance.
+
 ## Quick Start with `vite`
 
 1. Install the library:

src/DittoLazyProvider.spec.tsx

@@ -96,40 +96,6 @@ describe('Ditto Lazy Provider Tests', () => {
     )
   })
 
-  it('should fail to load ditto from web assembly file that does not exist', async function () {
-    const config = testConfig()
-    const initOptions = {
-      webAssemblyModule:
-        '/base/node_modules/@dittolive/ditto/web/ditto-that-does-not-exist.wasm',
-    }
-
-    root.render(
-      <DittoLazyProvider
-        initOptions={initOptions}
-        setup={() => openOfflineDitto(config.databaseID, config.path)}
-      >
-        {({ loading, error }) => {
-          return (
-            <>
-              <div data-testid="loading">{`${loading}`}</div>
-              <div data-testid="error">{error?.message}</div>
-            </>
-          )
-        }}
-      </DittoLazyProvider>,
-    )
-
-    await waitFor(
-      () =>
-        container.querySelector("div[data-testid='loading']").innerHTML ===
-        'false',
-    )
-    await waitFor(
-      () =>
-        container.querySelector("div[data-testid='error']").innerHTML === '',
-    )
-  })
-
   it('should mount the provider with an empty set of Ditto instances.', async () => {
     const config = testConfig()
 

src/DittoProvider.spec.tsx

@@ -97,41 +97,6 @@ describe('Ditto Provider Tests', () => {
     )
   })
 
-  it('should fail to load ditto from web assembly file that does not exist', async function () {
-    const config = testConfig()
-
-    const initOptions = {
-      webAssemblyModule:
-        '/base/node_modules/@dittolive/ditto/web/ditto-that-does-not-exist.wasm',
-    }
-
-    root.render(
-      <DittoProvider
-        initOptions={initOptions}
-        setup={() => openOfflineDitto(config.databaseID, config.path)}
-      >
-        {({ loading, error }) => {
-          return (
-            <>
-              <div data-testid="loading">{`${loading}`}</div>
-              <div data-testid="error">{error?.message}</div>
-            </>
-          )
-        }}
-      </DittoProvider>,
-    )
-
-    await waitFor(
-      () =>
-        container.querySelector("div[data-testid='loading']").innerHTML ===
-        'false',
-    )
-    await waitFor(
-      () =>
-        container.querySelector("div[data-testid='error']").innerHTML === '',
-    )
-  })
-
   it('should mount the provider with the initialized Ditto instance.', async () => {
     const config = testConfig()
 

src/queries/useQuery.spec.tsx

@@ -189,6 +189,59 @@ describe('useQuery', function () {
     await waitFor(() => expect(result.current.error).to.exist)
   })
 
+  it('keeps a working observer when the subscription query is rejected under v5', async () => {
+    const config = testConfig()
+
+    const { result } = renderHook(
+      () =>
+        // `ORDER BY`/`LIMIT` are valid to observe but rejected by
+        // `registerSubscription` under v5's `DQL_RESTRICT_SUBSCRIPTION`.
+        useQuery('select * from foo order by document limit 3', {
+          persistenceDirectory: config.persistenceDirectory,
+          // Swallow the expected subscription failure so it is not logged.
+          onError: () => {},
+        }),
+      {
+        wrapper: wrapper(config.databaseID, config.persistenceDirectory),
+      },
+    )
+
+    await waitFor(() => expect(result.current.items).not.to.be.empty, {
+      timeout: 5000,
+    })
+
+    // The observer succeeded and is serving data...
+    expect(result.current.items).to.have.lengthOf(3)
+    // ...so the rejected subscription must not have set the error state.
+    expect(result.current.error).to.be.null
+    // The subscription itself failed to register.
+    expect(result.current.syncSubscription).to.be.undefined
+  })
+
+  it('registers the subscription with subscriptionQuery when provided', async () => {
+    const config = testConfig()
+
+    const { result } = renderHook(
+      () =>
+        useQuery('select * from foo order by document limit 3', {
+          persistenceDirectory: config.persistenceDirectory,
+          subscriptionQuery: 'select * from foo',
+        }),
+      {
+        wrapper: wrapper(config.databaseID, config.persistenceDirectory),
+      },
+    )
+
+    await waitFor(() => expect(result.current.items).not.to.be.empty, {
+      timeout: 5000,
+    })
+
+    expect(result.current.items).to.have.lengthOf(3)
+    // The unrestricted subscriptionQuery registers cleanly, no error.
+    expect(result.current.error).to.be.null
+    expect(result.current.syncSubscription).to.exist
+  })
+
   it('has the expected failure mode when used with a mutating query', async () => {
     const config = testConfig()
 

src/queries/useQuery.ts

@@ -33,6 +33,19 @@ export interface UseQueryParams<
    * property of the return value will be `undefined`.
    */
   localOnly?: boolean
+  /**
+   * The query used for the {@link SyncSubscription} instead of the observed
+   * `query`. Use this to pass a sync-appropriate query when the observed query
+   * carries clauses that Ditto rejects in subscriptions.
+   *
+   * Ditto v5 enables `DQL_RESTRICT_SUBSCRIPTION` by default, so a subscription
+   * query containing `ORDER BY`, `LIMIT`, or `OFFSET` throws
+   * ("Unsupported feature: Limit or Order by"). When your `query` needs those
+   * clauses for observation, pass an unrestricted `subscriptionQuery` here so
+   * sync still registers. Ignored when {@link UseQueryParams.localOnly} is
+   * `true`.
+   */
+  subscriptionQuery?: string
   /**
    * A callback to run when an error occurs.
    *
@@ -170,11 +183,16 @@ export function useQuery<
       if (!params?.localOnly) {
         try {
           syncSubscriptionRef.current = ditto.sync.registerSubscription(
-            query,
+            params?.subscriptionQuery ?? query,
             params?.queryArguments,
           )
         } catch (e: unknown) {
-          setError(e)
+          // A failed subscription registration must not overwrite `error`: the
+          // observer may have succeeded and be serving data, and under v5's
+          // `DQL_RESTRICT_SUBSCRIPTION` an observed query with
+          // `ORDER BY`/`LIMIT`/`OFFSET` throws here even though observation is
+          // fine. Surface it via `onError` instead of the shared error state,
+          // and let callers pass `subscriptionQuery` to avoid it.
           if (params?.onError) params.onError(e)
           else console.error(e)
         }
@@ -191,7 +209,13 @@ export function useQuery<
     // dependency but ensures that the hook is reset when deep changes occur in
     // `queryArguments`.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [ditto, queryArgumentsVersion, query, params?.localOnly])
+  }, [
+    ditto,
+    queryArgumentsVersion,
+    query,
+    params?.localOnly,
+    params?.subscriptionQuery,
+  ])
 
   useEffect(() => {
     reset().then(() => setIsLoading(false))