@gravito/flux 1.0.0-beta.1 → 1.0.0-beta.2

package/README.zh-TW.md

@@ -1,11 +1,25 @@
 # @gravito/flux
 
-> Gravito 的高效能工作流程引擎，跨平台、型別安全的狀態機。
+> Gravito 的高效能工作流程引擎，跨平台、型別安全的狀態機，強調可追蹤、可重播與可靠重試。
+
+## 核心特色
+
+- **純狀態機模型** - 以明確狀態描述流程，讓每一步清晰可控
+- **鏈式 Builder API** - 型別安全的流程定義方式
+- **儲存介面** - Memory、Bun SQLite，其他儲存可自訂
+- **重試與逾時** - Step 可設定 retries/timeout/when，面對不穩定依賴也能自動恢復
+- **同步/非同步** - 同時支援同步流程與非同步長流程
+- **事件 Hooks** - 監聽流程與步驟生命週期
+- **事件 Hooks** - 監聽流程與步驟生命周期
+- **雙平台支援** - Bun 與 Node.js 均可使用
 
 ## 安裝
 
 ```bash
 bun add @gravito/flux
+
+# npm
+npm install @gravito/flux
 ```
 
 ## 快速開始
@@ -28,3 +42,208 @@ const orderFlow = createWorkflow('order-process')
 const engine = new FluxEngine()
 const result = await engine.execute(orderFlow, { orderId: '123' })
 ```
+
+## 範例
+
+### 訂單履約
+
+```typescript
+const orderWorkflow = createWorkflow('order-fulfillment')
+  .input<{ orderId: string; items: Item[] }>()
+  .step('validate', async (ctx) => {
+    for (const item of ctx.input.items) {
+      const stock = await db.products.getStock(item.productId)
+      if (stock < item.qty) throw new Error(`Out of stock: ${item.productId}`)
+    }
+  })
+  .step(
+    'payment',
+    async (ctx) => {
+      ctx.data.payment = await payment.charge(ctx.input.orderId)
+    },
+    { retries: 3, timeout: 30_000 }
+  )
+  .commit('deduct', async (ctx) => {
+    await inventory.deduct(ctx.data.reservationIds)
+  })
+```
+
+### 影像處理
+
+```typescript
+const uploadWorkflow = createWorkflow('image-processing')
+  .input<{ fileBuffer: Buffer; fileName: string; userId: string }>()
+  .step('validate', async (ctx) => {
+    if (ctx.input.fileBuffer.length > 10 * 1024 * 1024) {
+      throw new Error('File size exceeds 10MB')
+    }
+  })
+  .step('resize', async (ctx) => {
+    ctx.data.thumbnail = await sharp(ctx.input.fileBuffer).resize(200).toBuffer()
+  })
+  .commit('upload', async (ctx) => {
+    ctx.data.url = await s3.upload(ctx.input.fileName, ctx.data.thumbnail)
+  })
+```
+
+### 報表生成
+
+```typescript
+const reportWorkflow = createWorkflow('generate-report')
+  .input<{ reportType: string; dateRange: DateRange; requestedBy: string }>()
+  .step('fetch-data', async (ctx) => {
+    ctx.data.sales = await db.orders.aggregate(ctx.input.dateRange)
+  }, { timeout: 60_000 })
+  .step('calculate', async (ctx) => {
+    ctx.data.metrics = { revenue: 0, orders: 0 }
+  })
+  .commit('upload', async (ctx) => {
+    ctx.data.url = await s3.upload(`reports/${ctx.id}.pdf`, ctx.data.pdf)
+  })
+```
+
+## API
+
+### `createWorkflow(name)`
+
+```typescript
+const flow = createWorkflow('my-workflow')
+  .input<{ value: number }>()
+  .step('step1', handler)
+  .step('step2', handler, { retries: 3 })
+  .commit('save', handler)
+```
+
+### `FluxEngine`
+
+```typescript
+const engine = new FluxEngine({
+  storage: new MemoryStorage(),
+  defaultRetries: 3,
+  defaultTimeout: 30_000,
+  logger: new FluxConsoleLogger(),
+  on: {
+    stepStart: (step, ctx) => {},
+    stepComplete: (step, ctx, result) => {},
+    stepError: (step, ctx, error) => {},
+    workflowComplete: (ctx) => {},
+    workflowError: (ctx, error) => {},
+  },
+})
+```
+
+### Step Options
+
+```typescript
+.step('name', handler, {
+  retries: 5,
+  timeout: 60_000,
+  when: (ctx) => ctx.data.x > 0,
+})
+```
+
+## 分支流程（多支點）
+
+```typescript
+const flow = createWorkflow('event-routing')
+  .input<{ payload: EventPayload }>()
+  .step('classify', async (ctx) => {
+    ctx.data.route = classify(ctx.input.payload)
+  })
+  .step(
+    'auto-handle',
+    async (ctx) => {
+      ctx.data.result = await autoProcess(ctx.input.payload)
+    },
+    { when: (ctx) => ctx.data.route === 'auto' }
+  )
+  .step(
+    'manual-review',
+    async (ctx) => {
+      ctx.data.ticketId = await ticketing.create(ctx.input.payload)
+    },
+    { when: (ctx) => ctx.data.route === 'manual' }
+  )
+  .step(
+    'risk-audit',
+    async (ctx) => {
+      ctx.data.auditId = await auditQueue.enqueue(ctx.input.payload)
+    },
+    { when: (ctx) => ctx.data.route === 'risk' }
+  )
+  .commit('notify', async (ctx) => {
+    await notifier.send(ctx.data)
+  })
+```
+
+## 本地開發視覺化
+
+```typescript
+import { FluxEngine, JsonFileTraceSink } from '@gravito/flux'
+
+const engine = new FluxEngine({
+  trace: new JsonFileTraceSink({ path: './.flux/trace.ndjson', reset: true }),
+})
+```
+
+```bash
+flux dev --trace ./.flux/trace.ndjson --port 4280
+```
+
+### 驗證流程（本 repo）
+
+```bash
+bun run examples/trace-viewer.ts
+bun run dev:viewer
+```
+
+## 企業級追蹤
+
+透過 `FluxTraceSink` 可以把事件流送到你自己的監控、排程或分析模組，建立完整的執行查詢、重播與告警能力。
+
+## 儲存介面
+
+### MemoryStorage
+
+```typescript
+import { FluxEngine, MemoryStorage } from '@gravito/flux'
+const engine = new FluxEngine({ storage: new MemoryStorage() })
+```
+
+### BunSQLiteStorage (Bun only)
+
+```typescript
+import { FluxEngine } from '@gravito/flux'
+import { BunSQLiteStorage } from '@gravito/flux/bun'
+
+const engine = new FluxEngine({
+  storage: new BunSQLiteStorage({ path: './data/workflows.db' })
+})
+```
+
+## Gravito 整合
+
+```typescript
+import { OrbitFlux } from '@gravito/flux'
+
+const core = await PlanetCore.boot({
+  orbits: [
+    new OrbitFlux({
+      storage: 'sqlite',
+      dbPath: './data/workflows.db',
+    })
+  ]
+})
+
+const flux = core.services.get<FluxEngine>('flux')
+await flux.execute(myWorkflow, input)
+```
+
+## 平台支援
+
+| Feature | Bun | Node.js |
+|---------|-----|---------|
+| FluxEngine | ✅ | ✅ |
+| MemoryStorage | ✅ | ✅ |
+| BunSQLiteStorage | ✅ | ❌ |
+| OrbitFlux | ✅ | ✅ |

package/bin/flux.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { createServer } from 'node:http'
+import { readFile } from 'node:fs/promises'
+import { dirname, extname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const args = process.argv.slice(2)
+const command = args[0]
+
+const help = () => {
+  console.log(`Flux CLI
+
+Usage:
+  flux dev --trace ./.flux/trace.ndjson --port 4280
+`)
+}
+
+if (!command || command === '--help' || command === '-h') {
+  help()
+  process.exit(0)
+}
+
+if (command !== 'dev') {
+  console.error(`Unknown command: ${command}`)
+  help()
+  process.exit(1)
+}
+
+const getArg = (name, fallback) => {
+  const idx = args.indexOf(name)
+  if (idx === -1) return fallback
+  return args[idx + 1] ?? fallback
+}
+
+const port = Number(getArg('--port', '4280'))
+const host = getArg('--host', '127.0.0.1')
+const tracePath = resolve(getArg('--trace', './.flux/trace.ndjson'))
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const viewerRoot = resolve(join(__dirname, '..', 'dev', 'viewer'))
+
+const contentType = (filePath) => {
+  const ext = extname(filePath)
+  switch (ext) {
+    case '.html':
+      return 'text/html; charset=utf-8'
+    case '.js':
+      return 'text/javascript; charset=utf-8'
+    case '.css':
+      return 'text/css; charset=utf-8'
+    case '.json':
+      return 'application/json; charset=utf-8'
+    case '.svg':
+      return 'image/svg+xml'
+    default:
+      return 'text/plain; charset=utf-8'
+  }
+}
+
+const server = createServer(async (req, res) => {
+  try {
+    const url = new URL(req.url ?? '/', `http://${host}:${port}`)
+    if (url.pathname === '/trace') {
+      try {
+        const data = await readFile(tracePath, 'utf8')
+        res.writeHead(200, {
+          'content-type': 'text/plain; charset=utf-8',
+          'cache-control': 'no-store',
+        })
+        res.end(data)
+      } catch {
+        res.writeHead(204, { 'cache-control': 'no-store' })
+        res.end('')
+      }
+      return
+    }
+
+    const reqPath = url.pathname === '/' ? '/index.html' : url.pathname
+    const filePath = join(viewerRoot, reqPath)
+    const data = await readFile(filePath)
+    res.writeHead(200, {
+      'content-type': contentType(filePath),
+      'cache-control': 'no-store',
+    })
+    res.end(data)
+  } catch (err) {
+    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' })
+    res.end('Not Found')
+  }
+})
+
+server.listen(port, host, () => {
+  console.log(`Flux dev viewer running at http://${host}:${port}`)
+  console.log(`Trace file: ${tracePath}`)
+})

