refactor: rename context to step in job handler API by coji · Pull Request #7 · coji/durably

coji · 2025-12-22T11:37:46Z

Summary

Renamed job handler first argument from context to step (Inngest-style API)
JobContext → StepContext
createJobContext → createStepContext
Bumped version to 0.2.0 (breaking change)
Added CHANGELOG.md

Migration

- durably.defineJob({ name: 'my-job', input }, async (context, payload) => {
-   await context.run('step1', () => doSomething())
+ durably.defineJob({ name: 'my-job', input }, async (step, payload) => {
+   await step.run('step1', () => doSomething())
  })

Test plan

All 230 tests passing (pnpm validate)
Documentation updated (EN/JA)
Examples updated

🤖 Generated with Claude Code

Summary by CodeRabbit

Breaking Changes
- The job handler now receives a step object instead of context (handler signature updated).
- Progress API renamed to progress(current, total, message?).
New Features
- Step-level streaming with checkpoint support.
- Subscribe to job events via a new subscribe(runId, options) capability.
Documentation
- Docs, guides, and examples updated to the new step-centric API and CHANGELOG added.
Chore
- Package version bumped to 0.2.0.

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

BREAKING CHANGE: Job handler's first parameter renamed from `context` to `step` This change aligns with Inngest's API design where `step.run()` reads more naturally as "run a step" compared to the previous `context.run()`. Changes: - Rename `JobContext` type to `StepContext` - Rename `createJobContext` to `createStepContext` - Update all job handlers: `(context, payload)` → `(step, payload)` - Update all step calls: `context.run()` → `step.run()` - Update logging: `context.log` → `step.log` - Update progress: `context.progress()` → `step.progress()` - Rename website docs: api/context.md → api/step.md Migration: ```ts // Before durably.defineJob("myJob", async (context, payload) => { await context.run("step1", () => fetchData()) }) // After durably.defineJob("myJob", async (step, payload) => { await step.run("step1", () => fetchData()) }) ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Breaking change: Job handler API renamed from `context` to `step` - JobContext → StepContext - createJobContext → createStepContext - Handler signature: (context, payload) → (step, payload) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

vercel · 2025-12-22T11:37:51Z

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

Project	Deployment	Review	Updated (UTC)
durably-demo	Ready	Preview	Dec 22, 2025 11:48am

coderabbitai · 2025-12-22T11:37:56Z

Walkthrough

A large API rename: the job handler context and related APIs were renamed from "context"/JobContext to "step"/StepContext across code, tests, docs (English & Japanese), examples, and package metadata; streaming spec additions include StepContext stream APIs and JobHandle.subscribe in docs.

Changes

Cohort / File(s)	Summary
Core types & exports `packages/durably/src/job.ts`, `packages/durably/src/index.ts`, `packages/durably/src/context.ts`	Renamed `JobContext` → `StepContext`; updated `JobFunction`/handler signatures to use `step: StepContext`; `createJobContext` → `createStepContext`; exports changed to include `StepContext`.
Runtime usage `packages/durably/src/worker.ts`	Replaced `createJobContext` calls with `createStepContext`; pass `step` into job.fn and renamed local variables/comments accordingly.
Package metadata `packages/durably/package.json`	Version bumped 0.1.1 → 0.2.0.
Specification & streaming docs `docs/spec.md`, `docs/spec-streaming.md`, `CHANGELOG.md`, `CLAUDE.md`	Documentation/spec updated from context→step; `docs/spec-streaming.md` adds StepContext APIs (stream, progress rename) and `JobHandle.subscribe` / `SubscribeOptions`; CHANGELOG documents breaking change and migration example.
API docs (English) `website/api/*.md`, deleted `website/api/context.md`, added `website/api/step.md`	Handler examples/signatures changed from `(context, payload)` → `(step, payload)`; `context.run/log/progress` → `step.run/log/progress`; `context.md` removed and `step.md` introduced; `log:write` event text updated.
API docs (Japanese) `website/ja/api/*.md`, deleted `website/ja/api/context.md`, added `website/ja/api/step.md`	Japanese equivalents updated to Step/StepContext and step.* usages; `context` page removed, `step` page added.
Guides (English) `website/guide/*.md` (getting-started, resumability, events, jobs-and-steps, react, index)	All example handlers renamed to `(step, payload)` and internal calls updated to `step.run`, `step.log`, `step.progress`.
Guides (Japanese) `website/ja/guide/*.md`	Japanese guide examples updated to use `step` and step.* APIs throughout.
Examples `examples/browser/src/main.ts`, `examples/node/basic.ts`, `examples/react/src/App.tsx`, `packages/durably/README.md`	Example job handlers renamed to `(step, payload)`; calls changed from `context.run(...)` → `step.run(...)`.
Tests `packages/durably/tests/shared/*.ts` (concurrency.shared.ts, job.shared.ts, log.shared.ts, plugin.shared.ts, recovery.shared.ts, run-api.shared.ts, step.shared.ts, worker.shared.ts)	Test handler parameters renamed from `context`/_context → `step`/_step; all `context.run/log/progress/runId` usages updated to `step` equivalents; test descriptions adjusted to step terminology.
Website nav/config `website/.vitepress/config.ts`	Navigation items changed from "Context" (/api/context) → "Step" (/api/step).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~35 minutes

Breadth: widespread, ~50 files across code, tests, docs.
Nature: mostly consistent mechanical renames (parameter/type/export/function), low logic density.
Attention hotspots:
- Ensure no remaining context.* references (run/log/progress/runId) remain in code/tests/docs.
- Verify exported type list and names in packages/durably/src/index.ts.
- Confirm docs/spec-streaming.md additions (stream API, subscribe) match intended public surface and examples.
- Validate version bump and changelog accurately reflect breaking change.

Possibly related PRs

v1 Implementation: Core durably package with documentation #3 — earlier refactor introducing/aligning step-based APIs and corresponding type/function renames (createJobContext → createStepContext, JobContext → StepContext).
Refactor specs and add tooling configuration #2 — streaming/spec changes and tooling docs that overlap docs/spec-streaming.md updates and event model additions.

Poem

A rabbit hops from context to step with glee, 🐰
I rename each handler, one, two, three!
From context.run to step.run, neat and bright,
Docs and tests all follow my light.
Step forward now — the API takes flight. ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.27% 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 describes the main change: renaming context to step throughout the job handler API, which is the primary refactoring across all modified files.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch refactor/context-to-step

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fe7c23c and 0b9083e.

📒 Files selected for processing (1)

CHANGELOG.md

✅ Files skipped from review due to trivial changes (1)

CHANGELOG.md

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

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

coderabbitai

Actionable comments posted: 1

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7e3cefe and fe7c23c.

📒 Files selected for processing (45)

CHANGELOG.md
CLAUDE.md
README.md
docs/spec-streaming.md
docs/spec.md
examples/browser/src/main.ts
examples/node/basic.ts
examples/react/src/App.tsx
packages/durably/README.md
packages/durably/package.json
packages/durably/src/context.ts
packages/durably/src/index.ts
packages/durably/src/job.ts
packages/durably/src/worker.ts
packages/durably/tests/shared/concurrency.shared.ts
packages/durably/tests/shared/job.shared.ts
packages/durably/tests/shared/log.shared.ts
packages/durably/tests/shared/plugin.shared.ts
packages/durably/tests/shared/recovery.shared.ts
packages/durably/tests/shared/run-api.shared.ts
packages/durably/tests/shared/step.shared.ts
packages/durably/tests/shared/worker.shared.ts
website/.vitepress/config.ts
website/api/context.md
website/api/define-job.md
website/api/events.md
website/api/index.md
website/api/step.md
website/guide/events.md
website/guide/getting-started.md
website/guide/index.md
website/guide/jobs-and-steps.md
website/guide/react.md
website/guide/resumability.md
website/ja/api/context.md
website/ja/api/define-job.md
website/ja/api/events.md
website/ja/api/index.md
website/ja/api/step.md
website/ja/guide/events.md
website/ja/guide/getting-started.md
website/ja/guide/index.md
website/ja/guide/jobs-and-steps.md
website/ja/guide/react.md
website/ja/guide/resumability.md

💤 Files with no reviewable changes (2)

website/api/context.md
website/ja/api/context.md

🧰 Additional context used

📓 Path-based instructions (2)

**/*.{js,ts,jsx,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{js,ts,jsx,tsx}: Use durably.defineJob() to define jobs with a context object and payload
Create steps via context.run() where each step's success state and return value is persisted
Use the retry() API for manual retry of failed runs; do not rely on automatic retry
Use dialect injection pattern - pass Kysely dialect to createDurably() to abstract SQLite implementations
Use event system for extensibility with events: run:start, run:complete, run:fail, step:*, log:write
In browser implementations, use SQLite WASM with OPFS backend for persistence
Configure pollingInterval default to 1000ms, heartbeatInterval to 5000ms, and staleThreshold to 30000ms

Files:

examples/browser/src/main.ts
packages/durably/src/job.ts
packages/durably/src/worker.ts
examples/react/src/App.tsx
packages/durably/src/context.ts
examples/node/basic.ts
packages/durably/tests/shared/concurrency.shared.ts
packages/durably/tests/shared/worker.shared.ts
packages/durably/tests/shared/log.shared.ts
packages/durably/src/index.ts
packages/durably/tests/shared/job.shared.ts
packages/durably/tests/shared/step.shared.ts
packages/durably/tests/shared/run-api.shared.ts
packages/durably/tests/shared/plugin.shared.ts
packages/durably/tests/shared/recovery.shared.ts

**/*.{js,ts}

📄 CodeRabbit inference engine (CLAUDE.md)

In Node.js implementations, use better-sqlite3 or libsql for database persistence

Files:

examples/browser/src/main.ts
packages/durably/src/job.ts
packages/durably/src/worker.ts
packages/durably/src/context.ts
examples/node/basic.ts
packages/durably/tests/shared/concurrency.shared.ts
packages/durably/tests/shared/worker.shared.ts
packages/durably/tests/shared/log.shared.ts
packages/durably/src/index.ts
packages/durably/tests/shared/job.shared.ts
packages/durably/tests/shared/step.shared.ts
packages/durably/tests/shared/run-api.shared.ts
packages/durably/tests/shared/plugin.shared.ts
packages/durably/tests/shared/recovery.shared.ts

🧠 Learnings (8)

📓 Common learnings

Learnt from: CR
Repo: coji/durably PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-21T13:14:30.311Z
Learning: Applies to **/*.{js,ts,jsx,tsx} : Create steps via `context.run()` where each step's success state and return value is persisted

Learnt from: CR
Repo: coji/durably PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-21T13:14:30.311Z
Learning: Applies to **/*.{js,ts,jsx,tsx} : Use `durably.defineJob()` to define jobs with a context object and payload