piemachine 0.0.1

package/README.md

@@ -0,0 +1,173 @@
+# pie machine
+
+A general-purpose library for defining and running state machines. Easy as pie.
+
+## Quickstart
+
+```typescript
+
+import { Graph } from "./lib/graph.js";
+
+// The state type for our graph
+type State = {
+  count: number;
+  log: string[];
+};
+
+// enable debug logging
+const graphConfig = {
+  debug: {
+    log: true,
+    logData: true,
+  },
+};
+
+// Define the names of the nodes in the graph
+// Useful for type safety
+const nodes = ["start", "increment", "finish"] as const;
+type Node = (typeof nodes)[number];
+
+// Create a new graph
+const graph = new Graph<State, Node>(nodes, graphConfig);
+
+// Add some nodes! Each node is an async function that takes the current state and returns a new state.
+graph.node("start", async (data) => {
+  return {
+    ...data,
+    log: [...data.log, "Starting computation"],
+  };
+});
+
+graph.node("increment", async (data) => {
+  return {
+    ...data,
+    count: data.count + 1,
+    log: [...data.log, `Incremented count to ${data.count + 1}`],
+  };
+});
+
+graph.node("finish", async (data) => data);
+
+// Define the edges between the nodes
+graph.edge("start", "increment");
+graph.conditionalEdge("increment", ["finish", "increment"], async (data) => {
+  if (data.count < 2) {
+    return "increment";
+  } else {
+    return "finish";
+  }
+});
+
+async function main() {
+  // Run the graph starting from the "start" node with an initial state
+  const initialState: State = { count: 0, log: [] };
+  const finalState = await graph.run("start", initialState);
+  console.log(finalState);
+}
+
+main();
+
+```
+
+
+Output:
+
+```
+[DEBUG]: Executing node: start | Data: {"count":0,"log":[]}
+[DEBUG]: Completed node: start | Data: {"count":0,"log":["Starting computation"]}
+[DEBUG]: Following regular edge to: increment
+[DEBUG]: Executing node: increment | Data: {"count":0,"log":["Starting computation"]}
+[DEBUG]: Completed node: increment | Data: {"count":1,"log":["Starting computation","Incremented count to 1"]}
+[DEBUG]: Following conditional edge to: increment | Data: {"count":1,"log":["Starting computation","Incremented count to 1"]}
+[DEBUG]: Executing node: increment | Data: {"count":1,"log":["Starting computation","Incremented count to 1"]}
+[DEBUG]: Completed node: increment | Data: {"count":2,"log":["Starting computation","Incremented count to 1","Incremented count to 2"]}
+[DEBUG]: Following conditional edge to: finish | Data: {"count":2,"log":["Starting computation","Incremented count to 1","Incremented count to 2"]}
+[DEBUG]: Executing node: finish | Data: {"count":2,"log":["Starting computation","Incremented count to 1","Incremented count to 2"]}
+[DEBUG]: Completed node: finish | Data: {"count":2,"log":["Starting computation","Incremented count to 1","Incremented count to 2"]}
+{
+  count: 2,
+  log: [
+    'Starting computation',
+    'Incremented count to 1',
+    'Incremented count to 2'
+  ]
+}
+```
+
+
+
+Some options to visualize the graph:
+
+```typescript
+graph.prettyPrint();
+/* Prints:
+start -> increment
+increment -> finish | increment
+*/
+
+console.log(graph.toMermaid());
+/* Prints:
+graph TD
+  start --> increment
+  increment --> finish
+  increment --> increment
+*/
+```
+
+## More about routing
+
+There are three ways a node can route to another node. One is to specify a single edge to the next node:
+
+```typescript
+graph.edge("start", "increment");
+```
+
+Alternatively, a node can conditionally route to multiple other nodes. It can do so by returning an instance of `GoToNode`, where the first parameter is the name of the node it wants to route to, and the second parameter is the data it is sending to that node.
+
+```typescript
+graph.node("increment", async (data) => {
+  const newCount = data.count + 1;
+  const newData = {
+    ...data,
+    count: newCount,
+    log: [...data.log, `Incremented count to ${newCount}`],
+  };
+
+  // Nodes can return GoToNode to jump to a specific node next
+  if (newCount < 2) {
+    // or new GoToNode("increment", newData);
+    return goToNode("increment", newData);
+  }
+  return goToNode("finish", newData);
+});
+
+```
+If you go with this approach, you also need to specify all the possible nodes that the node could route to.
+
+```typescript
+graph.conditionalEdge("increment", ["finish", "increment"]);
+```
+
+Finally, a node can conditionally route to multiple other nodes by having a routing function in the call to `conditionalEdge`.
+
+```typescript
+graph.conditionalEdge("increment", ["finish", "increment"], async (data) => {
+  if (data.count < 2) {
+    return "increment";
+  } else {
+    return "finish";
+  }
+});
+```
+
+Note that if you want a node to route to multiple other nodes, you need to do so conditionally. You can't have a node route to multiple other nodes in parallel:
+
+```typescript
+// This is not allowed
+graph.edge("start", ["increment", "finish"]);
+
+// This is also not allowed
+graph.edge("start", "increment");
+graph.edge("start", "finish");
+```
+

