KitBuilder.wrap so that we can call any JS library (#191)

With this we are able to import any JS lib and
then make nodes out of them.

+ Maps input names to argument positions in the function
+ Maps output to `result` if Number, String, Array
+ Maps output to Node Output names if an Object.

Author: PaulKinlan

seeds/breadboard/.eslintrc

@@ -0,0 +1,10 @@
+{
+  "rules": {
+    "@typescript-eslint/ban-types": ["warn", {
+      "types": {
+        "Function": false
+      },
+      "extendDefaults": true
+    }]
+  }
+}

seeds/breadboard/docs/libraries-as-kits.md

@@ -0,0 +1,82 @@
+# Wrapping a library as a Kit
+
+If you aren't familiar with the concept of Breadboard Kits, please read the [Kits](kits.md) guide first.
+
+## Why wrap a library as a Kit?
+
+Breadboard Kits are a great way to share functionality with other Breadboard users. The `KitBuilder` class is a great tool for encapsulating your own logic in to something that can be imported in to your Breadboards.
+
+Sometimes though you might want to import a library directly from `npm` and not have to worry about creating custom `InputValues` and `OutputValues` and then handling the mapping of those values to the library's API.
+
+`KitBuilder.wrap` solves this for you. It allows you to use any functions from any library in your project as a Breadboard Kit and returns a strongly typed `Kit` that you can add in to your Breadboard.
+
+## How to wrap a library
+
+We are going to create a little example that validates a JSON object against a JSON schema. We will use the [jsonschema](https://www.npmjs.com/package/jsonschema) library from `npm`.
+
+### Step 1: Create a board
+
+```TypeScript
+const board = new Board({
+  title: "Test Echo",
+  description: "Test Breadboard Kit",
+  version: "0.0.1",
+});
+```
+
+### Step 2: Import the library
+
+```TypeScript
+const js = await import("jsonschema");
+```
+
+### Step 3: Wrap the library and add it to the board
+
+```TypeScript 
+const MyKit = KitBuilder.wrap({ url: "test" }, { ...js.default });
+// The validate method is the only method that will be exposed from the library (it's the only function, the other properties are just Classes)
+
+const myKit = board.addKit(MyKit);
+```
+
+### Step 4: Use the library in a board
+
+We are going to use the `validate` function. The `validate` function takes 3 arguments: 'instance', 'schema', and 'options'. We will use 3 `input` nodes to supply these arguments.
+
+```TypeScript
+
+const inputA = board.input();
+const inputB = board.input();
+const inputC = board.input();
+
+const validateNode = myKit.validate();
+
+inputA.wire("a->instance", validateNode);
+inputB.wire("b->schema", validateNode);
+inputC.wire("c->options", validateNode);
+```
+
+Now that we have the inputs wired up, we can wire the wire the `validateNode` to the output of the board.
+
+In this case, we need to look to see if there are any values on the `errors` value.
+
+
+
+```TypeScript
+// result because it's just a string from a dynamic function
+validateNode.wire("errors->", board.output());
+```
+
+Finally, we run the board with the parameters for the inputs, and wait until there is one output.
+
+```TypeScript
+const output = await board.runOnce({
+  "a": { "hello": "world" },
+  "b": { "type": "object" },
+  "c": { allowUnknownAttributes: true }
+});
+
+console.log(output); // { errors: [] } ! YAY.
+```
+
+Yay. We have successfully wrapped a library as a Breadboard Kit.

seeds/breadboard/src/kits/builder.ts

@@ -11,6 +11,7 @@ import {
   Kit,
   KitConstructor,
   NodeFactory,
+  NodeHandler,
   NodeHandlers,
   OutputValues,
 } from "../types.js";
@@ -23,6 +24,10 @@ export type KitBuilderOptions = {
   namespacePrefix?: string;
 };
 
+/* eslint-disable  @typescript-eslint/no-explicit-any */
+type FunctionsKeysOnly<T> = ({ [P in keyof T]: T[P] extends (...args: any[]) => void ? P : never })[keyof T];
+type FunctionsOnly<T> = Pick<T, FunctionsKeysOnly<T>>;
+
 export class KitBuilder {
   url: string;
   title?: string;
@@ -98,4 +103,43 @@ export class KitBuilder {
       }
     } as KitConstructor<GenericKit<Handlers>>;
   }
+
+  static wrap<F extends Record<string, Function>>(params: KitBuilderOptions, functions: F): KitConstructor<GenericKit<{ [x in keyof FunctionsOnly<F>]: NodeHandler }>> {
+    
+    const createHandler = (previous: NodeHandlers, current: [string, Function]) => {
+      const [name, fn] = current;
+
+      previous[name] = {
+        invoke: async (inputs: InputValues) => {
+          const argNames = fn.toString().match(/\((.*?)\)/)?.[1].split(",") ?? [];
+
+          // Validate the input names.
+          for (const argName of argNames) {
+            if (argName.trim() in inputs === false) { // Maybe we should use hasOwnProperty here?
+              throw new Error(`Missing input: ${argName.trim()}. Valid inputs are: ${Object.keys(inputs).join(", ")}`);
+            }
+          }
+
+          const args = argNames.map((argName: string) => inputs[argName.trim()]);
+
+          const results = await fn(...args);
+
+          if (typeof results !== "object" || Array.isArray(results)) {
+            // Number, Boolean, Array, String, will output to `result`.
+            return { result: results };
+          }
+
+          // Objects will destructured into the output.
+          return { ...results };
+        }
+      };
+      return previous;
+    }
+
+    const handlers = Object.entries(functions).reduce<NodeHandlers>(createHandler, {});
+
+    const builder = new KitBuilder(params);
+
+    return builder.build(handlers) as KitConstructor<GenericKit<{ [x in keyof FunctionsOnly<F>]: NodeHandler }>>;
+  }
 }

