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

package/README.zh-TW.md

@@ -2,6 +2,25 @@
 
 > Gravito 的高效能工作流程引擎，跨平台、型別安全的狀態機，強調可追蹤、可重播與可靠重試。
 
+## 定位與價值
+
+- **工作流標準化**：在框架內用同一套模型描述流程，而不是每個服務自行手寫流程。
+- **可靠性與可觀測**：狀態機 + 重試 + trace sink，讓流程可追蹤、可審計、可恢復。
+- **可抽離與可複用**：Flux 可獨立於框架使用，讓 workflow 本身成為可移植的 workflow as code。
+
+## API 語意（input / step / commit）
+
+- `input<T>()`：定義輸入資料型別，提供型別推斷與編輯器提示。
+- `step(name, handler, options)`：一般步驟，會依序執行，可設定重試/逾時/條件。
+- `commit(name, handler, options)`：具副作用的步驟（寫庫、扣款、通知），在重播或重跑時語意更明確。
+
+## 最佳實務與注意事項
+
+- **儲存介面**：Memory 僅適合開發與測試，正式環境請使用持久化 storage。
+- **版本變更**：workflow 定義改動時，既有流程的重跑需評估相容性。
+- **重試策略**：外部依賴錯誤才重試，業務邏輯錯誤建議直接 fail。
+- **Step vs Commit**：有副作用的操作應放在 commit，確保重播一致性。
+
 ## 核心特色
 
 - **純狀態機模型** - 以明確狀態描述流程，讓每一步清晰可控
@@ -142,6 +161,75 @@ const engine = new FluxEngine({
 })
 ```
 
+## 重跑指定步驟
+
+```typescript
+const first = await engine.execute(flow, { orderId: 'ORD-001' })
+await engine.retryStep(flow, first.id, 'charge')
+```
+
+## 與隊列搭配的應用
+
+隊列消費者只負責觸發 Flux，Flux 會把任務拆成多步驟 workflow。當某一步失敗時，只重試該步，不會重跑已完成的步驟。
+
+```typescript
+queue.on('message', async (job) => {
+  await flux.execute(orderFlow, job.data)
+})
+```
+
+搭配持久化 storage，已完成的步驟會被保留，避免重複執行。
+
+### Kafka 完整案例（事件 → 消費者 → Flux）
+
+**1) 事件觸發：把任務丟進 Kafka**
+
+```typescript
+import { Kafka } from 'kafkajs'
+
+const kafka = new Kafka({ clientId: 'orders', brokers: ['localhost:9092'] })
+const producer = kafka.producer()
+
+await producer.connect()
+await producer.send({
+  topic: 'order.created',
+  messages: [
+    { key: 'ORD-001', value: JSON.stringify({ orderId: 'ORD-001', userId: 'u_1' }) },
+  ],
+})
+```
+
+**2) 消費者接到任務後交給 Flux**
+
+```typescript
+import { Kafka } from 'kafkajs'
+import { createWorkflow, FluxEngine, MemoryStorage } from '@gravito/flux'
+
+const orderFlow = createWorkflow('order-flow')
+  .input<{ orderId: string; userId: string }>()
+  .step('validate', async (ctx) => {
+    ctx.data.validated = true
+  })
+  .step('reserve', async (ctx) => {
+    ctx.data.reserved = true
+  })
+  .commit('notify', async () => {})
+
+const flux = new FluxEngine({ storage: new MemoryStorage() })
+
+const kafka = new Kafka({ clientId: 'orders-worker', brokers: ['localhost:9092'] })
+const consumer = kafka.consumer({ groupId: 'order-workers' })
+
+await consumer.connect()
+await consumer.subscribe({ topic: 'order.created' })
+await consumer.run({
+  eachMessage: async ({ message }) => {
+    const payload = JSON.parse(message.value?.toString() ?? '{}')
+    await flux.execute(orderFlow, payload)
+  },
+})
+```
+
 ## 分支流程（多支點）
 
 ```typescript
