add multi-{key,query} stream to daml-ledger

This is an attempt to address #7034 & #7036. Strictly speaking, this
does not match their acceptance criteria, as this only supports multiple
queries, not mixed templates.

Because the two new functions can cover the exact same use cases (and
more) as the existing `streamQuery` and `streamFetchByKey`, the latter
are deprecated. The deprecation cycle I suggest is to deprecate them
immediately by annotating them as such in the documentation (done on
this PR).

That's it. I do not think we ever need to actually remove them, nor to
make them print annoying warnings or anything. There is nothing wrong
with the functions as they stand, they just don't fit in the API
anymore.

We could, at some point, move them to a separate documentation page, or
to the boottm of the existing one, but I feel even removing them from
the documentation is unnecessary.

CHANGELOG_BEGIN

- [JavaScript Client Libraries] Two new methods have been added to
  `daml-ledger`: `streamQueries` and `streamFetchByKeys`. They are
  similar to the existing singular versions, except they can take
  multiple queries and multiple keys, respectively, and return a union
  of what the corresponding individual queries/keys would have. Because
  these new functions can do everything the existing ones can, we are
  deprecating the latter, though there is no plan to remove them.

  Upgrade path is straightforward:

  ```
  streamQuery(t); => streamQueries(t, []);
  streamQuery(t, undefined); => streamQueries(t, []);
  streamQuery(t, q); => streamQueries(t, [q]);
  streamFetchByKey(t, k); => streamFetchByKey(t, [k]);
  ```

  There is one caveat, though: `streamFetchByKeys` is a little bit less
  lenient in the format in which it expects the key. If your existing
  code was conforming to the generated TypeScript code we provide,
  everything should keep working, but if you were using plain JS or
  bypassing the TS type system, it is possible that you used to
  construct keys that will no longer be accepted. The new function
  requires all keys to be given in the _output_ format of the JSON API,
  which is a little bit more strict than the general JSON <-> LF
  conversion rules.

CHANGELOG_END

Author: garyverhaegen-da

language-support/ts/codegen/tests/daml/Main.daml

@@ -153,3 +153,17 @@ data VoidRecord = VoidRecord with
 
 data VoidEnum = VoidEnum VoidEnum
   deriving (Eq, Show)
+
+template Counter with
+    p: Party
+    t: Text
+    c: Int
+  where
+    signatory p
+    key (p, t): (Party, Text)
+    maintainer key._1
+    controller p can
+      preconsuming Change: ContractId Counter
+        with n: Int
+        do
+          create Counter {c = n, ..}

language-support/ts/codegen/tests/ts/build-and-lint-test/src/__tests__/test.ts

@@ -312,3 +312,146 @@ test('create + fetch & exercise', async () => {
   const nonTopLevelContracts = await aliceLedger.query(buildAndLint.Lib.Mod.NonTopLevel);
   expect(nonTopLevelContracts).toEqual([nonTopLevelContract]);
 });