seeds/breadboard/tests/kits.ts

@@ -0,0 +1,181 @@
+import test from "ava";
+import { KitBuilder } from "../src/kits/builder.js";
+import { Board } from "../src/board.js";
+
+test("KitBuilder can wrap a function", async (t) => {
+
+  // A normal function that will be wrapped.
+  const echo = (input: string) => input;
+  const test = (input: string) => input;
+
+  const MyKit = KitBuilder.wrap({ url: "test" }, { echo, test });
+
+  const board = new Board({
+    title: "Test Echo",
+    description: "Test Breadboard Kit",
+    version: "0.0.1",
+  });
+
+  const myKit = board.addKit(MyKit);
+
+  t.true(myKit.echo instanceof Function);
+  t.true(myKit.test instanceof Function);
+});
+
+
+test("KitBuilder can call a function that returns a string", async (t) => {
+
+  // A normal function that will be wrapped.
+  const echo = (echo_this: string) => echo_this;
+
+  const MyKit = KitBuilder.wrap({ url: "test" }, { echo });
+
+  const board = new Board({
+    title: "Test Echo",
+    description: "Test Breadboard Kit",
+    version: "0.0.1",
+  });
+
+  const myKit = board.addKit(MyKit);
+
+  const input = board.input();
+  const echoNode = myKit.echo();
+
+  input.wire("an_input->echo_this", echoNode);
+  // result because it's just a string from a dynamic function
+  echoNode.wire("result->an_output", board.output());
+
+  const output = await board.runOnce({
+    "an_input": "hello world"
+  });
+
+  t.is((<string>output["an_output"]), "hello world");
+
+});
+
+test("KitBuilder can call a function that returns an object", async (t) => {
+
+  // A normal function that will be wrapped.
+  const echo = (echo_this: string) => {
+    return { "out": echo_this, "other": "stuff" }
+  };
+
+  const MyKit = KitBuilder.wrap({ url: "test" }, { echo });
+
+  const board = new Board({
+    title: "Test Echo",
+    description: "Test Breadboard Kit",
+    version: "0.0.1",
+  });
+
+  const myKit = board.addKit(MyKit);
+
+  const input = board.input();
+  const echoNode = myKit.echo();
+
+  input.wire("an_input->echo_this", echoNode);
+  // result because it's just a string from a dynamic function
+  echoNode.wire("out->an_output", board.output());
+
+  const output = await board.runOnce({
+    "an_input": "hello world"
+  });
+
+  t.is((<string>output["an_output"]), "hello world");
+
+});
+
+test("KitBuilder can call a function that has more than one input", async (t) => {
+
+  // A normal function that will be wrapped.
+  const add = (a: number, b: number) => {
+    return a + b;
+  };
+
+  const MyKit = KitBuilder.wrap({ url: "test" }, { add });
+
+  const board = new Board({
+    title: "Test Echo",
+    description: "Test Breadboard Kit",
+    version: "0.0.1",
+  });
+
+  const myKit = board.addKit(MyKit);
+
+  const inputA = board.input();
+  const inputB = board.input();
+
+  const addNode = myKit.add();
+
+  inputA.wire("a->a", addNode);
+  inputB.wire("b->b", addNode);
+  // result because it's just a string from a dynamic function
+  addNode.wire("result->", board.output());
+
+  const output = await board.runOnce({
+    "a": 1,
+    "b": 2
+  });
+
+  t.is((<number>output["result"]), 3);
+});
+
+test("KitBuilder can call a function from an external import", async (t) => {
+
+  const js = await import("jsonschema");
+
+  // Wrap the jsonschema validate function in a kit and expose function as a node.
+  const MyKit = KitBuilder.wrap({ url: "test" }, { validate: js.default.validate });
+
+  const board = new Board({
+    title: "Test Echo",
+    description: "Test Breadboard Kit",
+    version: "0.0.1",
+  });
+
+  const myKit = board.addKit(MyKit);
+
+  const inputA = board.input();
+  const inputB = board.input();
+  const inputC = board.input();
+
+  const validateNode = myKit.validate();
+
+  inputA.wire("a->instance", validateNode);
+  inputB.wire("b->schema", validateNode);
+  inputC.wire("c->options", validateNode);
+
+  // result because it's just a string from a dynamic function
+  validateNode.wire("errors->", board.output());
+
+  const output = await board.runOnce({
+    "a": { "hello": "world" },
+    "b": { "type": "object" },
+    "c": { allowUnknownAttributes: true }
+  });
+
+  const result = js.default.validate({ "hello": "world" }, { "type": "object" }, { allowUnknownAttributes: true });
+
+  t.is(((<Array<string>>output["errors"]).length), result.errors.length);
+});
+
+test("KitBuilder can splat all the functions in the extenral library and make nodes", async (t) => {
+
+  const js = await import("jsonschema");
+
+  // Wrap the jsonschema validate function in a kit and expose function as a node.
+  const MyKit = KitBuilder.wrap({ url: "test" }, { ...js.default });
+
+  const board = new Board({
+    title: "Test Echo",
+    description: "Test Breadboard Kit",
+    version: "0.0.1",
+  });
+
+  const myKit = board.addKit(MyKit);
+
+  myKit.validate()
+
+  // We really need to pick a library with more than one function.
+  t.true(myKit.validate instanceof Function);
+});