@@ -176,6 +264,54 @@ const flow = createWorkflow('event-routing')
   })
 ```
 
+## 多節點任務（類似 n8n）
+
+```typescript
+const flow = createWorkflow('multi-node')
+  .input<{ type: 'email' | 'slack' | 'webhook'; payload: unknown }>()
+  .step('classify', async (ctx) => {
+    ctx.data.route = ctx.input.type
+  })
+  .step(
+    'send-email',
+    async (ctx) => {
+      await email.send(ctx.input.payload)
+    },
+    { when: (ctx) => ctx.data.route === 'email' }
+  )
+  .step(
+    'send-slack',
+    async (ctx) => {
+      await slack.send(ctx.input.payload)
+    },
+    { when: (ctx) => ctx.data.route === 'slack' }
+  )
+  .step(
+    'call-webhook',
+    async (ctx) => {
+      await webhook.post(ctx.input.payload)
+    },
+    { when: (ctx) => ctx.data.route === 'webhook' }
+  )
+  .commit('audit', async (ctx) => {
+    await audit.save(ctx.data)
+  })
+```
+
+<img
+  src="./assets/flux-branching.svg"
+  alt="Flux branching diagram"
+  style="max-width: 720px; width: 100%; height: auto; display: block; margin: 12px 0;"
+/>
+
+上圖對應 `when` 條件：只會走符合條件的分支，未符合者會被標記為 skipped。
+
+### 可執行分支範例
+
+```bash
+bun run examples/branching.ts
+```
+
 ## 本地開發視覺化
 
 ```typescript
@@ -201,6 +337,59 @@ bun run dev:viewer
 
 透過 `FluxTraceSink` 可以把事件流送到你自己的監控、排程或分析模組，建立完整的執行查詢、重播與告警能力。
 
+## 以微服務或 AWS Lambda 部署
+
+Flux 可抽離成無狀態 workflow runner。把 workflow 定義與 input 交給函式執行，再將狀態與 trace 寫入外部儲存即可：
+
+```typescript
+import { FluxEngine, JsonFileTraceSink, MemoryStorage, createWorkflow } from '@gravito/flux'
+
+const workflow = createWorkflow('lambda-flow')
+  .input<{ orderId: string }>()
+  .step('prepare', async (ctx) => {
+    ctx.data.ready = true
+  })
+  .commit('notify', async () => {})
+
+const engine = new FluxEngine({
+  storage: new MemoryStorage(),
+  trace: new JsonFileTraceSink({ path: '/tmp/flux-trace.ndjson', reset: false }),
+})
+
+export const handler = async (event: { orderId: string }) => {
+  const result = await engine.execute(workflow, { orderId: event.orderId })
+  return { status: result.status, id: result.id }
+}
+```
+
+### 其他雲端函式範例
+
+GCP Cloud Functions（HTTP，需安裝對應套件並確認最新版本）：
+
+```typescript
+import type { HttpFunction } from '@google-cloud/functions-framework'
+
+export const runFlux: HttpFunction = async (req, res) => {
+  const payload = req.body ?? {}
+  const result = await engine.execute(workflow, payload)
+  res.json({ status: result.status, id: result.id })
+}
+```
+
+Azure Functions（HTTP Trigger，需安裝對應套件並確認最新版本）：
+
+```typescript
+import type { AzureFunction, Context, HttpRequest } from '@azure/functions'
+
+const httpTrigger: AzureFunction = async (context: Context, req: HttpRequest) => {
+  const payload = req.body ?? {}
+  const result = await engine.execute(workflow, payload)
+  context.res = { status: 200, body: { status: result.status, id: result.id } }
+}
+
+export default httpTrigger
+```
+
 ## 儲存介面
 
 ### MemoryStorage

package/assets/flux-branching.svg

