feat: add run:progress event for real-time progress tracking

[coji]

Summary

• Add run:progress event that is emitted when step.progress() is called
• Enables real-time progress tracking via event subscription
• Event payload: { runId, jobName, progress: { current, total?, message? } }
• Bump version to 0.5.0

Changes

• events.ts: Add RunProgressEvent interface
• context.ts: Emit run:progress event in progress() method
• index.ts: Export RunProgressEvent type
• Tests: Add test for event emission
• Docs: Update API and guide documentation

Test plan

• Unit test for run:progress event emission passes
• All existing tests pass (Node: 114, React: 6)
• TypeScript check passes

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a run:progress event that enables real-time progress tracking, emitting updates when step progress is recorded with payload including run ID, job name, current/total progress, and optional messages.

• Documentation

  • Updated documentation with event subscription examples and API reference for the new progress tracking functionality.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
durably-demo	Building	Preview	Dec 23, 2025 3:37pm

[coderabbitai]

Walkthrough

Introduces a new run:progress event emitted when step.progress() is called, enabling real-time progress tracking. The event carries the run ID, job name, and progress payload containing current, optional total, and optional message fields. Updates span type definitions, core logic, tests, and documentation.

Changes

Cohort / File(s)	Summary
Type Definitions & Exports packages/durably/src/events.ts, packages/durably/src/index.ts	Added RunProgressEvent interface to the DurablyEvent union with type 'run:progress' and payload shape { runId, jobName, progress: { current, total?, message? } }. Exported from index for public API surface.
Core Implementation packages/durably/src/context.ts	Modified createStepContext.progress to encapsulate progress data (current, total, message) into a single progressData object, update run with this object, and emit the new run:progress event with run ID and job name.
Testing packages/durably/tests/shared/step.shared.ts	Imported RunProgressEvent type and added test verifying event emission during step.progress() calls with multiple progress updates and validation of payload structure.
Documentation packages/durably/docs/llms.md, website/api/events.md, website/guide/events.md	Updated Events documentation to reflect new run:progress event, added subscription example, and extended event tables with payload specifications.
Release Management CHANGELOG.md, packages/durably/package.json	Version bumped from 0.4.0 to 0.5.0 and changelog entry added documenting the new event feature.

Sequence Diagram

sequenceDiagram
    participant App as Application
    participant Ctx as Step Context
    participant Store as Storage
    participant Event as Event Emitter
    participant Listener as Event Listener

    App->>Ctx: step.progress(current, total, message)
    Ctx->>Ctx: Create progressData object
    Ctx->>Store: updateRun(progressData)
    Store->>Store: Persist progress state
    Ctx->>Event: emit('run:progress', { runId, jobName, progress })
    Event->>Listener: Deliver RunProgressEvent
    Listener->>Listener: Handle progress update

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main feature added: a new run:progress event for real-time progress tracking, which aligns with all file changes shown in the changeset.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/run-progress-event

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f39a874 and c5ada17.

📒 Files selected for processing (9)

• CHANGELOG.md
• packages/durably/docs/llms.md
• packages/durably/package.json
• packages/durably/src/context.ts
• packages/durably/src/events.ts
• packages/durably/src/index.ts
• packages/durably/tests/shared/step.shared.ts
• website/api/events.md
• website/guide/events.md

🧰 Additional context used

📓 Path-based instructions (1)

packages/durably/docs/llms.md

📄 CodeRabbit inference engine (CLAUDE.md)

Update packages/durably/docs/llms.md to keep it in sync with API changes, as this file is bundled in the npm package for coding agents to read from node_modules and symlinked to website/public/llms.txt for web access

Files:

• packages/durably/docs/llms.md

🧠 Learnings (5)

📓 Common learnings

Learnt from: CR
Repo: coji/durably PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-22T12:46:22.679Z
Learning: Use the event system for extensibility via events: `run:start`, `run:complete`, `run:fail`, `step:*`, `log:write`

📚 Learning: 2025-12-22T12:46:22.679Z

Learnt from: CR
Repo: coji/durably PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-22T12:46:22.679Z
Learning: Use the event system for extensibility via events: `run:start`, `run:complete`, `run:fail`, `step:*`, `log:write`

Applied to files:

• packages/durably/src/index.ts
• packages/durably/docs/llms.md
• website/guide/events.md
• website/api/events.md
• packages/durably/src/events.ts
• packages/durably/tests/shared/step.shared.ts
• CHANGELOG.md

