oxc/napi/transform-react/index.d.ts

/* auto-generated by NAPI-RS */
/* eslint-disable */

/**
 * Which binding artifact the generated loader actually loaded: `'native'` for
 * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
 * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
 * can point the loader at a WASI artifact this package does not build itself.
 */
export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'

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',
}

/** See <https://tc39.es/ecma426/#sec-source-map-format>. */
export interface JSONSourceMap {
  /** The version field, must be 3. */
  version: number
  /** An optional name of the generated code that this source map is associated with. */
  file?: string
  /** A string with the encoded mapping data. */
  mappings: string
  /**
   * An optional source root, useful for relocating source files on a server or removing repeated values in the "sources" entry.
   * This value is prepended to the individual entries in the "source" field.
   */
  sourceRoot?: string
  /** A list of original sources used by the "mappings" entry. */
  sources: Array<string>
  /**
   * An optional list of source content, useful when the "source" can't be hosted.
   * The contents are listed in the same order as the sources in line 5. "null" may be used if some original sources should be retrieved by name.
   */
  sourcesContent?: Array<string | undefined | null>
  /** A list of symbol names used by the "mappings" entry. */
  names: Array<string>
  /** An optional field containing the debugId for this sourcemap. */
  debugId?: string
  /**
   * Identifies third-party sources (such as framework code or bundler-generated code), allowing developers to avoid code that they don't want to see or step through, without having to configure this beforehand.
   * The `ignoreList` field refers to the `sources` array, and lists the indices of all the known third-party sources in that source map.
   * When parsing the source map, developer tools can use this to determine sections of the code that the browser loads and runs that could be automatically ignore-listed.
   * JSON input falls back to the deprecated `x_google_ignoreList` when `ignoreList` is missing or null.
   */
  ignoreList?: Array<number>
}

export interface SourceMap {
  file?: string
  mappings: string
  names: Array<string>
  sourceRoot?: string
  sources: Array<string>
  sourcesContent?: Array<string>
  version: number
  ignoreList?: Array<number>
}

/**
 * Configure how TSX and JSX are transformed.
 *
 * @see <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.
   *
   * @default false
   */
  refresh?: boolean | ReactRefreshOptions
}

/** Dynamic feature-gating import. */
export interface ReactCompilerDynamicGating {
  source: string
}

/**
 * Partial React Compiler environment configuration.
 *
 * Unset fields retain compiler defaults. Callback-valued providers and the
 * compiler's test-only panic switch are intentionally not exposed.
 */
export interface ReactCompilerEnvironmentOptions {
  customMacros?: Array<string>
  enableResetCacheOnSourceFileChanges?: boolean
  enablePreserveExistingMemoizationGuarantees?: boolean
  validatePreserveExistingMemoizationGuarantees?: boolean
  /**
   * Enable exhaustive manual memo dependency validation.
   *
   * @default false
   */
  validateExhaustiveMemoizationDependencies?: boolean
  validateExhaustiveEffectDependencies?: 'off' | 'all' | 'missing-only' | 'extra-only'
  enableOptionalDependencies?: boolean
  enableNameAnonymousFunctions?: boolean
  validateHooksUsage?: boolean
  validateRefAccessDuringRender?: boolean
  validateNoSetStateInRender?: boolean
  enableUseKeyedState?: boolean
  validateNoSetStateInEffects?: boolean
  validateNoDerivedComputationsInEffects?: boolean
  validateNoDerivedComputationsInEffectsExp?: boolean
  validateNoJsxInTryStatements?: boolean
  validateStaticComponents?: boolean
  validateNoCapitalizedCalls?: Array<string>
  validateBlocklistedImports?: Array<string>
  validateSourceLocations?: boolean
  validateNoImpureFunctionsInRender?: boolean
  validateNoFreezingKnownMutableFunctions?: boolean
  enableAssumeHooksFollowRulesOfReact?: boolean
  enableTransitivelyFreezeFunctionExpressions?: boolean
  enableFunctionOutlining?: boolean
  enableJsxOutlining?: boolean
  assertValidMutableRanges?: boolean
  enableCustomTypeDefinitionForReanimated?: boolean
  enableTreatRefLikeIdentifiersAsRefs?: boolean
  enableTreatSetIdentifiersAsStateSetters?: boolean
  /**
   * Validate that `useMemo` callbacks return a value.
   *
   * @default false
   */
  validateNoVoidUseMemo?: boolean
  enableAllowSetStateFromRefsInEffects?: boolean
  enableVerboseNoSetStateInEffect?: boolean
  enableForest?: boolean
}

/** Static feature-gating import. */
export interface ReactCompilerGating {
  source: string
  importSpecifierName: string
}

/** Meta-internal React runtime target. */
export interface ReactCompilerMetaTarget {
  kind: 'donotuse_meta_internal'
  runtimeModule?: string
}

/**
 * React Compiler options.
 *
 * Fields mirror `babel-plugin-react-compiler` and `react-compiler-napi`.
 */