+
+test("multi-{key,query} stream", async () => {
+  const ledger = new Ledger({token: ALICE_TOKEN, httpBaseUrl: httpBaseUrl()});
+
+  function collect<T extends object, K, I extends string, State>(stream: Stream<T, K, I, State>): [State, readonly Event<T, K, I>[]][] {
+    const res = [] as [State, readonly Event<T, K, I>[]][];
+    stream.on('change', (state, events) => res.push([state, events]));
+    return res;
+  }
+  async function create(t: string): Promise<void> {
+    await ledger.create(buildAndLint.Main.Counter, {p: ALICE_PARTY, t, c: "0"});
+  }
+  async function update(t: string, c: number): Promise<void> {
+    await ledger.exerciseByKey(buildAndLint.Main.Counter.Change, {_1: ALICE_PARTY, _2: t}, {n: c.toString()});
+  }
+  async function archive(t: string): Promise<void> {
+    await ledger.archiveByKey(buildAndLint.Main.Counter, {_1: ALICE_PARTY, _2: t});
+  }
+  async function close<T extends object, K, I extends string, State>(s: Stream<T, K, I, State>): Promise<void> {
+    const p = pEvent(s, 'close');
+    s.close();
+    await p;
+  }
+  // Add support for comparison queries
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const streamQueriesWithComparison = ledger.streamQueries.bind(ledger) as (t: any, qs: any) => any;
+  const q = streamQueriesWithComparison(
+    buildAndLint.Main.Counter,
+    [{p: ALICE_PARTY, t: "included"},
+     {c: {"%gt": 5}}]);
+  const queryResult = collect(q);
+  const ks = ledger.streamFetchByKeys(
+    buildAndLint.Main.Counter,
+    [{_1: ALICE_PARTY, _2: "included"},
+     {_1: ALICE_PARTY, _2: "byKey"},
+     {_1: ALICE_PARTY, _2: "included"}]);
+  const byKeysResult = collect(ks);
+
+  await create("included");
+  await create("byKey");
+  await create("excluded");
+
+  await update("excluded", 10);
+  await update("byKey", 3);
+  await update("byKey", 6);
+  await update("excluded", 3);
+  await update("included", 2);
+
+  await archive("included");
+  await archive("byKey");
+
+  await create("included");
+
+
+  await close(q);
+  await close(ks);
+
+  expect(queryResult).toMatchObject(
+    [[[{"payload": {"c": "0", "t": "included"}}],
+      [{"created": {"payload": {"c": "0", "t": "included"}}}]],
+
+     [[{"payload": {"c": "0", "t": "included"}},
+       {"payload": {"c": "10", "t": "excluded"}}],
+      [{"archived": {}},
+       {"created": {"payload": {"c": "10", "t": "excluded"}}}]],
+
+     [[{"payload": {"c": "0", "t": "included"}},
+       {"payload": {"c": "10", "t": "excluded"}}],
+      [{"archived": {}}]],
+
+     [[{"payload": {"c": "0", "t": "included"}},
+       {"payload": {"c": "10", "t": "excluded"}},
+       {"payload": {"c": "6", "t": "byKey"}}],
+      [{"archived": {}},
+       {"created": {"payload": {"c": "6", "t": "byKey"}}}]],
+
+     [[{"payload": {"c": "0", "t": "included"}},
+       {"payload": {"c": "6", "t": "byKey"}}],
+      [{"archived": {}}]],
+
+     [[{"payload": {"c": "6", "t": "byKey"}},
+       {"payload": {"c": "2", "t": "included"}}],
+      [{"archived": {}},
+       {"created": {"payload": {"c": "2", "t": "included"}}}]],
+
+     [[{"payload": {"c": "6", "t": "byKey"}}],
+      [{"archived": {}}]],
+
+     [[],
+      [{"archived": {}}]],
+
+     [[{"payload": {"c": "0", "t": "included"}}],
+      [{"created": {"payload": {"c": "0", "t": "included"}}}]]]
+
+  );
+
+  expect(byKeysResult).toMatchObject(
+    [[[{"payload": {"c": "0", "t": "included"}},
+       null,
+       {"payload": {"c": "0", "t": "included"}}],
+      [{"created": {"payload": {"c": "0", "t": "included"}}}]],
+
+     [[{"payload": {"c": "0", "t": "included"}},
+       {"payload": {"c": "0", "t": "byKey"}},
+       {"payload": {"c": "0", "t": "included"}}],
+      [{"created": {"payload": {"c": "0", "t": "byKey"}}}]],
+
+     [[{"payload": {"c": "0", "t": "included"}},
+       {"payload": {"c": "3", "t": "byKey"}},
+       {"payload": {"c": "0", "t": "included"}}],
+      [{"archived": {}},
+       {"created": {"payload": {"c": "3", "t": "byKey"}}}]],
+
+     [[{"payload": {"c": "0", "t": "included"}},
+       {"payload": {"c": "6", "t": "byKey"}},
+       {"payload": {"c": "0", "t": "included"}}],
+      [{"archived": {}},
+       {"created": {"payload": {"c": "6", "t": "byKey"}}}]],
+
+     [[{"payload": {"c": "2", "t": "included"}},
+       {"payload": {"c": "6", "t": "byKey"}},
+       {"payload": {"c": "2", "t": "included"}}],
+      [{"archived": {}},
+       {"created": {"payload": {"c": "2", "t": "included"}}}]],
+
+     [[null,
+       {"payload": {"c": "6", "t": "byKey"}},
+       null],
+      [{"archived": {}}]],
+
+     [[null,
+       null,
+       null],
+      [{"archived": {}}]],
+
+     [[{"payload": {"c": "0", "t": "included"}},
+       null,
+       {"payload": {"c": "0", "t": "included"}}],
+      [{"created": {"payload": {"c": "0", "t": "included"}}}]]
+    ]
+  );
+
+});

