Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
826f969
Rewrite framework docs to showcase power and developer experience
claude Feb 28, 2026
e055f5b
Rewrite Docusaurus docs site to be compelling and developer-focused
claude Feb 28, 2026
2ab6415
Highlight tools-as-blocks, hybrid resources, ecosystem, and flows-as-…
claude Feb 28, 2026
3beeba8
Fix incorrect session state route — sessions endpoint has no kind seg…
claude Feb 28, 2026
a124c47
Stylize as flow-state.dev, fix branding, improve examples, add connec…
claude Feb 28, 2026
c93a5c7
Rewrite blog post to reflect framework vision: exploring new AI patterns
claude Feb 28, 2026
15967b8
Redesign landing page: dark theme, modern layout, mobile-friendly
claude Feb 28, 2026
01be582
Show component item model in landing page examples
claude Feb 28, 2026
ed2ee16
Showcase full sequencer DSL power in landing page and blocks docs
claude Feb 28, 2026
3854c7f
Replace analyze handler with sequencer that emits component via tap
claude Feb 28, 2026
59228a0
Fix API contract mismatches flagged in PR review comments
claude Feb 28, 2026
f8b34ec
Merge main into feature branch, resolve conflict in core README
claude Mar 1, 2026
eeebc57
Improve Define tab: imports, comments, inputSchema, sessionStateSchema
claude Mar 1, 2026
f8e67a7
Fix comment indentation on landing page, add state bubbling docs
claude Mar 1, 2026
482de34
Add Type System concept page, callout in state docs, fix comment indent
claude Mar 1, 2026
e9a6097
Reorder type-system in sidebar, fix naming, add type extraction docs
claude Mar 1, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Showcase full sequencer DSL power in landing page and blocks docs
Landing page Define tab now shows a sequencer with parallel steps,
doUntil loop, background work, and rescue — not just .then() chains.
Feature card calls out specific DSL methods by name.

blocks.md sequencer section expanded from a single example to full
coverage of all DSL capabilities: parallel, forEach, doUntil/doWhile,
loopBack, work/waitForWork, branch, tap/tapIf, rescue, and map —
each with code examples. Closes with a composed example showing how
they combine into a single block.

https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh
  • Loading branch information
claude committed Feb 28, 2026
commit ed2ee1625481a0dcae88cdd74e23bdb2c2eccd26
158 changes: 140 additions & 18 deletions apps/docs/docs/concepts/blocks.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,27 +92,149 @@ When the LLM calls `deep-research`, the framework runs the full sequencer pipeli

### Sequencer — the composition engine

Sequencers compose blocks into pipelines using a fluent DSL. Each step's output feeds into the next step's input.
Sequencers compose blocks into pipelines using a fluent DSL with 15 chainable methods. Each step's output feeds into the next step's input, with full type inference through the chain.

#### Sequential steps

The basics — chain blocks in order, conditionally skip steps, or transform values inline:

```ts
import { sequencer } from "@flow-state-dev/core";
const pipeline = sequencer({ name: "pipeline", inputSchema })
.then(analyzeInput) // always runs
.thenIf((result) => result.needsContext, enrichWithContext) // conditional
.map((result) => ({ ...result, timestamp: Date.now() })) // inline transform
.then(agent);
```

const pipeline = sequencer({
name: "chat-pipeline",
inputSchema: z.object({ message: z.string() }),
})
.then(analyzeInput)
.thenIf((result) => result.needsContext, enrichWithContext)
.then(agent)
.tap(analyticsBlock)
.rescue([
{ when: [NetworkError], block: retryWithBackup },
{ when: [ModelError], block: fallbackModel },
{ block: genericRecovery },
]);
```

The DSL has 14 methods: `then`, `thenIf`, `parallel`, `forEach`, `doUntil`, `doWhile`, `map`, `tap`, `tapIf`, `rescue`, `branch`, `work`, `waitForWork`, `loopBack`. See [Sequencer Patterns](/docs/guides/sequencer-patterns) for recipes.
#### Parallel execution

Run multiple blocks concurrently with a single step. Output is an object keyed by step name:

```ts
const enriched = sequencer({ name: "enrich" })
.then(parseQuery)
.parallel({
web: searchWeb,
docs: searchInternalDocs,
memory: { connector: (input) => input.userId, block: searchUserHistory },
}, { maxConcurrency: 3 })
// output: { web: WebResults, docs: DocResults, memory: HistoryResults }
.then(mergeResults);
```

#### Collection processing

Process arrays concurrently with `forEach`. Supports dynamic block selection per item:

```ts
pipeline
.forEach(processChunk, { maxConcurrency: 5 }) // static block
.forEach((input) => input.urls, fetchUrl, { maxConcurrency: 10 }) // extract array first
.forEach((item, index) => item.type === "pdf" ? parsePdf : parseText); // dynamic block
```

#### Loops

Three loop constructs — each with built-in guards to prevent infinite loops:

```ts
pipeline
// Loop until condition is true (checked after each iteration)
.doUntil((result) => result.confidence > 0.9, refineBlock)

