Renaming `options` to `ctx` by RobinTail · Pull Request #2934 · RobinTail/express-zod-api

RobinTail · 2025-09-13T12:04:17Z

I realized that context is more clear naming for that entity, which is also the same in hono and trpc. It should also reduce the potential confusion with "config options" and OPTIONS request method.

However, it might not be possible to rename in without breaking changes, since it's present in public interfaces.

todo

diagram
migration
changelog

Summary by CodeRabbit

Breaking Changes
- Standardized context naming: replace options with ctx across handlers, middleware, and factory APIs. Renamed addOptions to addContext. This affects handler signatures and how context is accessed.
Documentation
- Updated README and examples to reflect ctx-based usage and patterns.
Tooling/Migration
- Added automated migration rules to rename options→ctx and addOptions→addContext.
Tests
- Updated test suites to align with ctx terminology and behavior.
Chores
- CHANGELOG updated to document the API rename and guidance.

…rd compatibility.

…ward compatibility.

coderabbitai · 2025-09-13T12:04:24Z

Walkthrough

Renames the contextual argument across the codebase from options to ctx and updates related types, signatures, and usages. EndpointsFactory.addOptions is renamed to addContext. Core endpoint/middleware flow, tests, examples, docs, and migration rules are updated accordingly. No functional logic changes; interface and parameter names are standardized.

Changes

Cohort / File(s)	Summary
Docs `CHANGELOG.md`, `README.md`	Documentation updated to use ctx instead of options; examples and text adjusted; addOptions references replaced with addContext.
Core endpoint flow `express-zod-api/src/endpoint.ts`, `express-zod-api/src/result-handler.ts`	Types and internals refactored to pass and accumulate ctx instead of options; Handler third generic renamed to CTX; all method parameters/locals updated.
Middleware layer `express-zod-api/src/middleware.ts`	Middleware handler and execute signatures switched from options to ctx; generic names updated (OPT/OUT → CTX/RET); ExpressMiddleware provider types adjusted.
Factory and helpers `express-zod-api/src/endpoints-factory.ts`, `express-zod-api/src/server-helpers.ts`	EndpointsFactory generics and BuildProps shifted to CTX; addOptions renamed to addContext; server helpers now call error handler with ctx: {}.
Testing utilities `express-zod-api/src/testing.ts`	testMiddleware parameter renamed from options to ctx and usages updated.
Examples `example/endpoints/*`	Handlers destructure ctx instead of options for method/authorized/emit/isClosed.
Tests `express-zod-api/tests/*.spec.ts`	All tests updated to use ctx instead of options; assertions, mocks, and messages adjusted; factory API rename reflected.
Migration rule `migration/index.ts`, `migration/index.spec.ts`	ESLint rule extended to auto-rename options→ctx and addOptions→addContext; added selectors and tests for new cases.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor C as Client
  participant S as Server
  participant E as Endpoint
  participant M as Middlewares
  participant H as Handler
  participant R as ResultHandler

  C->>S: HTTP Request
  S->>E: route match(request)
  E->>M: execute(request, ctx = {})
  loop each middleware
    M-->>E: merge into ctx
  end
  E->>H: handler({ input, request, response, logger, ctx })
  H-->>E: result or throws
  alt success
    E->>R: execute({ input, ctx, ... })
    R-->>S: send response
  else error
    E->>R: execute({ input: null, ctx, ... })
    R-->>S: send error response
  end

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

I nudge my nose at ctx, not options past,
Hop-hop through types, the rename done at last.
Fact’ries addContext, middlewares align,
Endpoints sip carrot-logs—everything’s fine.
Tests burrow through flows, all green on the run,
A tidy warren of context—refactor won! 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.
Title Check	✅ Passed	The title succinctly states the main change—renaming `options` to `ctx`—and directly reflects the broad code and API refactor described in the pull request, making it clear and specific to readers.

✨ Finishing touches

📝 Generate Docstrings

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch mv-options-to-context

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.}

coveralls-official · 2025-09-13T12:07:19Z

coverage: 100.0%. remained the same
when pulling 555d503 on mv-options-to-context
into a8138fb on make-v26.

RobinTail · 2025-09-25T18:53:04Z

@coderabbitai, review

coderabbitai · 2025-09-25T18:53:20Z

@RobinTail I'll review the changes in this PR about renaming options to ctx.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

coderabbitai

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a8138fb and 555d503.

⛔ Files ignored due to path filters (1)

