@siglo/core
v1.2.6
Published
TypeScript workflow orchestration with durable checkpoints, retries, saga compensation, and live DevTools.
Maintainers
Readme
Siglo Core
Zero-daemon, in-process workflow orchestration with durable checkpoints, Sagas, and live visual DevTools.
Siglo is a lightweight, zero-daemon workflow runtime for TypeScript. It orchestrates complex business logic into composable, resilient steps—featuring end-to-end type inference, automatic Sagas, durable checkpoints, and live DevTools without external infrastructure.
Positioning: In-Process Orchestration vs Distributed Engines
| Dimension | Siglo | Distributed Engines (Temporal, Inngest) |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| Architecture | Lightweight, zero-infrastructure in-process library | Heavy multi-cluster / external orchestrator daemon |
| Latency | Microsecond direct async function invocation | Millisecond-to-second RPC / polling overhead |
| Footprint | Zero external dependencies, pure TypeScript | Requires persistent workers, queue servers, and databases |
| Primary Focus | Modular workflows, parallel fan-out/fan-in, bounded worker mapping, request-scoped sagas, idempotency, durable event waits, retry backoff with jitter, OCC checkpointing | Months-long durable human-in-the-loop workflows |
Documentation & Topic Guides
Explore the 11 comprehensive guides covering architecture, design patterns, testing, and production operations:
- 🚀 01. Getting Started — Installation, quickstart walkthrough, minimal examples, and CLI scaffolding.
- 💡 02. Core Concepts — Executable ASTs, accumulated context immutability, 5-phase step lifecycle, and reserved keys.
- ⛓️ 03. Sequential Workflows — Linear pipelines, clean POJO parameters, lifecycle hooks (
onBefore,onSkip,onAfter), and caching. - 🔀 04. Branching and Parallelism — Concurrent fan-outs (
parallel,all,allSettled,race), dynamic routing (when,branch), and bounded mapping (map). - 🛡️ 05. Retries, Timeouts, and Cancellation — Two-tier timeouts, exponential backoff with jitter, cooperative
AbortSignalcancellation, and saga rollbacks. - ⏳ 06. Durable Workflows — Long-running human-in-the-loop waits (
waitForEvent,wait), checkpoint resumption, and state migrations. - 💾 07. Storage and Adapters — Distributed persistence contracts, PostgreSQL & Redis adapters, and multi-tenant namespaces.
- 🔭 08. Observability — Graph exports (Mermaid, DOT, JSON), OpenTelemetry distributed tracing, and W3C trace propagation.
- 🧪 09. Testing and Replay — Deterministic workflow harnesses (
@siglo/testing), fake clocks, step spies, mocks, and failure replay. - 🏷️ 10. TypeScript Reference — End-to-end accumulated context inference, typed step history (
$steps), and Standard Schema integration. - 🏭 11. Production Operations — Production deployment checklist, zero-daemon operational topologies, connection pooling, and retention cleanup.
Quickstart: Type-Safe Composable Flows
Install the TypeScript workflow runtime:
npm install @siglo/coreimport { Step, flow } from '@siglo/core';
// 1. Define modular steps with input/output contracts
const fetchUser = Step.create('fetchUser', async (param: { userId: string }) => {
return { name: 'Alice', tier: 'PRO' };
});
const calculateDiscount = Step.create('calculateDiscount', async (param: { tier: string }) => {
const discount = param.tier === 'PRO' ? 0.2 : 0.05;
return { discountPercentage: discount };
});
// 2. Compose into an executable flow
export const orderWorkflow = flow(fetchUser, calculateDiscount);
// 3. Run the flow with full type safety
async function main() {
const result = await orderWorkflow.run({ userId: 'u_123' }, { pojo: true });
console.log(result.name); // 'Alice'
console.log(result.discountPercentage); // 0.20
console.log(result.$steps.fetchUser); // { name: 'Alice', tier: 'PRO' }
}
main();Key Features
- ⚡ Composable Flows (
flow) — Compose steps directly into workflows without global registries; steps are pure execution units. - 🧠 Accumulated Context Inference — TypeScript automatically computes the accumulated output type across composed sequential steps at compile time.
- 📜 Typed Step History (
$steps) — Statically typed access to any step's output using string literal names (context.$steps.loadUser.user). - 🗺️ Workflow Graph Visualization — Export workflow graphs directly to Mermaid diagrams (
flow.toMermaid()), Graphviz DOT (flow.toDot()), and JSON AST (flow.toJSON()) with policy badges. - 💉 Runtime Dependency Injection — Inject services and repositories explicitly via
options.servicesor step-levelstep.withDependencies(). - 🔀 Parallel Execution Combinators — Run branches concurrently with
parallel,all,allSettled, andrace, equipped with branch context isolation and configurable merge strategies. - 🌿 Conditional Branching & Routing — Dynamic decision routing via
when(predicate, thenStep, elseStep)and multi-branch selectors viabranch(selectorFn, branchesMap, defaultBranch). - 🔄 Dynamic Mapping & Bounded Concurrency — Process arrays with
map(items, step, { concurrency }), order preservation, and error aggregation. - 🔑 Scoped Idempotency & Deduplication — Protect workflows and individual steps (
step.idempotent()) with deterministic hash keys and TTL stores. - ⏪ Sagas & LIFO Compensations — Attach rollback handlers (
step.compensate(handler)) that run automatically in reverse execution order upon failure. - ⏳ Durable Waits & Event Resumption — Pause execution with
waitForEvent(eventName)orwait('30m'), persist suspended checkpoints, and safely resume workflows. - 🏷️ Workflow Versioning & State Migrations — Declare workflow versions (
flow.version('v2')), detect version mismatches upon resumption, and run registered state transformation functions. - ⏱️ Resilient Deadlines & Two-Tier Timeouts — Enforce per-step SLA (
step.timeout(ms)) and workflow-level deadlines (flow.timeout(ms)).\ - 🔁 Structured Retry Strategies — Automatic retries with exponential, linear, or fixed backoff, jitter, and
onRetryhooks right inonFail.\ - 📦 Standard Schema Integration (
spec/schema) — Native Standard Schema, Zod, Valibot, and ArkType contract enforcement.\ - 🛑 Graceful Cancellation & AbortSignals — Cancel flows, in-flight async steps, and retry timers seamlessly using standard
AbortSignal.
License
This project is licensed under the MIT License - see the LICENSE file for details.
