Updates to get, at helpers, tests

Author: liamgriffiths

src/Future.ts

@@ -247,10 +247,24 @@ export class Future<T> {
   }
 }
 
+/**
+ * `concat` combines multiple `string` or `Future<string>` items together into a new `Future<string>`.
+ *
+ * @example
+ *
+ *    let newFuture = concat("string", node.future.someString, "!")
+ */
 export const concat = (...items: (string | Future<string>)[]) => {
   return new Future<string>(new StringConcat(items));
 };
 
+/**
+ * `interpolate` creates a `Future<string>` using interpolate and supports `Future<string>` values.
+ *
+ * @example
+ *
+ *    let newFuture = interpolate`hello ${"world"}, you look ${node.future.niceString} today.`
+ */
 export const interpolate = (
   strings: TemplateStringsArray,
   ...exprs: ({ toString(): string } | Future<string>)[]
@@ -263,6 +277,14 @@ export const interpolate = (
   );
 };
 
+/**
+ * `jq` supports running [jq](https://jqlang.github.io/jq) operations on a `Future` and returns a new `Future<T>`.
+ *
+ * @example
+ *
+ *    let newFuture = jq<string>(node.future.json_object, ".country")
+ *
+ */
 export const jq = <T>(
   future: JQDirectiveTarget,
   query: string,
@@ -272,83 +294,36 @@ export const jq = <T>(
   return new Future<T>(directive);
 };
 
-// export class FutureBoolean extends Future<boolean> {}
-//
-// export class FutureString extends Future<string> {
-//   static concat(...items: (string | FutureString)[]) {
-//     return new FutureString(new StringConcat(items));
-//   }
-//
-//   static interpolate(
-//     strings: TemplateStringsArray,
-//     ...exprs: ({ toString(): string } | FutureString)[]
-//   ): FutureString {
-//     return FutureString.concat(
-//       ...strings
-//         .filter((s) => s !== "") // FIXME: Work around until SubstrateLabs/substrate#514 is live
-//         .flatMap((s: string, i: number) => {
-//           const expr = exprs[i];
-//           return expr
-//             ? [s, expr instanceof Future ? expr : expr.toString()]
-//             : [s];
-//         }),
-//     );
-//   }
-//
-//   concat(...items: (string | FutureString)[]) {
-//     return FutureString.concat(...[this, ...items]);
-//   }
-//
-//   protected override async _result(): Promise<string> {
-//     return super._result();
-//   }
-// }
-//
-// export class FutureNumber extends Future<number> {}
-//
-// export abstract class FutureArray extends Future<any[] | FutureArray> {
-//   abstract at(index: number): Future<any>;
-//
-//   protected override async _result(): Promise<any[] | FutureArray> {
-//     return super._result();
-//   }
-// }
-//
-// export abstract class FutureObject extends Future<Object> {
-//   get(path: string): Future<any> {
-//     const props = parsePath(path);
-//     return props.reduce((future, prop) => {
-//       if (future instanceof FutureAnyObject) {
-//         return typeof prop === "string"
-//           ? future.get(prop as string)
-//           : future.at(prop as number);
-//       } else {
-//         // @ts-ignore
-//         return typeof prop === "string" ? future[prop] : future.at(prop);
-//       }
-//     }, this) as Future<any>;
-//   }
-//
-//   protected override async _result(): Promise<Object> {
-//     return super._result();
-//   }
-// }
-
-/** Represents a future of some unknown type, and so it is equipped with special accessors for getting values at arbitrary paths or indexes */
-export class FutureAny<T> extends Future<T> {
-  get<T>(path: string | Future<string>) {
-    const d =
-      typeof path === "string"
-        ? this._directive.next(...parsePath(path))
-        : this._directive.next(path);
-    return new FutureAny<T>(d);
-  }
-
-  at<T>(index: number | Future<number>) {
-    return new FutureAny<T>(this._directive.next(index));
-  }
+/**
+ * `get` returns a `Future` by selecting a value by path from a `Future<Object>`.
+ *
+ * @example
+ *
+ *    let newFuture = get<string>(node.future, "choices[0].text")
+ *
+ */
+export const get = <T = unknown>(
+  future: Future<Object>,
+  path: string | Future<string>,
+) => {
+  const d =
+    typeof path === "string"
+      ? // @ts-ignore (protected _directive)
+        future._directive.next(...parsePath(path))
+      : // @ts-ignore (protected _directive)
+        future._directive.next(path);
+  return new Future<T>(d);
+};
 
-  protected override async _result(): Promise<T> {
-    return super._result();
-  }
-}
+/**
+ * `at` returns a `Future` item at some index of a `Future` containing an array.
+ *
+ * @example
+ *
+ *    let newFuture = at<string>(node.future.strings, 0);
+ *
+ */
+export const at = <T>(future: Future<T[]>, index: number | Future<number>) => {
+  // @ts-ignore (protected _directive)
+  return new Future<T>(future._directive.next(index));
+};

src/sb.ts

@@ -1,10 +1,12 @@
-import { concat, interpolate, jq } from "substrate/Future";
+import { concat, interpolate, jq, get, at } from "substrate/Future";
 import { StreamingResponse } from "substrate/SubstrateStreamingResponse";
 
 export const sb = {
   concat,
   jq,
   interpolate,
+  get,
+  at,
   streaming: {
     fromSSEResponse: StreamingResponse.fromReponse,
   },

tests/Future.test.ts

@@ -4,10 +4,10 @@ import "substrate/nodejs/polyfill";
 import { expect, describe, test } from "vitest";
 import {
   Future,
-  FutureString,
-  FutureNumber,
   Trace,
   StringConcat,
+  concat,
+  interpolate,
 } from "substrate/Future";
 import { Node } from "substrate/Node";
 import { SubstrateResponse } from "substrate/SubstrateResponse";
@@ -43,9 +43,9 @@ describe("Future", () => {
   });
 
   test(".referencedFutures", () => {
-    const a = new FutureString(new Trace([], node()));
-    const b = new FutureString(new Trace([], node()));
-    const c = new FutureString(new StringConcat([a, b]));
+    const a = new Future<string>(new Trace([], node()));
+    const b = new Future<string>(new Trace([], node()));
+    const c = new Future<string>(new StringConcat([a, b]));
     const f = new FooFuture(new StringConcat([c, "d"]));
 
     // @ts-expect-error (accessing protected property)
@@ -54,8 +54,8 @@ describe("Future", () => {
 
   describe("Trace (Directive)", () => {
     test(".next", () => {
-      const s = new FutureString(new Trace([], node("123")));
-      const n = new FutureNumber(new Trace([], node("456")));
+      const s = new Future<string>(new Trace([], node("123")));
+      const n = new Future<number>(new Trace([], node("456")));
       const d = new Trace(["a", 1, s, n], node("NodeId"));
       const d2 = d.next("b", 2);
 
@@ -75,16 +75,16 @@ describe("Future", () => {
       expect(t1.result()).resolves.toEqual("result1");
 
       // when the trace contains futures, they get resolved
-      const fs = new FutureString(new Trace([], staticNode("b")));
-      const fn = new FutureNumber(new Trace([], staticNode(1)));
+      const fs = new Future<string>(new Trace([], staticNode("b")));
+      const fn = new Future<number>(new Trace([], staticNode(1)));
       const n2 = staticNode({ a: [{ b: [undefined, "result2"] }] });
       const t2 = new Trace(["a", 0, fs, fn], n2);
       expect(t2.result()).resolves.toEqual("result2");
     });
 
     test(".toJSON", () => {
-      const s = new FutureString(new Trace([], node()), "123");
-      const n = new FutureNumber(new Trace([], node()), "456");
+      const s = new Future<string>(new Trace([], node()), "123");
+      const n = new Future<number>(new Trace([], node()), "456");
       const d = new Trace(["a", 1, s, n], node("NodeId"));
 
       expect(d.toJSON()).toEqual({
@@ -94,14 +94,15 @@ describe("Future", () => {
           Trace.Operation.key("attr", "a"),
           Trace.Operation.key("item", 1),
           Trace.Operation.future("attr", "123"),
-          Trace.Operation.future("item", "456"),
+          Trace.Operation.future("attr", "456"), // LIAM_TODO: there isn't a way to distinguish at runtime using static types
+          // Trace.Operation.future("item", "456"),
         ],
       });
     });
 
     test(".referencedFutures", () => {
-      const s = new FutureString(new Trace([], node()));
-      const n = new FutureNumber(new Trace([], node()));
+      const s = new Future<string>(new Trace([], node()));
+      const n = new Future<number>(new Trace([], node()));
       const d = new Trace(["a", 1, s, n], node("NodeId"));
 
       expect(d.referencedFutures()).toEqual([s, n]);
@@ -110,8 +111,8 @@ describe("Future", () => {
 
   describe("StringConcat (Directive)", () => {
     test(".next", () => {
-      const s = new FutureString(new Trace([], node()));
-      const s2 = new FutureString(new Trace([], node()));
+      const s = new Future<string>(new Trace([], node()));
+      const s2 = new Future<string>(new Trace([], node()));
       const d = new StringConcat(["a", s]);
       const d2 = d.next("b", s2);
 
@@ -128,13 +129,13 @@ describe("Future", () => {
       expect(s1.result()).resolves.toEqual("ab");
 
       // when the items includes primitive values and futures
-      const fs = new FutureString(new Trace([], staticNode("b")));
+      const fs = new Future<string>(new Trace([], staticNode("b")));
       const s2 = new StringConcat(["a", fs]);
       expect(s2.result()).resolves.toEqual("ab");
     });
 
     test(".toJSON", () => {
-      const s = new FutureString(new Trace([], node()), "123");
+      const s = new Future<string>(new Trace([], node()), "123");
       const d = new StringConcat(["a", s]);
 
       expect(d.toJSON()).toEqual({
@@ -147,44 +148,37 @@ describe("Future", () => {
     });
 
     test(".referencedFutures", () => {
-      const a = new FutureString(new Trace([], node()));
-      const b = new FutureString(new Trace([], node()));
-      const c = new FutureString(new StringConcat([a, b]));
+      const a = new Future<string>(new Trace([], node()));
+      const b = new Future<string>(new Trace([], node()));
+      const c = new Future<string>(new StringConcat([a, b]));
       const d = new StringConcat([c, "d"]);
 
       expect(d.referencedFutures()).toEqual([c, a, b]);
     });
   });
 
-  describe("FutureString", () => {
-    test(".concat (static)", () => {
-      const s = FutureString.concat("a");
-      expect(s).toBeInstanceOf(FutureString);
-      // @ts-expect-error (protected access)
-      expect(s._directive).toEqual(new StringConcat(["a"]));
-    });
-
-    test(".concat", () => {
-      const s1 = FutureString.concat("a");
-      const s2 = s1.concat("b", "c");
-      expect(s2).toBeInstanceOf(FutureString);
+  describe("Strings", () => {
+    test("concat", () => {
+      const s1 = concat("a");
+      const s2 = concat(s1, "b", "c");
+      expect(s2).toBeInstanceOf(Future);
       // @ts-expect-error (protected access)
       expect(s2._directive).toEqual(new StringConcat([s1, "b", "c"]));
     });
 
-    test(".interpolate", async () => {
+    test("interpolate", async () => {
       const world = "world";
       const nice = "nice";
-      const i1 = FutureString.interpolate`hello ${world}, you look ${nice} today.`;
+      const i1 = interpolate`hello ${world}, you look ${nice} today.`;
 
       // @ts-expect-error
       expect(i1._result()).resolves.toEqual(
         "hello world, you look nice today.",
       );
 
-      const f1 = FutureString.concat("texas", " ", "sun");
-      const f2 = FutureString.concat("texas", " ", "moon");
-      const i2 = FutureString.interpolate`~~ ${f1} x ${f2} ~~`;
+      const f1 = concat("texas", " ", "sun");
+      const f2 = concat("texas", " ", "moon");
+      const i2 = interpolate`~~ ${f1} x ${f2} ~~`;
 
       // @ts-expect-error
       expect(i2._result()).resolves.toEqual("~~ texas sun x texas moon ~~");

tests/Node.test.ts

@@ -1,6 +1,6 @@
 import { expect, describe, test } from "vitest";
 import { Node } from "substrate/Node";
-import { FutureString, Trace, StringConcat } from "substrate/Future";
+import { Future, Trace, StringConcat, get } from "substrate/Future";
 
 class FooNode extends Node {}
 
@@ -13,10 +13,10 @@ describe("Node", () => {
   });
 
   test(".toJSON", () => {
-    const a = new FutureString(new Trace([], new FooNode({})));
-    const b = new FutureString(new Trace([], new FooNode({})));
-    const c = new FutureString(new StringConcat([a, b]));
-    const d = new FutureString(new StringConcat([c, "d"]));
+    const a = new Future<string>(new Trace([], new FooNode({})));
+    const b = new Future<string>(new Trace([], new FooNode({})));
+    const c = new Future<string>(new StringConcat([a, b]));
+    const d = new Future<string>(new StringConcat([c, "d"]));
     const n = new FooNode({ prompt: d });
 
     expect(n.toJSON()).toEqual({
@@ -31,13 +31,13 @@ describe("Node", () => {
   });
 
   test(".references", () => {
-    const a = new FooNode({ x: "x" }, { id: "a" });
-    const f1 = a.future.get("x");
-    const f2 = a.future.get("y");
-    const b = new FooNode({ x: f1, z: f2 }, { id: "b" });
-    const f3 = b.future.get("x");
-    const c = new FooNode({ x: f3 }, { id: "c" });
-    const d = new FooNode({}, { id: "d", depends: [c] });
+    const a = new FooNode({ x: "x" });
+    const f1 = get(a.future, "x");
+    const f2 = get(a.future, "y");
+    const b = new FooNode({ x: f1, z: f2 });
+    const f3 = get(b.future, "x");
+    const c = new FooNode({ x: f3 });
+    const d = new FooNode({}, { depends: [c] });
 
     // @ts-ignore (protected)
     const { nodes, futures } = d.references();

tests/Substrate.test.ts

@@ -10,7 +10,7 @@ describe("Substrate", () => {
     test("when there are nodes and futures", () => {
       const a = new FooNode({ a: 123 }, { id: "a" });
       const b = new FooNode(
-        { b: a.future.get("x"), c: sb.concat("x", "y") },
+        { b: sb.get(a.future, "x"), c: sb.concat("x", "y") },
         { id: "b" },
       );
 
@@ -79,7 +79,7 @@ describe("Substrate", () => {
 
     test("when there are nodes and futures, but we only supply the 'final' node", () => {
       const a = new FooNode({ a: 123 });
-      const b = new FooNode({ b: a.future.get("x"), c: sb.concat("x", "y") });
+      const b = new FooNode({ b: sb.get(a.future, "x"), c: sb.concat("x", "y") });
 
       // Here we're only supplying `b` and relying on the graph-serialiation to find `a`
       const result = Substrate.serialize(b);