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).
oxc-project · Aug 6, 2024 · 9b51e04 · 9b51e04
1 parent 8dd76e4
commit 9b51e04
Show file tree

Hide file tree

Showing 9 changed files with 985 additions and 559 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/napi/transform/Cargo.toml b/napi/transform/Cargo.toml
@@ -22,12 +22,14 @@ doctest    = false
 
 [dependencies]
 oxc_allocator             = { workspace = true }
-oxc_parser                = { workspace = true }
-oxc_span                  = { 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_sourcemap             = { workspace = true }
 oxc_transformer           = { workspace = true }
-oxc_diagnostics           = { workspace = true }
 
 napi        = { workspace = true }
 napi-derive = { workspace = true }

diff --git a/napi/transform/index.d.ts b/napi/transform/index.d.ts
@@ -1,72 +1,222 @@
-/* auto-generated by NAPI-RS */
+/* tslint:disable */
 /* eslint-disable */
-export interface ArrowFunctionsBindingOptions {
-  spec?: boolean
-}
-
-export interface Es2015BindingOptions {
-  arrowFunction?: ArrowFunctionsBindingOptions
-}
 
-/** TypeScript Isolated Declarations for Standalone DTS Emit */
-export declare function isolatedDeclaration(filename: string, sourceText: string): IsolatedDeclarationsResult
+/* auto-generated by NAPI-RS */
 
-export interface IsolatedDeclarationsResult {
-  sourceText: string
-  errors: Array<string>
+export interface TypeScriptBindingOptions {
+  jsxPragma?: string
+  jsxPragmaFrag?: string
+  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 Sourcemap {
-  file?: string
-  mappings?: string
-  sourceRoot?: string
-  sources?: Array<string | undefined | null>
-  sourcesContent?: Array<string | undefined | null>
-  names?: Array<string>
+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 declare function transform(filename: string, sourceText: string, options?: TransformOptions | undefined | null): TransformResult
-
+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
-  /** Force jsx parsing, */
+  /**
+   * 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 Sourcemap
+   * Enable source map generation.
    *
-   * * `true` to generate a sourcemap for the code and include it in the result object.
+   * When `true`, the `sourceMap` field of transform result objects will be populated.
    *
-   * Default: false
+   * @default false
+   *
+   * @see {@link SourceMap}
    */
   sourcemap?: boolean
 }
-
-export interface TransformResult {
+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
-  map?: Sourcemap
   errors: Array<string>
 }
-
-export interface TypeScriptBindingOptions {
-  jsxPragma?: string
-  jsxPragmaFrag?: string
-  onlyRemoveTypeImports?: boolean
-  allowNamespaces?: boolean
-  allowDeclareFields?: boolean
+/** 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