package/dev/viewer/app.js

@@ -0,0 +1,131 @@
+const pathEl = document.getElementById('tracePath')
+const updateEl = document.getElementById('lastUpdate')
+const pathElContainer = document.getElementById('path')
+const statusEl = document.getElementById('status')
+const eventsEl = document.getElementById('events')
+
+const state = {
+  events: [],
+  lastHash: '',
+}
+
+const formatTime = (ts) => new Date(ts).toLocaleTimeString()
+
+const parseNdjson = (text) =>
+  text
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line)
+      } catch {
+        return null
+      }
+    })
+    .filter(Boolean)
+
+const hashText = (text) => {
+  let hash = 0
+  for (let i = 0; i < text.length; i += 1) {
+    hash = (hash << 5) - hash + text.charCodeAt(i)
+    hash |= 0
+  }
+  return String(hash)
+}
+
+const renderPath = (events) => {
+  const steps = []
+  const seen = new Set()
+  for (const event of events) {
+    if (event.stepName && event.type.startsWith('step:')) {
+      if (!seen.has(event.stepName)) {
+        seen.add(event.stepName)
+        steps.push(event.stepName)
+      }
+    }
+  }
+
+  if (!steps.length) {
+    pathElContainer.innerHTML = '<div class="empty">No execution data yet.</div>'
+    return
+  }
+
+  pathElContainer.innerHTML = steps
+    .map((step, index) => {
+      const node = `<span class="node">${step}</span>`
+      const arrow = index < steps.length - 1 ? '<span class="arrow">-&gt;</span>' : ''
+      return `${node}${arrow}`
+    })
+    .join('')
+}
+
+const renderStatus = (events) => {
+  if (!events.length) {
+    statusEl.innerHTML = '<div class="empty">No trace events.</div>'
+    return
+  }
+
+  const lastWorkflow = [...events]
+    .reverse()
+    .find((event) => event.type.startsWith('workflow:'))
+
+  const status = lastWorkflow?.status ?? 'unknown'
+  const badgeClass = status === 'completed' ? 'ok' : status === 'failed' ? 'fail' : ''
+
+  statusEl.innerHTML = `
+    <div>Workflow: <span class="badge ${badgeClass}">${status}</span></div>
+    <div>Workflow ID: ${lastWorkflow?.workflowId ?? '-'}</div>
+    <div>Workflow Name: ${lastWorkflow?.workflowName ?? '-'}</div>
+    <div>Duration: ${lastWorkflow?.duration ? `${lastWorkflow.duration}ms` : '-'}</div>
+  `
+}
+
+const renderEvents = (events) => {
+  if (!events.length) {
+    eventsEl.innerHTML = '<tr><td colspan="6" class="empty">No events yet.</td></tr>'
+    return
+  }
+
+  eventsEl.innerHTML = events
+    .slice()
+    .reverse()
+    .map((event) => {
+      const retry =
+        typeof event.retries === 'number'
+          ? `${event.retries}${event.maxRetries ? `/${event.maxRetries}` : ''}`
+          : '-'
+      const duration = event.duration ? `${event.duration}ms` : '-'
+      const msg = event.error ?? ''
+      return `
+        <tr>
+          <td>${formatTime(event.timestamp)}</td>
+          <td>${event.type}</td>
+          <td>${event.stepName ?? '-'}</td>
+          <td>${retry}</td>
+          <td>${duration}</td>
+          <td>${msg}</td>
+        </tr>
+      `
+    })
+    .join('')
+}
+
+const refresh = async () => {
+  const res = await fetch('/trace', { cache: 'no-store' })
+  const text = await res.text()
+  const hash = hashText(text)
+  if (hash === state.lastHash) return
+
+  state.lastHash = hash
+  state.events = parseNdjson(text)
+  pathEl.textContent = 'Trace: /trace'
+  updateEl.textContent = `Updated: ${new Date().toLocaleTimeString()}`
+
+  renderPath(state.events)
+  renderStatus(state.events)
+  renderEvents(state.events)
+}
+
+refresh()
+setInterval(refresh, 1500)