@@ -0,0 +1,84 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 240" role="img" aria-label="Flux branching diagram">
+  <defs>
+    <linearGradient id="fluxNode" x1="0" x2="1">
+      <stop offset="0%" stop-color="#141c2b" />
+      <stop offset="100%" stop-color="#0b1220" />
+    </linearGradient>
+    <linearGradient id="glow-blue" x1="0" x2="1">
+      <stop offset="0%" stop-color="#38bdf8" />
+      <stop offset="100%" stop-color="#60a5fa" />
+    </linearGradient>
+    <linearGradient id="glow-violet" x1="0" x2="1">
+      <stop offset="0%" stop-color="#a78bfa" />
+      <stop offset="100%" stop-color="#8b5cf6" />
+    </linearGradient>
+    <linearGradient id="glow-amber" x1="0" x2="1">
+      <stop offset="0%" stop-color="#fbbf24" />
+      <stop offset="100%" stop-color="#f59e0b" />
+    </linearGradient>
+    <linearGradient id="glow-emerald" x1="0" x2="1">
+      <stop offset="0%" stop-color="#34d399" />
+      <stop offset="100%" stop-color="#10b981" />
+    </linearGradient>
+    <linearGradient id="glow-rose" x1="0" x2="1">
+      <stop offset="0%" stop-color="#fb7185" />
+      <stop offset="100%" stop-color="#f43f5e" />
+    </linearGradient>
+    <filter id="nodeShadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="8" stdDeviation="10" flood-color="#0b1120" flood-opacity="0.6" />
+    </filter>
+    <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#60a5fa" />
+    </marker>
+  </defs>
+
+  <!-- classify -->
+  <g filter="url(#nodeShadow)">
+    <rect x="30" y="100" width="160" height="50" rx="14" fill="url(#fluxNode)" stroke="#1f2937" />
+    <rect x="42" y="112" width="26" height="26" rx="8" fill="url(#glow-blue)" />
+    <path d="M52 119h6l4 6-4 6h-6l-4-6z" fill="#0f172a" />
+    <text x="120" y="130" fill="#e2e8f0" font-size="12" text-anchor="middle">classify</text>
+  </g>
+
+  <!-- send-email -->
+  <g filter="url(#nodeShadow)">
+    <rect x="250" y="20" width="180" height="46" rx="14" fill="url(#fluxNode)" stroke="#1f2937" />
+    <rect x="262" y="32" width="26" height="26" rx="8" fill="url(#glow-amber)" />
+    <path d="M268 38h14l-7 6z" fill="#0f172a" />
+    <rect x="268" y="40" width="14" height="10" rx="2" fill="none" stroke="#0f172a" stroke-width="1.6" />
+    <text x="350" y="48" fill="#e2e8f0" font-size="12" text-anchor="middle">send-email</text>
+  </g>
+
+  <!-- send-slack -->
+  <g filter="url(#nodeShadow)">
+    <rect x="250" y="96" width="180" height="46" rx="14" fill="url(#fluxNode)" stroke="#1f2937" />
+    <rect x="262" y="108" width="26" height="26" rx="8" fill="url(#glow-violet)" />
+    <path d="M269 115h10a4 4 0 0 1 4 4v6l-5-3h-9a4 4 0 0 1-4-4v-3a4 4 0 0 1 4-4z" fill="#0f172a" />
+    <text x="350" y="124" fill="#e2e8f0" font-size="12" text-anchor="middle">send-slack</text>
+  </g>
+
+  <!-- call-webhook -->
+  <g filter="url(#nodeShadow)">
+    <rect x="250" y="172" width="180" height="46" rx="14" fill="url(#fluxNode)" stroke="#1f2937" />
+    <rect x="262" y="184" width="26" height="26" rx="8" fill="url(#glow-emerald)" />
+    <path d="M268 198h14m-7-6v12" stroke="#0f172a" stroke-width="2" stroke-linecap="round" />
+    <text x="350" y="200" fill="#e2e8f0" font-size="12" text-anchor="middle">call-webhook</text>
+  </g>
+
+  <!-- audit -->
+  <g filter="url(#nodeShadow)">
+    <rect x="520" y="100" width="160" height="50" rx="14" fill="url(#fluxNode)" stroke="#1f2937" />
+    <rect x="532" y="112" width="26" height="26" rx="8" fill="url(#glow-rose)" />
+    <path d="M538 118h14v12h-14z" fill="none" stroke="#0f172a" stroke-width="1.6" />
+    <path d="M541 122h8M541 126h8M541 130h6" stroke="#0f172a" stroke-width="1.6" stroke-linecap="round" />
+    <text x="610" y="130" fill="#e2e8f0" font-size="12" text-anchor="middle">audit</text>
+  </g>
+
+  <line x1="190" y1="125" x2="250" y2="43" stroke="#60a5fa" stroke-width="2" marker-end="url(#arrow)" />
+  <line x1="190" y1="125" x2="250" y2="119" stroke="#60a5fa" stroke-width="2" marker-end="url(#arrow)" />
+  <line x1="190" y1="125" x2="250" y2="195" stroke="#60a5fa" stroke-width="2" marker-end="url(#arrow)" />
+
+  <line x1="430" y1="43" x2="520" y2="125" stroke="#38bdf8" stroke-width="2" marker-end="url(#arrow)" />
+  <line x1="430" y1="119" x2="520" y2="125" stroke="#38bdf8" stroke-width="2" marker-end="url(#arrow)" />
+  <line x1="430" y1="195" x2="520" y2="125" stroke="#38bdf8" stroke-width="2" marker-end="url(#arrow)" />
+</svg>

package/dist/bun.cjs

@@ -0,0 +1,7 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkSJSPR4ZUcjs = require('./chunk-SJSPR4ZU.cjs');
+
+
+exports.BunSQLiteStorage = _chunkSJSPR4ZUcjs.BunSQLiteStorage;
+//# sourceMappingURL=bun.cjs.map

