feat(typescript): expose latest Program to transformers in watch mode (#1923)

* feat(typescript): expose latest Program to transformers in watch mode\n\n- Add optional getProgram to ProgramTransformerFactory.factory\n- Pass getProgram() to program-scoped transformer factories\n- Recompute custom transformers after each TS watch rebuild\n- Docs: document getProgram and watch-mode behavior\n- Test: ensure factories are recreated and getProgram returns the latest Program * test(typescript): close bundle in new watch-mode transformer test; refactor customTransformers for clearer lazy initialization * test(typescript): add watch-mode test for typeChecker factories; tidy emitted-file cleanup in program test * fix(typescript): replace runtime undefined with void 0 in new code\n\n- watchProgram: use void 0 when resetting cached transformers in watch mode\n- tests: use void 0 in new watch-mode transformer test to satisfy no-undefined\n\nRefs PR #1923 review feedback from @shellscape * feat(typescript): add `recreateTransformersOnRebuild` option; default to legacy watch behavior\n\n- Gate watch-mode transformer recreation behind new option (default false)\n- Plumb option through plugin options -> watch host\n- Types/README: document option and clarify `getProgram` semantics\n- Tests: enable option for watch-mode freshness tests * test(typescript): add legacy-behavior regression and format via ESLint * docs(typescript): clarify getProgram getter semantics; fix typos in README (its/TypeScript factory, below) * fix(typescript): strict boolean normalization for recreateTransformersOnRebuild\n\nUse === true instead of Boolean(...) to avoid enabling the option for truthy strings in JS configs. Refs PR #1923 review by @shellscape. --------- Co-authored-by: CharlieHelps <charlie@charlielabs.ai>

Author: charliecreates[bot]

packages/typescript/README.md

@@ -142,15 +142,20 @@ Supported transformer factories:
 
 - all **built-in** TypeScript custom transformer factories:
 
- - `import('typescript').TransformerFactory` annotated **TransformerFactory** bellow
- - `import('typescript').CustomTransformerFactory` annotated **CustomTransformerFactory** bellow
+ - `import('typescript').TransformerFactory` annotated **TransformerFactory** below
+ - `import('typescript').CustomTransformerFactory` annotated **CustomTransformerFactory** below
 
 - **ProgramTransformerFactory** represents a transformer factory allowing the resulting transformer to grab a reference to the **Program** instance
 
  ```js
  {
  type: 'program',
- factory: (program: Program) => TransformerFactory | CustomTransformerFactory
+ // An optional `getProgram` getter is provided in all modes. In non‑watch it returns
+ // the same Program as the first argument. In watch mode, when the
+ // `recreateTransformersOnRebuild` option is enabled, the getter reflects the latest
+ // Program across rebuilds; otherwise it refers to the initial Program.
+ factory: (program: Program, getProgram?: () => Program) =>
+ TransformerFactory | CustomTransformerFactory
  }
  ```
 
@@ -167,16 +172,24 @@ typescript({
  transformers: {
  before: [
  {
- // Allow the transformer to get a Program reference in it's factory
+ // Allow the transformer to get a Program reference in its factory.
+ // Prefer deferring `getProgram()` usage to transformation time so watch
+ // mode can see the freshest Program when `recreateTransformersOnRebuild`
+ // is enabled.
  type: 'program',
- factory: (program) => {
- return ProgramRequiringTransformerFactory(program);
+ factory: (program, getProgram) => {
+ const get = getProgram ?? (() => program);
+ return (context) => (source) => {
+ const latest = get();
+ // use `latest` here
+ return ts.visitEachChild(source, (n) => n, context);
+ };
  }
  },
  {
  type: 'typeChecker',
  factory: (typeChecker) => {
- // Allow the transformer to get a TypeChecker reference in it's factory
+ // Allow the transformer to get a TypeChecker reference in its factory
  return TypeCheckerRequiringTransformerFactory(typeChecker);
  }
  }
@@ -209,8 +222,8 @@ Supported transformer factories:
 
 - all **built-in** TypeScript custom transformer factories:
 
- - `import('typescript').TransformerFactory` annotated **TransformerFactory** bellow
- - `import('typescript').CustomTransformerFactory` annotated **CustomTransformerFactory** bellow
+ - `import('typescript').TransformerFactory` annotated **TransformerFactory** below
+ - `import('typescript').CustomTransformerFactory` annotated **CustomTransformerFactory** below
 
 The example above could be written like this:
 
@@ -245,6 +258,34 @@ typescript({
 });
 ```
 
+Note on watch mode
+
+By default (legacy behavior), this plugin reuses the same custom transformer factories for the lifetime of a watch session. Advanced users can opt into recreating factories on every TypeScript rebuild by enabling the `recreateTransformersOnRebuild` option. When enabled, both `program`- and `typeChecker`-based factories are rebuilt per watch cycle, and `getProgram()` (when used) reflects the latest Program across rebuilds.
+
+### `recreateTransformersOnRebuild`
+
+Type: `Boolean`<br>
+Default: `false` (legacy behavior)
+
+When `true`, the plugin recreates custom transformer factories on each TypeScript watch rebuild. This ensures factories capture the current `Program`/`TypeChecker` per cycle and that the optional `getProgram()` getter provided to `program`-based factories reflects the latest `Program` across rebuilds. Most users do not need this; enable it if your transformers depend on up‑to‑date Program/TypeChecker identities.
+
+```js
+// Opt-in to per-rebuild transformer recreation in watch mode
+typescript({
+ recreateTransformersOnRebuild: true,
+ transformers: {
+ before: [
+ {
+ type: 'program',
+ factory(program, getProgram) {
+ /* ... */
+ }
+ }
+ ]
+ }
+});
+```
+
 ### `cacheDir`
 
 Type: `String`<br>

packages/typescript/src/customTransformers.ts

@@ -35,21 +35,19 @@ export function mergeTransformers(
 
  if ('type' in transformer) {
  if (typeof transformer.factory === 'function') {
- // Allow custom factories to grab the extra information required
- program = program || builder.getProgram();
- typeChecker = typeChecker || program.getTypeChecker();
-
  let factory: ReturnType<typeof transformer.factory>;
 
  if (transformer.type === 'program') {
- program = program || builder.getProgram();
-
- factory = transformer.factory(program);
+ const currentProgram = program ?? builder.getProgram();
+ // Pass a getter so transformers can access the latest Program in watch mode
+ factory = transformer.factory(currentProgram, () => builder.getProgram());
+ program = currentProgram;
  } else {
- program = program || builder.getProgram();
- typeChecker = typeChecker || program.getTypeChecker();
-
- factory = transformer.factory(typeChecker);
+ const currentProgram = program ?? builder.getProgram();
+ const currentTypeChecker = typeChecker ?? currentProgram.getTypeChecker();
+ factory = transformer.factory(currentTypeChecker);
+ program = currentProgram;
+ typeChecker = currentTypeChecker;
  }
 
  // Forward the requested reference to the custom transformer factory

packages/typescript/src/index.ts

@@ -35,6 +35,7 @@ export default function typescript(options: RollupTypescriptOptions = {}): Plugi
  outputToFilesystem,
  noForceEmit,
  transformers,
+ recreateTransformersOnRebuild,
  tsconfig,
  tslib,
  typescript: ts
@@ -180,7 +181,8 @@ export default function typescript(options: RollupTypescriptOptions = {}): Plugi
  status(diagnostic) {
  watchProgramHelper.handleStatus(diagnostic);
  },
- transformers
+ transformers,
+ recreateTransformersOnRebuild
  });
  }
  },

packages/typescript/src/options/plugin.ts

@@ -21,6 +21,7 @@ export const getPluginOptions = (options: RollupTypescriptOptions) => {
  filterRoot,
  noForceEmit,
  transformers,
+ recreateTransformersOnRebuild,
  tsconfig,
  tslib,
  typescript,
@@ -41,6 +42,8 @@ export const getPluginOptions = (options: RollupTypescriptOptions) => {
  typescript: typescript || defaultTs,
  tslib: tslib || getTsLibPath(),
  transformers,
+ // Only enable when explicitly set to true to avoid truthy string pitfalls in JS configs
+ recreateTransformersOnRebuild: recreateTransformersOnRebuild === true,
  outputToFilesystem
  };
 };

packages/typescript/src/watchProgram.ts

@@ -42,6 +42,12 @@ interface CreateProgramOptions {
  resolveModule: Resolver;
  /** Custom TypeScript transformers */
  transformers?: CustomTransformerFactories | ((program: Program) => CustomTransformers);
+ /**
+ * Advanced: when true, recreate custom transformer factories on each
+ * TypeScript watch rebuild. Defaults to legacy behavior (false), which
+ * reuses the same factories for the lifetime of the watch session.
+ */
+ recreateTransformersOnRebuild?: boolean;
 }
 
 type DeferredResolve = ((value: boolean | PromiseLike<boolean>) => void) | (() => void);
@@ -142,7 +148,8 @@ function createWatchHost(
  writeFile,
  status,
  resolveModule,
- transformers
+ transformers,
+ recreateTransformersOnRebuild
  }: CreateProgramOptions
 ): WatchCompilerHostOfFilesAndCompilerOptions<BuilderProgram> {
  const createProgram = ts.createEmitAndSemanticDiagnosticsBuilderProgram;
@@ -162,6 +169,13 @@ function createWatchHost(
  ...baseHost,
  /** Override the created program so an in-memory emit is used */
  afterProgramCreate(program) {
+ // Optionally recompute custom transformers for each new builder program in watch mode
+ // so factories capture the current Program/TypeChecker and any provided getters can
+ // return the latest values. When disabled (default), legacy behavior reuses the
+ // same factories across rebuilds.
+ if (recreateTransformersOnRebuild) {
+ createdTransformers = void 0;
+ }
  const origEmit = program.emit;
  // eslint-disable-next-line no-param-reassign
  program.emit = (