feat(deps): Sync loadPeer()

[RobinTail]

This is now possible because we dropped Node 20 in v28 ( #3242 ) and require(ESM) is available since 22.12 without flags. So we can do dynamic module import without async.

Could benefit in #3463

A semi-breaking change to Integration::create() is postponed until next major.

⌛ Mocking peers in tests requires a rework (in progress)

Summary by CodeRabbit

• Refactor

  • Peer dependency loading is now synchronous, simplifying server startup flow.
  • Middleware setup for cookies and uploads now runs synchronously during initialization.
  • Integration TypeScript configuration is optional; prefer new Integration(...) over the deprecated Integration.create().

• Tests

  • Updated integration and peer-helper tests to reflect synchronous initialization/loader behavior.
  • Adjusted and streamlined mocks for peers used in tests.

• Documentation

  • Updated the README “End-to-End Type Safety” example and added a v28.6.0 changelog entry.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e19abc9c-f15c-44c4-997b-44714bb1fd2a

📥 Commits

Reviewing files that changed from the base of the PR and between 7d3ccea and 03a8cd9.

📒 Files selected for processing (1)

• express-zod-api/src/config-type.ts

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

• express-zod-api/src/config-type.ts

---

📝 Walkthrough

Walkthrough

loadPeer is rewritten from an async dynamic-import() function to a synchronous CommonJS loader using createRequire. All call sites—server-helpers.ts, server.ts, integration.ts—remove await accordingly. Test peer mocks are extracted from express-mock.ts into a new peers-mock.ts file, and affected spec files are updated to match synchronous invocation patterns. Documentation is updated to reflect the API change.

Changes

Synchronous loadPeer propagation

Layer / File(s)	Summary
loadPeer sync CJS rewrite + unit tests express-zod-api/src/peer-helpers.ts, express-zod-api/tests/peer-helpers.spec.ts	loadPeer is rewritten using createRequire(import.meta.url) to return T directly instead of Promise<T>, with explicit default/named export selection and MissingPeerError on failure. Tests switch from promise-rejection assertions to synchronous throw assertions.
Server helpers: remove await from peer loading express-zod-api/src/server-helpers.ts	createCookieParser and createUploadParsers signatures change from async/Promise-returning to synchronous functions returning handlers directly, removing await on loadPeer calls.
Server startup: remove await from middleware setup express-zod-api/src/server.ts	createServer removes await from compression loading, cookie-parser installation, and upload-parser initialization, while keeping the beforeRouting hook awaited.
Integration class: optional typescript, remove await express-zod-api/src/integration.ts	IntegrationParams.typescript becomes optional with a synchronous loadPeer default in the constructor. Integration.create() and printFormatted() remove their await calls on loadPeer.
Test mock infrastructure: peers-mock extraction express-zod-api/tests/peers-mock.ts, express-zod-api/tests/express-mock.ts	New peers-mock.ts registers a vi.mock for peer-helpers routing loadPeer to per-module vi.fn() mocks. The same mocks and their exports are removed from express-mock.ts.
Test call-site updates for synchronous API express-zod-api/tests/server.spec.ts, express-zod-api/tests/server-helpers.spec.ts, express-zod-api/tests/integration.spec.ts, compat-test/int.spec.ts	server.spec.ts and server-helpers.spec.ts imports switch to peers-mock and drop await on createUploadParsers. Integration test cases and the compat test switch from await Integration.create(...) to new Integration(...).
Documentation and changelog updates CHANGELOG.md, README.md, express-zod-api/src/config-type.ts	CHANGELOG.md adds a v28.6.0 release section documenting the optional typescript parameter and deprecation of Integration.create(). README.md updates the Integration example to demonstrate synchronous construction. config-type.ts adds a TODO about future synchronous server creation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• RobinTail/express-zod-api#3149: Introduced the async loadPeer/Integration.create pattern that this PR replaces with synchronous loading.
• RobinTail/express-zod-api#3391: Originally added the compat-test/int.spec.ts integration test that this PR converts to synchronous construction.
• RobinTail/express-zod-api#3148: Made typescript optional in IntegrationParams, overlapping with this PR's same change in integration.ts.

Suggested labels

refactoring, dependencies

Poem

🐇 No more await in the morning queue,
loadPeer now leaps without a pause!
require() hops through modules true,
Sync all the things—just because.
🎉 The warren runs on time today!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: making the loadPeer() function synchronous, which is the primary objective driving all modifications throughout the codebase.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch sync-load-peer

---

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

[coveralls-official]

coverage: 100.0%. remained the same — sync-load-peer into master

[pullfrog]

✅ No new issues found.

Reviewed changes — loadPeer() is made synchronous by switching from await import() to createRequire-based require(), leveraging Node 22.12+ ESM-require support. This enables the typescript parameter on Integration's constructor to default to loadPeer("typescript"), removing the need for Integration.create().

• Sync loadPeer() — replaces await import() with createRequire(import.meta.url) + require(); the engine floor of ^22.19.0 ensures require(ESM) is available.
• IntegrationParams.typescript now optional — defaults to loadPeer("typescript") with @default JSDoc.
• Deprecate Integration.create() — the static factory is marked @deprecated with a @todo to remove in the next major; compat-test updated to use new Integration() directly.
• Remove await from all loadPeer() call sites — createServer, createCookieParser, createUploadParsers, and Integration.formatClientCode all drop await.
• Restructure test peer mocks — move peer mocking from express-mock.ts (per-module vi.mock) to new peers-mock.ts (mock loadPeer itself with a module-name switch).

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@express-zod-api/src/peer-helpers.ts`:
- Around line 12-13: The function is returning mod[moduleExport] without
verifying it exists when moduleExport is not "default", allowing undefined
values to be returned instead of failing immediately. Add a check after
attempting to access mod[moduleExport] to verify the named export exists, and
throw an error if it is undefined. Only return the value if it is actually
present, ensuring the peer-loading failure is surfaced immediately rather than
returning an invalid undefined value.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 779dba11-9731-4111-bcc4-b36e0812b2d3

📥 Commits

Reviewing files that changed from the base of the PR and between 08d3644 and 7d640e2.

📒 Files selected for processing (11)

• compat-test/int.spec.ts
• express-zod-api/src/integration.ts
• express-zod-api/src/peer-helpers.ts
• express-zod-api/src/server-helpers.ts
• express-zod-api/src/server.ts
• express-zod-api/tests/express-mock.ts
• express-zod-api/tests/integration.spec.ts
• express-zod-api/tests/peer-helpers.spec.ts
• express-zod-api/tests/peers-mock.ts
• express-zod-api/tests/server-helpers.spec.ts
• express-zod-api/tests/server.spec.ts

💤 Files with no reviewable changes (1)

• express-zod-api/tests/express-mock.ts