📚 Learning: 2025-12-22T12:46:22.679Z

Learnt from: CR
Repo: coji/durably PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-22T12:46:22.679Z
Learning: Applies to packages/durably/docs/llms.md : Update `packages/durably/docs/llms.md` to keep it in sync with API changes, as this file is bundled in the npm package for coding agents to read from `node_modules` and symlinked to `website/public/llms.txt` for web access

Applied to files:

• packages/durably/docs/llms.md
• packages/durably/package.json

📚 Learning: 2025-12-22T12:46:22.679Z

Learnt from: CR
Repo: coji/durably PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-22T12:46:22.679Z
Learning: Each step's success state and return value must be persisted, created via `step.run()`

Applied to files:

• website/api/events.md
• packages/durably/src/context.ts

📚 Learning: 2025-12-22T12:46:22.679Z

Learnt from: CR
Repo: coji/durably PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-22T12:46:22.679Z
Learning: Job definitions must be created via `durably.defineJob()`, receiving a step context and payload

Applied to files:

• packages/durably/tests/shared/step.shared.ts

🧬 Code graph analysis (2)

packages/durably/src/events.ts (1)

packages/durably/src/index.ts (1)

• RunProgressEvent (24-24)

packages/durably/tests/shared/step.shared.ts (2)

packages/durably/src/events.ts (1)

• RunProgressEvent (45-50)

packages/durably/src/index.ts (1)

• RunProgressEvent (24-24)

🪛 LanguageTool

website/api/events.md

[style] ~69-~69: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ber // } }) #### `run:progress` Fired when `step.progress()` is called. t...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🔇 Additional comments (13)

packages/durably/package.json (1)

3-3: LGTM!

The version bump to 0.5.0 appropriately reflects the addition of a new feature (run:progress event) following semantic versioning conventions.

website/guide/events.md (1)

16-16: LGTM!

The documentation entry for the run:progress event is clear and consistent with the existing event table format.

CHANGELOG.md (1)

8-14: LGTM!

The changelog entry clearly documents the new run:progress event feature with an accurate description of its payload structure. Follows the Keep a Changelog format consistently.

packages/durably/src/context.ts (1)

114-125: LGTM!

The progress() implementation correctly consolidates progress data, updates storage asynchronously (fire-and-forget), and emits the run:progress event with the appropriate payload structure.

packages/durably/docs/llms.md (1)

190-192: LGTM!

The documentation example correctly demonstrates subscribing to the run:progress event and accessing its payload properties. As per coding guidelines, this file is properly maintained for bundling in the npm package and web access.

packages/durably/src/index.ts (1)

24-24: LGTM!

The RunProgressEvent type is correctly exported as part of the public API in the Events section, maintaining alphabetical order.

website/api/events.md (2)

68-83: LGTM!

The run:progress event documentation is comprehensive and follows the established pattern. It includes all relevant details: trigger condition, event structure with all fields, and proper typing.

Note: The static analysis hint about repeated "Fired" is a false positive—the consistent use of "Fired when..." across all event descriptions is intentional and maintains documentation uniformity.

---

209-209: LGTM!

The DurablyEvent union type documentation is correctly updated to include RunProgressEvent.

packages/durably/tests/shared/step.shared.ts (2)

8-8: LGTM!

The RunProgressEvent type is correctly imported from the public API using a type-only import.

---

328-376: LGTM!

Excellent test coverage for the run:progress event. The test:

• Properly subscribes to the event before triggering the job
• Verifies all three progress updates are emitted with correct payload structure
• Validates all fields including runId, jobName, and nested progress object properties
• Ensures job completion for test stability

packages/durably/src/events.ts (3)

42-50: LGTM! Well-structured progress event interface.

The RunProgressEvent interface follows the established pattern of other run-level events and provides a flexible progress tracking structure. The required current field with optional total and message fields offers good balance between strictness and flexibility.

---

113-122: LGTM! Proper integration into discriminated union.

The RunProgressEvent is correctly added to the DurablyEvent discriminated union, with logical placement grouping run-level events together.

---

148-157: LGTM! Complete type system integration.

The EventInput<'run:progress'> is properly added to the AnyEventInput union, enabling the new event to be emitted through the event system with auto-generated timestamp and sequence fields.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}