javascript-transformer.ts

/**
 * @license
 * Copyright Google LLC All Rights Reserved.
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://angular.dev/license
 */

import { createHash } from 'node:crypto';
import { readFile } from 'node:fs/promises';
import path from 'node:path';
import { IMPORT_EXEC_ARGV } from '../../utils/server-rendering/esm-in-memory-loader/utils';
import { WorkerPool, WorkerPoolOptions } from '../../utils/worker-pool';
import { Cache } from './cache';

/**
 * Transformation options that should apply to all transformed files and data.
 */
export interface JavaScriptTransformerOptions {
  sourcemap: boolean;
  thirdPartySourcemaps?: boolean;
  advancedOptimizations?: boolean;
  jit?: boolean;
}

/**
 * A class that performs transformation of JavaScript files and raw data.
 * A worker pool is used to distribute the transformation actions and allow
 * parallel processing. Transformation behavior is based on the filename and
 * data. Transformations may include: async downleveling, Angular linking,
 * and advanced optimizations.
 */
export class JavaScriptTransformer {
  #workerPool: WorkerPool | undefined;
  #commonOptions: Required<JavaScriptTransformerOptions>;
  #fileCacheKeyBase: Uint8Array;

  constructor(
    options: JavaScriptTransformerOptions,
    readonly maxThreads: number,
    private readonly cache?: Cache<Uint8Array>,
  ) {
    // Extract options to ensure only the named options are serialized and sent to the worker
    const {
      sourcemap,
      thirdPartySourcemaps = false,
      advancedOptimizations = false,
      jit = false,
    } = options;
    this.#commonOptions = {
      sourcemap,
      thirdPartySourcemaps,
      advancedOptimizations,
      jit,
    };
    this.#fileCacheKeyBase = Buffer.from(JSON.stringify(this.#commonOptions), 'utf-8');
  }

  #ensureWorkerPool(): WorkerPool {
    if (this.#workerPool) {
      return this.#workerPool;
    }

    const workerPoolOptions: WorkerPoolOptions = {
      filename: require.resolve('./javascript-transformer-worker'),
      maxThreads: this.maxThreads,
    };

    // Prevent passing SSR `--import` (loader-hooks) from parent to child worker.
    const filteredExecArgv = process.execArgv.filter((v) => v !== IMPORT_EXEC_ARGV);
    if (process.execArgv.length !== filteredExecArgv.length) {
      workerPoolOptions.execArgv = filteredExecArgv;
    }

    this.#workerPool = new WorkerPool(workerPoolOptions);

    return this.#workerPool;
  }

  /**
   * Performs JavaScript transformations on a file from the filesystem.
   * If no transformations are required, the data for the original file will be returned.
   * @param filename The full path to the file.
   * @param skipLinker If true, bypass all Angular linker processing; if false, attempt linking.
   * @param sideEffects If false, and `advancedOptimizations` is enabled tslib decorators are wrapped.
   * @returns A promise that resolves to a UTF-8 encoded Uint8Array containing the result.
   */
  async transformFile(
    filename: string,
    skipLinker?: boolean,
    sideEffects?: boolean,
    instrumentForCoverage?: boolean,
  ): Promise<Uint8Array> {
    const data = await readFile(filename);

    let result;
    let cacheKey;
    if (this.cache) {
      // Create a cache key from the file data and options that effect the output.
      // NOTE: If additional options are added, this may need to be updated.
      // TODO: Consider xxhash or similar instead of SHA256
      const hash = createHash('sha256');
      hash.update(`${!!skipLinker}--${!!sideEffects}`);
      hash.update(data);
      hash.update(this.#fileCacheKeyBase);
      cacheKey = hash.digest('hex');

      try {
        result = await this.cache?.get(cacheKey);
      } catch {
        // Failure to get the value should not fail the transform
      }
    }

    if (result === undefined) {
      // If there is no cache or no cached entry, process the file
      result = (await this.#ensureWorkerPool().run(
        {
          filename,
          data,
          skipLinker,
          sideEffects,
          instrumentForCoverage,
          ...this.#commonOptions,
        },
        {
          // The below is disable as with Yarn PNP this causes build failures with the below message
          // `Unable to deserialize cloned data`.
          transferList: process.versions.pnp ? undefined : [data.buffer],
        },
      )) as Uint8Array;

      // If there is a cache then store the result
      if (this.cache && cacheKey) {
        try {
          await this.cache.put(cacheKey, result);
        } catch {
          // Failure to store the value in the cache should not fail the transform
        }
      }
    }

    return result;
  }

  /**
   * Performs JavaScript transformations on the provided data of a file. The file does not need
   * to exist on the filesystem.
   * @param filename The full path of the file represented by the data.
   * @param data The data of the file that should be transformed.
   * @param skipLinker If true, bypass all Angular linker processing; if false, attempt linking.
   * @param sideEffects If false, and `advancedOptimizations` is enabled tslib decorators are wrapped.
   * @returns A promise that resolves to a UTF-8 encoded Uint8Array containing the result.
   */
  async transformData(
    filename: string,
    data: string,
    skipLinker: boolean,
    sideEffects?: boolean,
    instrumentForCoverage?: boolean,
  ): Promise<Uint8Array> {
    // Perform a quick test to determine if the data needs any transformations.
    // This allows directly returning the data without the worker communication overhead.
    if (skipLinker && !this.#commonOptions.advancedOptimizations && !instrumentForCoverage) {
      const keepSourcemap =
        this.#commonOptions.sourcemap &&
        (!!this.#commonOptions.thirdPartySourcemaps || !/[\\/]node_modules[\\/]/.test(filename));

      if (!keepSourcemap) {
        return Buffer.from(data.replace(/^\/\/# sourceMappingURL=[^\r\n]*/gm, ''), 'utf-8');
      }

      // Inline any external sourceMappingURL so esbuild can chain through to the original source.
      // When no Babel plugins run, external map references are preserved in the returned data but
      // esbuild does not follow them. Converting to an inline base64 map allows esbuild to compose
      // the full sourcemap chain from bundle output back to the original TypeScript source.
      const externalMapMatch = /^\/\/# sourceMappingURL=(?!data:)([^\r\n]+)/m.exec(data);
      if (externalMapMatch) {
        const mapRef = externalMapMatch[1];
        const fileDir = path.dirname(filename);
        const mapPath = path.resolve(fileDir, mapRef);
        // Reject path traversal — the resolved map file must remain within the source
        // file's directory tree and must be a .map file. This prevents a crafted
        // sourceMappingURL from reading arbitrary files from disk.
        const fileDirPrefix = fileDir.endsWith(path.sep) ? fileDir : fileDir + path.sep;
        if (mapPath.startsWith(fileDirPrefix) && mapPath.endsWith('.map')) {
          try {
            const mapContent = await readFile(mapPath, 'utf-8');
            const inlineMap = Buffer.from(mapContent).toString('base64');
            // Strip ALL sourceMappingURL comments before appending the composed inline map.
            // When allowJs + inlineSourceMap are enabled, the TypeScript compiler preserves
            // the original external reference AND appends its own data: inline sourcemap.
            // esbuild uses the last comment, so leaving both would cause it to follow the
            // TS-generated map (which only traces back to the compiled JS, not TypeScript).
            const stripped = data.replace(/^\/\/# sourceMappingURL=[^\r\n]*/gm, '');
            const result =
              stripped.trimEnd() +
              '\n//# sourceMappingURL=data:application/json;charset=utf-8;base64,' +
              inlineMap +
              '\n';
            return Buffer.from(result, 'utf-8');
          } catch (error) {
            // Map file not readable; return data with the original external reference
            // eslint-disable-next-line no-console
            console.warn(
              `Unable to inline sourcemap for '${filename}': ${error instanceof Error ? error.message : error}`,
            );
          }
        }
      }

      return Buffer.from(data, 'utf-8');
    }

    return this.#ensureWorkerPool().run({
      filename,
      data,
      skipLinker,
      sideEffects,
      instrumentForCoverage,
      ...this.#commonOptions,
    });
  }

  /**
   * Stops all active transformation tasks and shuts down all workers.
   * @returns A void promise that resolves when closing is complete.
   */
  async close(): Promise<void> {
    if (this.#workerPool) {
      try {
        await this.#workerPool.destroy();
      } finally {
        this.#workerPool = undefined;
      }
    }
  }
}