@daml/react: support for multi-{key,query} streams

This follows up on #7066 and exposes the new underlying multi-key and
multi-query stream functions through the React bindings. Following the
same reasoning as in #7066, we therefore deprecate the existing
functions (with no intention of removing them) as they become redundant.

CHANGELOG_BEGIN
* JavaScript Client Libraries: Updated React bindings to expose the
  recent addition of multi-key and multi-query streams in @daml/ledger.
  The singular versions are marked as deprecated as they have become
  redundant.

  The upgrade path for `useStreamQuery` is very straightforward: the
  query factory remains optional, but if specified it should return an
  array of queries instead of a single query. The array may be empty,
  which will return all contracts for that template (similar as not
  passing in a query factory). The return values of `useStreamQuery` and
  `useStreamQueries` are the same type.
  ```
  useStreamQuery(T) --> useStreamQueries(T)
  useStreamQuery(T, () => query, ...) --> useStreamQueries(T, () => [query], ...)
  ```

  The upgrade path for `useStreamFetchByKey` is only slightly more
  involved as the return type of `useStreamFetchByKeys` is a new type
  called `FetchByKeysResult` instead of the existing `FetchResult`.
  `FetchByKeysResult` differs from `FetchResult` in that it contains a
  `contracts` field with an array of contracts instead of a singular
  `contract` field. (It differs from `QueryResult` in that each element of
  the returned array can also be `null`, if there is no corresponding
  active contract.) `QueryResult` instead of a `FetchResult`, i.e. it
  contains a list of contracts rather than a single contract. Call sites
  can be updated as follows:
  ```
  const {loading, contract} = useStreamFetchByKey(T, () => k, ...);

  -->

  const {loading, contracts} = useStreamFetchByKeys(T, () => [k], ...));
  const contract = contracts[0];
  ```
CHANGELOG_END

Author: garyverhaegen-da

docs/source/getting-started/app-architecture.rst

@@ -134,7 +134,7 @@ It uses DAML React hooks to query and update ledger state.
 
 The ``useParty`` hook simply returns the current user as stored in the ``DamlLedger`` context.
 A more interesting example is the ``allUsers`` line.
-This uses the ``useStreamQuery`` hook to get all ``User`` contracts on the ledger.
+This uses the ``useStreamQueries`` hook to get all ``User`` contracts on the ledger.
 (``User.User`` here is an object generated by ``daml codegen js`` - it stores metadata of the ``User`` template defined in ``User.daml``.)
 Note however that this query preserves privacy: only users that follow the current user have their contracts revealed.
 This behaviour is due to the observers on the ``User`` contract being exactly in the list of users that the current user is following.

language-support/ts/daml-react/README.md

@@ -88,6 +88,9 @@ const onClick = reload;
 
 `useStreamQuery`
 ----------------
+
+> Deprecated: prefer `useStreamQueries`
+
 `useStreamQuery` has the same signature as `useQuery`, but it constantly refreshes the results.
 
 ```typescript
@@ -101,6 +104,27 @@ If the query is omitted, all visible contracts of the given template are returne
 const {contracts, loading} = useStreamQuery(ContractTemplate);
 ```
 
+`useStreamQueries`
+------------------
+
+`useStreamQueries` is similar to `useQuery`, except that:
+- It constantly refreshes the results.
+- The factory function is expected to return a list of queries, and the
+  resulting set of contracts is the union of all the contracts that match at
+  least one query.
+- Like `useQuery`, if no factory function is provided, or if the provided
+  function returns an empty array, the set will contain all contracts of that
+  template.
+
+```typescript
+const {contracts, loading} = useStreamQueries(ContractTemplate,
+                                              () => [{field: value}, ...],
+                                              [dependency1, dependency2, ...]);
+```
+
+You can additionally pass in an extra function to handle WebSocket connection
+failures.
+
 `useFetchByKey`
 ---------------
 `useFetchByKey` returns the unique contract of a given template and a given contract key.