package/dev/viewer/index.html

@@ -0,0 +1,52 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>Flux Dev Viewer</title>
+    <link rel="stylesheet" href="/styles.css" />
+  </head>
+  <body>
+    <header class="topbar">
+      <div>
+        <h1>Flux Dev Viewer</h1>
+        <p class="subtitle">Local workflow trace explorer</p>
+      </div>
+      <div class="meta">
+        <div id="tracePath">Trace: -</div>
+        <div id="lastUpdate">Updated: -</div>
+      </div>
+    </header>
+
+    <main class="grid">
+      <section class="card">
+        <h2>Execution Path</h2>
+        <div id="path" class="path"></div>
+      </section>
+
+      <section class="card">
+        <h2>Status</h2>
+        <div id="status" class="status"></div>
+      </section>
+
+      <section class="card full">
+        <h2>Timeline</h2>
+        <table class="timeline">
+          <thead>
+            <tr>
+              <th>Time</th>
+              <th>Event</th>
+              <th>Step</th>
+              <th>Retry</th>
+              <th>Duration</th>
+              <th>Message</th>
+            </tr>
+          </thead>
+          <tbody id="events"></tbody>
+        </table>
+      </section>
+    </main>
+
+    <script src="/app.js"></script>
+  </body>
+</html>

package/dev/viewer/styles.css

