feat(v27): Async loading TypeScript by Integration

[RobinTail]

The better implementation of #3139 using the dynamic import() instead of createRequire().

The new implementation requires either:

• to import and provide the typescript to Integration::constructor()
• or to use the new async method Integration::create()

This is a breaking change.

typescript becomes an optional peer dependency. Documentation adjusted accordingly.

Summary by CodeRabbit

• Documentation

  • Updated README installation section to clarify TypeScript handling.
  • Enhanced frontend client generation examples with explicit TypeScript configuration instructions and usage patterns.

• New Features

  • Added async factory method for integration setup, offering alternative to direct instantiation.
  • Made TypeScript an optional peer dependency instead of required, reducing installation footprint.

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Walkthrough

The changes refactor TypeScript compilation API integration to use constructor-based dependency injection instead of dynamic loading, introduce a string-based identifier system to replace TypeScript Identifier objects throughout the codebase, and add an async factory pattern (Integration.create()) with optional TypeScript peer dependency support.

Changes

Cohort / File(s)	Summary
Documentation & Examples README.md, example/generate-client.ts	Updated installation guidance to clarify TypeScript is optional; enhanced examples to explicitly import and pass TypeScript module to Integration constructor.
Linting Configuration eslint.config.js	Added ESLint rule for TypeScript AST transformations, suggesting makeId() helper instead of createIdentifier for identifier creation.
Package Configuration express-zod-api/package.json	Marked TypeScript as an optional peer dependency via peerDependenciesMeta.typescript.
Integration Core API express-zod-api/src/integration.ts, express-zod-api/src/integration-base.ts	Added typescript parameter to IntegrationParams and constructor; introduced new static Integration.create() async factory for lazy TypeScript loading; updated super calls to pass typescript to base class; converted method references from static identifiers to dynamic makeXxx() calls.
TypeScript API Layer express-zod-api/src/typescript-api.ts	Changed constructor to accept TypeScript module as argument instead of dynamic require; introduced public makeId(name: string) helper; refactored all public methods to accept and work with string-based names/identifiers instead of ts.Identifier objects (e.g., makePublicMethod, makeDeconstruction, makeParam, makeTernary, makeCall, makeNew, makeAssignment).
Test Suite express-zod-api/tests/integration.spec.ts, express-zod-api/tests/zts.spec.ts	Updated to use async Integration.create() factory instead of synchronous constructor; modified TypescriptAPI instantiation to pass ts module to constructor.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• v26 is for Lia Smith #2939: Modifies IntegrationParams and Integration constructor signature to add a config parameter and adjust constructor usage patterns in the same core integration files.
• Memory usage optimization #3139: Addresses TypeScript runtime loading surface within TypescriptAPI and Integration; the referenced PR uses dynamic createRequire while this PR refactors to constructor-injected TypeScript with lazy loading via Integration.create().
• chores: tsconfig module: node20 and import extensions #2974: Touches the same trio of files (integration.ts, integration-base.ts, typescript-api.ts); the referenced PR normalizes import specifiers while this PR introduces substantive API and runtime-injection changes.

Poem

🐰 String identifiers hop where Identifiers once stood,
Lazy TypeScript loads just when it should,
Dependencies injected, sweet and clean,
The finest refactor this rabbit's seen! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the main change: replacing synchronous TypeScript loading with async loading via the Integration class, which is the core objective of this breaking change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

---

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
when pulling 0a76baa on async-load-ts-integration
into 3d369bb on make-v27.

[RobinTail]

@coderabbitai please review

[coderabbitai]

@RobinTail, I'll review the changes in this PR for you.

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

[RobinTail]

reviewed, but changelog and migration are requried