refactor: overhaul napi transformer package (#4592)

## What This PR Does
- Support declaration emit with `transform()`
- Consolidate shared parsing and error reporting logic into a `TransformContext`
- Add JSDoc comments to options

I'm getting this package ready for consumption in [oxc-jest](https://github.com/oxc-project/oxc-jest).

Cargo.lock

@@ -1817,10 +1817,12 @@ dependencies = [
  "napi-build",
  "napi-derive",
  "oxc_allocator",
+ "oxc_ast",
  "oxc_codegen",
  "oxc_diagnostics",
  "oxc_isolated_declarations",
  "oxc_parser",
+ "oxc_sourcemap",
  "oxc_span",
  "oxc_transformer",
 ]

napi/transform/Cargo.toml

@@ -22,12 +22,14 @@ doctest    = false
 
 [dependencies]
 oxc_allocator             = { workspace = true }
+oxc_ast                   = { workspace = true }
+oxc_codegen               = { workspace = true }
+oxc_diagnostics           = { workspace = true }
+oxc_isolated_declarations = { workspace = true }
 oxc_parser                = { workspace = true }
 oxc_span                  = { workspace = true }
-oxc_codegen               = { workspace = true }
+oxc_sourcemap             = { workspace = true }
-oxc_isolated_declarations = { workspace = true }
 oxc_transformer           = { workspace = true }
-oxc_diagnostics           = { workspace = true }
 
 napi        = { workspace = true }
 napi-derive = { workspace = true }

napi/transform/index.d.ts

@@ -1,66 +1,7 @@
-/* auto-generated by NAPI-RS */
+/* tslint:disable */
 /* eslint-disable */
-export interface ArrowFunctionsBindingOptions {
-  spec?: boolean
-}
 
-export interface Es2015BindingOptions {
+/* auto-generated by NAPI-RS */
-  arrowFunction?: ArrowFunctionsBindingOptions
-}
-
-/** TypeScript Isolated Declarations for Standalone DTS Emit */
-export declare function isolatedDeclaration(filename: string, sourceText: string): IsolatedDeclarationsResult
-
-export interface IsolatedDeclarationsResult {
-  sourceText: string
-  errors: Array<string>
-}
-
-export interface ReactBindingOptions {
-  runtime?: 'classic' | 'automatic'
-  development?: boolean
-  throwIfNamespace?: boolean
-  pure?: boolean
-  importSource?: string
-  pragma?: string
-  pragmaFrag?: string
-  useBuiltIns?: boolean
-  useSpread?: boolean
-}
-
-export interface Sourcemap {
-  file?: string
-  mappings?: string
-  sourceRoot?: string
-  sources?: Array<string | undefined | null>
-  sourcesContent?: Array<string | undefined | null>
-  names?: Array<string>
-}
-
-export declare function transform(filename: string, sourceText: string, options?: TransformOptions | undefined | null): TransformResult
-
-export interface TransformOptions {
-  sourceType?: 'script' | 'module' | 'unambiguous' | undefined
-  /** Force jsx parsing, */
-  jsx?: boolean
-  typescript?: TypeScriptBindingOptions
-  react?: ReactBindingOptions
-  es2015?: Es2015BindingOptions
-  /**
-   * Enable Sourcemap
-   *
-   * * `true` to generate a sourcemap for the code and include it in the result object.
-   *
-   * Default: false
-   */
-  sourcemap?: boolean
-}
-
-export interface TransformResult {
-  sourceText: string
-  map?: Sourcemap
-  errors: Array<string>
-}
 
 export interface TypeScriptBindingOptions {
   jsxPragma?: string
@@ -68,5 +9,214 @@ export interface TypeScriptBindingOptions {
   onlyRemoveTypeImports?: boolean
   allowNamespaces?: boolean
   allowDeclareFields?: boolean
+  /**
+   * Also generate a `.d.ts` declaration file for TypeScript files.
+   *
+   * The source file must be compliant with all
+   * [`isolatedDeclarations`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html#isolated-declarations)
+   * requirements.
+   *
+   * @default false
+   */
+  declaration?: boolean
 }
-
+/**
+ * Configure how TSX and JSX are transformed.
+ *
+ * @see [@babel/plugin-transform-react-jsx](https://babeljs.io/docs/babel-plugin-transform-react-jsx#options)
+ */
+export interface ReactBindingOptions {
+  /**
+   * Decides which runtime to use.
+   *
+   * - 'automatic' - auto-import the correct JSX factories
+   * - 'classic' - no auto-import
+   *
+   * @default 'automatic'
+   */
+  runtime?: 'classic' | 'automatic'
+  /**
+   * Emit development-specific information, such as `__source` and `__self`.
+   *
+   * @default false
+   *
+   * @see [@babel/plugin-transform-react-jsx-development](https://babeljs.io/docs/babel-plugin-transform-react-jsx-development)
+   */
+  development?: boolean
+  /**
+   * Toggles whether or not to throw an error if an XML namespaced tag name
+   * is used.
+   *
+   * Though the JSX spec allows this, it is disabled by default since React's
+   * JSX does not currently have support for it.
+   *
+   * @default true
+   */
+  throwIfNamespace?: boolean
+  /**
+   * Enables [@babel/plugin-transform-react-pure-annotations](https://babeljs.io/docs/en/babel-plugin-transform-react-pure-annotations).
+   *
+   * It will mark top-level React method calls as pure for tree shaking.
+   *
+   * @default true
+   */
+  pure?: boolean
+  /**
+   * Replaces the import source when importing functions.
+   *
+   * @default 'react'
+   */
+  importSource?: string
+  /**
+   * Replace the function used when compiling JSX expressions. It should be a
+   * qualified name (e.g. `React.createElement`) or an identifier (e.g.
+   * `createElement`).
+   *
+   * Only used for `classic` {@link runtime}.
+   *
+   * @default 'React.createElement'
+   */
+  pragma?: string
+  /**
+   * Replace the component used when compiling JSX fragments. It should be a
+   * valid JSX tag name.
+   *
+   * Only used for `classic` {@link runtime}.
+   *
+   * @default 'React.Fragment'
+   */
+  pragmaFrag?: string
+  /**
+   * When spreading props, use `Object.assign` directly instead of an extend helper.
+   *
+   * Only used for `classic` {@link runtime}.
+   *
+   * @default false
+   */
+  useBuiltIns?: boolean
+  /**
+   * When spreading props, use inline object with spread elements directly
+   * instead of an extend helper or Object.assign.
+   *
+   * Only used for `classic` {@link runtime}.
+   *
+   * @default false
+   */
+  useSpread?: boolean
+}
+export interface ArrowFunctionsBindingOptions {
+  /**
+   * This option enables the following:
+   * * Wrap the generated function in .bind(this) and keeps uses of this inside the function as-is, instead of using a renamed this.
+   * * Add a runtime check to ensure the functions are not instantiated.
+   * * Add names to arrow functions.
+   *
+   * @default false
+   */
+  spec?: boolean
+}
+export interface Es2015BindingOptions {
+  /** Transform arrow functions into function expressions. */
+  arrowFunction?: ArrowFunctionsBindingOptions
+}
+/**
+ * Options for transforming a JavaScript or TypeScript file.
+ *
+ * @see {@link transform}
+ */
+export interface TransformOptions {
+  sourceType?: 'script' | 'module' | 'unambiguous' | undefined
+  /**
+   * The current working directory. Used to resolve relative paths in other
+   * options.
+   */
+  cwd?: string
+  /**
+   * Force jsx parsing,
+   *
+   * @default false
+   */
+  jsx?: boolean
+  /** Configure how TypeScript is transformed. */
+  typescript?: TypeScriptBindingOptions
+  /** Configure how TSX and JSX are transformed. */
+  react?: ReactBindingOptions
+  /** Enable ES2015 transformations. */
+  es2015?: Es2015BindingOptions
+  /**
+   * Enable source map generation.
+   *
+   * When `true`, the `sourceMap` field of transform result objects will be populated.
+   *
+   * @default false
+   *
+   * @see {@link SourceMap}
+   */
+  sourcemap?: boolean
+}
+export interface SourceMap {
+  file?: string
+  mappings?: string
+  sourceRoot?: string
+  sources?: Array<string | undefined | null>
+  sourcesContent?: Array<string | undefined | null>
+  names?: Array<string>
+}
+export interface IsolatedDeclarationsResult {
+  sourceText: string
+  errors: Array<string>
+}
+/** TypeScript Isolated Declarations for Standalone DTS Emit */
+declare function isolatedDeclaration(filename: string, sourceText: string): IsolatedDeclarationsResult
+export interface TransformResult {
+  /**
+   * The transformed code.
+   *
+   * If parsing failed, this will be an empty string.
+   */
+  sourceText: string
+  /**
+   * The source map for the transformed code.
+   *
+   * This will be set if {@link TransformOptions#sourcemap} is `true`.
+   */
+  sourceMap?: SourceMap
+  /**
+   * The `.d.ts` declaration file for the transformed code. Declarations are
+   * only generated if `declaration` is set to `true` and a TypeScript file
+   * is provided.
+   *
+   * If parsing failed and `declaration` is set, this will be an empty string.
+   *
+   * @see {@link TypeScriptBindingOptions#declaration}
+   * @see [declaration tsconfig option](https://www.typescriptlang.org/tsconfig/#declaration)
+   */
+  declaration?: string
+  /**
+   * Declaration source map. Only generated if both
+   * {@link TypeScriptBindingOptions#declaration declaration} and
+   * {@link TransformOptions#sourcemap sourcemap} are set to `true`.
+   */
+  declarationMap?: SourceMap
+  /**
+   * Parse and transformation errors.
+   *
+   * Oxc's parser recovers from common syntax errors, meaning that
+   * transformed code may still be available even if there are errors in this
+   * list.
+   */
+  errors: Array<string>
+}
+/**
+ * Transpile a JavaScript or TypeScript into a target ECMAScript version.
+ *
+ * @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 an object containing the transformed code, source maps, and any
+ * errors that occurred during parsing or transformation.
+ */
+declare function transform(filename: string, sourceText: string, options?: TransformOptions | undefined | null): TransformResult

napi/transform/index.js

@@ -1,365 +1,316 @@
-// prettier-ignore
+/* tslint:disable */
 /* eslint-disable */
+/* prettier-ignore */
+
 /* auto-generated by NAPI-RS */
 
-const { readFileSync } = require('fs')
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
 
 let nativeBinding = null
-const loadErrors = []
+let localFileExisted = false
+let loadError = null
 
-const isMusl = () => {
+function isMusl() {
-  let musl = false
+  // For Node 10
-  if (process.platform === 'linux') {
+  if (!process.report || typeof process.report.getReport !== 'function') {
-    musl = isMuslFromFilesystem()
-    if (musl === null) {
-      musl = isMuslFromReport()
-    }
-    if (musl === null) {
-      musl = isMuslFromChildProcess()
-    }
-  }
-  return musl
-}
-
-const isFileMusl = (f) => f.includes('libc.musl-') || f.includes('ld-musl-')
-
-const isMuslFromFilesystem = () => {
     try {
-    return readFileSync('/usr/bin/ldd', 'utf-8').includes('musl')
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
-  } catch {
+      return readFileSync(lddPath, 'utf8').includes('musl')
-    return null
+    } catch (e) {
-  }
-}
-
-const isMuslFromReport = () => {
-  const report = typeof process.report.getReport === 'function' ? process.report.getReport() : null
-  if (!report) {
-    return null
-  }
-  if (report.header && report.header.glibcVersionRuntime) {
-    return false
-  }
-  if (Array.isArray(report.sharedObjects)) {
-    if (report.sharedObjects.some(isFileMusl)) {
       return true
     }
-  }
+  } else {
-  return false
+    const { glibcVersionRuntime } = process.report.getReport().header
-}
+    return !glibcVersionRuntime
-
-const isMuslFromChildProcess = () => {
-  try {
-    return require('child_process').execSync('ldd --version', { encoding: 'utf8' }).includes('musl')
-  } catch (e) {
-    // If we reach this case, we don't know if the system is musl or not, so is better to just fallback to false
-    return false
   }
 }
 
-function requireNative() {
+switch (platform) {
-  if (process.platform === 'android') {
+  case 'android':
-    if (process.arch === 'arm64') {
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'index.android-arm64.node'))
         try {
-        return require('./transform.android-arm64.node')
+          if (localFileExisted) {
-      } catch (e) {
+            nativeBinding = require('./index.android-arm64.node')
-        loadErrors.push(e)
-      }
-      try {
-        return require('@oxc-transform/binding-android-arm64')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-
-    } else if (process.arch === 'arm') {
-      try {
-        return require('./transform.android-arm-eabi.node')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-      try {
-        return require('@oxc-transform/binding-android-arm-eabi')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-
           } else {
-      loadErrors.push(new Error(`Unsupported architecture on Android ${process.arch}`))
+            nativeBinding = require('@oxc-transform/binding-android-arm64')
           }
-  } else if (process.platform === 'win32') {
-    if (process.arch === 'x64') {
-      try {
-        return require('./transform.win32-x64-msvc.node')
         } catch (e) {
-        loadErrors.push(e)
+          loadError = e
         }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'index.android-arm-eabi.node'))
         try {
-        return require('@oxc-transform/binding-win32-x64-msvc')
+          if (localFileExisted) {
-      } catch (e) {
+            nativeBinding = require('./index.android-arm-eabi.node')
-        loadErrors.push(e)
-      }
-
-    } else if (process.arch === 'ia32') {
-      try {
-        return require('./transform.win32-ia32-msvc.node')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-      try {
-        return require('@oxc-transform/binding-win32-ia32-msvc')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-
-    } else if (process.arch === 'arm64') {
-      try {
-        return require('./transform.win32-arm64-msvc.node')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-      try {
-        return require('@oxc-transform/binding-win32-arm64-msvc')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-
           } else {
-      loadErrors.push(new Error(`Unsupported architecture on Windows: ${process.arch}`))
+            nativeBinding = require('@oxc-transform/binding-android-arm-eabi')
           }
-  } else if (process.platform === 'darwin') {
-    try {
-        return require('./transform.darwin-universal.node')
         } catch (e) {
-        loadErrors.push(e)
+          loadError = e
         }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.win32-x64-msvc.node')
+        )
         try {
-        return require('@oxc-transform/binding-darwin-universal')
+          if (localFileExisted) {
-      } catch (e) {
+            nativeBinding = require('./index.win32-x64-msvc.node')
-        loadErrors.push(e)
-      }
-
-    if (process.arch === 'x64') {
-      try {
-        return require('./transform.darwin-x64.node')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-      try {
-        return require('@oxc-transform/binding-darwin-x64')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-
-    } else if (process.arch === 'arm64') {
-      try {
-        return require('./transform.darwin-arm64.node')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-      try {
-        return require('@oxc-transform/binding-darwin-arm64')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-
           } else {
-      loadErrors.push(new Error(`Unsupported architecture on macOS: ${process.arch}`))
+            nativeBinding = require('@oxc-transform/binding-win32-x64-msvc')
           }
-  } else if (process.platform === 'freebsd') {
-    if (process.arch === 'x64') {
-      try {
-        return require('./transform.freebsd-x64.node')
         } catch (e) {
-        loadErrors.push(e)
+          loadError = e
         }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.win32-ia32-msvc.node')
+        )
         try {
-        return require('@oxc-transform/binding-freebsd-x64')
+          if (localFileExisted) {
-      } catch (e) {
+            nativeBinding = require('./index.win32-ia32-msvc.node')
-        loadErrors.push(e)
-      }
-
-    } else if (process.arch === 'arm64') {
-      try {
-        return require('./transform.freebsd-arm64.node')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-      try {
-        return require('@oxc-transform/binding-freebsd-arm64')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-
           } else {
-      loadErrors.push(new Error(`Unsupported architecture on FreeBSD: ${process.arch}`))
+            nativeBinding = require('@oxc-transform/binding-win32-ia32-msvc')
           }
-  } else if (process.platform === 'linux') {
+        } catch (e) {
-    if (process.arch === 'x64') {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@oxc-transform/binding-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'index.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./index.darwin-universal.node')
+      } else {
+        nativeBinding = require('@oxc-transform/binding-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'index.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.darwin-x64.node')
+          } else {
+            nativeBinding = require('@oxc-transform/binding-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@oxc-transform/binding-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'index.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./index.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@oxc-transform/binding-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
         if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-x64-musl.node')
+          )
           try {
-        return require('./transform.linux-x64-musl.node')
+            if (localFileExisted) {
-      } catch (e) {
+              nativeBinding = require('./index.linux-x64-musl.node')
-        loadErrors.push(e)
-      }
-      try {
-        return require('@oxc-transform/binding-linux-x64-musl')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-
             } else {
-        try {
+              nativeBinding = require('@oxc-transform/binding-linux-x64-musl')
-        return require('./transform.linux-x64-gnu.node')
+            }
           } catch (e) {
-        loadErrors.push(e)
+            loadError = e
           }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-x64-gnu.node')
+          )
           try {
-        return require('@oxc-transform/binding-linux-x64-gnu')
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@oxc-transform/binding-linux-x64-gnu')
+            }
           } catch (e) {
-        loadErrors.push(e)
+            loadError = e
           }
-
         }
-    } else if (process.arch === 'arm64') {
+        break
+      case 'arm64':
         if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-arm64-musl.node')
+          )
           try {
-        return require('./transform.linux-arm64-musl.node')
+            if (localFileExisted) {
-      } catch (e) {
+              nativeBinding = require('./index.linux-arm64-musl.node')
-        loadErrors.push(e)
-      }
-      try {
-        return require('@oxc-transform/binding-linux-arm64-musl')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-
             } else {
-        try {
+              nativeBinding = require('@oxc-transform/binding-linux-arm64-musl')
-        return require('./transform.linux-arm64-gnu.node')
+            }
           } catch (e) {
-        loadErrors.push(e)
+            loadError = e
           }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-arm64-gnu.node')
+          )
           try {
-        return require('@oxc-transform/binding-linux-arm64-gnu')
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@oxc-transform/binding-linux-arm64-gnu')
+            }
           } catch (e) {
-        loadErrors.push(e)
+            loadError = e
           }
-
         }
-    } else if (process.arch === 'arm') {
+        break
+      case 'arm':
         if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-arm-musleabihf.node')
+          )
           try {
-        return require('./transform.linux-arm-musleabihf.node')
+            if (localFileExisted) {
-      } catch (e) {
+              nativeBinding = require('./index.linux-arm-musleabihf.node')
-        loadErrors.push(e)
-      }
-      try {
-        return require('@oxc-transform/binding-linux-arm-musleabihf')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-
             } else {
-        try {
+              nativeBinding = require('@oxc-transform/binding-linux-arm-musleabihf')
-        return require('./transform.linux-arm-gnueabihf.node')
+            }
           } catch (e) {
-        loadErrors.push(e)
+            loadError = e
           }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-arm-gnueabihf.node')
+          )
           try {
-        return require('@oxc-transform/binding-linux-arm-gnueabihf')
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@oxc-transform/binding-linux-arm-gnueabihf')
+            }
           } catch (e) {
-        loadErrors.push(e)
+            loadError = e
           }
-
         }
-    } else if (process.arch === 'riscv64') {
+        break
+      case 'riscv64':
         if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-riscv64-musl.node')
+          )
           try {
-        return require('./transform.linux-riscv64-musl.node')
+            if (localFileExisted) {
-      } catch (e) {
+              nativeBinding = require('./index.linux-riscv64-musl.node')
-        loadErrors.push(e)
-      }
-      try {
-        return require('@oxc-transform/binding-linux-riscv64-musl')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-
             } else {
-        try {
+              nativeBinding = require('@oxc-transform/binding-linux-riscv64-musl')
-        return require('./transform.linux-riscv64-gnu.node')
+            }
           } catch (e) {
-        loadErrors.push(e)
+            loadError = e
-      }
-      try {
-        return require('@oxc-transform/binding-linux-riscv64-gnu')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-
-      }
-    } else if (process.arch === 'ppc64') {
-      try {
-        return require('./transform.linux-ppc64-gnu.node')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-      try {
-        return require('@oxc-transform/binding-linux-ppc64-gnu')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-
-    } else if (process.arch === 's390x') {
-      try {
-        return require('./transform.linux-s390x-gnu.node')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-      try {
-        return require('@oxc-transform/binding-linux-s390x-gnu')
-      } catch (e) {
-        loadErrors.push(e)
-      }
-
-    } else {
-      loadErrors.push(new Error(`Unsupported architecture on Linux: ${process.arch}`))
           }
         } else {
-    loadErrors.push(new Error(`Unsupported OS: ${process.platform}, architecture: ${process.arch}`))
+          localFileExisted = existsSync(
-  }
+            join(__dirname, 'index.linux-riscv64-gnu.node')
-}
+          )
-
-nativeBinding = requireNative()
-
-if (!nativeBinding || process.env.NAPI_RS_FORCE_WASI) {
           try {
-    nativeBinding = require('./transform.wasi.cjs')
+            if (localFileExisted) {
-  } catch (err) {
+              nativeBinding = require('./index.linux-riscv64-gnu.node')
-    if (process.env.NAPI_RS_FORCE_WASI) {
+            } else {
-      console.error(err)
+              nativeBinding = require('@oxc-transform/binding-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
           }
         }
-  if (!nativeBinding) {
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.linux-s390x-gnu.node')
+        )
         try {
-      nativeBinding = require('@oxc-transform/binding-wasm32-wasi')
+          if (localFileExisted) {
-    } catch (err) {
+            nativeBinding = require('./index.linux-s390x-gnu.node')
-      if (process.env.NAPI_RS_FORCE_WASI) {
+          } else {
-        console.error(err)
+            nativeBinding = require('@oxc-transform/binding-linux-s390x-gnu')
           }
+        } catch (e) {
+          loadError = e
         }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
     }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
 }
 
 if (!nativeBinding) {
-  if (loadErrors.length > 0) {
+  if (loadError) {
-    // TODO Link to documentation with potential fixes
+    throw loadError
-    //  - The package owner could build/publish bindings for this arch
-    //  - The user may need to bundle the correct files
-    //  - The user may need to re-install node_modules to get new packages
-    throw new Error('Failed to load native binding', { cause: loadErrors })
   }
   throw new Error(`Failed to load native binding`)
 }
 
-module.exports.isolatedDeclaration = nativeBinding.isolatedDeclaration
+const { isolatedDeclaration, transform } = nativeBinding
-module.exports.transform = nativeBinding.transform
+
+module.exports.isolatedDeclaration = isolatedDeclaration
+module.exports.transform = transform

napi/transform/src/context.rs

@@ -0,0 +1,173 @@
+use oxc_allocator::Allocator;
+use oxc_ast::{ast::Program, Trivias};
+use oxc_codegen::Codegen;
+use std::{
+    cell::{OnceCell, Ref, RefCell, RefMut},
+    path::Path,
+    sync::Arc,
+};
+
+use oxc_diagnostics::{Error, NamedSource, OxcDiagnostic};
+use oxc_parser::{Parser, ParserReturn};
+use oxc_span::SourceType;
+
+use crate::TransformOptions;
+
+#[must_use]
+pub(crate) struct TransformContext<'a> {
+    pub allocator: &'a Allocator,
+    program: RefCell<Program<'a>>,
+    pub trivias: Trivias,
+
+    /// Will be initialized if provided to constructor or first accessed.
+    /// Prevents allocations for codegen tasks that don't require options.
+    options: OnceCell<oxc_transformer::TransformOptions>,
+    /// Generate source maps?
+    source_map: bool,
+    /// Generate `.d.ts` files?
+    ///
+    /// Used by [`crate::transform`].
+    declarations: bool,
+
+    /// Path to the file being transformed.
+    filename: &'a str,
+    /// Source text of the file being transformed.
+    source_text: &'a str,
+    source_type: SourceType,
+
+    /// Errors that occurred during transformation.
+    errors: RefCell<Vec<OxcDiagnostic>>,
+}
+
+impl<'a> TransformContext<'a> {
+    pub fn new(
+        allocator: &'a Allocator,
+        filename: &'a str,
+        source_text: &'a str,
+        source_type: SourceType,
+        options: Option<TransformOptions>,
+    ) -> Self {
+        let ParserReturn { errors, program, trivias, .. } =
+            Parser::new(allocator, source_text, source_type).parse();
+
+        // Options that are added by this napi crates and don't exist in
+        // oxc_transformer.
+        let source_map = options.as_ref().and_then(|o| o.sourcemap).unwrap_or_default();
+        let declarations = options
+            .as_ref()
+            .and_then(|o| o.typescript.as_ref())
+            .and_then(|t| t.declaration)
+            .unwrap_or_default();
+
+        // Insert options into the cell if provided. Otherwise they will be
+        // initialized to default when first accessed.
+        let options_cell = OnceCell::new();
+        if let Some(options) = options {
+            options_cell.set(options.into()).unwrap();
+        }
+
+        Self {
+            allocator,
+            program: RefCell::new(program),
+            trivias,
+
+            options: options_cell,
+            source_map,
+            declarations,
+
+            filename,
+            source_text,
+            source_type,
+            errors: RefCell::new(errors),
+        }
+    }
+
+    #[inline]
+    pub fn file_name(&self) -> &'a str {
+        self.filename
+    }
+    #[inline]
+    pub fn file_path(&self) -> &'a Path {
+        Path::new(self.filename)
+    }
+
+    #[inline]
+    pub fn source_text(&self) -> &'a str {
+        self.source_text
+    }
+
+    #[inline]
+    pub fn oxc_options(&self) -> oxc_transformer::TransformOptions {
+        self.options.get_or_init(Default::default).clone()
+    }
+
+    #[inline]
+    pub(crate) fn declarations(&self) -> bool {
+        self.declarations
+    }
+
+    #[inline]
+    pub fn source_type(&self) -> SourceType {
+        self.source_type
+    }
+
+    #[inline]
+    pub fn program(&self) -> Ref<'_, Program<'a>> {
+        self.program.borrow()
+    }
+
+    #[inline]
+    pub fn program_mut(&self) -> RefMut<'_, Program<'a>> {
+        self.program.borrow_mut()
+    }
+
+    pub fn codegen<const MINIFY: bool>(&self) -> Codegen<'a, MINIFY> {
+        let codegen = Codegen::<MINIFY>::new();
+        if self.source_map {
+            codegen.enable_source_map(self.file_name(), self.source_text())
+        } else {
+            codegen
+        }
+    }
+
+    pub fn add_diagnostics(&self, diagnostics: Vec<OxcDiagnostic>) {
+        if diagnostics.is_empty() {
+            return;
+        }
+        self.errors.borrow_mut().extend(diagnostics);
+    }
+
+    pub fn take_and_render_reports(&self) -> Vec<String> {
+        let diagnostics = std::mem::take(&mut *self.errors.borrow_mut());
+        // TODO: make pretty-printed errors configurable
+        self.wrap_diagnostics(diagnostics).map(|error| format!("{error:?}")).collect()
+    }
+
+    fn wrap_diagnostics<D: IntoIterator<Item = OxcDiagnostic>>(
+        &self,
+        diagnostics: D,
+    ) -> impl Iterator<Item = Error> {
+        let source = {
+            let lang = match (self.source_type.is_javascript(), self.source_type.is_jsx()) {
+                (true, false) => "JavaScript",
+                (true, true) => "JSX",
+                (false, true) => "TypeScript React",
+                (false, false) => {
+                    if self.source_type.is_typescript_definition() {
+                        "TypeScript Declaration"
+                    } else {
+                        "TypeScript"
+                    }
+                }
+            };
+
+            let ns = NamedSource::new(self.file_name(), self.source_text().to_string())
+                .with_language(lang);
+            Arc::new(ns)
+        };
+
+        diagnostics
+            .into_iter()
+            .map(move |diagnostic| Error::from(diagnostic).with_source_code(Arc::clone(&source)))
+    }
+}

napi/transform/src/isolated_declaration.rs

@@ -1,17 +1,17 @@
-use std::sync::Arc;
-
 use napi_derive::napi;
 
 use oxc_allocator::Allocator;
-use oxc_codegen::CodeGenerator;
+use oxc_codegen::CodegenReturn;
-use oxc_diagnostics::{Error, NamedSource};
 use oxc_isolated_declarations::IsolatedDeclarations;
-use oxc_parser::Parser;
 use oxc_span::SourceType;
 
+use crate::context::TransformContext;
+
 #[napi(object)]
 pub struct IsolatedDeclarationsResult {
     pub source_text: String,
+    // TODO: should we expose source maps?
+    // pub source_map: Option<SourceMap>,
     pub errors: Vec<String>,
 }
 
@@ -21,22 +21,17 @@ pub struct IsolatedDeclarationsResult {
 pub fn isolated_declaration(filename: String, source_text: String) -> IsolatedDeclarationsResult {
     let source_type = SourceType::from_path(&filename).unwrap_or_default().with_typescript(true);
     let allocator = Allocator::default();
-    let parser_ret = Parser::new(&allocator, &source_text, source_type).parse();
+    let ctx = TransformContext::new(&allocator, &filename, &source_text, source_type, None);
-    let transformed_ret = IsolatedDeclarations::new(&allocator).build(&parser_ret.program);
+    let transformed_ret = build_declarations(&ctx);
-    let printed = CodeGenerator::new().build(&transformed_ret.program).source_text;
 
-    let mut errors = vec![];
+    IsolatedDeclarationsResult {
-    if !parser_ret.errors.is_empty() || !transformed_ret.errors.is_empty() {
+        source_text: transformed_ret.source_text,
-        let source = Arc::new(NamedSource::new(filename, source_text.to_string()));
+        errors: ctx.take_and_render_reports(),
-        errors.extend(
-            parser_ret
-                .errors
-                .into_iter()
-                .chain(transformed_ret.errors)
-                .map(|diagnostic| Error::from(diagnostic).with_source_code(Arc::clone(&source)))
-                .map(|error| format!("{error:?}")),
-        );
     }
-
+}
-    IsolatedDeclarationsResult { source_text: printed, errors }
+
+pub(crate) fn build_declarations(ctx: &TransformContext<'_>) -> CodegenReturn {
+    let transformed_ret = IsolatedDeclarations::new(ctx.allocator).build(&ctx.program_mut());
+    ctx.add_diagnostics(transformed_ret.errors);
+    ctx.codegen::<false>().build(&ctx.program())
 }

napi/transform/src/lib.rs

@@ -1,4 +1,40 @@
-mod isolated_declaration;
+// NOTE: the strange order of struct and `mod` statements is to establish the
-mod transformer;
+// desired order in generated `index.d.ts` code. We want options to be on top.
+// This is not only for aesthetics, but using declarations before they're parsed
+// breaks NAPI typegen.
+mod context;
+mod options;
 
-pub use crate::{isolated_declaration::*, transformer::*};
+use napi_derive::napi;
+
+#[napi(object)]
+pub struct SourceMap {
+    pub file: Option<String>,
+    pub mappings: Option<String>,
+    pub source_root: Option<String>,
+    pub sources: Option<Vec<Option<String>>>,
+    pub sources_content: Option<Vec<Option<String>>>,
+    pub names: Option<Vec<String>>,
+}
+
+pub use crate::options::*;
+
+mod isolated_declaration;
+pub use isolated_declaration::*;
+
+mod transformer;
+pub use transformer::*;
+
+impl From<oxc_sourcemap::SourceMap> for SourceMap {
+    fn from(source_map: oxc_sourcemap::SourceMap) -> Self {
+        let json = source_map.to_json();
+        Self {
+            file: json.file,
+            mappings: json.mappings,
+            source_root: json.source_root,
+            sources: json.sources,
+            sources_content: json.sources_content,
+            names: json.names,
+        }
+    }
+}

napi/transform/src/options.rs

@@ -0,0 +1,213 @@
+use std::path::PathBuf;
+
+use napi_derive::napi;
+
+use oxc_transformer::{
+    ArrowFunctionsOptions, ES2015Options, ReactJsxRuntime, ReactOptions, TypeScriptOptions,
+};
+
+#[napi(object)]
+#[derive(Default)]
+pub struct TypeScriptBindingOptions {
+    pub jsx_pragma: Option<String>,
+    pub jsx_pragma_frag: Option<String>,
+    pub only_remove_type_imports: Option<bool>,
+    pub allow_namespaces: Option<bool>,
+    pub allow_declare_fields: Option<bool>,
+    /// Also generate a `.d.ts` declaration file for TypeScript files.
+    ///
+    /// The source file must be compliant with all
+    /// [`isolatedDeclarations`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html#isolated-declarations)
+    /// requirements.
+    ///
+    /// @default false
+    pub declaration: Option<bool>,
+}
+
+impl From<TypeScriptBindingOptions> for TypeScriptOptions {
+    fn from(options: TypeScriptBindingOptions) -> Self {
+        let ops = TypeScriptOptions::default();
+        TypeScriptOptions {
+            jsx_pragma: options.jsx_pragma.map(Into::into).unwrap_or(ops.jsx_pragma),
+            jsx_pragma_frag: options.jsx_pragma_frag.map(Into::into).unwrap_or(ops.jsx_pragma_frag),
+            only_remove_type_imports: options
+                .only_remove_type_imports
+                .unwrap_or(ops.only_remove_type_imports),
+            allow_namespaces: options.allow_namespaces.unwrap_or(ops.allow_namespaces),
+            allow_declare_fields: options.allow_declare_fields.unwrap_or(ops.allow_declare_fields),
+        }
+    }
+}
+
+/// Configure how TSX and JSX are transformed.
+///
+/// @see [@babel/plugin-transform-react-jsx](https://babeljs.io/docs/babel-plugin-transform-react-jsx#options)
+#[napi(object)]
+pub struct ReactBindingOptions {
+    /// Decides which runtime to use.
+    ///
+    /// - 'automatic' - auto-import the correct JSX factories
+    /// - 'classic' - no auto-import
+    ///
+    /// @default 'automatic'
+    #[napi(ts_type = "'classic' | 'automatic'")]
+    pub runtime: Option<String>,
+
+    /// Emit development-specific information, such as `__source` and `__self`.
+    ///
+    /// @default false
+    ///
+    /// @see [@babel/plugin-transform-react-jsx-development](https://babeljs.io/docs/babel-plugin-transform-react-jsx-development)
+    pub development: Option<bool>,
+
+    /// Toggles whether or not to throw an error if an XML namespaced tag name
+    /// is used.
+    ///
+    /// Though the JSX spec allows this, it is disabled by default since React's
+    /// JSX does not currently have support for it.
+    ///
+    /// @default true
+    pub throw_if_namespace: Option<bool>,
+
+    /// Enables [@babel/plugin-transform-react-pure-annotations](https://babeljs.io/docs/en/babel-plugin-transform-react-pure-annotations).
+    ///
+    /// It will mark top-level React method calls as pure for tree shaking.
+    ///
+    /// @default true
+    pub pure: Option<bool>,
+
+    /// Replaces the import source when importing functions.
+    ///
+    /// @default 'react'
+    pub import_source: Option<String>,
+
+    /// Replace the function used when compiling JSX expressions. It should be a
+    /// qualified name (e.g. `React.createElement`) or an identifier (e.g.
+    /// `createElement`).
+    ///
+    /// Only used for `classic` {@link runtime}.
+    ///
+    /// @default 'React.createElement'
+    pub pragma: Option<String>,
+
+    /// Replace the component used when compiling JSX fragments. It should be a
+    /// valid JSX tag name.
+    ///
+    /// Only used for `classic` {@link runtime}.
+    ///
+    /// @default 'React.Fragment'
+    pub pragma_frag: Option<String>,
+
+    /// When spreading props, use `Object.assign` directly instead of an extend helper.
+    ///
+    /// Only used for `classic` {@link runtime}.
+    ///
+    /// @default false
+    pub use_built_ins: Option<bool>,
+
+    /// When spreading props, use inline object with spread elements directly
+    /// instead of an extend helper or Object.assign.
+    ///
+    /// Only used for `classic` {@link runtime}.
+    ///
+    /// @default false
+    pub use_spread: Option<bool>,
+}
+
+impl From<ReactBindingOptions> for ReactOptions {
+    fn from(options: ReactBindingOptions) -> Self {
+        let ops = ReactOptions::default();
+        ReactOptions {
+            runtime: match options.runtime.as_deref() {
+                Some("classic") => ReactJsxRuntime::Classic,
+                /* "automatic" */ _ => ReactJsxRuntime::Automatic,
+            },
+            development: options.development.unwrap_or(ops.development),
+            throw_if_namespace: options.throw_if_namespace.unwrap_or(ops.throw_if_namespace),
+            pure: options.pure.unwrap_or(ops.pure),
+            import_source: options.import_source,
+            pragma: options.pragma,
+            pragma_frag: options.pragma_frag,
+            use_built_ins: options.use_built_ins,
+            use_spread: options.use_spread,
+            ..Default::default()
+        }
+    }
+}
+
+#[napi(object)]
+pub struct ArrowFunctionsBindingOptions {
+    /// This option enables the following:
+    /// * Wrap the generated function in .bind(this) and keeps uses of this inside the function as-is, instead of using a renamed this.
+    /// * Add a runtime check to ensure the functions are not instantiated.
+    /// * Add names to arrow functions.
+    ///
+    /// @default false
+    pub spec: Option<bool>,
+}
+
+impl From<ArrowFunctionsBindingOptions> for ArrowFunctionsOptions {
+    fn from(options: ArrowFunctionsBindingOptions) -> Self {
+        ArrowFunctionsOptions { spec: options.spec.unwrap_or_default() }
+    }
+}
+
+#[napi(object)]
+pub struct ES2015BindingOptions {
+    /// Transform arrow functions into function expressions.
+    pub arrow_function: Option<ArrowFunctionsBindingOptions>,
+}
+
+impl From<ES2015BindingOptions> for ES2015Options {
+    fn from(options: ES2015BindingOptions) -> Self {
+        ES2015Options { arrow_function: options.arrow_function.map(Into::into) }
+    }
+}
+
+/// Options for transforming a JavaScript or TypeScript file.
+///
+/// @see {@link transform}
+#[napi(object)]
+pub struct TransformOptions {
+    #[napi(ts_type = "'script' | 'module' | 'unambiguous' | undefined")]
+    pub source_type: Option<String>,
+
+    /// The current working directory. Used to resolve relative paths in other
+    /// options.
+    pub cwd: Option<String>,
+
+    /// Force jsx parsing,
+    ///
+    /// @default false
+    pub jsx: Option<bool>,
+
+    /// Configure how TypeScript is transformed.
+    pub typescript: Option<TypeScriptBindingOptions>,
+
+    /// Configure how TSX and JSX are transformed.
+    pub react: Option<ReactBindingOptions>,
+
+    /// Enable ES2015 transformations.
+    pub es2015: Option<ES2015BindingOptions>,
+
+    /// Enable source map generation.
+    ///
+    /// When `true`, the `sourceMap` field of transform result objects will be populated.
+    ///
+    /// @default false
+    ///
+    /// @see {@link SourceMap}
+    pub sourcemap: Option<bool>,
+}
+
+impl From<TransformOptions> for oxc_transformer::TransformOptions {
+    fn from(options: TransformOptions) -> Self {
+        Self {
+            cwd: options.cwd.map(PathBuf::from).unwrap_or_default(),
+            typescript: options.typescript.map(Into::into).unwrap_or_default(),
+            react: options.react.map(Into::into).unwrap_or_default(),
+            es2015: options.es2015.map(Into::into).unwrap_or_default(),
+            ..Self::default()
+        }
+    }
+}

napi/transform/src/transformer.rs

@@ -1,142 +1,58 @@
-use std::path::Path;
-
 use napi_derive::napi;
 
+use crate::{context::TransformContext, isolated_declaration, SourceMap, TransformOptions};
 use oxc_allocator::Allocator;
-use oxc_codegen::CodeGenerator;
+use oxc_codegen::CodegenReturn;
-use oxc_parser::Parser;
 use oxc_span::SourceType;
-use oxc_transformer::{
+use oxc_transformer::Transformer;
-    ArrowFunctionsOptions, ES2015Options, ReactJsxRuntime, ReactOptions, Transformer,
-    TypeScriptOptions,
-};
 
-#[napi(object)]
+// NOTE: use JSDoc syntax for all doc comments, not rustdoc.
-pub struct TypeScriptBindingOptions {
-    pub jsx_pragma: Option<String>,
-    pub jsx_pragma_frag: Option<String>,
-    pub only_remove_type_imports: Option<bool>,
-    pub allow_namespaces: Option<bool>,
-    pub allow_declare_fields: Option<bool>,
-}
-
-impl From<TypeScriptBindingOptions> for TypeScriptOptions {
-    fn from(options: TypeScriptBindingOptions) -> Self {
-        let ops = TypeScriptOptions::default();
-        TypeScriptOptions {
-            jsx_pragma: options.jsx_pragma.map(Into::into).unwrap_or(ops.jsx_pragma),
-            jsx_pragma_frag: options.jsx_pragma_frag.map(Into::into).unwrap_or(ops.jsx_pragma_frag),
-            only_remove_type_imports: options
-                .only_remove_type_imports
-                .unwrap_or(ops.only_remove_type_imports),
-            allow_namespaces: options.allow_namespaces.unwrap_or(ops.allow_namespaces),
-            allow_declare_fields: options.allow_declare_fields.unwrap_or(ops.allow_declare_fields),
-        }
-    }
-}
-
-#[napi(object)]
-pub struct ReactBindingOptions {
-    #[napi(ts_type = "'classic' | 'automatic'")]
-    pub runtime: Option<String>,
-    pub development: Option<bool>,
-    pub throw_if_namespace: Option<bool>,
-    pub pure: Option<bool>,
-    pub import_source: Option<String>,
-    pub pragma: Option<String>,
-    pub pragma_frag: Option<String>,
-    pub use_built_ins: Option<bool>,
-    pub use_spread: Option<bool>,
-}
-
-impl From<ReactBindingOptions> for ReactOptions {
-    fn from(options: ReactBindingOptions) -> Self {
-        let ops = ReactOptions::default();
-        ReactOptions {
-            runtime: match options.runtime.as_deref() {
-                Some("classic") => ReactJsxRuntime::Classic,
-                /* "automatic" */ _ => ReactJsxRuntime::Automatic,
-            },
-            development: options.development.unwrap_or(ops.development),
-            throw_if_namespace: options.throw_if_namespace.unwrap_or(ops.throw_if_namespace),
-            pure: options.pure.unwrap_or(ops.pure),
-            import_source: options.import_source,
-            pragma: options.pragma,
-            pragma_frag: options.pragma_frag,
-            use_built_ins: options.use_built_ins,
-            use_spread: options.use_spread,
-            ..Default::default()
-        }
-    }
-}
-
-#[napi(object)]
-pub struct ArrowFunctionsBindingOptions {
-    pub spec: Option<bool>,
-}
-
-impl From<ArrowFunctionsBindingOptions> for ArrowFunctionsOptions {
-    fn from(options: ArrowFunctionsBindingOptions) -> Self {
-        ArrowFunctionsOptions { spec: options.spec.unwrap_or_default() }
-    }
-}
-
-#[napi(object)]
-pub struct ES2015BindingOptions {
-    pub arrow_function: Option<ArrowFunctionsBindingOptions>,
-}
-
-impl From<ES2015BindingOptions> for ES2015Options {
-    fn from(options: ES2015BindingOptions) -> Self {
-        ES2015Options { arrow_function: options.arrow_function.map(Into::into) }
-    }
-}
-
-#[napi(object)]
-pub struct TransformOptions {
-    #[napi(ts_type = "'script' | 'module' | 'unambiguous' | undefined")]
-    pub source_type: Option<String>,
-    /// Force jsx parsing,
-    pub jsx: Option<bool>,
-    pub typescript: Option<TypeScriptBindingOptions>,
-    pub react: Option<ReactBindingOptions>,
-    pub es2015: Option<ES2015BindingOptions>,
-    /// Enable Sourcemap
-    ///
-    /// * `true` to generate a sourcemap for the code and include it in the result object.
-    ///
-    /// Default: false
-    pub sourcemap: Option<bool>,
-}
-
-impl From<TransformOptions> for oxc_transformer::TransformOptions {
-    fn from(options: TransformOptions) -> Self {
-        Self {
-            typescript: options.typescript.map(Into::into).unwrap_or_default(),
-            react: options.react.map(Into::into).unwrap_or_default(),
-            es2015: options.es2015.map(Into::into).unwrap_or_default(),
-            ..Self::default()
-        }
-    }
-}
-
-#[napi(object)]
-pub struct Sourcemap {
-    pub file: Option<String>,
-    pub mappings: Option<String>,
-    pub source_root: Option<String>,
-    pub sources: Option<Vec<Option<String>>>,
-    pub sources_content: Option<Vec<Option<String>>>,
-    pub names: Option<Vec<String>>,
-}
 
 #[napi(object)]
 pub struct TransformResult {
+    /// The transformed code.
+    ///
+    /// If parsing failed, this will be an empty string.
     pub source_text: String,
-    pub map: Option<Sourcemap>,
+
+    /// The source map for the transformed code.
+    ///
+    /// This will be set if {@link TransformOptions#sourcemap} is `true`.
+    pub source_map: Option<SourceMap>,
+
+    /// The `.d.ts` declaration file for the transformed code. Declarations are
+    /// only generated if `declaration` is set to `true` and a TypeScript file
+    /// is provided.
+    ///
+    /// If parsing failed and `declaration` is set, this will be an empty string.
+    ///
+    /// @see {@link TypeScriptBindingOptions#declaration}
+    /// @see [declaration tsconfig option](https://www.typescriptlang.org/tsconfig/#declaration)
+    pub declaration: Option<String>,
+
+    /// Declaration source map. Only generated if both
+    /// {@link TypeScriptBindingOptions#declaration declaration} and
+    /// {@link TransformOptions#sourcemap sourcemap} are set to `true`.
+    pub declaration_map: Option<SourceMap>,
+
+    /// Parse and transformation errors.
+    ///
+    /// Oxc's parser recovers from common syntax errors, meaning that
+    /// transformed code may still be available even if there are errors in this
+    /// list.
     pub errors: Vec<String>,
 }
 
+/// Transpile a JavaScript or TypeScript into a target ECMAScript version.
+///
+/// @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 an object containing the transformed code, source maps, and any
+/// errors that occurred during parsing or transformation.
 #[allow(clippy::needless_pass_by_value, dead_code)]
 #[napi]
 pub fn transform(
@@ -144,9 +60,6 @@ pub fn transform(
     source_text: String,
     options: Option<TransformOptions>,
 ) -> TransformResult {
-    let sourcemap = options.as_ref().is_some_and(|x| x.sourcemap.unwrap_or_default());
-    let mut errors = vec![];
-
     let source_type = {
         let mut source_type = SourceType::from_path(&filename).unwrap_or_default();
         // Force `script` or `module`
@@ -163,46 +76,37 @@ pub fn transform(
     };
 
     let allocator = Allocator::default();
-    let parser_ret = Parser::new(&allocator, &source_text, source_type).parse();
+    let ctx = TransformContext::new(&allocator, &filename, &source_text, source_type, options);
-    if !parser_ret.errors.is_empty() {
-        errors.extend(parser_ret.errors.into_iter().map(|error| error.message.to_string()));
-    }
 
-    let mut program = parser_ret.program;
+    let should_build_types = ctx.declarations() && source_type.is_typescript();
-    let transform_options = options.map(Into::into).unwrap_or_default();
+    let declarations_result =
-    let ret = Transformer::new(
+        should_build_types.then(|| isolated_declaration::build_declarations(&ctx));
-        &allocator,
-        Path::new(&filename),
-        source_type,
-        &source_text,
-        parser_ret.trivias.clone(),
-        transform_options,
-    )
-    .build(&mut program);
 
-    if !ret.errors.is_empty() {
+    let transpile_result = transpile(&ctx);
-        errors.extend(ret.errors.into_iter().map(|error| error.to_string()));
-    }
 
-    let mut codegen = CodeGenerator::new();
+    let (declaration, declaration_map) = declarations_result
-    if sourcemap {
+        .map_or((None, None), |d| (Some(d.source_text), d.source_map.map(Into::into)));
-        codegen = codegen.enable_source_map(&filename, &source_text);
-    }
-    let ret = codegen.build(&program);
 
     TransformResult {
-        source_text: ret.source_text,
+        source_text: transpile_result.source_text,
-        map: ret.source_map.map(|sourcemap| {
+        source_map: transpile_result.source_map.map(Into::into),
-            let json = sourcemap.to_json();
+        declaration,
-            Sourcemap {
+        declaration_map,
-                file: json.file,
+        errors: ctx.take_and_render_reports(),
-                mappings: json.mappings,
-                source_root: json.source_root,
-                sources: json.sources,
-                sources_content: json.sources_content,
-                names: json.names,
-            }
-        }),
-        errors,
     }
 }
+
+fn transpile(ctx: &TransformContext<'_>) -> CodegenReturn {
+    let ret = Transformer::new(
+        ctx.allocator,
+        ctx.file_path(),
+        ctx.source_type(),
+        ctx.source_text(),
+        ctx.trivias.clone(),
+        ctx.oxc_options(),
+    )
+    .build(&mut ctx.program_mut());
+
+    ctx.add_diagnostics(ret.errors);
+    ctx.codegen::<false>().build(&ctx.program())
+}