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 <[email protected]>

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 = (