@@ -0,0 +1,163 @@
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  background: #0c0f14;
+  color: #e6eaf2;
+}
+
+.topbar {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 20px 32px;
+  border-bottom: 1px solid #1d2330;
+  background: linear-gradient(120deg, #111826, #0f1420);
+}
+
+.topbar h1 {
+  margin: 0 0 6px;
+  font-size: 20px;
+  letter-spacing: 0.04em;
+}
+
+.subtitle {
+  margin: 0;
+  color: #93a0b4;
+  font-size: 13px;
+}
+
+.meta {
+  text-align: right;
+  font-size: 12px;
+  color: #9aa6ba;
+  line-height: 1.6;
+}
+
+.grid {
+  display: grid;
+  gap: 18px;
+  padding: 24px 32px 40px;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.card {
+  background: #131a26;
+  border: 1px solid #1d2330;
+  border-radius: 14px;
+  padding: 18px 18px 12px;
+  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.25);
+}
+
+.card.full {
+  grid-column: 1 / -1;
+}
+
+.card h2 {
+  margin: 0 0 14px;
+  font-size: 14px;
+  color: #c7d1e6;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.path {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  align-items: center;
+}
+
+.node {
+  padding: 8px 12px;
+  border-radius: 999px;
+  background: #1a2333;
+  border: 1px solid #2b3a52;
+  font-size: 12px;
+  color: #d6deec;
+}
+
+.arrow {
+  color: #7c8da7;
+  font-size: 14px;
+}
+
+.status {
+  display: grid;
+  gap: 8px;
+  font-size: 13px;
+  color: #b9c5d9;
+}
+
+.badge {
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 999px;
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  background: #1e2532;
+  color: #9db0cc;
+  border: 1px solid #2b364a;
+}
+
+.badge.ok {
+  background: rgba(34, 197, 94, 0.15);
+  color: #7ee4a6;
+  border-color: rgba(34, 197, 94, 0.3);
+}
+
+.badge.fail {
+  background: rgba(248, 113, 113, 0.15);
+  color: #fca5a5;
+  border-color: rgba(248, 113, 113, 0.3);
+}
+
+.timeline {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 12px;
+}
+
+.timeline th,
+.timeline td {
+  padding: 10px 8px;
+  border-bottom: 1px solid #1d2330;
+  text-align: left;
+}
+
+.timeline th {
+  color: #91a0b7;
+  font-weight: 600;
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.timeline tr:last-child td {
+  border-bottom: none;
+}
+
+.empty {
+  color: #7f8ba3;
+  font-size: 12px;
+  padding: 10px 0;
+}
+
+@media (max-width: 900px) {
+  .grid {
+    grid-template-columns: 1fr;
+  }
+  .meta {
+    text-align: left;
+    margin-top: 10px;
+  }
+  .topbar {
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 12px;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/flux",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "description": "Platform-agnostic workflow engine for Gravito",
   "type": "module",
   "main": "./dist/node/index.cjs",
@@ -28,12 +28,19 @@
       }
     }
   },
+  "bin": {
+    "flux": "./bin/flux.js"
+  },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "README.zh-TW.md",
+    "bin",
+    "dev"
   ],
   "scripts": {
     "build": "bun run build.ts",
+    "dev:viewer": "node ./bin/flux.js dev --trace ./.flux/trace.ndjson --port 4280",
     "typecheck": "tsc --noEmit",
     "test": "bun test"
   },