feat(napi/transform): add async transform function (#13881)

Boshen · Boshen · commit 70c402b9f965 · 2025-09-18T12:44:53.000Z
## Summary This PR adds an async transform function to the NAPI transform package, following the same pattern used in the parser package for consistency. Closes #10900 ## Changes - Added `transformAsync` function that returns a Promise - Implemented `TransformTask` struct with `napi::Task` trait - Reuses existing transform logic from the synchronous version - Added comprehensive tests to verify async behavior ## Test Plan Added tests in `test/transform.test.ts` that verify: - Async function works correctly - Produces identical results to sync version - Properly handles errors All existing tests continue to pass. 🤖 Generated with [Claude Code](https://claude.ai/code)
diff --git a/napi/transform/index.d.ts b/napi/transform/index.d.ts
@@ -436,6 +436,22 @@ export interface StyledComponentsOptions {
  */
 export declare function transform(filename: string, sourceText: string, options?: TransformOptions | undefined | null): TransformResult
 
+/**
+ * Transpile a JavaScript or TypeScript into a target ECMAScript version, asynchronously.
+ *
+ * Note: This function can be slower than `transform` due to the overhead of spawning a thread.
+ *
+ * @param filename The name of the file being transformed. If this is a
+ * relative path, consider setting the {@link TransformOptions#cwd} option.
+ * @param sourceText the source code itself
+ * @param options The options for the transformation. See {@link
+ * TransformOptions} for more information.
+ *
+ * @returns a promise that resolves to an object containing the transformed code,
+ * source maps, and any errors that occurred during parsing or transformation.
+ */
+export declare function transformAsync(filename: string, sourceText: string, options?: TransformOptions | undefined | null): Promise<TransformResult>
+
 /**
  * Options for transforming a JavaScript or TypeScript file.
  *
diff --git a/napi/transform/index.js b/napi/transform/index.js
@@ -565,9 +565,10 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { Severity, HelperMode, isolatedDeclaration, moduleRunnerTransform, transform } = nativeBinding
+const { Severity, HelperMode, isolatedDeclaration, moduleRunnerTransform, transform, transformAsync } = nativeBinding
 export { Severity }
 export { HelperMode }
 export { isolatedDeclaration }
 export { moduleRunnerTransform }
 export { transform }
+export { transformAsync }
diff --git a/napi/transform/src/transformer.rs b/napi/transform/src/transformer.rs
@@ -6,7 +6,7 @@ use std::{
     path::{Path, PathBuf},
 };
 
-use napi::Either;
+use napi::{Either, Task, bindgen_prelude::AsyncTask};
 use napi_derive::napi;
 use rustc_hash::FxHashMap;
 
@@ -902,6 +902,74 @@ pub fn transform(
     }
 }
 
+pub struct TransformTask {
+    filename: String,
+    source_text: String,
+    options: Option<TransformOptions>,
+}
+
+#[napi]
+impl Task for TransformTask {
+    type JsValue = TransformResult;
+    type Output = TransformResult;
+
+    fn compute(&mut self) -> napi::Result<Self::Output> {
+        let source_path = Path::new(&self.filename);
+
+        let source_type = get_source_type(
+            &self.filename,
+            self.options.as_ref().and_then(|options| options.lang.as_deref()),
+            self.options.as_ref().and_then(|options| options.source_type.as_deref()),
+        );
+
+        let mut compiler = match Compiler::new(self.options.take()) {
+            Ok(compiler) => compiler,
+            Err(errors) => {
+                return Ok(TransformResult {
+                    errors: OxcError::from_diagnostics(&self.filename, &self.source_text, errors),
+                    ..Default::default()
+                });
+            }
+        };
+
+        compiler.compile(&self.source_text, source_type, source_path);
+
+        Ok(TransformResult {
+            code: compiler.printed,
+            map: compiler.printed_sourcemap,
+            declaration: compiler.declaration,
+            declaration_map: compiler.declaration_map,
+            helpers_used: compiler.helpers_used,
+            errors: OxcError::from_diagnostics(&self.filename, &self.source_text, compiler.errors),
+        })
+    }
+
+    fn resolve(&mut self, _: napi::Env, result: Self::Output) -> napi::Result<Self::JsValue> {
+        Ok(result)
+    }
+}
+
+/// Transpile a JavaScript or TypeScript into a target ECMAScript version, asynchronously.
+///
+/// Note: This function can be slower than `transform` due to the overhead of spawning a thread.
+///
+/// @param filename The name of the file being transformed. If this is a
+/// relative path, consider setting the {@link TransformOptions#cwd} option.
+/// @param sourceText the source code itself
+/// @param options The options for the transformation. See {@link
+/// TransformOptions} for more information.
+///
+/// @returns a promise that resolves to an object containing the transformed code,
+/// source maps, and any errors that occurred during parsing or transformation.
+#[napi]
+pub fn transform_async(
+    filename: String,
+    source_text: String,
+    options: Option<TransformOptions>,
+) -> AsyncTask<TransformTask> {
+    AsyncTask::new(TransformTask { filename, source_text, options })
+}
+
 #[derive(Default)]
 #[napi(object)]
 pub struct ModuleRunnerTransformOptions {
diff --git a/napi/transform/test/transform.test.ts b/napi/transform/test/transform.test.ts
@@ -1,7 +1,7 @@
 import { Worker } from 'node:worker_threads';
 import { describe, expect, it, test } from 'vitest';
 
-import { HelperMode, transform } from '../index';
+import { HelperMode, transform, transformAsync } from '../index';
 
 describe('simple', () => {
   const code = 'export class A<T> {}';
@@ -45,6 +45,45 @@ describe('simple', () => {
   });
 });
 
+describe('transformAsync', () => {
+  const code = 'export class A<T> {}';
+
+  it('should work asynchronously', async () => {
+    const ret = await transformAsync('test.ts', code, { sourcemap: true });
+    expect(ret).toMatchObject({
+      code: 'export class A {}\n',
+      errors: [],
+      helpersUsed: {},
+      map: {
+        names: [],
+        sources: ['test.ts'],
+        sourcesContent: ['export class A<T> {}'],
+        version: 3,
+      },
+    });
+  });
+
+  it('should produce the same result as sync transform', async () => {
+    const sourceCode = `
+      const add = (a, b) => a + b;
+      console.log(add(1, 2));
+    `;
+
+    const syncResult = transform('test.js', sourceCode, { target: 'es2015' });
+    const asyncResult = await transformAsync('test.js', sourceCode, { target: 'es2015' });
+
+    expect(asyncResult.code).toEqual(syncResult.code);
+    expect(asyncResult.errors).toEqual(syncResult.errors);
+    expect(asyncResult.helpersUsed).toEqual(syncResult.helpersUsed);
+  });
+
+  it('should handle errors properly', async () => {
+    const invalidCode = 'export class { invalid syntax';
+    const ret = await transformAsync('test.ts', invalidCode);
+    expect(ret.errors.length).toBeGreaterThan(0);
+  });
+});
+
 describe('transform', () => {
   it('should not transform by default', () => {
     const cases = [
diff --git a/napi/transform/transform.wasi-browser.js b/napi/transform/transform.wasi-browser.js
@@ -61,3 +61,4 @@ export const HelperMode = __napiModule.exports.HelperMode
 export const isolatedDeclaration = __napiModule.exports.isolatedDeclaration
 export const moduleRunnerTransform = __napiModule.exports.moduleRunnerTransform
 export const transform = __napiModule.exports.transform
+export const transformAsync = __napiModule.exports.transformAsync
diff --git a/napi/transform/transform.wasi.cjs b/napi/transform/transform.wasi.cjs
@@ -113,3 +113,4 @@ module.exports.HelperMode = __napiModule.exports.HelperMode
 module.exports.isolatedDeclaration = __napiModule.exports.isolatedDeclaration
 module.exports.moduleRunnerTransform = __napiModule.exports.moduleRunnerTransform
 module.exports.transform = __napiModule.exports.transform
+module.exports.transformAsync = __napiModule.exports.transformAsync