package/dist/bun.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/carl/Dev/Carl/gravito-core/packages/flux/dist/bun.cjs"],"names":[],"mappings":"AAAA;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,8DAAC","file":"/Users/carl/Dev/Carl/gravito-core/packages/flux/dist/bun.cjs"}

package/dist/{storage/BunSQLiteStorage.d.ts → bun.d.cts}

@@ -1,3 +1,6 @@
+import { Database } from 'bun:sqlite';
+import { n as WorkflowStorage, l as WorkflowState, k as WorkflowFilter } from './types-DvVHBmP6.cjs';
+
 /**
  * @fileoverview Bun SQLite Storage Adapter
  *
@@ -5,12 +8,11 @@
  *
  * @module @gravito/flux/storage
  */
-import { Database } from 'bun:sqlite';
-import type { WorkflowFilter, WorkflowState, WorkflowStorage } from '../types';
+
 /**
  * SQLite Storage Options
  */
-export interface BunSQLiteStorageOptions {
+interface BunSQLiteStorageOptions {
     /** Database file path (default: ':memory:') */
     path?: string;
     /** Table name (default: 'flux_workflows') */
@@ -28,7 +30,7 @@ export interface BunSQLiteStorageOptions {
  * })
  * ```
  */
-export declare class BunSQLiteStorage implements WorkflowStorage {
+declare class BunSQLiteStorage implements WorkflowStorage {
     private db;
     private tableName;
     private initialized;
@@ -70,4 +72,5 @@ export declare class BunSQLiteStorage implements WorkflowStorage {
      */
     vacuum(): void;
 }
-//# sourceMappingURL=BunSQLiteStorage.d.ts.map
+
+export { BunSQLiteStorage, type BunSQLiteStorageOptions };

package/dist/bun.d.ts

@@ -1,9 +1,76 @@
+import { Database } from 'bun:sqlite';
+import { n as WorkflowStorage, l as WorkflowState, k as WorkflowFilter } from './types-DvVHBmP6.js';
+
 /**
- * @fileoverview Bun-specific exports
+ * @fileoverview Bun SQLite Storage Adapter
  *
- * This entry exports Bun-optimized components.
+ * High-performance storage using Bun's built-in SQLite.
  *
- * @module @gravito/flux/bun
+ * @module @gravito/flux/storage
  */
-export { BunSQLiteStorage, type BunSQLiteStorageOptions } from './storage/BunSQLiteStorage';
-//# sourceMappingURL=bun.d.ts.map
+
+/**
+ * SQLite Storage Options
+ */
+interface BunSQLiteStorageOptions {
+    /** Database file path (default: ':memory:') */
+    path?: string;
+    /** Table name (default: 'flux_workflows') */
+    tableName?: string;
+}
+/**
+ * Bun SQLite Storage
+ *
+ * High-performance storage adapter using Bun's built-in SQLite.
+ *
+ * @example
+ * ```typescript
+ * const engine = new FluxEngine({
+ *   storage: new BunSQLiteStorage({ path: './data/flux.db' })
+ * })
+ * ```
+ */
+declare class BunSQLiteStorage implements WorkflowStorage {
+    private db;
+    private tableName;
+    private initialized;
+    constructor(options?: BunSQLiteStorageOptions);
+    /**
+     * Initialize storage (create tables)
+     */
+    init(): Promise<void>;
+    /**
+     * Save workflow state
+     */
+    save(state: WorkflowState): Promise<void>;
+    /**
+     * Load workflow state by ID
+     */
+    load(id: string): Promise<WorkflowState | null>;
+    /**
+     * List workflow states with optional filter
+     */
+    list(filter?: WorkflowFilter): Promise<WorkflowState[]>;
+    /**
+     * Delete workflow state
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Close database connection
+     */
+    close(): Promise<void>;
+    /**
+     * Convert SQLite row to WorkflowState
+     */
+    private rowToState;
+    /**
+     * Get raw database (for advanced usage)
+     */
+    getDatabase(): Database;
+    /**
+     * Run a vacuum to optimize database
+     */
+    vacuum(): void;
+}
+
+export { BunSQLiteStorage, type BunSQLiteStorageOptions };

package/dist/bun.js

@@ -1,7 +1,7 @@
-// @bun
 import {
   BunSQLiteStorage
-} from "./chunk-qjdtqchy.js";
+} from "./chunk-ZAMVC732.js";
 export {
   BunSQLiteStorage
 };
+//# sourceMappingURL=bun.js.map

package/dist/bun.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}