export interface ReactCompilerOptions {
  /**
   * Which functions the compiler attempts to compile.
   *
   * @default 'infer'
   */
  compilationMode?: 'infer' | 'syntax' | 'annotation' | 'all'
  /**
   * When compiler diagnostics escalate into a hard failure.
   *
   * @default 'none'
   */
  panicThreshold?: 'none' | 'critical_errors' | 'all_errors'
  /**
   * Include recoverable React Compiler diagnostics in `errors`.
   *
   * Enable this to receive recoverable diagnostics (bail-outs, rule suppressions,
   * lint findings) while code is still produced. Fatal diagnostics are reported
   * regardless of this option.
   *
   * @default false
   */
  reportDiagnostics?: boolean
  /**
   * React runtime target. React 17 and 18 use `react-compiler-runtime`;
   * React 19 uses `react/compiler-runtime`.
   *
   * @default '19'
   */
  target?: '17' | '18' | '19' | ReactCompilerMetaTarget
  /** Emit both compiled and original functions behind an imported feature gate. */
  gating?: ReactCompilerGating
  /** Enable `"use memo if(...)"` directive-driven gating. */
  dynamicGating?: ReactCompilerDynamicGating
  /**
   * Analyze without applying compiler output. Pair with `reportDiagnostics`
   * to receive the findings.
   *
   * @deprecated Prefer `outputMode: "lint"`.
   * @default false
   */
  noEmit?: boolean
  /**
   * Select client, SSR, or lint output. Lint findings are recoverable
   * diagnostics, so pair lint output with `reportDiagnostics`.
   */
  outputMode?: 'client' | 'ssr' | 'lint'
  /**
   * ESLint rule names whose suppressions opt a function out of compilation.
   * Defaults to `react-hooks/exhaustive-deps` and `react-hooks/rules-of-hooks`;
   * pass an empty array to disable this behavior.
   */
  eslintSuppressionRules?: Array<string>
  /**
   * Treat Flow suppression comments as opt-outs.
   *
   * @default true
   */
  flowSuppressions?: boolean
  /**
   * Compile functions carrying `"use no memo"` or `"use no forget"`.
   *
   * @default false
   */
  ignoreUseNoForget?: boolean
  /** Additional directives that opt a function out of compilation. */
  customOptOutDirectives?: Array<string>
  /**
   * Only run the React Compiler when the filename contains one of these strings.
   *
   * By default, files whose filename contains `node_modules` are skipped.
   * Providing this option replaces that default filter.
   *
   * Function-valued `sources` filters from the Babel plugin are intentionally
   * unsupported across the native boundary.
   */
  sources?: Array<string>
  /** Feature flags and validation settings for compiler passes. */
  environment?: ReactCompilerEnvironmentOptions
}

/** React Fast Refresh options. */
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
  /**
   * Emit full hook signatures instead of compact hashes.
   *
   * @default false
   */
  emitFullSignatures?: boolean
}

/**
 * Compile a JavaScript or TypeScript React module asynchronously.
 *
 * This uses a worker-pool thread and can be slower than `transformSync` for a
 * single small module.
 */
export declare function transform(filename: string, sourceText: string, options?: TransformOptions | undefined | null): Promise<TransformResult>

/**
 * Options for compiling a JavaScript or TypeScript React module.
 *
 * `lang`, `sourceType`, and `sourcemap` configure the surrounding Oxc
 * parse/codegen pipeline. React Compiler and JSX transforms are configured
 * independently.
 */
export interface TransformOptions {
  /** Treat the source as `js`, `jsx`, `ts`, `tsx`, or `dts`. */
  lang?: 'js' | 'jsx' | 'ts' | 'tsx' | 'dts'
  /** Treat the source as script, module, CommonJS, or infer it from syntax. */
  sourceType?: 'script' | 'module' | 'commonjs' | 'unambiguous'
  /**
   * Generate a source map.
   *
   * @default false
   */
  sourcemap?: boolean
  /**
   * Configure how TSX and JSX are transformed, or preserve JSX syntax.
   *
   * @see <https://oxc.rs/docs/guide/usage/transformer/jsx>
   */
  jsx?: 'preserve' | JsxOptions
  /**
   * Configure React Compiler, or disable it with `false`.
   *
   * @default true
   */
  reactCompiler?: boolean | ReactCompilerOptions
}

/** Result returned by the React Compiler transform. */
export interface TransformResult {
  /** Whether the transform was aborted without emitting code. */
  fatal: boolean
  /**
   * Transformed JavaScript code.
   *
   * This is empty when parsing, semantic analysis, option validation, or the
   * React Compiler reports a fatal error.
   */
  code: string
  /** Source map, populated when `sourcemap` is `true`. */
  map?: SourceMap
  /**
   * Parse, semantic, downstream transform, and fatal React Compiler diagnostics.
   *
   * Recoverable React Compiler diagnostics are included when
   * `reactCompiler.reportDiagnostics` is `true`.
   */
  errors: Array<OxcError>
}

/**
 * Compile a JavaScript or TypeScript React module synchronously.
 *
 * The React Compiler runs first on the pristine AST. TypeScript syntax is
 * removed and configured JSX transforms run afterwards.
 */
export declare function transformSync(filename: string, sourceText: string, options?: TransformOptions | undefined | null): TransformResult