more docs

Author: fibo

dflow.ts

@@ -5,6 +5,8 @@
 
 /**
  * Includes JSON data types and `undefined`.
+ *
+ * @see {@link https://fibo.github.io/dflow/#dflowdata}
  */
 export type DflowData =
   | undefined
@@ -19,6 +21,11 @@ export type DflowObject = { [Key in string]: DflowData };
 
 export type DflowArray = DflowData[];
 
+/**
+ * Dflow data types represent values that can be serialized as JSON.
+ *
+ * @see {@link https://fibo.github.io/dflow/#dflowdatatype}
+ */
 export type DflowDataType =
   | "null"
   | "boolean"
@@ -30,7 +37,11 @@ export type DflowDataType =
 // Inputs, outputs, links and nodes.
 // ////////////////////////////////////////////////////////////////////
 
-/** Connects two nodes in the graph. */
+/**
+ * Connects two nodes in the graph.
+ *
+ * @see {@link https://fibo.github.io/dflow/#dflowlink}
+ */
 export type DflowLink = [
   sourceNodeId: string,
   sourcePosition: number,
@@ -46,6 +57,8 @@ export type DflowLink = [
  * ```json
  * { "name": "label", "types": ["string"] }
  * ```
+ *
+ * @see {@link https://fibo.github.io/dflow/#dflowinput}
  */
 export type DflowInput = {
   /** Ignored by Dflow, but could be used by UI. */
@@ -70,6 +83,8 @@ export type DflowInput = {
  * ```json
  * { "name": "sum", "types": ["number"] }
  * ```
+ *
+ * @see {@link https://fibo.github.io/dflow/#dflowoutput}
  */
 export type DflowOutput = {
   /** Ignored by Dflow, but could be used by UI. */
@@ -78,7 +93,11 @@ export type DflowOutput = {
   types: DflowDataType[];
 };
 
-/** Defines a block of code: it can have inputs and outputs. */
+/**
+ * Defines a block of code: it can have inputs and outputs.
+ *
+ * @see {@link https://fibo.github.io/dflow/#dflownode}
+ */
 export type DflowNode = {
   kind: string;
   inputs?: DflowInput[];
@@ -102,6 +121,8 @@ export type DflowGraph = {
  * A `Dflow` represents a program as an executable graph.
  * A graph can contain nodes and links.
  * Nodes are executed, sorted by their connections.
+ *
+ * @see {@link https://fibo.github.io/dflow/#api}
  */
 export class Dflow {
   /** Node definitions indexed by node kind. */
@@ -155,6 +176,11 @@ export class Dflow {
    */
   ERR?: (...data: any[]) => void;
 
+  /**
+   * Dflow constructor requires a list of node definitions which is an `Array<DflowNode>`.
+   *
+   * @see {@link https://fibo.github.io/dflow/#constructor}
+   */
   constructor(nodeDefinitions: Array<DflowNode>) {
     // Add given node definitions, followed by builtin nodes.
     for (const nodeDefinition of nodeDefinitions)
@@ -227,18 +253,20 @@ export class Dflow {
     // Output types are stored in output items.
     const sourceOutput = this.#outputs.get(sourceNodeId)?.[sourcePosition];
     if (!sourceOutput) return false;
-    const sourceTypes = sourceOutput.types;
-
-    // If source can have any type or
-    // target can have any type,
+    // If source can have any type or target can have any type,
     // then source and target are compatible.
-    if (!sourceTypes.length || !targetTypes.length) return true;
-
+    if (!sourceOutput.types.length || !targetTypes.length) return true;
     // Check if target accepts some of the `dataType` source can have.
-    return targetTypes.some((dataType) => sourceTypes.includes(dataType));
+    return targetTypes.some((dataType) =>
+      sourceOutput.types.includes(dataType)
+    );
   }
 
-  /** Create a new node. Returns node id. */
+  /**
+   * Create a new node. Returns node id.
+   *
+   * @see {@link https://fibo.github.io/dflow/#dflow.node}
+   */
   node(kind: string, wantedId?: string): string {
     const nodeDef = this.#nodeDefinitions.get(kind);
     if (!nodeDef) throw new Error("Cannot create node", { cause: { kind } });
@@ -286,7 +314,11 @@ export class Dflow {
     return id;
   }
 
-  /** Delete node or link with given id. */
+  /**
+   * Delete node or link with given id.
+   *
+   * @see {@link https://fibo.github.io/dflow/#dflow.delete}
+   */
   delete(id: string) {
     // Delete node.
     if (this.#kinds.delete(id)) {
@@ -306,7 +338,11 @@ export class Dflow {
     if (targetInput) targetInput.source = undefined;
   }
 
-  /** Create a new data node. Returns node id. */
+  /**
+   * Create a new data node. Returns node id.
+   *
+   * @see {@link https://fibo.github.io/dflow/#dflow.data}
+   */
   data(value: unknown, wantedId?: string): string {
     const id = this.#newId(this.#kinds, "n", wantedId);
     this.#kinds.set(id, "data");
@@ -324,7 +360,11 @@ export class Dflow {
     return id;
   }
 
-  /** Create a new link and connect two nodes. Returns link id. */
+  /**
+   * Create a new link and connect two nodes. Returns link id.
+   *
+   * @see {@link https://fibo.github.io/dflow/#dflow.link}
+   */
   link(
     source: string | [nodeId: string, position: number],
     target: string | [nodeId: string, position: number],
@@ -368,7 +408,11 @@ export class Dflow {
     throw error;
   }
 
-  /** Execute all nodes, sorted by their connections. */
+  /**
+   * Execute all nodes, sorted by their connections.
+   *
+   * @see {@link https://fibo.github.io/dflow/#dflow.run}
+   */
   async run(): Promise<void> {
     // Reset errors.
     this.#errors.clear();
@@ -431,7 +475,11 @@ export class Dflow {
     }
   }
 
-  /** A graph contains nodes and links. */
+  /**
+   * A graph contains nodes and links.
+   *
+   * @see {@link https://fibo.github.io/dflow/#dflow.graph}
+   */
   get graph(): DflowGraph {
     const node: DflowGraph["node"] = {};
     const data: DflowGraph["data"] = {};
@@ -447,12 +495,20 @@ export class Dflow {
     };
   }
 
-  /** Get error messages from last run, indexed by node id. */
+  /**
+   * Get error messages from last run, indexed by node id.
+   *
+   * @see {@link https://fibo.github.io/dflow/#dflow.error}
+   */
   get error(): Record<string, string> {
     return Object.fromEntries(this.#errors.entries());
   }
 
-  /** Get output data of last run, indexed by node id. */
+  /**
+   * Get output data of last run, indexed by node id.
+   *
+   * @see {@link https://fibo.github.io/dflow/#dflow.out}
+   */
   get out(): Record<string, DflowArray> {
     const out: Record<string, DflowArray> = {};
     for (const nodeId of this.#kinds.keys()) {

docs/examples/README.md

@@ -9,5 +9,6 @@ Then you can run examples via an npm script:
 
     npm run example:hello_world
     npm run example:usage
-    npm run example:context
     npm run example:async_nodes
+    npm run example:dynamic_math_nodes
+    npm run example:context

docs/examples/dynamic_math_nodes.ts

@@ -0,0 +1,48 @@
+import { Dflow } from "dflow";
+
+// Generate Dflow nodes for all Math properties and functions.
+
+const mathNodes = Object.getOwnPropertyNames(Math).map((key) => {
+  // @ts-expect-error: expression of type 'string' can't be used to index type 'Math'
+  const item = Math[key];
+
+  const kind = `Math.${key}`;
+  const outputs = [Dflow.output("number")];
+
+  // If the item is a number, create a constant node.
+  if (typeof item === "number") {
+    return {
+      kind,
+      outputs,
+      run: () => item
+    };
+  }
+
+  // If the item is a function, create a function node.
+  if (typeof item === "function") {
+    return {
+      kind,
+      // Get the number of inputs from the function's length property.
+      inputs: Array(item.length).fill(Dflow.input("number")),
+      outputs,
+      run: (...args: number[]) => {
+        return item(...args);
+      }
+    };
+  }
+  // Not needed, just to make TS happy.
+  throw new Error(`Unsupported Math property: ${key}`);
+});
+
+// Create a Dflow instance with the generated node definitions.
+const dflow = new Dflow(mathNodes);
+
+// Compute Math.trunc(Math.E)
+const nodeId1 = dflow.node("Math.E");
+const nodeId2 = dflow.node("Math.trunc");
+dflow.link(nodeId1, nodeId2);
+
+dflow.run();
+
+console.log(dflow.out);
+// { n0: [ 2.718281828459045 ], n1: [ 2 ] }

docs/examples/inject_doc_snippets.ts

@@ -15,7 +15,7 @@ const inputContent = await readFile(filepath, { encoding: "utf8" });
 
 for await (const line of inputContent.split("\n")) {
   const snippetStartMatch = line.match(/START file:([\w_\.\/]+)/);
-  const snippetEndMatch = line.match(/END file:/);
+  const snippetEndMatch = line.match(/END snippet/);
   const isInSnippet = snippetRelativePath !== "";
 
   if (snippetStartMatch) {

docs/examples/snippets/mathPI.ts

@@ -0,0 +1,7 @@
+import { Dflow, type DflowNode } from "dflow";
+
+const MathPI: DflowNode = {
+  kind: "mathPI",
+  outputs: [Dflow.output("number", { name: "π" })],
+  run: () => Math.PI
+};

docs/examples/snippets/print.ts

@@ -0,0 +1,9 @@
+import { Dflow, type DflowNode } from "dflow";
+
+const Print: DflowNode = {
+  kind: "print",
+  inputs: [Dflow.input("string")],
+  run: (message: string) => {
+    console.log(message);
+  }
+};

docs/examples/snippets/sum.ts

@@ -0,0 +1,10 @@
+import { Dflow, type DflowNode } from "dflow";
+
+const Sum: DflowNode = {
+  kind: "sum",
+  inputs: [Dflow.input("number"), Dflow.input("number")],
+  outputs: [Dflow.output("number")],
+  run(a: number, b: number) {
+    return a + b;
+  }
+};