@hazeljs/flow-runtime 0.2.0-beta.75 → 0.2.0-beta.77
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +54 -12
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -4,32 +4,74 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@hazeljs/flow-runtime)
|
|
5
5
|
[](https://www.apache.org/licenses/LICENSE-2.0)
|
|
6
6
|
|
|
7
|
-
Standalone
|
|
7
|
+
Standalone HTTP service for [@hazeljs/flow](https://www.npmjs.com/package/@hazeljs/flow) workflows. Expose flows via REST so other systems can start runs, tick, resume waiting runs, and read status and timeline—or invoke the runtime from your app with `runFlowRuntime({ flows, port, databaseUrl?, services })` so you don't reimplement the server.
|
|
8
|
+
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
- **REST API** — Start runs, tick, resume, get run status and timeline, list flows, health check
|
|
12
|
+
- **In-memory by default** — No database required; set `DATABASE_URL` (or pass `databaseUrl`) only when you want durable persistence
|
|
13
|
+
- **Fallback to in-memory** — If `DATABASE_URL` is missing or the connection fails, the runtime uses in-memory storage and logs a message
|
|
14
|
+
- **Recovery** — On startup, picks up any `RUNNING` runs (when using Prisma storage) and ticks them so they continue after a restart
|
|
15
|
+
- **Programmatic API** — Call `runFlowRuntime({ port, databaseUrl?, flows, services? })` from your app to register your own flows and optional services (logger, slack, etc.) while the package owns the HTTP server
|
|
8
16
|
|
|
9
17
|
## Requirements
|
|
10
18
|
|
|
11
|
-
-
|
|
12
|
-
-
|
|
19
|
+
- **Node.js** — 20+
|
|
20
|
+
- **@hazeljs/flow** — Required peer; install with `pnpm add @hazeljs/flow`
|
|
21
|
+
- **PORT** — Optional; default `3000`
|
|
22
|
+
- **DATABASE_URL** — Optional; if set and connection succeeds, uses Prisma storage for durability and recovery. If unset or connection fails, uses in-memory storage.
|
|
13
23
|
|
|
14
|
-
##
|
|
24
|
+
## Installation
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pnpm add @hazeljs/flow-runtime @hazeljs/flow
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Run as a standalone process
|
|
15
31
|
|
|
16
32
|
```bash
|
|
17
33
|
# From monorepo root
|
|
18
34
|
pnpm flow:runtime
|
|
19
35
|
|
|
20
36
|
# Or from this package
|
|
21
|
-
pnpm dev
|
|
37
|
+
pnpm dev # watch mode
|
|
38
|
+
pnpm start # after build: node dist/main.js
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Uses default demo flows. With no `DATABASE_URL`, runs in-memory. Set `DATABASE_URL` for Postgres persistence and recovery.
|
|
42
|
+
|
|
43
|
+
## Run from your app (programmatic)
|
|
44
|
+
|
|
45
|
+
Register your own flows and optional services; the package runs the HTTP server and recovery:
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
import { runFlowRuntime } from '@hazeljs/flow-runtime';
|
|
49
|
+
import { buildFlowDefinition } from '@hazeljs/flow';
|
|
50
|
+
import { OrderFlow } from './flows/OrderFlow';
|
|
51
|
+
|
|
52
|
+
await runFlowRuntime({
|
|
53
|
+
port: 3000,
|
|
54
|
+
databaseUrl: process.env.DATABASE_URL, // optional; in-memory if omitted or connection fails
|
|
55
|
+
flows: [buildFlowDefinition(OrderFlow)],
|
|
56
|
+
services: { logger: myLogger, slack: slackClient }, // optional; injected into flow context
|
|
57
|
+
});
|
|
22
58
|
```
|
|
23
59
|
|
|
24
60
|
## API
|
|
25
61
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
62
|
+
| Method | Path | Description |
|
|
63
|
+
|--------|------|-------------|
|
|
64
|
+
| `POST` | `/v1/runs/start` | Start a flow run (body: `flowId`, `version`, `input`) |
|
|
65
|
+
| `POST` | `/v1/runs/:runId/tick` | Advance a running run one step |
|
|
66
|
+
| `POST` | `/v1/runs/:runId/resume` | Resume a waiting run (body: payload for the wait) |
|
|
67
|
+
| `GET` | `/v1/runs/:runId` | Get run status |
|
|
68
|
+
| `GET` | `/v1/runs/:runId/timeline` | Get run event timeline |
|
|
69
|
+
| `GET` | `/v1/flows` | List registered flows |
|
|
70
|
+
| `GET` | `/health` | Health check |
|
|
71
|
+
|
|
72
|
+
## Example
|
|
73
|
+
|
|
74
|
+
See [hazeljs-flow-example](https://github.com/hazel-js/hazeljs-flow-example) for a full app that registers order, approval, and fraud-detection flows and starts the runtime with `runFlowRuntime(...)`.
|
|
33
75
|
|
|
34
76
|
## License
|
|
35
77
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hazeljs/flow-runtime",
|
|
3
|
-
"version": "0.2.0-beta.
|
|
3
|
+
"version": "0.2.0-beta.77",
|
|
4
4
|
"description": "Standalone deployable flow runtime service (HazelJS)",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|
|
@@ -49,5 +49,5 @@
|
|
|
49
49
|
"engines": {
|
|
50
50
|
"node": ">=20.0.0"
|
|
51
51
|
},
|
|
52
|
-
"gitHead": "
|
|
52
|
+
"gitHead": "4b9b457803b0b0c6c204e31709a72f09fc3411c3"
|
|
53
53
|
}
|