language-support/ts/daml-ledger/BUILD.bazel

@@ -23,9 +23,11 @@ da_ts_library(
     deps = [
         "//language-support/ts/daml-types",
         "@language_support_ts_deps//@mojotech/json-type-validation",
+        "@language_support_ts_deps//@types/deep-equal",
         "@language_support_ts_deps//@types/jest",
         "@language_support_ts_deps//@types/ws",
         "@language_support_ts_deps//cross-fetch",
+        "@language_support_ts_deps//deep-equal",
         "@language_support_ts_deps//events",
         "@language_support_ts_deps//isomorphic-ws",
         "@language_support_ts_deps//jest-mock-console",

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

@@ -54,10 +54,21 @@ of that template visible for the submitting party are returned.
 
 `streamQuery`
 -------------
-Retrieve a consolidated stream of events for a given template and query. The accumulated state is
-the current set of active contracts matching the query. An event can be a `CreateEvent` or an
-`ArchiveEvent`. When no `query` argument is given, all events visible to the submitting party are
-returned.
+
+> Deprecated: prefer `streamQueries`.
+
+Retrieve a consolidated stream of events for a given template and optional
+query. The accumulated state is the current set of active contracts matching
+the query if one was given; if the function was called without a query
+argument, or the query argument was `undefined`, the accumulated state will
+instead contain all of the active contracts for the given template.
+
+`streamQueries`
+---------------
+Retrieve a consolidated stream of events for a given template and queries. The
+accumulated state is the current set of active contracts matching at least one
+of the given queries, or all contracts for the given template if no query is
+given.
 
 `fetch`
 -------
@@ -69,11 +80,31 @@ Fetch a contract identified by its contract key.
 
 `streamFetchByKey`
 ------------------
-Retrieve a consolidated stream of `CreateEvent`'s for a given template and contract key.
 
+> Deprecated: prefer `streamFetchByKeys`.
+
+Retrieve a consolidated stream of `CreateEvent`'s for a given template and
+contract key. The accumulated state is either the `CreateEvent` for the active
+contract matching the given key, or null if there is no currently-active
+contract for the given key.
+
+`streamFetchByKeys`
+-------------------
+Retrieve a consolidated stream of `CreateEvent`'s for a given template and
+contract keys. The accumulated state is a vector of the same length as the
+given vector of keys, where each element is the CreateEvent for the current
+active contract of the corresponding key (element-wise), or null if there is no
+current active contract for that key.
+
+Note: the given `key` objects will be compared for (deep) equality with the
+values returned by the API. As such, they have to be given in the "output"
+format of the API, including the values of `encodeDecimalAsString` and
+`encodeInt64AsString`. See [the JSON API docs for details][0].
 
 ## Source
 https://github.com/digital-asset/daml/tree/master/language-support/ts/daml-ledger
 
 ## License
 [Apache-2.0](https://github.com/digital-asset/daml/blob/master/LICENSE)
+
+[0]: https://docs.daml.com/json-api/lf-value-specification.html