dataflow.svg is excluded by !**/*.svg

📒 Files selected for processing (21)

CHANGELOG.md (1 hunks)
README.md (11 hunks)
example/endpoints/retrieve-user.ts (1 hunks)
example/endpoints/time-subscription.ts (1 hunks)
example/endpoints/update-user.ts (1 hunks)
express-zod-api/src/endpoint.ts (12 hunks)
express-zod-api/src/endpoints-factory.ts (8 hunks)
express-zod-api/src/middleware.ts (5 hunks)
express-zod-api/src/result-handler.ts (1 hunks)
express-zod-api/src/server-helpers.ts (2 hunks)
express-zod-api/src/testing.ts (2 hunks)
express-zod-api/tests/endpoint.spec.ts (5 hunks)
express-zod-api/tests/endpoints-factory.spec.ts (3 hunks)
express-zod-api/tests/middleware.spec.ts (2 hunks)
express-zod-api/tests/result-handler.spec.ts (5 hunks)
express-zod-api/tests/routing.spec.ts (1 hunks)
express-zod-api/tests/sse.spec.ts (3 hunks)
express-zod-api/tests/system.spec.ts (3 hunks)
express-zod-api/tests/testing.spec.ts (1 hunks)
migration/index.spec.ts (2 hunks)
migration/index.ts (2 hunks)

🧰 Additional context used

🧠 Learnings (5)

📚 Learning: 2025-06-14T16:42:52.972Z

Learnt from: RobinTail
PR: RobinTail/express-zod-api#2736
File: express-zod-api/tsup.config.ts:12-26
Timestamp: 2025-06-14T16:42:52.972Z
Learning: In express-zod-api tsup configurations, the direct mutation of `options.supported` in the `esbuildOptions` callback is intentional behavior and should not be flagged as a side effect issue.

Applied to files:

express-zod-api/tests/routing.spec.ts
express-zod-api/tests/result-handler.spec.ts
express-zod-api/tests/testing.spec.ts
express-zod-api/src/server-helpers.ts
express-zod-api/tests/endpoint.spec.ts
express-zod-api/src/testing.ts
express-zod-api/tests/middleware.spec.ts
express-zod-api/tests/system.spec.ts
express-zod-api/tests/sse.spec.ts

📚 Learning: 2025-05-28T07:58:09.853Z

Learnt from: RobinTail
PR: RobinTail/express-zod-api#2546
File: express-zod-api/src/documentation-helpers.ts:508-512
Timestamp: 2025-05-28T07:58:09.853Z
Learning: In express-zod-api, when working with Zod's JSON schema override callbacks, using `delete` to mutate `ctx.jsonSchema` is the recommended approach per Zod's official documentation, even if it triggers performance linting warnings. This is preferable to creating copies with `undefined` values, especially for snapshot testing.

Applied to files:

express-zod-api/tests/testing.spec.ts
express-zod-api/tests/endpoint.spec.ts
express-zod-api/src/testing.ts
express-zod-api/tests/system.spec.ts

📚 Learning: 2025-05-27T19:35:57.357Z

Learnt from: RobinTail
PR: RobinTail/express-zod-api#2546
File: express-zod-api/tests/buffer-schema.spec.ts:32-37
Timestamp: 2025-05-27T19:35:57.357Z
Learning: In the express-zod-api project, tests are run from the `express-zod-api` workspace directory, and the project uses an ESM-first environment without `__dirname`. Relative paths like `../logo.svg` in test files correctly resolve to the repository root due to this test execution context.

Applied to files:

express-zod-api/tests/endpoint.spec.ts

📚 Learning: 2025-06-02T21:08:56.475Z

Learnt from: RobinTail
PR: RobinTail/express-zod-api#2697
File: CHANGELOG.md:5-5
Timestamp: 2025-06-02T21:08:56.475Z
Learning: The `cjs-test` directory in the express-zod-api repository is a test workspace and should be excluded when checking for main project version consistency with changelog entries.

Applied to files:

express-zod-api/tests/endpoint.spec.ts

📚 Learning: 2025-08-25T17:43:34.491Z

Learnt from: RobinTail
PR: RobinTail/express-zod-api#2904
File: express-zod-api/src/routing.ts:74-79
Timestamp: 2025-08-25T17:43:34.491Z
Learning: In express-zod-api, OPTIONS (CORS preflight) requests intentionally go through the same middleware and parser chain as other HTTP methods. This was specifically implemented to fix Issue #514 where middlewares were not running for OPTIONS requests. The framework seeds "options" with the same [parsers, endpoint] pair as other methods to ensure consistent middleware execution for CORS preflight requests.

Applied to files:

express-zod-api/tests/middleware.spec.ts
express-zod-api/tests/system.spec.ts
README.md
express-zod-api/src/endpoint.ts

🪛 Biome (2.1.2)

express-zod-api/tests/endpoints-factory.spec.ts

[error] 135-135: Unexpected empty object pattern.