upstash/workflow-js / skills
upstash-workflow-js
UnverifiedLightweight guidance for using the Upstash Workflow SDK to define, trigger, and manage workflows. Use this Skill whenever a user wants to create workflow endpoints, run steps, or interact with the Upstash Workflow client.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.2 KB |
| agents.md | markdown | 6.7 KB |
| basics/client.md | markdown | 4.1 KB |
| basics/context.md | markdown | 5.1 KB |
| basics/serve.md | markdown | 2.4 KB |
| features/flow-control.md | markdown | 3.9 KB |
| features/invoke.md | markdown | 2.6 KB |
| features/retries-failures-reliability.md | markdown | 6.3 KB |
| features/wait-for-event.md | markdown | 2.8 KB |
| features/webhooks.md | markdown | 2.5 KB |
| how-to/local-dev.md | markdown | 3.2 KB |
| how-to/middleware.md | markdown | 4.7 KB |
| how-to/migrations.md | markdown | 4.8 KB |
| how-to/realtime.md | markdown | 4.8 KB |
| rest-api.md | markdown | 6.6 KB |
| troubleshooting.md | markdown | 4.8 KB |
features/flow-control.md
View on GitHub# Flow Control
Flow Control defines how many workflow steps may run or start within a given time, ensuring predictable load and preventing overload of internal or third‑party systems. It applies per **flow control key**, allowing steps across different workflow runs to share the same limits.
This skill documents:
- parallelism
- rate and period
- monitoring
- common behaviors and pitfalls
## Core Concepts
### Flow Control Key
A string identifier grouping related workflow steps under shared limits.
All steps triggered with the same key share the same concurrency and rate budget.
```ts
const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.trigger({
url: "https://<YOUR_ENDPOINT>",
flowControl: {
key: "user-onboarding", // Groups steps under this key
parallelism: 5, // max concurrent steps
rate: 20, // max starts per period
period: "1m", // time window
},
});
```
## Parallelism
Controls **how many steps may run concurrently**.
Works like a token bucket: each running step consumes one token; when it finishes, the token is released.
- If tokens are available → step starts immediately.
- If no tokens → step enters the waitlist.
- Token handoff is **not FIFO**; later steps may start earlier.
### Example Behavior
- `parallelism = 3` → at most 3 steps run at the same time.
- Step 4 waits until one of the first 3 completes.
Parallelism affects **execution concurrency**, not rate‑of‑start per time window.
## Rate & Period
Controls **how many steps may START within a defined time window**.
```ts
flowControl: {
key: "billing-jobs",
rate: 2, // allow 2 starts
period: "10s", // every 10 seconds
parallelism: 1, // can be combined
}
```
Behavior:
- First `rate` steps in each period start immediately.
- Additional steps wait until the next window.
- Execution duration **does not** count toward the period; only start time matters.
This is rate limiting, not concurrency control.
## Combining Rate + Parallelism
Both limits apply **independently**.
A step must satisfy _both_ to run.
Example:
- `rate = 3 per minute`
- `parallelism = 7`
Even if concurrency slots are free, steps may be delayed by the rate window.
Even if rate window is open, steps may be delayed by concurrency.
This enables predictable load patterns.
## Monitoring
Flow control queues and waitlists are visible from:
- Console → **FlowControl** tab (waitlist size per key)
- REST API:
- List all keys
- Get details for one key
Useful for diagnosing bottlenecks, long queues, or misconfigured limits.
## Important Behaviors & Pitfalls
### Limits are stored on each step
If you deploy new limits, previously published steps keep their original configuration.
### No per‑step config (mostly)
All steps inherit the workflow‑run’s flowControl block.
Exceptions:
- `context.call` – may define a separate key to isolate API throttling.
- `context.invoke` – spawns a new workflow run with its own flowControl.
To isolate heavy or sensitive steps, move them into a separate workflow and invoke them.
### Waitlist order is not guaranteed
A later step may receive a token before an earlier one.
Do not rely on ordering.
### Queueing is automatic
Exceeding limits never rejects steps. Everything is eventually executed.
## Full Example
Demonstrates defining all parameters together and how they interact.
```ts
import { Client } from "@upstash/workflow";
const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.trigger({
url: "https://<YOUR_WORKFLOW_ENDPOINT>/process",
flowControl: {
key: "media-processing", // Shared grouping key
parallelism: 4, // Max 4 at the same time
rate: 10, // Max 10 starts
period: "60s", // in 60 seconds
},
});
```
This configuration:
- ensures no more than 4 processing tasks run concurrently
- ensures no more than 10 tasks start per minute
- queues everything automatically beyond those limits
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |