visual-node 0.1.0 → 0.2.0

package/dist/examples/01-hello-world/README.md

@@ -0,0 +1,25 @@
+# Hello World
+
+The canonical minimal flow — the shape every other example builds on.
+
+**Nodes involved:** `express.init`, `express.middleware.jsonParser`, `express.route`,
+`handler.sendJson`, `express.listen`.
+
+A single `GET /hello` route answers with a static JSON body. No custom code, no
+variables, no dependencies — just the five node types every generated server starts
+from.
+
+## Run it
+
+```bash
+npx visual-node examples/01-hello-world
+```
+
+Open `http://localhost:4000`, hit **Compile**, then **Run Server** to spawn it — or just
+read the committed [`server.js`](server.js), which is exactly what compiling this flow
+produces.
+
+```bash
+curl http://localhost:3001/hello
+# {"message":"Hello World"}
+```

package/dist/examples/01-hello-world/flow.json

@@ -0,0 +1,38 @@
+{
+  "version": "1",
+  "meta": { "name": "hello-world", "target": "express" },
+  "nodes": [
+    { "id": "init_1", "type": "express.init", "position": { "x": 0, "y": 0 }, "data": {} },
+    {
+      "id": "json_parser_1",
+      "type": "express.middleware.jsonParser",
+      "position": { "x": 200, "y": 0 },
+      "data": {}
+    },
+    {
+      "id": "route_1",
+      "type": "express.route",
+      "position": { "x": 400, "y": 0 },
+      "data": { "method": "GET", "path": "/hello" }
+    },
+    {
+      "id": "send_json_1",
+      "type": "handler.sendJson",
+      "position": { "x": 600, "y": 0 },
+      "data": { "statusCode": 200, "body": { "message": "Hello World" } }
+    },
+    {
+      "id": "listen_1",
+      "type": "express.listen",
+      "position": { "x": 200, "y": 200 },
+      "data": { "port": 3001 }
+    }
+  ],
+  "edges": [
+    { "id": "e1", "source": "init_1", "target": "json_parser_1", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e2", "source": "json_parser_1", "target": "route_1", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e3", "source": "route_1", "target": "send_json_1", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e4", "source": "init_1", "target": "listen_1", "sourceHandle": "out", "targetHandle": "in" }
+  ],
+  "variables": []
+}

package/dist/examples/01-hello-world/server.js

@@ -0,0 +1,13 @@
+const express = require("express");
+
+const app = express();
+
+app.use(express.json());
+
+app.get("/hello", (req, res) => {
+  res.status(200).json({ message: "Hello World" });
+});
+
+app.listen(3001, () => {
+  console.log("Server running on port 3001");
+});

package/dist/examples/02-rest-crud-with-variables/README.md

@@ -0,0 +1,34 @@
+# REST CRUD with Variables
+
+An in-memory `items` REST API demonstrating the **Variables** system alongside the
+**Custom Code** escape hatch.
+
+**Nodes involved:** `variable.set`, `variable.get`, `debug.consoleLog`,
+`handler.customCode`, `handler.sendJson`, plus the standard `express.*` wiring.
+
+A file-scoped `let items = []` (declared once, in the flow's **Variables** panel) backs
+four routes:
+
+- `GET /items` — reads `items` directly (a Custom Code node can reference any file-scoped
+  variable by name, no wiring needed).
+- `POST /items` — pushes a new item built from `req.body`.
+- `DELETE /items/:id` — reassigns `items` via a wired **Set Variable** node (its literal
+  value field holds `items.filter(...)`), then responds with a static `Send JSON` node.
+- `GET /items/count` — wires a **Get Variable** node's output into a **Console Log**
+  node (logging the current array server-side) before a Custom Code node responds with
+  the count — the one route here that actually wires a value pin end to end, rather than
+  referencing the variable by bare identifier.
+
+## Run it
+
+```bash
+npx visual-node examples/02-rest-crud-with-variables
+```
+
+```bash
+curl http://localhost:3002/items                                    # []
+curl -X POST -H 'content-type: application/json' -d '{"name":"widget"}' http://localhost:3002/items
+curl http://localhost:3002/items                                    # [{"id":"1","name":"widget"}]
+curl http://localhost:3002/items/count                               # {"count":1}
+curl -X DELETE http://localhost:3002/items/1                         # {"success":true}
+```

package/dist/examples/02-rest-crud-with-variables/flow.json

@@ -0,0 +1,76 @@
+{
+  "version": "1",
+  "meta": { "name": "rest-crud-with-variables", "target": "express" },
+  "nodes": [
+    { "id": "init_1", "type": "express.init", "position": { "x": 0, "y": 0 }, "data": {} },
+    {
+      "id": "json_parser_1",
+      "type": "express.middleware.jsonParser",
+      "position": { "x": 200, "y": 0 },
+      "data": {}
+    },
+    {
+      "id": "listen_1",
+      "type": "express.listen",
+      "position": { "x": 0, "y": 400 },
+      "data": { "port": 3002 }
+    },
+
+    { "id": "route_list", "type": "express.route", "position": { "x": 450, "y": 0 }, "data": { "method": "GET", "path": "/items" } },
+    { "id": "handler_list", "type": "handler.customCode", "position": { "x": 650, "y": 0 }, "data": { "code": "res.status(200).json(items);" } },
+
+    { "id": "route_create", "type": "express.route", "position": { "x": 450, "y": 100 }, "data": { "method": "POST", "path": "/items" } },
+    {
+      "id": "handler_create",
+      "type": "handler.customCode",
+      "position": { "x": 650, "y": 100 },
+      "data": { "code": "const item = { id: String(items.length + 1), ...req.body };\nitems.push(item);\nres.status(201).json(item);" }
+    },
+
+    { "id": "route_delete", "type": "express.route", "position": { "x": 450, "y": 200 }, "data": { "method": "DELETE", "path": "/items/:id" } },
+    {
+      "id": "var_set_delete",
+      "type": "variable.set",
+      "position": { "x": 650, "y": 200 },
+      "data": { "variableId": "var_items", "literals": { "value": "items.filter((item) => item.id !== req.params.id)" } }
+    },
+    { "id": "handler_delete_response", "type": "handler.sendJson", "position": { "x": 850, "y": 200 }, "data": { "statusCode": 200, "body": { "success": true } } },
+
+    { "id": "route_count", "type": "express.route", "position": { "x": 450, "y": 300 }, "data": { "method": "GET", "path": "/items/count" } },
+    { "id": "var_get_count", "type": "variable.get", "position": { "x": 450, "y": 380 }, "data": { "variableId": "var_items" } },
+    {
+      "id": "log_count",
+      "type": "debug.consoleLog",
+      "position": { "x": 650, "y": 300 },
+      "data": { "expression": "\"items snapshot:\"" }
+    },
+    {
+      "id": "handler_count",
+      "type": "handler.customCode",
+      "position": { "x": 850, "y": 300 },
+      "data": { "code": "res.status(200).json({ count: items.length });" }
+    }
+  ],
+  "edges": [
+    { "id": "e1", "source": "init_1", "target": "json_parser_1", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e2", "source": "init_1", "target": "listen_1", "sourceHandle": "out", "targetHandle": "in" },
+
+    { "id": "e3", "source": "json_parser_1", "target": "route_list", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e4", "source": "route_list", "target": "handler_list", "sourceHandle": "out", "targetHandle": "in" },
+
+    { "id": "e5", "source": "json_parser_1", "target": "route_create", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e6", "source": "route_create", "target": "handler_create", "sourceHandle": "out", "targetHandle": "in" },
+
+    { "id": "e7", "source": "json_parser_1", "target": "route_delete", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e8", "source": "route_delete", "target": "var_set_delete", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e9", "source": "var_set_delete", "target": "handler_delete_response", "sourceHandle": "out", "targetHandle": "in" },
+
+    { "id": "e10", "source": "json_parser_1", "target": "route_count", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e11", "source": "route_count", "target": "log_count", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e12", "source": "var_get_count", "target": "log_count", "sourceHandle": "value", "targetHandle": "value" },
+    { "id": "e13", "source": "log_count", "target": "handler_count", "sourceHandle": "out", "targetHandle": "in" }
+  ],
+  "variables": [
+    { "id": "var_items", "name": "items", "keyword": "let", "dataType": "array", "defaultValue": "[]" }
+  ]
+}

package/dist/examples/02-rest-crud-with-variables/server.js

@@ -0,0 +1,31 @@
+const express = require("express");
+
+const app = express();
+
+let items = [];
+
+app.use(express.json());
+
+app.get("/items", (req, res) => {
+  res.status(200).json(items);
+});
+
+app.post("/items", (req, res) => {
+  const item = { id: String(items.length + 1), ...req.body };
+  items.push(item);
+  res.status(201).json(item);
+});
+
+app.delete("/items/:id", (req, res) => {
+  items = items.filter((item) => item.id !== req.params.id);
+  res.status(200).json({ success: true });
+});
+
+app.get("/items/count", (req, res) => {
+  console.log(items);
+  res.status(200).json({ count: items.length });
+});
+
+app.listen(3002, () => {
+  console.log("Server running on port 3002");
+});

package/dist/examples/03-custom-middleware-logging/README.md

@@ -0,0 +1,26 @@
+# Custom Middleware Logging
+
+Demonstrates the middleware escape hatch: a hand-written `app.use(...)` request logger
+placed ahead of the JSON body parser.
+
+**Nodes involved:** `middleware.customCode`, plus the standard `express.*` wiring and a
+`handler.sendJson` route.
+
+`middleware.customCode` wraps its raw code in `app.use((req, res, next) => { ... })` —
+call `next()` to continue the chain, or respond directly to end it there. This example
+just logs `METHOD path` for every request before falling through to a trivial
+`GET /ping` route.
+
+## Run it
+
+```bash
+npx visual-node examples/03-custom-middleware-logging
+```
+
+```bash
+curl http://localhost:3003/ping
+# {"pong":true}
+```
+
+Watch the server's console output — it prints `GET /ping` for the request above, logged
+entirely from the custom middleware node.

package/dist/examples/03-custom-middleware-logging/flow.json

@@ -0,0 +1,45 @@
+{
+  "version": "1",
+  "meta": { "name": "custom-middleware-logging", "target": "express" },
+  "nodes": [
+    { "id": "init_1", "type": "express.init", "position": { "x": 0, "y": 0 }, "data": {} },
+    {
+      "id": "mw_logger",
+      "type": "middleware.customCode",
+      "position": { "x": 200, "y": 0 },
+      "data": { "code": "console.log(`${req.method} ${req.path}`);\nnext();", "isAsync": false, "npmDependencies": "" }
+    },
+    {
+      "id": "json_parser_1",
+      "type": "express.middleware.jsonParser",
+      "position": { "x": 400, "y": 0 },
+      "data": {}
+    },
+    {
+      "id": "route_1",
+      "type": "express.route",
+      "position": { "x": 600, "y": 0 },
+      "data": { "method": "GET", "path": "/ping" }
+    },
+    {
+      "id": "send_json_1",
+      "type": "handler.sendJson",
+      "position": { "x": 800, "y": 0 },
+      "data": { "statusCode": 200, "body": { "pong": true } }
+    },
+    {
+      "id": "listen_1",
+      "type": "express.listen",
+      "position": { "x": 200, "y": 200 },
+      "data": { "port": 3003 }
+    }
+  ],
+  "edges": [
+    { "id": "e1", "source": "init_1", "target": "mw_logger", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e2", "source": "mw_logger", "target": "json_parser_1", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e3", "source": "json_parser_1", "target": "route_1", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e4", "source": "route_1", "target": "send_json_1", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e5", "source": "init_1", "target": "listen_1", "sourceHandle": "out", "targetHandle": "in" }
+  ],
+  "variables": []
+}

package/dist/examples/03-custom-middleware-logging/server.js

@@ -0,0 +1,18 @@
+const express = require("express");
+
+const app = express();
+
+app.use((req, res, next) => {
+  console.log(`${req.method} ${req.path}`);
+  next();
+});
+
+app.use(express.json());
+
+app.get("/ping", (req, res) => {
+  res.status(200).json({ pong: true });
+});
+
+app.listen(3003, () => {
+  console.log("Server running on port 3003");
+});

package/dist/examples/04-function-graph-branch/README.md

@@ -0,0 +1,29 @@
+# Function Graph with Branch
+
+A `logic.function` node ("isEven") authored in **blueprint mode** — a nested visual node
+graph instead of hand-typed code — using `controlFlow.branch` to fork execution and a
+function-scoped **Variable** to carry the result back out.
+
+**Nodes involved (inside the function's nested graph):** `logic.graphEntry`,
+`controlFlow.branch`, `variable.set`, `variable.get`, `logic.graphReturn`. **On the main
+canvas:** the same `logic.function` node (private — never wired to an Export, so it stays
+a file-local helper), called directly by name from a `handler.customCode` node.
+
+The nested graph: `Start` → `Branch` (condition `n % 2 === 0`, a literal expression, not
+wired) → **True** arm sets a `result` variable to `true`, **False** arm sets it to
+`false`. A **Get Variable** node feeds the **Return** node's value — since reading a
+variable is always safe regardless of which arm set it, this sidesteps the restriction
+that a Branch/Switch arm's own values can't be read directly from the Return node. Open
+this function's "Blueprint Graph" from its config panel to see the two-arm graph on
+canvas.
+
+## Run it
+
+```bash
+npx visual-node examples/04-function-graph-branch
+```
+
+```bash
+curl "http://localhost:3004/is-even?n=4"   # {"n":4,"isEven":true}
+curl "http://localhost:3004/is-even?n=7"   # {"n":7,"isEven":false}
+```

package/dist/examples/04-function-graph-branch/flow.json

@@ -0,0 +1,85 @@
+{
+  "version": "1",
+  "meta": { "name": "function-graph-branch", "target": "express" },
+  "nodes": [
+    { "id": "init_1", "type": "express.init", "position": { "x": 0, "y": 0 }, "data": {} },
+    {
+      "id": "json_parser_1",
+      "type": "express.middleware.jsonParser",
+      "position": { "x": 200, "y": 0 },
+      "data": {}
+    },
+    {
+      "id": "listen_1",
+      "type": "express.listen",
+      "position": { "x": 0, "y": 300 },
+      "data": { "port": 3004 }
+    },
+    {
+      "id": "fn_isEven",
+      "type": "logic.function",
+      "position": { "x": 0, "y": 150 },
+      "data": {
+        "name": "isEven",
+        "params": "n",
+        "body": "",
+        "mode": "blueprint",
+        "isAsync": false,
+        "npmDependencies": "",
+        "graph": {
+          "variables": [
+            { "id": "var_result", "name": "result", "keyword": "let", "dataType": "boolean", "defaultValue": "false" }
+          ],
+          "nodes": [
+            { "id": "entry1", "type": "logic.graphEntry", "position": { "x": 0, "y": 0 }, "data": { "params": ["n"] } },
+            {
+              "id": "branch1",
+              "type": "controlFlow.branch",
+              "position": { "x": 200, "y": 0 },
+              "data": { "literals": { "condition": "n % 2 === 0" } }
+            },
+            {
+              "id": "set_true",
+              "type": "variable.set",
+              "position": { "x": 400, "y": -80 },
+              "data": { "variableId": "var_result", "literals": { "value": "true" } }
+            },
+            {
+              "id": "set_false",
+              "type": "variable.set",
+              "position": { "x": 400, "y": 80 },
+              "data": { "variableId": "var_result", "literals": { "value": "false" } }
+            },
+            { "id": "get_result", "type": "variable.get", "position": { "x": 600, "y": 0 }, "data": { "variableId": "var_result" } },
+            { "id": "ret1", "type": "logic.graphReturn", "position": { "x": 800, "y": 0 }, "data": {} }
+          ],
+          "edges": [
+            { "id": "ge1", "source": "entry1", "target": "branch1", "sourceHandle": "out", "targetHandle": "in" },
+            { "id": "ge2", "source": "branch1", "target": "set_true", "sourceHandle": "true", "targetHandle": "in" },
+            { "id": "ge3", "source": "branch1", "target": "set_false", "sourceHandle": "false", "targetHandle": "in" },
+            { "id": "ge4", "source": "get_result", "target": "ret1", "sourceHandle": "value", "targetHandle": "value" }
+          ]
+        }
+      }
+    },
+    {
+      "id": "route_1",
+      "type": "express.route",
+      "position": { "x": 400, "y": 0 },
+      "data": { "method": "GET", "path": "/is-even" }
+    },
+    {
+      "id": "handler_1",
+      "type": "handler.customCode",
+      "position": { "x": 600, "y": 0 },
+      "data": { "code": "const n = Number(req.query.n ?? 0);\nres.status(200).json({ n, isEven: isEven(n) });" }
+    }
+  ],
+  "edges": [
+    { "id": "e1", "source": "init_1", "target": "json_parser_1", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e2", "source": "json_parser_1", "target": "route_1", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e3", "source": "route_1", "target": "handler_1", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e4", "source": "init_1", "target": "listen_1", "sourceHandle": "out", "targetHandle": "in" }
+  ],
+  "variables": []
+}

package/dist/examples/04-function-graph-branch/server.js

@@ -0,0 +1,24 @@
+const express = require("express");
+
+const app = express();
+
+function isEven(n) {
+  let result = false;
+  if (n % 2 === 0) {
+    result = true;
+  } else {
+    result = false;
+  }
+  return result;
+}
+
+app.use(express.json());
+
+app.get("/is-even", (req, res) => {
+  const n = Number(req.query.n ?? 0);
+  res.status(200).json({ n, isEven: isEven(n) });
+});
+
+app.listen(3004, () => {
+  console.log("Server running on port 3004");
+});

package/dist/examples/05-npm-package-require/README.md

@@ -0,0 +1,30 @@
+# npm Package Require
+
+Demonstrates requiring an installed npm package (not just another local `.blueprint`
+file) and the **Async Handler** checkbox for `await`-ing inside a route.
+
+**Nodes involved:** `logic.require` (Source: npm, Package: `uuid`, Version: `^9.0.0`),
+`express.route` with **Async Handler** enabled, `handler.customCode`.
+
+The Require node emits `const uuid = require("uuid");` at the top of the file and
+declares `uuid` as a dependency — compiling this flow (or the whole project) collects it
+into the generated `package.json`, so `npm install` in the output directory pulls in
+everything the flow needs. **Note the pinned `^9.0.0`**: newer `uuid` majors ship
+ESM-only and can't be `require()`'d from CommonJS output — this pin is load-bearing, not
+arbitrary.
+
+The route itself has **Async Handler** checked, so its generated handler is
+`async (req, res) => { ... }`, letting the Custom Code node `await` a promise (here just
+a small `setTimeout` delay, standing in for any real async work like a database call or
+network request) before responding.
+
+## Run it
+
+```bash
+npx visual-node examples/05-npm-package-require
+```
+
+```bash
+curl http://localhost:3005/id
+# {"id":"...","generatedAt":"..."}
+```

package/dist/examples/05-npm-package-require/flow.json

@@ -0,0 +1,47 @@
+{
+  "version": "1",
+  "meta": { "name": "npm-package-require", "target": "express" },
+  "nodes": [
+    { "id": "init_1", "type": "express.init", "position": { "x": 0, "y": 0 }, "data": {} },
+    {
+      "id": "json_parser_1",
+      "type": "express.middleware.jsonParser",
+      "position": { "x": 200, "y": 0 },
+      "data": {}
+    },
+    {
+      "id": "req_uuid",
+      "type": "logic.require",
+      "position": { "x": 0, "y": 150 },
+      "data": { "sourceType": "npm", "path": "uuid", "variableName": "uuid", "version": "^9.0.0" }
+    },
+    {
+      "id": "route_1",
+      "type": "express.route",
+      "position": { "x": 400, "y": 0 },
+      "data": { "method": "GET", "path": "/id", "isAsync": true }
+    },
+    {
+      "id": "handler_1",
+      "type": "handler.customCode",
+      "position": { "x": 600, "y": 0 },
+      "data": {
+        "code": "await new Promise((resolve) => setTimeout(resolve, 5));\nres.status(200).json({ id: uuid.v4(), generatedAt: new Date().toISOString() });",
+        "npmDependencies": ""
+      }
+    },
+    {
+      "id": "listen_1",
+      "type": "express.listen",
+      "position": { "x": 200, "y": 300 },
+      "data": { "port": 3005 }
+    }
+  ],
+  "edges": [
+    { "id": "e1", "source": "init_1", "target": "json_parser_1", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e2", "source": "json_parser_1", "target": "route_1", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e3", "source": "route_1", "target": "handler_1", "sourceHandle": "out", "targetHandle": "in" },
+    { "id": "e4", "source": "init_1", "target": "listen_1", "sourceHandle": "out", "targetHandle": "in" }
+  ],
+  "variables": []
+}

package/dist/examples/05-npm-package-require/server.js

@@ -0,0 +1,17 @@
+const express = require("express");
+const uuid = require("uuid");
+
+const app = express();
+
+app.use(express.json());
+
+app.get("/id", async (req, res) => {
+  await new Promise((resolve) => setTimeout(resolve, 5));
+  res
+    .status(200)
+    .json({ id: uuid.v4(), generatedAt: new Date().toISOString() });
+});
+
+app.listen(3005, () => {
+  console.log("Server running on port 3005");
+});

package/dist/examples/README.md

@@ -0,0 +1,30 @@
+# Examples
+
+Five worked flows, each in its own folder with a source `flow.json`, the compiled
+`server.js` output, and a `.blueprint` binary you can open directly in the editor. Every
+example has been built and run for real — the curl commands in each `README.md` are not
+hypothetical.
+
+| Example | Demonstrates |
+| --- | --- |
+| [`01-hello-world`](01-hello-world/) | The minimal flow: init → middleware → route → handler → listen |
+| [`02-rest-crud-with-variables`](02-rest-crud-with-variables/) | Variables (`variable.get`/`variable.set`) + the Custom Code escape hatch |
+| [`03-custom-middleware-logging`](03-custom-middleware-logging/) | The middleware escape hatch (`middleware.customCode`) |
+| [`04-function-graph-branch`](04-function-graph-branch/) | A visual Function Graph with `controlFlow.branch` |
+| [`05-npm-package-require`](05-npm-package-require/) | Requiring an npm package + the Async Handler checkbox |
+
+## Opening an example in the editor
+
+```bash
+npx visual-node examples/01-hello-world
+```
+
+## Regenerating `server.js` / `.blueprint` from `flow.json`
+
+Each example's `flow.json` is the hand-editable source of truth. After changing one,
+regenerate its compiled output from the repo root (requires `pnpm -r run build` to have
+been run first, so `packages/core/dist` exists):
+
+```bash
+node examples/build.mjs
+```