// Loop while condition is true (checked after each iteration)
.doWhile((result) => result.remaining > 0, processNextBatch)

// Jump back to a named step — requires explicit max iterations
.then(generateBlock)
.then(validateBlock)
.loopBack("generate-block", {
when: (result) => !result.isValid,
maxIterations: 3,
});
```

#### Background work

Queue non-blocking tasks that run alongside the main pipeline. The main chain continues immediately — background failures emit `step_error` items but never abort the pipeline:

```ts
pipeline
.then(coreLogic)
.work(logAnalytics) // fire and forget
.work((output) => output.metrics, reportMetrics) // with connector
.then(moreWork)
.waitForWork({ timeoutMs: 5000 }); // optionally converge later
```

#### Branching

Route to different blocks based on runtime conditions. First matching branch wins:

```ts
pipeline.branch({
urgent: [
(input) => input,
(input) => input.priority === "critical",
urgentPipeline,
],
standard: [
(input) => input,
(input) => input.priority === "normal",
standardPipeline,
],
fallback: [
(input) => input,
() => true, // catch-all
defaultPipeline,
],
});
```

#### Side effects

Run blocks or functions for observation without changing the payload:

```ts
pipeline
.tap(auditLogBlock) // block side effect
.tap((value, ctx) => console.log("checkpoint", value)) // inline side effect
.tapIf((value) => value.score < 0.5, alertBlock); // conditional side effect
```

#### Error recovery

Catch errors from prior steps and route to recovery blocks by error type:

```ts
pipeline.rescue([
{ when: [RateLimitError], block: retryWithBackoff },
{ when: [ModelError], block: fallbackModel },
{ block: genericRecovery }, // catch-all
]);
```

#### Putting it all together

These compose into sophisticated workflows that would be painful to build from scratch:

```ts
const researchAgent = sequencer({ name: "research-agent" })
.then(parseQuery)
.parallel({
web: searchWeb,
docs: searchDocs,
memory: searchMemory,
})
.then(mergeAndRank)
.doUntil((r) => r.confidence > 0.9, refineResults)
.work(logAnalytics)
.then(synthesize)
.tapIf((r) => r.citations.length > 5, notifyReviewer)
.rescue([{ when: [SearchError], block: fallbackSearch }]);
```

That's a parallel search across three sources, iterative refinement until confidence is high, background analytics, synthesis, conditional notification, and error recovery — all as a single composable block that can be nested inside other sequencers, used as a generator tool, or registered as a flow action.

### Router — runtime dispatch

Expand Down
20 changes: 15 additions & 5 deletions apps/docs/src/pages/index.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,21 @@ import styles from "./index.module.css";

const defineExample = `import { defineFlow, generator, handler, sequencer } from "@flow-state-dev/core";

// A tool that's a full multi-step pipeline — not a function wrapper
// A tool that's a full pipeline — parallel steps, background work, error recovery
const deepResearch = sequencer({ name: "deep-research" })
.then(searchIndex)
.then(rankResults)
.then(summarize);
.then(parseQuery)
.parallel({
web: searchWeb,
docs: searchInternalDocs,
memory: searchMemory,
}, { maxConcurrency: 3 })
.then(mergeAndRank)
.doUntil(
(result) => result.confidence > 0.9,
refineResults
)
.work(logAnalytics)
.rescue([{ when: [SearchError], block: fallbackSearch }]);

// Blocks emit component items — structured data for the UI
const analyze = handler({
Expand Down Expand Up @@ -174,7 +184,7 @@ const features: FeatureItem[] = [
{
title: "Four primitives. Compose freely.",
description:
"Handler, generator, sequencer, router — every AI workflow reduces to these four blocks. Compose with branching, parallelism, loops, and error recovery.",
"Handler, generator, sequencer, router. The sequencer DSL alone gives you parallel steps, forEach, doUntil/doWhile loops, background work, branching, error recovery, and more.",
},
{
title: "Flows are full APIs.",
Expand Down