package/dist/error.d.ts

@@ -0,0 +1,4 @@
+declare class PieMachineError extends Error {
+    constructor(message: string);
+}
+export { PieMachineError };

package/dist/error.js

@@ -0,0 +1,7 @@
+class PieMachineError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PieMachineError";
+    }
+}
+export { PieMachineError };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./pieMachine.js";
+export * from "./types.js";
+export * from "./error.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./pieMachine.js";
+export * from "./types.js";
+export * from "./error.js";

package/dist/pieMachine.d.ts

@@ -0,0 +1,24 @@
+import { ConditionalFunc, Edge, PieMachineConfig } from "./types.js";
+export declare class GoToNode<T, N extends string> {
+    to: N;
+    data: T;
+    constructor(to: N, data: T);
+}
+export declare function goToNode<T, N extends string>(to: N, data: T): GoToNode<T, N>;
+export declare class PieMachine<T, N extends string> {
+    private nodes;
+    private edges;
+    private config;
+    private statelogClient;
+    constructor(nodes: N[], config?: PieMachineConfig<T>);
+    node(id: N, func: (data: T) => Promise<T | GoToNode<T, N>>): void;
+    edge(from: N, to: N): void;
+    conditionalEdge<const Adjacent extends N>(from: N, adjacentNodes: readonly Adjacent[], to?: ConditionalFunc<T, Adjacent>): void;
+    debug(message: string, data?: T): void;
+    run(startId: N, input: T): Promise<T>;
+    runAndValidate(nodeFunc: (data: T) => Promise<T | GoToNode<T, N>>, currentId: N, _data: T, retries?: number): Promise<T | GoToNode<T, N>>;
+    prettyPrint(): void;
+    prettyPrintEdge(edge: Edge<T, N>): string;
+    toMermaid(): string;
+    private validateGoToNodeTarget;
+}

package/dist/pieMachine.js

