oxc-transform-react-compiler-experimental 0.0.0

package/index.d.ts

@@ -0,0 +1,782 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+export interface Comment {
+  type: 'Line' | 'Block'
+  value: string
+  start: number
+  end: number
+}
+
+export interface ErrorLabel {
+  message: string | null
+  start: number
+  end: number
+}
+
+export interface OxcError {
+  severity: Severity
+  message: string
+  labels: Array<ErrorLabel>
+  helpMessage: string | null
+  codeframe: string | null
+}
+
+export declare const enum Severity {
+  Error = 'Error',
+  Warning = 'Warning',
+  Advice = 'Advice'
+}
+export interface SourceMap {
+  file?: string
+  mappings: string
+  names: Array<string>
+  sourceRoot?: string
+  sources: Array<string>
+  sourcesContent?: Array<string>
+  version: number
+  x_google_ignoreList?: Array<number>
+}
+export interface ArrowFunctionsOptions {
+  /**
+   * 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 CompilerAssumptions {
+  ignoreFunctionLength?: boolean
+  noDocumentAll?: boolean
+  objectRestNoSymbols?: boolean
+  pureGetters?: boolean
+  /**
+   * When using public class fields, assume that they don't shadow any getter in the current class,
+   * in its subclasses or in its superclass. Thus, it's safe to assign them rather than using
+   * `Object.defineProperty`.
+   *
+   * For example:
+   *
+   * Input:
+   * ```js
+   * class Test {
+   *  field = 2;
+   *
+   *  static staticField = 3;
+   * }
+   * ```
+   *
+   * When `set_public_class_fields` is `true`, the output will be:
+   * ```js
+   * class Test {
+   *  constructor() {
+   *    this.field = 2;
+   *  }
+   * }
+   * Test.staticField = 3;
+   * ```
+   *
+   * Otherwise, the output will be:
+   * ```js
+   * import _defineProperty from "@oxc-project/runtime/helpers/defineProperty";
+   * class Test {
+   *   constructor() {
+   *     _defineProperty(this, "field", 2);
+   *   }
+   * }
+   * _defineProperty(Test, "staticField", 3);
+   * ```
+   *
+   * NOTE: For TypeScript, if you wanted behavior is equivalent to `useDefineForClassFields: false`, you should
+   * set both `set_public_class_fields` and [`crate::TypeScriptOptions::remove_class_fields_without_initializer`]
+   * to `true`.
+   */
+  setPublicClassFields?: boolean
+}
+
+export interface DecoratorOptions {
+  /**
+   * Enables experimental support for decorators, which is a version of decorators that predates the TC39 standardization process.
+   *
+   * Decorators are a language feature which hasn’t yet been fully ratified into the JavaScript specification.
+   * This means that the implementation version in TypeScript may differ from the implementation in JavaScript when it it decided by TC39.
+   *
+   * @see https://www.typescriptlang.org/tsconfig/#experimentalDecorators
+   * @default false
+   */
+  legacy?: boolean
+  /**
+   * Enables emitting decorator metadata.
+   *
+   * This option the same as [emitDecoratorMetadata](https://www.typescriptlang.org/tsconfig/#emitDecoratorMetadata)
+   * in TypeScript, and it only works when `legacy` is true.
+   *
+   * @see https://www.typescriptlang.org/tsconfig/#emitDecoratorMetadata
+   * @default false
+   */
+  emitDecoratorMetadata?: boolean
+}
+
+/** Configuration for dynamic gating via `use memo if(...)` directives. */
+export interface DynamicGatingConfig {
+  /** The module source to import from. */
+  source: string
+}
+
+export interface Es2015Options {
+  /** Transform arrow functions into function expressions. */
+  arrowFunction?: ArrowFunctionsOptions
+}
+
+/** Configuration for an external function import used for gating. */
+export interface ExternalFunctionConfig {
+  /** The module source to import from. */
+  source: string
+  /** The import specifier name. */
+  importSpecifierName: string
+}
+
+export declare const enum HelperMode {
+  /**
+   * Runtime mode (default): Helper functions are imported from a runtime package.
+   *
+   * Example:
+   *
+   * ```js
+   * import helperName from "@oxc-project/runtime/helpers/helperName";
+   * helperName(...arguments);
+   * ```
+   */
+  Runtime = 'Runtime',
+  /**
+   * External mode: Helper functions are accessed from a global `babelHelpers` object.
+   *
+   * Example:
+   *
+   * ```js
+   * babelHelpers.helperName(...arguments);
+   * ```
+   */
+  External = 'External'
+}
+
+export interface Helpers {
+  mode?: HelperMode
+}
+
+/**
+ * TypeScript Isolated Declarations for Standalone DTS Emit (async)
+ *
+ * Note: This function can be slower than `isolatedDeclarationSync` due to the overhead of spawning a thread.
+ */
+export declare function isolatedDeclaration(filename: string, sourceText: string, options?: IsolatedDeclarationsOptions | undefined | null): Promise<IsolatedDeclarationsResult>
+
+export interface IsolatedDeclarationsOptions {
+  /**
+   * Do not emit declarations for code that has an @internal annotation in its JSDoc comment.
+   * This is an internal compiler option; use at your own risk, because the compiler does not check that the result is valid.
+   *
+   * Default: `false`
+   *
+   * See <https://www.typescriptlang.org/tsconfig/#stripInternal>
+   */
+  stripInternal?: boolean
+  sourcemap?: boolean
+}
+
+export interface IsolatedDeclarationsResult {
+  code: string
+  map?: SourceMap
+  errors: Array<OxcError>
+}
+
+/** TypeScript Isolated Declarations for Standalone DTS Emit */
+export declare function isolatedDeclarationSync(filename: string, sourceText: string, options?: IsolatedDeclarationsOptions | undefined | null): IsolatedDeclarationsResult
+
+/**
+ * Configure how TSX and JSX are transformed.
+ *
+ * @see {@link https://oxc.rs/docs/guide/usage/transformer/jsx}
+ */
+export interface JsxOptions {
+  /**
+   * 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
+   */
+  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
+  /**
+   * Mark JSX elements and 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
+  /**
+   * Enable React Fast Refresh .
+   *
+   * Conforms to the implementation in {@link https://github.com/facebook/react/tree/v18.3.1/packages/react-refresh}
+   *
+   * @default false
+   */
+  refresh?: boolean | ReactRefreshOptions
+}
+
+/**
+ * Transform JavaScript code to a Vite Node runnable module.
+ *
+ * @param filename The name of the file being transformed.
+ * @param sourceText the source code itself
+ * @param options The options for the transformation. See {@link
+ * ModuleRunnerTransformOptions} for more information.
+ *
+ * @returns an object containing the transformed code, source maps, and any
+ * errors that occurred during parsing or transformation.
+ *
+ * Note: This function can be slower than `moduleRunnerTransformSync` due to the overhead of spawning a thread.
+ *
+ * @deprecated Only works for Vite.
+ */
+export declare function moduleRunnerTransform(filename: string, sourceText: string, options?: ModuleRunnerTransformOptions | undefined | null): Promise<ModuleRunnerTransformResult>
+
+export interface ModuleRunnerTransformOptions {
+  /**
+   * 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 ModuleRunnerTransformResult {
+  /**
+   * The transformed code.
+   *
+   * If parsing failed, this will be an empty string.
+   */
+  code: string
+  /**
+   * The source map for the transformed code.
+   *
+   * This will be set if {@link TransformOptions#sourcemap} is `true`.
+   */
+  map?: SourceMap
+  deps: Array<string>
+  dynamicDeps: Array<string>
+  /**
+   * 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<OxcError>
+}
+
+/** @deprecated Only works for Vite. */
+export declare function moduleRunnerTransformSync(filename: string, sourceText: string, options?: ModuleRunnerTransformOptions | undefined | null): ModuleRunnerTransformResult
+
+export interface PluginsOptions {
+  styledComponents?: StyledComponentsOptions
+  taggedTemplateEscape?: boolean
+  reactCompiler?: boolean | ReactCompilerOptions
+}
+
+/** Configure React Compiler behavior in the transformer pipeline. */
+export interface ReactCompilerOptions {
+  /**
+   * Enables the React Compiler plugin.
+   *
+   * @default true
+   */
+  enabled?: boolean
+  /**
+   * Strategy used to decide which functions to compile.
+   *
+   * - "infer" - infer components/hooks by naming convention
+   * - "annotation" - compile only opt-in directives
+   * - "all" - compile all functions
+   * - "syntax" - compile only syntax-marked functions
+   *
+   * @default "infer"
+   */
+  compilationMode?: string
+  /**
+   * Panic threshold for compilation failures.
+   *
+   * - "none"
+   * - "critical_errors"
+   * - "all_errors"
+   *
+   * @default "none"
+   */
+  panicThreshold?: string
+  /**
+   * Target React version.
+   *
+   * Controls which runtime module to import:
+   * - "react-17" / "react-18" -> "react-compiler-runtime" (npm package)
+   * - "react-19" (default)    -> "react/compiler-runtime" (from react namespace)
+   *
+   * @default "react-19"
+   */
+  target?: string
+  /**
+   * Whether to validate hooks usage (Rules of Hooks).
+   *
+   * @default true
+   */
+  validateHooksUsage?: boolean
+  /**
+   * Whether to validate ref access during render.
+   *
+   * @default true
+   */
+  validateRefAccessDuringRender?: boolean
+  /**
+   * Whether to validate no setState in render.
+   *
+   * @default true
+   */
+  validateNoSetStateInRender?: boolean
+  /**
+   * Output mode: "client", "ssr", "lint".
+   * When not set, defaults to "client" (or "lint" if `noEmit` is true).
+   */
+  outputMode?: string
+  /**
+   * When true, the compiler still runs validation but does not emit compiled output.
+   * Equivalent to setting `outputMode` to "lint".
+   */
+  noEmit?: boolean
+  /** Whether to ignore "use no forget" / "use no memo" directives. */
+  ignoreUseNoForget?: boolean
+  /** Custom opt-out directives (in addition to "use no memo" / "use no forget"). */
+  customOptOutDirectives?: Array<string>
+  /**
+   * Gating function config. When set, emits gated output that wraps
+   * compiled + original functions behind a feature flag.
+   */
+  gating?: ExternalFunctionConfig
+  /** Dynamic gating config. When set, enables `use memo if(...)` directives. */
+  dynamicGating?: DynamicGatingConfig
+  /**
+   * ESLint suppression rules to check for when scanning for suppression comments.
+   *
+   * @default `["react-hooks/rules-of-hooks", "react-hooks/exhaustive-deps"]`
+   */
+  eslintSuppressionRules?: Array<string>
+  /**
+   * Whether to bail on Flow suppression comments.
+   *
+   * @default true
+   */
+  flowSuppressions?: boolean
+  /**
+   * Array of filename regex patterns to filter which files get compiled.
+   * When set, only files whose path matches at least one pattern will be compiled.
+   */
+  sources?: Array<string>
+  /**
+   * Enable optional dependency tracking for optional chain expressions.
+   *
+   * @default true
+   */
+  enableOptionalDependencies?: boolean
+  /**
+   * Enable transitive freezing of function expression captures.
+   *
+   * @default true
+   */
+  enableTransitivelyFreezeFunctionExpressions?: boolean
+  /**
+   * Enable treating ref-like identifiers as refs for type inference.
+   *
+   * @default true
+   */
+  enableTreatRefLikeIdentifiersAsRefs?: boolean
+  /**
+   * Validate that useMemo/useCallback results are not void.
+   *
+   * @default true
+   */
+  validateNoVoidUseMemo?: boolean
+  /**
+   * Validate exhaustive memoization dependencies.
+   *
+   * @default true
+   */
+  validateExhaustiveMemoizationDependencies?: boolean
+}
+
+export interface ReactRefreshOptions {
+  /**
+   * Specify the identifier of the refresh registration variable.
+   *
+   * @default `$RefreshReg$`.
+   */
+  refreshReg?: string
+  /**
+   * Specify the identifier of the refresh signature variable.
+   *
+   * @default `$RefreshSig$`.
+   */
+  refreshSig?: string
+  emitFullSignatures?: boolean
+}
+
+/**
+ * Configure how styled-components are transformed.
+ *
+ * @see {@link https://oxc.rs/docs/guide/usage/transformer/plugins#styled-components}
+ */
+export interface StyledComponentsOptions {
+  /**
+   * Enhances the attached CSS class name on each component with richer output to help
+   * identify your components in the DOM without React DevTools.
+   *
+   * @default true
+   */
+  displayName?: boolean
+  /**
+   * Controls whether the `displayName` of a component will be prefixed with the filename
+   * to make the component name as unique as possible.
+   *
+   * @default true
+   */
+  fileName?: boolean
+  /**
+   * Adds a unique identifier to every styled component to avoid checksum mismatches
+   * due to different class generation on the client and server during server-side rendering.
+   *
+   * @default true
+   */
+  ssr?: boolean
+  /**
+   * Transpiles styled-components tagged template literals to a smaller representation
+   * than what Babel normally creates, helping to reduce bundle size.
+   *
+   * @default true
+   */
+  transpileTemplateLiterals?: boolean
+  /**
+   * Minifies CSS content by removing all whitespace and comments from your CSS,
+   * keeping valuable bytes out of your bundles.
+   *
+   * @default true
+   */
+  minify?: boolean
+  /**
+   * Enables transformation of JSX `css` prop when using styled-components.
+   *
+   * **Note: This feature is not yet implemented in oxc.**
+   *
+   * @default true
+   */
+  cssProp?: boolean
+  /**
+   * Enables "pure annotation" to aid dead code elimination by bundlers.
+   *
+   * @default false
+   */
+  pure?: boolean
+  /**
+   * Adds a namespace prefix to component identifiers to ensure class names are unique.
+   *
+   * Example: With `namespace: "my-app"`, generates `componentId: "my-app__sc-3rfj0a-1"`
+   */
+  namespace?: string
+  /**
+   * List of file names that are considered meaningless for component naming purposes.
+   *
+   * When the `fileName` option is enabled and a component is in a file with a name
+   * from this list, the directory name will be used instead of the file name for
+   * the component's display name.
+   *
+   * @default `["index"]`
+   */
+  meaninglessFileNames?: Array<string>
+  /**
+   * Import paths to be considered as styled-components imports at the top level.
+   *
+   * **Note: This feature is not yet implemented in oxc.**
+   */
+  topLevelImportPaths?: Array<string>
+}
+
+/**
+ * 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 transform(filename: string, sourceText: string, options?: TransformOptions | undefined | null): Promise<TransformResult>
+
+/**
+ * Options for transforming a JavaScript or TypeScript file.
+ *
+ * @see {@link transform}
+ */
+export interface TransformOptions {
+  /** Treat the source text as `js`, `jsx`, `ts`, `tsx`, or `dts`. */
+  lang?: 'js' | 'jsx' | 'ts' | 'tsx' | 'dts'
+  /** Treat the source text as `script` or `module` code. */
+  sourceType?: 'script' | 'module' | 'commonjs' | 'unambiguous' | undefined
+  /**
+   * The current working directory. Used to resolve relative paths in other
+   * options.
+   */
+  cwd?: string
+  /**
+   * Enable source map generation.
+   *
+   * When `true`, the `sourceMap` field of transform result objects will be populated.
+   *
+   * @default false
+   *
+   * @see {@link SourceMap}
+   */
+  sourcemap?: boolean
+  /** Set assumptions in order to produce smaller output. */
+  assumptions?: CompilerAssumptions
+  /**
+   * Configure how TypeScript is transformed.
+   * @see {@link https://oxc.rs/docs/guide/usage/transformer/typescript}
+   */
+  typescript?: TypeScriptOptions
+  /**
+   * Configure how TSX and JSX are transformed.
+   * @see {@link https://oxc.rs/docs/guide/usage/transformer/jsx}
+   */
+  jsx?: 'preserve' | JsxOptions
+  /**
+   * Sets the target environment for the generated JavaScript.
+   *
+   * The lowest target is `es2015`.
+   *
+   * Example:
+   *
+   * * `'es2015'`
+   * * `['es2020', 'chrome58', 'edge16', 'firefox57', 'node12', 'safari11']`
+   *
+   * @default `esnext` (No transformation)
+   *
+   * @see {@link https://oxc.rs/docs/guide/usage/transformer/lowering#target}
+   */
+  target?: string | Array<string>
+  /** Behaviour for runtime helpers. */
+  helpers?: Helpers
+  /**
+   * Define Plugin
+   * @see {@link https://oxc.rs/docs/guide/usage/transformer/global-variable-replacement#define}
+   */
+  define?: Record<string, string>
+  /**
+   * Inject Plugin
+   * @see {@link https://oxc.rs/docs/guide/usage/transformer/global-variable-replacement#inject}
+   */
+  inject?: Record<string, string | [string, string]>
+  /** Decorator plugin */
+  decorator?: DecoratorOptions
+  /**
+   * Third-party plugins to use.
+   * @see {@link https://oxc.rs/docs/guide/usage/transformer/plugins}
+   */
+  plugins?: PluginsOptions
+}
+
+export interface TransformResult {
+  /**
+   * The transformed code.
+   *
+   * If parsing failed, this will be an empty string.
+   */
+  code: string
+  /**
+   * The source map for the transformed code.
+   *
+   * This will be set if {@link TransformOptions#sourcemap} is `true`.
+   */
+  map?: 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 TypeScriptOptions#declaration}
+   * @see [declaration tsconfig option](https://www.typescriptlang.org/tsconfig/#declaration)
+   */
+  declaration?: string
+  /**
+   * Declaration source map. Only generated if both
+   * {@link TypeScriptOptions#declaration declaration} and
+   * {@link TransformOptions#sourcemap sourcemap} are set to `true`.
+   */
+  declarationMap?: SourceMap
+  /**
+   * Helpers used.
+   *
+   * @internal
+   *
+   * Example:
+   *
+   * ```text
+   * { "_objectSpread": "@oxc-project/runtime/helpers/objectSpread2" }
+   * ```
+   */
+  helpersUsed: Record<string, string>
+  /**
+   * 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<OxcError>
+}
+
+/**
+ * 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.
+ */
+export declare function transformSync(filename: string, sourceText: string, options?: TransformOptions | undefined | null): TransformResult
+
+export interface TypeScriptOptions {
+  jsxPragma?: string
+  jsxPragmaFrag?: string
+  onlyRemoveTypeImports?: boolean
+  allowNamespaces?: boolean
+  /**
+   * When enabled, type-only class fields are only removed if they are prefixed with the declare modifier:
+   *
+   * @deprecated
+   *
+   * Allowing `declare` fields is built-in support in Oxc without any option. If you want to remove class fields
+   * without initializer, you can use `remove_class_fields_without_initializer: true` instead.
+   */
+  allowDeclareFields?: boolean
+  /**
+   * When enabled, class fields without initializers are removed.
+   *
+   * For example:
+   * ```ts
+   * class Foo {
+   *    x: number;
+   *    y: number = 0;
+   * }
+   * ```
+   * // transform into
+   * ```js
+   * class Foo {
+   *    x: number;
+   * }
+   * ```
+   *
+   * The option is used to align with the behavior of TypeScript's `useDefineForClassFields: false` option.
+   * When you want to enable this, you also need to set [`crate::CompilerAssumptions::set_public_class_fields`]
+   * to `true`. The `set_public_class_fields: true` + `remove_class_fields_without_initializer: true` is
+   * equivalent to `useDefineForClassFields: false` in TypeScript.
+   *
+   * When `set_public_class_fields` is true and class-properties plugin is enabled, the above example transforms into:
+   *
+   * ```js
+   * class Foo {
+   *   constructor() {
+   *     this.y = 0;
+   *   }
+   * }
+   * ```
+   *
+   * Defaults to `false`.
+   */
+  removeClassFieldsWithoutInitializer?: 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?: IsolatedDeclarationsOptions
+  /**
+   * Rewrite or remove TypeScript import/export declaration extensions.
+   *
+   * - When set to `rewrite`, it will change `.ts`, `.mts`, `.cts` extensions to `.js`, `.mjs`, `.cjs` respectively.
+   * - When set to `remove`, it will remove `.ts`/`.mts`/`.cts`/`.tsx` extension entirely.
+   * - When set to `true`, it's equivalent to `rewrite`.
+   * - When set to `false` or omitted, no changes will be made to the extensions.
+   *
+   * @default false
+   */
+  rewriteImportExtensions?: 'rewrite' | 'remove' | boolean
+}