@@ -111,13 +135,37 @@ const {contract, loading} = useFetchByKey(ContractTemplate, () => key, [dependen
 
 `useStreamFetchByKey`
 ---------------------
-`useStreamFetchByKey` has the same signature as `useFetchByKey`, but it constantly keeps refreshes
+
+> Deprecated: prefer `useStreamFetchByKeys`
+
+`useStreamFetchByKey` has the same signature as `useFetchByKey`, but it constantly keeps refreshing
 the result.
 
 ```typescript
 const {contract, loading} = useStreamFetchByKey(ContractTemplate, () => key, [dependency1, dependency2, ...]);
 ```
 
+`useStreamFetchByKeys`
+---------------------
+
+`useStreamFetchByKeys` takes a template and a factory that returns a list of
+keys, and returns a list of contracts that correspond to those keys (or null if
+no contract matches the corresponding key). This hook will keep an open
+WebSocket connection and listen for any change to the corresponding contracts.
+
+If the factory function returns an empty array, the hook will similarly produce
+an empty array of contracts.
+
+
+```typescript
+const {contracts, loading} = useStreamFetchByKeys(ContractTemplate,
+                                                  () => [key1, key2, ...],
+                                                  [dependency1, dependency2, ...]);
+```
+
+You can additionally pass in an extra function to handle WebSocket connection
+failures.
+
 ## Advanced Usage
 
 In order to interact as multiple parties or to connect to several ledgers, one needs to create an extra

language-support/ts/daml-react/createLedgerContext.ts

@@ -54,6 +54,20 @@ export type FetchResult<T extends object, K, I extends string> = {
   loading: boolean;
 }
 
+/**
+ * The result of a streaming ``fetchByKeys`` against the ledger.
+ *
+ * @typeparam T The contract template type of the query.
+ * @typeparam K The contract key type of the query.
+ * @typeparam I The template id type.
+ */
+export type FetchByKeysResult<T extends object, K, I extends string> = {
+  /** Contracts of the given contract template and key. */
+  contracts: (CreateEvent<T, K, I> | null)[];
+  /** Indicator for whether the fetch is executing. */
+  loading: boolean;
+}
+
 /**
  * A LedgerContext is a React context that stores information about a DAML Ledger
  * and hooks necessary to use it.
@@ -66,7 +80,9 @@ export type LedgerContext = {
   useFetch: <T extends object, K, I extends string>(template: Template<T, K, I>, contractId: ContractId<T>) => FetchResult<T, K, I>;
   useFetchByKey: <T extends object, K, I extends string>(template: Template<T, K, I>, keyFactory: () => K, keyDeps: readonly unknown[]) => FetchResult<T, K, I>;
   useStreamQuery: <T extends object, K, I extends string>(template: Template<T, K, I>, queryFactory?: () => Query<T>, queryDeps?: readonly unknown[], closeHandler?: (e: StreamCloseEvent) => void) => QueryResult<T, K, I>;
+  useStreamQueries: <T extends object, K, I extends string>(template: Template<T, K, I>, queryFactory?: () => Query<T>[], queryDeps?: readonly unknown[], closeHandler?: (e: StreamCloseEvent) => void) => QueryResult<T, K, I>;
   useStreamFetchByKey: <T extends object, K, I extends string>(template: Template<T, K, I>, keyFactory: () => K, keyDeps: readonly unknown[], closeHandler?: (e: StreamCloseEvent) => void) => FetchResult<T, K, I>;
+  useStreamFetchByKeys: <T extends object, K, I extends string>(template: Template<T, K, I>, keyFactory: () => K[], keyDeps: readonly unknown[], closeHandler?: (e: StreamCloseEvent) => void) => FetchByKeysResult<T, K, I>;
   useReload: () => () => void;
 }
 
@@ -220,6 +236,23 @@ export function createLedgerContext(contextName="DamlLedgerContext"): LedgerCont
     });
   }
 
+  function useStreamQueries<T extends object, K, I extends string>(template: Template<T, K, I>, queryFactory?: () => Query<T>[], queryDeps?: readonly unknown[], closeHandler?: (e: StreamCloseEvent) => void): QueryResult<T, K, I> {
+    return useStream<T, K, I, readonly CreateEvent<T, K, I>[], QueryResult<T, K, I>>({
+      name: "useStreamQueries",
+      template,
+      init: {loading: true, contracts: []},
+      mkStream: (state) => {
+        const query = queryFactory ? queryFactory() : [];
+        const stream = state.ledger.streamQueries(template, query);
+        return [stream, query];
+      },
+      setLoading: (r, b) => ({...r, loading: b}),
+      setData: (r, d) => ({...r, contracts: d}),
+      deps: queryDeps ?? [],
+      closeHandler
+    });
+  }
+
   function useStreamFetchByKey<T extends object, K, I extends string>(template: Template<T, K, I>, keyFactory: () => K, keyDeps: readonly unknown[], closeHandler?: (e: StreamCloseEvent) => void): FetchResult<T, K, I> {
     return useStream<T, K, I, (CreateEvent<T, K, I> | null)[], FetchResult<T, K, I>>({
       name: "useStreamFetchByKey",
@@ -237,10 +270,27 @@ export function createLedgerContext(contextName="DamlLedgerContext"): LedgerCont
     });
   }
 
+  function useStreamFetchByKeys<T extends object, K, I extends string>(template: Template<T, K, I>, keyFactory: () => K[], keyDeps: readonly unknown[], closeHandler?: (e: StreamCloseEvent) => void): FetchByKeysResult<T, K, I> {
+    return useStream<T, K, I, (CreateEvent<T, K, I> | null)[], FetchByKeysResult<T, K, I>>({
+      name: "useStreamFetchByKeys",
+      template,
+      init: {loading: true, contracts: []},
+      mkStream: (state) => {
+        const keys = keyFactory();
+        const stream = state.ledger.streamFetchByKeys(template, keys);
+        return [stream, keys as unknown as object];
+      },
+      setLoading: (r, b) => ({...r, loading: b}),
+      setData: (r, d) => ({...r, contracts: d}),
+      deps: keyDeps,
+      closeHandler
+    });
+  }
+
   const useReload = (): () => void => {
     const state = useDamlState();
     return (): void => state.triggerReload();
   }
 
-  return { DamlLedger, useParty, useLedger, useQuery, useFetch, useFetchByKey, useStreamQuery, useStreamFetchByKey, useReload };
+  return { DamlLedger, useParty, useLedger, useQuery, useFetch, useFetchByKey, useStreamQuery, useStreamQueries, useStreamFetchByKey, useStreamFetchByKeys, useReload };
 }

language-support/ts/daml-react/defaultLedgerContext.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { createLedgerContext, FetchResult, QueryResult, LedgerProps } from "./createLedgerContext";
+import { createLedgerContext, FetchResult, QueryResult, LedgerProps, FetchByKeysResult } from "./createLedgerContext";
 import { ContractId, Party, Template } from '@daml/types';
 import Ledger, { Query, StreamCloseEvent } from '@daml/ledger';
 
@@ -84,6 +84,8 @@ export function useFetchByKey<T extends object, K, I extends string>(template: T
 /**
  * React Hook to query the ledger, the returned result is updated as the ledger state changes.
  *
+ * @deprecated prefer useStreamQueries
+ *
  * @typeparam T The contract template type of the query.
  * @typeparam K The contract key type of the query.
  * @typeparam I The template id type.
@@ -99,9 +101,29 @@ export function useStreamQuery<T extends object, K, I extends string>(template:
   return ledgerContext.useStreamQuery(template, queryFactory, queryDeps, closeHandler);
 }
 
+/**
+ * React Hook to query the ledger, the returned result is updated as the ledger state changes.
+ *
+ * @typeparam T The contract template type of the query.
+ * @typeparam K The contract key type of the query.
+ * @typeparam I The template id type.
+ *
+ * @param template The template of the contracts to match.
+ * @param queryFactory A function returning an array of queries. If no queryFactory is given, or if the given factory returns an empty array, all visible contracts of the given template are returned. Otherwise, returns a union of all the contracts that match at least one of the given queries.
+ * @param queryDeps The dependencies of the query (for which a change triggers an update of the result).
+ * @param closeHandler A callback that will be called if the underlying WebSocket connection fails in an unrecoverable way.
+ *
+ * @return The matching contracts.
+ */
+export function useStreamQueries<T extends object, K, I extends string>(template: Template<T, K, I>, queryFactory?: () => Query<T>[], queryDeps?: readonly unknown[], closeHandler?: (e: StreamCloseEvent) => void): QueryResult<T, K, I> {
+  return ledgerContext.useStreamQueries(template, queryFactory, queryDeps, closeHandler);
+}
+
 /**
  * React Hook to query the ledger. Same as useStreamQuery, but query by contract key instead.
  *
+ * @deprecated prefer useStreamFetchByKeys
+ *
  * @typeparam T The contract template type of the query.
  * @typeparam K The contract key type of the query.
  * @typeparam I The template id type.
@@ -111,12 +133,37 @@ export function useStreamQuery<T extends object, K, I extends string>(template:
  * @param queryDeps The dependencies of the query (for which a change triggers an update of the result).
  * @param closeHandler A callback that will be called if the underlying WebSocket connection fails in an unrecoverable way.
  *
- * @return The matching (unique) contract.
+ * @return The matching (unique) contract, or null.
  */
 export function useStreamFetchByKey<T extends object, K, I extends string>(template: Template<T, K, I>, keyFactory: () => K, keyDeps: readonly unknown[]): FetchResult<T, K, I> {
   return ledgerContext.useStreamFetchByKey(template, keyFactory, keyDeps);
 }
 
+/**
+ * React Hook to query the ledger. Same as useStreamQueries, but query by contract keys instead.
+ *
+ * @typeparam T The contract template type of the query.
+ * @typeparam K The contract key type of the query.
+ * @typeparam I The template id type.
+ *
+ * @param template The template of the contracts to match.
+ * @param queryFactory A function returning an array of contract keys. Contract
+ *        keys must be in "output" format as defined in the [JSON API
+ *        docs](https://docs.daml.com/json-api/lf-value-specification.html),
+ *        i.e., have to match the types generated by the daml-types library.
+ * @param queryDeps The dependencies of the query (for which a change triggers an update of the result).
+ * @param closeHandler A callback that will be called if the underlying
+ *        WebSocket connection fails in an unrecoverable way.
+ *
+ * @return An array of the same length as the given array of keys, where each
+ *         element is either the currently active contract that matches the
+ *         corresponding key, or null if no active contract matches the key in
+ *         the same position.
+ */
+export function useStreamFetchByKeys<T extends object, K, I extends string>(template: Template<T, K, I>, keyFactory: () => K[], keyDeps: readonly unknown[]): FetchByKeysResult<T, K, I> {
+  return ledgerContext.useStreamFetchByKeys(template, keyFactory, keyDeps);
+}
+
 /**
  * React Hook to reload all active queries.
  */