Implements sb.jinja helper

Author: liamgriffiths

examples/jinja.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env -S npx ts-node --transpileOnly
+
+import { Substrate, Box, sb } from "substrate";
+
+async function main() {
+  const SUBSTRATE_API_KEY = process.env["SUBSTRATE_API_KEY"];
+
+  const substrate = new Substrate({
+    apiKey: SUBSTRATE_API_KEY,
+    baseUrl: "https://api-staging.substrate.run",
+  });
+
+  const a = new Box({ value: ["a", "b"] });
+  const b = new Box({ value: { x: "x" } });
+
+  const f = sb.jinja('as=[{% for a in as %}{{a}},{% endfor%}], b={{b["x"]}}, c={{c}}', {
+    as: a.future.value,
+    b: b.future.value,
+    c: "1234",
+  });
+
+  const c = new Box({ value: f });
+
+  const res = await substrate.run(a, b, c);
+  console.log(JSON.stringify(res.json, null, 2));
+}
+main();

src/Future.ts

@@ -122,7 +122,7 @@ export class JQ extends Directive {
     rawValue: (val: JQCompatible) => ({ future_id: null, val }),
   };
 
-  override next(...items: TraceProp[]) {
+  override next(..._items: TraceProp[]) {
     return new JQ(this.query, this.target);
   }
 
@@ -189,6 +189,84 @@ export class StringConcat extends Directive {
   }
 }
 
+type JinjaTemplate =
+  | {
+      future_id: string;
+      val: null;
+    }
+  | { val: string; future_id: null };
+
+export type JinjaVariables = {
+  [key: string]:
+    | string
+    | number
+    | boolean
+    | (string | number | boolean)[]
+    | JinjaVariables
+    | Future<any>;
+};
+
+export class Jinja extends Directive {
+  template: string | Future<string>;
+  variables: JinjaVariables;
+  items: Future<any>[];
+
+  static templateJSON(template: string | Future<string>): JinjaTemplate {
+    return template instanceof Future
+      ? // @ts-ignore
+        { val: null, future_id: template._id }
+      : { val: template, future_id: null };
+  }
+
+  constructor(template: string | Future<string>, variables: JinjaVariables) {
+    super();
+    this.template = template;
+    this.variables = variables;
+
+    // use items to contain all of the futures from the inputs
+    const futures = new Set<Future<any>>();
+    const collectFutures = (obj: any) => {
+      if (Array.isArray(obj)) {
+        for (let item of obj) {
+          collectFutures(item);
+        }
+      }
+
+      if (obj instanceof Future) {
+        futures.add(obj);
+        return;
+      }
+
+      if (obj && typeof obj === "object") {
+        for (let key of Object.keys(obj)) {
+          collectFutures(obj[key]);
+        }
+      }
+    };
+    collectFutures([template, variables]);
+    this.items = Array.from(futures)
+  }
+
+  override next(..._items: any[]) {
+    return new Jinja(this.template, this.variables);
+  }
+
+  override async result(): Promise<string> {
+    return this.template instanceof Future
+      ? // @ts-ignore
+        await this.template._result()
+      : this.template;
+  }
+
+  override toJSON(): any {
+    return {
+      type: "jinja",
+      template: Jinja.templateJSON(this.template),
+      variables: replaceWithPlaceholders(this.variables),
+    };
+  }
+}
+
 export abstract class Future<T> {
   protected _directive: Directive;
   protected _id: string = "";
@@ -263,6 +341,13 @@ export class FutureString extends Future<string> {
     return FutureString.concat(...[this, ...items]);
   }
 
+  static jinja(
+    template: string | FutureString,
+    variables: JinjaVariables,
+  ): FutureString {
+    return new FutureString(new Jinja(template, variables));
+  }
+
   protected override async _result(): Promise<string> {
     return super._result();
   }
@@ -315,3 +400,27 @@ export class FutureAnyObject extends Future<Object> {
     return super._result();
   }
 }
+
+/**
+ * @internal
+ * Given some value, recursively replace `Future` instances with SB Placeholder
+ */
+export const replaceWithPlaceholders = (val: any): any => {
+  if (Array.isArray(val)) {
+    return val.map((item) => replaceWithPlaceholders(item));
+  }
+
+  if (val instanceof Future) {
+    // @ts-expect-error (accessing protected method toPlaceholder)
+    return val.toPlaceholder();
+  }
+
+  if (val && typeof val === "object") {
+    return Object.keys(val).reduce((acc: any, k: any) => {
+      acc[k] = replaceWithPlaceholders(val[k]);
+      return acc;
+    }, {});
+  }
+
+  return val;
+};

src/Node.ts

@@ -1,5 +1,5 @@
 import { idGenerator } from "substrate/idGenerator";
-import { Future, FutureAnyObject, Trace } from "substrate/Future";
+import { Future, FutureAnyObject, Trace, replaceWithPlaceholders } from "substrate/Future";
 import { SubstrateResponse } from "substrate/SubstrateResponse";
 import { NodeError, SubstrateError } from "substrate/Error";
 import { AnyNode } from "substrate/Nodes";
@@ -102,30 +102,10 @@ export abstract class Node {
   }
 
   toJSON() {
-    const withPlaceholders = (obj: any): any => {
-      if (Array.isArray(obj)) {
-        return obj.map((item) => withPlaceholders(item));
-      }
-
-      if (obj instanceof Future) {
-        // @ts-expect-error (accessing protected method toPlaceholder)
-        return obj.toPlaceholder();
-      }
-
-      if (obj && typeof obj === "object") {
-        return Object.keys(obj).reduce((acc: any, k: any) => {
-          acc[k] = withPlaceholders(obj[k]);
-          return acc;
-        }, {});
-      }
-
-      return obj;
-    };
-
     return {
       id: this.id,
       node: this.node,
-      args: withPlaceholders(this.args),
+      args: replaceWithPlaceholders(this.args),
       _should_output_globally: !this.hide,
       ...(this.cache_age && { _cache_age: this.cache_age }),
       ...(this.cache_keys && { _cache_keys: this.cache_keys }),

src/Substrate.ts

@@ -112,7 +112,7 @@ export class Substrate {
    *  @throws {Error} when the client encounters an error making the request.
    */
   async runSerialized(
-    nodes: Node[],
+    nodes: Node[] = [],
     endpoint: string = "/compose",
   ): Promise<SubstrateResponse> {
     const serialized = Substrate.serialize(...nodes);

src/sb.ts

@@ -5,6 +5,7 @@ export const sb = {
   concat: FutureString.concat,
   jq: FutureAnyObject.jq,
   interpolate: FutureString.interpolate,
+  jinja: FutureString.jinja,
   streaming: {
     fromSSEResponse: StreamingResponse.fromReponse,
   },

tests/Future.test.ts

@@ -205,5 +205,31 @@ describe("Future", () => {
       // @ts-expect-error
       expect(i2._result()).resolves.toEqual("hello12");
     });
+
+    describe(".jinja", () => {
+      test(".toJSON", () => {
+        const x = FutureString.concat("1", "2", "3");
+        const f = FutureString.jinja("template: x={{x}} y={{y}}", {
+          x,
+          y: "abc",
+        });
+
+        const json = f.toJSON();
+
+        expect(json).toEqual({
+          // @ts-ignore
+          id: f._id,
+          directive: {
+            type: "jinja",
+            template: { future_id: null, val: "template: x={{x}} y={{y}}" },
+            variables: {
+              // @ts-ignore (_id)
+              x: { __$$SB_GRAPH_OP_ID$$__: x._id },
+              y: "abc",
+            },
+          },
+        });
+      });
+    });
   });
 });