@@ -0,0 +1,250 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { color } from "termcolors";
+import { PieMachineError } from "./error.js";
+import { StatelogClient } from "statelog-client";
+import { conditionalEdge, edgeToJSON, isRegularEdge, regularEdge, } from "./types.js";
+export class GoToNode {
+    constructor(to, data) {
+        this.to = to;
+        this.data = data;
+    }
+}
+export function goToNode(to, data) {
+    return new GoToNode(to, data);
+}
+export class PieMachine {
+    constructor(nodes, config = {}) {
+        var _a;
+        this.nodes = {};
+        this.edges = {};
+        this.statelogClient = null;
+        this.config = config;
+        if (config.statelog) {
+            this.statelogClient = new StatelogClient({
+                host: config.statelog.host,
+                apiKey: config.statelog.apiKey,
+                projectId: config.statelog.projectId,
+                traceId: config.statelog.traceId,
+                debugMode: (_a = config.statelog.debugMode) !== null && _a !== void 0 ? _a : false,
+            });
+        }
+    }
+    node(id, func) {
+        this.nodes[id] = func;
+    }
+    edge(from, to) {
+        if (!this.edges[from]) {
+            this.edges[from] = regularEdge(to);
+        }
+        else {
+            throw new PieMachineError(` ${from} already has an edge, which leads to ${this.edges[from]}.`);
+        }
+    }
+    conditionalEdge(from, adjacentNodes, to) {
+        if (!this.edges[from]) {
+            this.edges[from] = conditionalEdge(to, adjacentNodes);
+        }
+        else {
+            throw new PieMachineError(` ${from} already has an edge, which leads to ${this.edges[from]}.`);
+        }
+    }
+    debug(message, data) {
+        var _a, _b;
+        let debugStr = `${color.magenta("[DEBUG]")}: ${message}`;
+        if (((_a = this.config.debug) === null || _a === void 0 ? void 0 : _a.logData) && data !== undefined) {
+            debugStr += ` | Data: ${color.green(JSON.stringify(data))}`;
+        }
+        if ((_b = this.config.debug) === null || _b === void 0 ? void 0 : _b.log) {
+            console.log(debugStr);
+        }
+        //this.statelogClient?.debug(message, data || {});
+    }
+    run(startId, input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+            const jsonEdges = {};
+            for (const from in this.edges) {
+                jsonEdges[from] = edgeToJSON(this.edges[from]);
+            }
+            (_a = this.statelogClient) === null || _a === void 0 ? void 0 : _a.graph({
+                nodes: Object.keys(this.nodes),
+                edges: jsonEdges,
+                startNode: startId,
+            });
+            let currentId = startId;
+            let data = input;
+            while (currentId) {
+                const nodeFunc = this.nodes[currentId];
+                if (!nodeFunc) {
+                    throw new PieMachineError(`Node function for ${currentId} not found.`);
+                }
+                if ((_b = this.config.hooks) === null || _b === void 0 ? void 0 : _b.beforeNode) {
+                    this.debug(`Before hook for node: ${color.green(currentId)}`, data);
+                    const startData = data;
+                    const startTime = performance.now();
+                    data = yield this.config.hooks.beforeNode(currentId, data);
+                    const endTime = performance.now();
+                    (_c = this.statelogClient) === null || _c === void 0 ? void 0 : _c.beforeHook({
+                        nodeId: currentId,
+                        startData,
+                        endData: data,
+                        timeTaken: endTime - startTime,
+                    });
+                }
+                this.debug(`Executing node: ${color.green(currentId)}`, data);
+                (_d = this.statelogClient) === null || _d === void 0 ? void 0 : _d.enterNode({ nodeId: currentId, data });
+                const startTime = performance.now();
+                const result = yield this.runAndValidate(nodeFunc, currentId, data);
+                const endTime = performance.now();
+                let nextNode;
+                if (result instanceof GoToNode) {
+                    nextNode = result.to;
+                    data = result.data;
+                }
+                else {
+                    data = result;
+                }
+                (_e = this.statelogClient) === null || _e === void 0 ? void 0 : _e.exitNode({
+                    nodeId: currentId,
+                    data,
+                    timeTaken: endTime - startTime,
+                });
+                this.debug(`Completed node: ${color.green(currentId)}`, data);
+                if ((_f = this.config.hooks) === null || _f === void 0 ? void 0 : _f.afterNode) {
+                    this.debug(`After hook for node: ${color.green(currentId)}`, data);
+                    const startData = data;
+                    const startTime = performance.now();
+                    data = yield this.config.hooks.afterNode(currentId, data);
+                    const endTime = performance.now();
+                    (_g = this.statelogClient) === null || _g === void 0 ? void 0 : _g.afterHook({
+                        nodeId: currentId,
+                        startData,
+                        endData: data,
+                        timeTaken: endTime - startTime,
+                    });
+                }
+                const edge = this.edges[currentId];
+                if (edge === undefined) {
+                    currentId = null;
+                    continue;
+                }
+                if (nextNode && edge) {
+                    const isValidTarget = this.validateGoToNodeTarget(nextNode, edge);
+                    if (!isValidTarget) {
+                        throw new PieMachineError(`${currentId} tried to go to ${nextNode}, but did not specify a conditional edge to it. Use graph.conditionalEdge("${currentId}", ["${nextNode}"]) to define the edge.`);
+                    }
+                    (_h = this.statelogClient) === null || _h === void 0 ? void 0 : _h.followEdge({
+                        fromNodeId: currentId,
+                        toNodeId: nextNode,
+                        isConditionalEdge: false,
+                        data,
+                    });
+                    this.debug(`Following goto edge to: ${color.green(nextNode)}`, data);
+                    currentId = nextNode;
+                    continue;
+                }
+                if (isRegularEdge(edge)) {
+                    (_j = this.statelogClient) === null || _j === void 0 ? void 0 : _j.followEdge({
+                        fromNodeId: currentId,
+                        toNodeId: edge.to,
+                        isConditionalEdge: false,
+                        data,
+                    });
+                    this.debug(`Following regular edge to: ${color.green(edge.to)}`);
+                    currentId = edge.to;
+                }
+                else {
+                    if (edge.condition) {
+                        const nextId = yield edge.condition(data);
+                        (_k = this.statelogClient) === null || _k === void 0 ? void 0 : _k.followEdge({
+                            fromNodeId: currentId,
+                            toNodeId: nextId,
+                            isConditionalEdge: true,
+                            data,
+                        });
+                        this.debug(`Following conditional edge to: ${color.green(nextId)}`, data);
+                        currentId = nextId;
+                    }
+                    else {
+                        throw new PieMachineError(`Expected ${currentId} to return a GoToNode, as no function was specified for the conditional edges to ${edge.adjacentNodes.join(", ")}.`);
+                    }
+                }
+            }
+            return data;
+        });
+    }
+    runAndValidate(nodeFunc_1, currentId_1, _data_1) {
+        return __awaiter(this, arguments, void 0, function* (nodeFunc, currentId, _data, retries = 0) {
+            var _a, _b;
+            const result = yield nodeFunc(_data);
+            let data;
+            if (result instanceof GoToNode) {
+                data = result.data;
+            }
+            else {
+                data = result;
+            }
+            if ((_a = this.config.validation) === null || _a === void 0 ? void 0 : _a.func) {
+                const maxRetries = (_b = this.config.validation.maxRetries) !== null && _b !== void 0 ? _b : 0;
+                let isValid = yield this.config.validation.func(data);
+                while (!isValid) {
+                    if (retries >= maxRetries) {
+                        throw new PieMachineError(`Validation failed for node ${currentId} after ${maxRetries} retries.`);
+                    }
+                    this.debug(`Validation failed for node ${color.green(currentId)}, retrying... (${retries + 1}/${maxRetries})`, data);
+                    return this.runAndValidate(nodeFunc, currentId, _data, retries + 1);
+                }
+            }
+            return result;
+        });
+    }
+    prettyPrint() {
+        for (const from in this.edges) {
+            const to = this.edges[from];
+            if (!to)
+                continue;
+            console.log(`${from} -> ${this.prettyPrintEdge(to)}`);
+        }
+    }
+    prettyPrintEdge(edge) {
+        if (isRegularEdge(edge)) {
+            return edge.to;
+        }
+        else {
+            return edge.adjacentNodes.join(" | ");
+        }
+    }
+    toMermaid() {
+        let mermaid = "graph TD\n";
+        for (const from in this.edges) {
+            const to = this.edges[from];
+            if (!to)
+                continue;
+            if (isRegularEdge(to)) {
+                mermaid += `  ${from} --> ${to.to}\n`;
+            }
+            else {
+                to.adjacentNodes.forEach((adjNode) => {
+                    mermaid += `  ${from} --> ${adjNode}\n`;
+                });
+            }
+        }
+        return mermaid;
+    }
+    validateGoToNodeTarget(to, edge) {
+        if (!isRegularEdge(edge)) {
+            if (edge.adjacentNodes.includes(to)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+export type PieMachineConfig<T> = {
+    debug?: {
+        log?: boolean;
+        logData?: boolean;
+    };
+    validation?: {
+        func?: (data: T) => Promise<boolean>;
+        maxRetries?: number;
+    };
+    hooks?: {
+        beforeNode?: (nodeId: string, data: T) => Promise<T>;
+        afterNode?: (nodeId: string, data: T) => Promise<T>;
+    };
+    statelog?: {
+        host: string;
+        apiKey: string;
+        projectId: string;
+        traceId?: string;
+        debugMode?: boolean;
+    };
+};
+export type NodeId = string;
+export type Edge<T, N extends string> = RegularEdge<N> | ConditionalEdge<T, N>;
+export type RegularEdge<N extends string> = {
+    type: "regular";
+    to: N;
+};
+export type ConditionalFunc<T, N extends string> = (data: T) => Promise<NoInfer<N>>;
+export type ConditionalEdge<T, N extends string> = {
+    type: "conditional";
+    condition?: ConditionalFunc<T, N>;
+    adjacentNodes: readonly N[];
+};
+export declare function regularEdge<N extends string>(to: N): RegularEdge<N>;
+export declare function conditionalEdge<T, N extends string>(condition: ConditionalFunc<T, N> | undefined, adjacentNodes: readonly N[]): ConditionalEdge<T, N>;
+export declare function isRegularEdge<T, N extends string>(edge: Edge<T, N>): edge is RegularEdge<N>;
+export declare function isConditionalEdge<T, N extends string>(edge: Edge<T, N>): edge is ConditionalEdge<T, N>;
+export type JSONEdge = {
+    type: "regular";
+    to: string;
+} | {
+    type: "conditional";
+    adjacentNodes: readonly string[];
+};
+export declare function edgeToJSON<T, N extends string>(edge: Edge<T, N>): JSONEdge;

package/dist/types.js

@@ -0,0 +1,23 @@
+export function regularEdge(to) {
+    return { type: "regular", to };
+}
+export function conditionalEdge(condition, adjacentNodes) {
+    return { type: "conditional", condition, adjacentNodes };
+}
+export function isRegularEdge(edge) {
+    return edge.type === "regular";
+}
+export function isConditionalEdge(edge) {
+    return edge.type === "conditional";
+}
+export function edgeToJSON(edge) {
+    if (isRegularEdge(edge)) {
+        return { type: "regular", to: edge.to };
+    }
+    else {
+        return {
+            type: "conditional",
+            adjacentNodes: edge.adjacentNodes,
+        };
+    }
+}

package/dist/utils.d.ts

@@ -0,0 +1 @@
+export declare function runtime(callback: Function): number | null;

package/dist/utils.js

@@ -0,0 +1,12 @@
+export function runtime(callback) {
+    if (performance && performance.now) {
+        const start = performance.now();
+        callback();
+        const end = performance.now();
+        return end - start;
+    }
+    else {
+        callback();
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "piemachine",
+  "version": "0.0.1",
+  "description": "A general-purpose library for defining and running state machines. Easy as pie.",
+  "homepage": "https://github.com/egonSchiele/piemachine",
+  "scripts": {
+    "test": "vitest",
+    "test:tsc": "tsc -p tests/tsconfig.json",
+    "coverage": "vitest --coverage",
+    "build": "rm -rf dist && tsc",
+    "start": "cd dist && node index.js",
+    "doc": "typedoc --disableSources --out docs lib && prettier docs/ --write",
+    "doc:prettier": "prettier docs/ --write"
+  },
+  "files": [
+    "./dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "keywords": [
+    "graph",
+    "dataflow",
+    "react"
+  ],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^20.19.27",
+    "prettier": "3.2.5",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.1"
+  },
+  "dependencies": {
+    "nanoid": "^5.1.6",
+    "statelog-client": "^0.0.31",
+    "termcolors": "github:egonSchiele/termcolors"
+  }
+}