next/dist/build/swc/generated-native.d.ts

The React Framework

// Manual additions to make the generated types below work.

import type {
  CompilationEvent,
  TurbopackResult,
  Update,
  UpdateMessage,
} from './types'

export type TurboTasks = { readonly __tag: unique symbol }
export type ExternalEndpoint = { readonly __tag: unique symbol }
export type ServerHmrVersion = { readonly __tag: unique symbol }
export type NextTurboTasks = { readonly __tag: unique symbol }
export type RefCell<_T = unknown> = { readonly __tag: unique symbol }
export type FlushGuard = { readonly __tag: unique symbol }
export type NapiRouteHas = {
  type: string
  key?: string
  value?: string
  readonly __tag: unique symbol
}
export type RcStr = string

export function lightningCssTransform(args: object): Promise<unknown>
export function lightningCssTransformStyleAttribute(
  args: object
): Promise<unknown>
export function lightningcssFeatureNamesToMaskNapi(names: Array<string>): number

// GENERATED-TYPES-BELOW
// DO NOT MANUALLY EDIT THESE TYPES
// You can regenerate this file by running `pnpm swc-build-native` in the root of the repo.

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

export declare class ExternalObject<T> {
  readonly '': {
    readonly '': unique symbol
    [K: symbol]: T
  }
}
/**
 * An opaque handle to a running trace server instance.
 * Holds a reference to the shared store so that `query_trace_spans` can
 * query it without blocking Node.js with the WebSocket server loop.
 */
export declare class TraceServerHandle {}

export interface AppPageNapiRoute {
  /** The relative path from project_path to the route file */
  originalName?: RcStr
  htmlEndpoint?: ExternalObject<ExternalEndpoint>
  rscHmrEndpoint?: ExternalObject<ExternalEndpoint>
}

/**
 * Renders a code frame showing the location of an error in source code
 *
 * This is a Rust implementation that replaces Babel's code-frame for better:
 * - Performance on large files
 * - Handling of long lines
 * - Memory efficiency
 *
 * # Arguments
 * * `source` - The source code to render
 * * `location` - The location to highlight (line and column numbers are 1-indexed)
 * * `options` - Optional configuration
 *
 * # Returns
 * The formatted code frame string, or `undefined` if the location is out of
 * range (e.g., empty source or line number past end of file).
 */
export declare function codeFrameColumns(
  source: string,
  location: NapiCodeFrameLocation,
  options?: NapiCodeFrameOptions | undefined | null
): string | null

export declare function endpointClientChangedSubscribe(
  endpoint: { __napiType: 'Endpoint' },
  func: (err: Error, value: TurbopackResult<undefined>) => void
): { __napiType: 'RootTask' }

export declare function endpointServerChangedSubscribe(
  endpoint: { __napiType: 'Endpoint' },
  issues: boolean,
  func: (err: Error, value: TurbopackResult<undefined>) => void
): { __napiType: 'RootTask' }

export declare function endpointWriteToDisk(endpoint: {
  __napiType: 'Endpoint'
}): Promise<TurbopackResult<NapiWrittenEndpoint>>

export declare function expandNextJsTemplate(
  content: Buffer,
  templatePath: string,
  nextPackageDirPath: string,
  replacements: Record<string, string>,
  injections: Record<string, string>,
  imports: Record<string, string | null>
): string

export declare function getModuleNamedExports(
  resourcePath: string
): Promise<string[]>

export declare function getTargetTriple(): string

export interface HmrChunkNames {
  chunkNames: Array<RcStr>
}

/**
 * Initialize tracing subscriber to emit traces. This configures subscribers
 * for Trace Event Format <https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview>.
 */
export declare function initCustomTraceSubscriber(
  traceOutFilePath?: string | undefined | null
): ExternalObject<RefCell<FlushGuard | undefined | null>>

export declare function isReactCompilerRequired(
  filename: string,
  signal?: AbortSignal | undefined | null
): Promise<boolean>

/**
 * Convert an array of dash-case feature name strings to a lightningcss
 * `Features` bitmask (u32). Called from the webpack lightningcss-loader to
 * avoid duplicating the name-to-bit mapping in JavaScript.
 */
export declare function lightningcssFeatureNamesToMaskNapi(
  names: Array<string>
): number

export declare function lightningCssTransform(opts: object): unknown

export declare function lightningCssTransformStyleAttribute(
  opts: object
): unknown

export declare function lockfileTryAcquire(
  path: string,
  content?: string | undefined | null
): Promise<{ __napiType: 'Lockfile' } | null>

export declare function lockfileTryAcquireSync(
  path: string,
  content?: string | undefined | null
): { __napiType: 'Lockfile' } | null

export declare function lockfileUnlock(lockfile: {
  __napiType: 'Lockfile'
}): Promise<undefined>

export declare function lockfileUnlockSync(lockfile: {
  __napiType: 'Lockfile'
}): void

export declare function mdxCompile(
  value: string,
  option: Buffer,
  signal?: AbortSignal | undefined | null
): Promise<unknown>

export declare function mdxCompileSync(value: string, option: Buffer): string

/**
 * Turbopack's memory eviction strategy for the persistent cache, mirroring the
 * `experimental.turbopackMemoryEviction` config option.
 *
 * This is a napi-facing mirror of [`EvictionMode`] (the backend crate can't
 * depend on napi). Keep the variants in sync; the `From` impl below is
 * exhaustive, so adding a variant to one enum forces updating the other.
 */
export declare const enum MemoryEvictionMode {
  /** Never evict. */
  Off = 'off',
  /**
   * Evict after a snapshot only once enough memory has been allocated since
   * the last eviction to justify the cost of restoring evicted tasks.
   */
  Auto = 'auto',
  /**
   * After every snapshot, evict all evictable tasks from memory, reloading
   * them from disk on demand.
   */
  Full = 'full',
}

export declare function minify(
  input: Buffer,
  opts: Buffer,
  signal?: AbortSignal | undefined | null
): Promise<TransformOutput>

export declare function minifySync(input: Buffer, opts: Buffer): TransformOutput

export interface NapiAdditionalIssueSource {
  description: RcStr
  source: NapiIssueSource
  /** Pre-rendered code frame for this additional source location, if available. */
  codeFrame?: string
}

export interface NapiAdditionalRoot {
  key: RcStr
  path: RcStr
  ignoreIfMissing?: boolean
}

export interface NapiAssetPath {
  path: RcStr
  contentHash: RcStr
}

export declare const enum NapiCodeFrameColorMode {
  Error = 0,
  Warning = 1,
  Info = 2,
}

export interface NapiCodeFrameLocation {
  start: NapiLocation
  end?: NapiLocation
}

export interface NapiCodeFrameOptions {
  /** Number of lines to show above the error (default: 2) */
  linesAbove?: number
  /** Number of lines to show below the error (default: 3) */
  linesBelow?: number
  /** Maximum width of the output in columns (default: 240) */
  maxWidth?: number
  /** Whether to use ANSI colors (default: false) */
  color?: NapiCodeFrameColorMode | boolean
  /**
   * Whether to highlight code syntax (default: follows color)
   *
   * This might be useful if syntax highlighting is very expensive or known to be useless for
   * this file.  The current syntax rules are optimized for javascript but should work well with
   * other C-like languages.
   */
  highlightCode?: boolean
  /** Optional message to display with the code frame */
  message?: string
  /** Language hint for keyword highlighting: "javascript" (default) or "css" */
  language?: string
}

export interface NapiCompilationEvent {
  typeName: string
  severity: string
  message: string
  eventJson: string
  eventData: unknown
}

export interface NapiDebugBuildPaths {
  app: Array<RcStr>
  pages: Array<RcStr>
}

export interface NapiDefineEnv {
  client: Array<NapiOptionEnvVar>
  edge: Array<NapiOptionEnvVar>
  nodejs: Array<NapiOptionEnvVar>
}

export interface NapiDraftModeOptions {
  previewModeId: RcStr
  previewModeEncryptionKey: RcStr
  previewModeSigningKey: RcStr
}

export interface NapiEndpointConfig {}

export interface NapiEntrypoints {
  routes: Array<NapiRoute>
  middleware?: NapiMiddleware
  instrumentation?: NapiInstrumentation
  pagesDocumentEndpoint: ExternalObject<ExternalEndpoint>
  pagesAppEndpoint: ExternalObject<ExternalEndpoint>
  pagesErrorEndpoint: ExternalObject<ExternalEndpoint>
}

export interface NapiEnvVar {
  name: RcStr
  value: RcStr
}

export interface NapiInstrumentation {
  nodeJs: ExternalObject<ExternalEndpoint>
  edge: ExternalObject<ExternalEndpoint>
}

export interface NapiIssue {
  severity: string
  stage: string
  filePath: RcStr
  title: any
  description?: any
  detail?: any
  source?: NapiIssueSource
  additionalSources: Array<NapiAdditionalIssueSource>
  documentationLink: RcStr
  importTraces: any
  /**
   * Pre-rendered code frame for the issue's source location, if available.
   * Rendered in Rust to avoid transferring full source file content to JS.
   */
  codeFrame?: string
}

export interface NapiIssueSource {
  source: NapiSource
  range?: NapiIssueSourceRange
}

export interface NapiIssueSourceRange {
  start: NapiSourcePos
  end: NapiSourcePos
}

export interface NapiLocation {
  line: number
  column?: number
}

export interface NapiMiddleware {
  endpoint: ExternalObject<ExternalEndpoint>
  isProxy: boolean
}

/**
 * A version of [`NapiNextTurbopackCallbacks`] that can accepted as an argument to a napi function.
 *
 * This can be converted into a [`NapiNextTurbopackCallbacks`] with
 * [`NapiNextTurbopackCallbacks::from_js`].
 */
export interface NapiNextTurbopackCallbacksJsObject {
  /**
   * Called when we've encountered a bug in Turbopack and not in the user's code. Constructs and
   * throws a `TurbopackInternalError` type. Logs to anonymized telemetry.
   *
   * As a result of the use of `ErrorStrategy::CalleeHandled`, the first argument is an error if
   * there's a runtime conversion error. This should never happen, but if it does, the function
   * can throw it instead.
   */
  throwTurbopackInternalError: (
    conversionError: Error | null,
    opts: TurbopackInternalErrorOpts
  ) => never
  /** Called before deferred entries are processed in a production build. */
  onBeforeDeferredEntries?: () => Promise<void>
}

export interface NapiOptionEnvVar {
  name: RcStr
  value?: RcStr
}

/**
 * The subset of [`NapiProjectOptions`] that may change without restarting the process. Used by
 * [`project_update`].
 *
 * Refer to [`NapiProjectOptions`] for documentation on this struct's fields.
 */
export interface NapiPartialProjectOptions {
  nextConfig?: RcStr
  env?: Array<NapiEnvVar>
  defineEnv?: NapiDefineEnv
  dev?: boolean
  encryptionKey?: RcStr
  buildId?: RcStr
  previewProps?: NapiDraftModeOptions
  browserslistQuery?: RcStr
  writeRoutesHashesManifest?: boolean
  noMangling?: boolean
}

export interface NapiProject {
  project: { __napiType: 'Project' }
}

export interface NapiProjectOptions {
  /**
   * An absolute root path (Unix or Windows path) from which all files must be nested under.
   * Trying to access a file outside this root will fail, so think of this as a chroot.
   * E.g. `/home/user/projects/my-repo`.
   */
  rootPath: RcStr
  /**
   * A path which contains the app/pages directories, relative to [`Project::root_path`], always
   * Unix path. E.g. `apps/my-app`
   */
  projectPath: RcStr
  /**
   * A path where tracing output will be written to and/or cache is read/written.
   * Usually equal to the `distDir` in next.config.js.
   * E.g. `.next`
   */
  distDir: RcStr
  /** Filesystem watcher options. */
  watch: NapiWatchOptions
  /** The contents of next.config.js, serialized to JSON. */
  nextConfig: RcStr
  /** Additional filesystem roots from next.config.js. */
  additionalRoots: Array<NapiAdditionalRoot>
  /** A map of environment variables to use when compiling code. */
  env: Array<NapiEnvVar>
  /**
   * A map of environment variables which should get injected at compile
   * time.
   */
  defineEnv: NapiDefineEnv
  /** The mode in which Next.js is running. */
  dev: boolean
  /** The server actions encryption key. */
  encryptionKey: RcStr
  /** The build id. */
  buildId: RcStr
  /** Options for draft mode. */
  previewProps: NapiDraftModeOptions
  /** The browserslist query to use for targeting browsers. */
  browserslistQuery: RcStr
  /**
   * When the code is minified, this opts out of the default mangling of
   * local names for variables, functions etc., which can be useful for
   * debugging/profiling purposes.
   */
  noMangling: boolean
  /** Whether to write the route hashes manifest. */
  writeRoutesHashesManifest: boolean
  /** The version of Node.js that is available/currently running. */
  currentNodeJsVersion: RcStr
  /**
   * Debug build paths for selective builds.
   * When set, only routes matching these paths will be included in the build.
   */
  debugBuildPaths?: NapiDebugBuildPaths
  /** App-router page routes that should be built after non-deferred routes. */
  deferredEntries?: Array<RcStr>
  isPersistentCachingEnabled: boolean
  /** The version of Next.js that is running. */
  nextVersion: RcStr
  /** Whether server-side HMR is enabled (disabled with --no-server-fast-refresh). */
  serverHmr?: boolean
}

/** Keep in sync with [`next_core::next_config::Rewrite`] */
export interface NapiRewrite {
  source: string
  destination: string
  basePath?: boolean
  locale?: boolean
  has?: Array<NapiRouteHas>
  missing?: Array<NapiRouteHas>
}

/** Keep in sync with [`next_core::next_config::Rewrites`] */
export interface NapiRewrites {
  fallback: Array<NapiRewrite>
  afterFiles: Array<NapiRewrite>
  beforeFiles: Array<NapiRewrite>
}

export interface NapiRoute {
  /** The router path */
  pathname: RcStr
  /** The relative path from project_path to the route file */
  originalName?: RcStr
  /** The type of route, eg a Page or App */
  type: string
  pages?: Array<AppPageNapiRoute>
  hasActionManifest?: boolean
  endpoint?: ExternalObject<ExternalEndpoint>
  htmlEndpoint?: ExternalObject<ExternalEndpoint>
  rscHmrEndpoint?: ExternalObject<ExternalEndpoint>
  dataEndpoint?: ExternalObject<ExternalEndpoint>
}

export interface NapiServerHmrUpdate {
  kind: 'none' | 'partial' | 'restart'
  /** `unknown` forces the TypeScript boundary to narrow the payload. */
  instruction?: unknown
  version?: ExternalObject<ServerHmrVersion>
}

export interface NapiSource {
  ident: RcStr
  filePath: RcStr
}

export interface NapiSourceDiagnostic {
  severity: string
  message: string
  loc: NapiIssueSourceRange
}

export interface NapiSourcePos {
  line: number
  column: number
}

export interface NapiTurboEngineOptions {
  /** Track dependencies between tasks. If false, any change during build will error. */
  dependencyTracking?: boolean
  /** Whether the project is running in a CI environment. */
  isCi?: boolean
  /** Whether the project is running in a short session. */
  isShortSession?: boolean
  /** Whether to skip database compaction during shutdown. */
  skipCompaction?: boolean
  /** Turbopack memory eviction mode for the persistent cache. */
  turbopackMemoryEviction: MemoryEvictionMode
  /** Tuning for Turbopack's reference-counting GC. `None` disables the GC. */
  gc?: NapiTurbopackGcOptions
}

/**
 * Tuning for Turbopack's reference-counting GC, mirroring the
 * `experimental.turbopackGc` config option.
 */
export interface NapiTurbopackGcOptions {
  /** How long a GC pass runs before it will honour an interrupt, in milliseconds. */
  minProgressMs?: number
  /** How long a GC root may go un-anchored before it ages out, in milliseconds. */
  rootTtlMs?: number
}

export interface NapiUpdateInfo {
  duration: number
  tasks: number
}

export interface NapiUpdateMessage {
  updateType: string
  value?: NapiUpdateInfo
}

export interface NapiUsedFeature {
  featureName: RcStr
  /** How many times it was used, typically this means how often it was imported. */
  invocationCount: number
}

export interface NapiWatchOptions {
  /** Whether to watch the filesystem for file changes. */
  enable: boolean
  /**
   * Enable polling at a certain interval if the native file watching doesn't work (e.g.
   * docker).
   */
  pollIntervalMs?: number
}

export interface NapiWrittenEndpoint {
  type: string
  entryPath?: string
  serverHmrEntryPaths: Array<string>
  clientPaths: Array<string>
  serverPaths: Array<NapiAssetPath>
  config: NapiEndpointConfig
}

export interface NextBuildContext {
  /** The root directory of the workspace. */
  root?: string
  /** The project's directory. */
  dir?: string
  /**
   * next.config.js's distDir. Current there's some early stage setup
   * requires this Before construct a context to read next.config.js,
   * which we passes separately here.
   */
  distDir?: string
  /** The build ID. */
  buildId?: string
  /** The rewrites, as computed by Next.js. */
  rewrites?: NapiRewrites
  defineEnv: NapiDefineEnv
}

export declare function parse(
  src: string,
  options: Buffer,
  filename?: string | undefined | null,
  signal?: AbortSignal | undefined | null
): Promise<string>

export declare function projectActivateLazyChunk(
  project: { __napiType: 'Project' },
  chunkPath: RcStr
): Promise<boolean>

export declare function projectClientHmrChunkNamesSubscribe(
  project: { __napiType: 'Project' },
  func: (err: Error, value: TurbopackResult<HmrChunkNames>) => void
): { __napiType: 'RootTask' }

export declare function projectClientHmrEvents(
  project: { __napiType: 'Project' },
  chunkName: RcStr,
  func: (err: Error, value: TurbopackResult<Update>) => void
): { __napiType: 'RootTask' }

/** Subscribes to all compilation events that are not cached like timing and progress information. */
export declare function projectCompilationEventsSubscribe(
  project: { __napiType: 'Project' },
  func: (err: Error, value: CompilationEvent) => void,
  eventTypes?: Array<string> | undefined | null
): void

export declare function projectEntrypoints(project: {
  __napiType: 'Project'
}): Promise<TurbopackResult<Partial<NapiEntrypoints> | null>>

export declare function projectEntrypointsSubscribe(
  project: { __napiType: 'Project' },
  func: (
    err: Error,
    value: TurbopackResult<Partial<NapiEntrypoints> | null>
  ) => void
): { __napiType: 'RootTask' }

/**
 * Returns the build-feature-usage telemetry summary for this project — the set of
 * `(featureName, invocationCount)` pairs reported to the Next.js telemetry service.
 *
 * Intended to be called once at the end of a build, after `writeAllEntrypointsToDisk`. The
 * summary is computed by walking the whole-app module graph and is cached by turbo-tasks, so the
 * call is cheap when the graph is already materialized.
 */
export declare function projectFeatureUsage(project: {
  __napiType: 'Project'
}): Promise<Array<NapiUsedFeature>>

export declare function projectGetAllCompilationIssues(project: {
  __napiType: 'Project'
}): Promise<TurbopackResult<undefined>>

export declare function projectGetServerHmrUpdate(
  project: { __napiType: 'Project' },
  from: ExternalObject<ServerHmrVersion> | undefined | null,
  entryPaths: Array<RcStr>
): Promise<TurbopackResult<NapiServerHmrUpdate>>

export declare function projectGetSourceForAsset(
  project: { __napiType: 'Project' },
  filePath: RcStr
): Promise<string | null>

export declare function projectGetSourceMap(
  project: { __napiType: 'Project' },
  sourceMapUrl: RcStr
): Promise<string | null>

export declare function projectGetSourceMapSync(
  project: { __napiType: 'Project' },
  sourceMapUrl: RcStr
): string | null

/**
 * Invalidates the filesystem cache so that it will be deleted next time that a turbopack project
 * is created with filesystem cache enabled.
 */
export declare function projectInvalidateFileSystemCache(project: {
  __napiType: 'Project'
}): Promise<void>

export declare function projectNew(
  options: NapiProjectOptions,
  turboEngineOptions: NapiTurboEngineOptions,
  napiCallbacks: NapiNextTurbopackCallbacksJsObject
): Promise<TurbopackResult<{ project: { __napiType: 'Project' } }>>

/**
 * Runs exit handlers for the project registered using the [`ExitHandler`] API.
 *
 * This is called by `project_shutdown`, so if you're calling that API, you shouldn't call this
 * one.
 */
export declare function projectOnExit(project: {
  __napiType: 'Project'
}): Promise<void>

/**
 * Runs `project_on_exit`, and then waits for turbo_tasks to gracefully shut down.
 *
 * This is used in builds where it's important that we completely persist turbo-tasks to disk, but
 * it's skipped in the development server (`project_on_exit` is used instead with a short timeout),
 * where we prioritize fast exit and user responsiveness over all else.
 */
export declare function projectShutdown(project: {
  __napiType: 'Project'
}): Promise<void>

export declare function projectTraceSource(
  project: { __napiType: 'Project' },
  frame: StackFrame,
  currentDirectoryFileUrl: string
): Promise<StackFrame | null>

export declare function projectUpdate(
  project: { __napiType: 'Project' },
  options: NapiPartialProjectOptions
): Promise<void>

/**
 * Subscribes to lifecycle events of the compilation.
 *
 * Emits an [UpdateMessage::Start] event when any computation starts.
 * Emits an [UpdateMessage::End] event when there was no computation for the
 * specified time (`aggregation_ms`). The [UpdateMessage::End] event contains
 * information about the computations that happened since the
 * [UpdateMessage::Start] event. It contains the duration of the computation
 * (excluding the idle time that was spend waiting for `aggregation_ms`), and
 * the number of tasks that were executed.
 *
 * The signature of the `func` is `(update_message: UpdateMessage) => void`.
 */
export declare function projectUpdateInfoSubscribe(
  project: { __napiType: 'Project' },
  aggregationMs: number,
  func: (err: Error, value: UpdateMessage) => void
): void

export declare function projectWriteAllEntrypointsToDisk(
  project: { __napiType: 'Project' },
  appDirOnly: boolean
): Promise<TurbopackResult<Partial<NapiEntrypoints> | null>>

export declare function projectWriteAnalyzeData(
  project: { __napiType: 'Project' },
  appDirOnly: boolean
): Promise<TurbopackResult<undefined>>

/** Query spans from the trace store held by a `TraceServerHandle`. */
export declare function queryTraceSpans(
  handle: TraceServerHandle,
  options: TraceQueryOptions
): TraceQueryResult

export declare function rootTaskDispose(rootTask: {
  __napiType: 'RootTask'
}): void

export interface StackFrame {
  isServer: boolean
  isIgnored?: boolean
  originalFile?: RcStr
  file: RcStr
  /** 1-indexed, unlike source map tokens */
  line?: number
  /** 1-indexed, unlike source map tokens */
  column?: number
  methodName?: RcStr
}

/**
 * Starts the turbopack trace server on a background thread and returns a
 * handle immediately (non-blocking). The WebSocket server will be available
 * at `ws://127.0.0.1:<port>` (default port 5747).
 */
export declare function startTurbopackTraceServerHandle(
  path: string,
  port?: number | undefined | null
): TraceServerHandle

/**
 * Teardown currently running tracing subscriber to flush out remaining traces.
 * This should be called when parent node.js process exits, otherwise generated
 * trace may drop traces in the buffer.
 */
export declare function teardownTraceSubscriber(
  guardExternal: ExternalObject<RefCell<FlushGuard | undefined | null>>
): void

/** Aggregate view of a span's TurboMalloc memory samples. */
export interface TraceMemorySummary {
  /** Number of samples in the span's range, after downsampling. */
  count: number
  /** Live bytes at the first sample in the range. */
  start: number
  /** Live bytes at the last sample in the range. */
  end: number
  /** Smallest live-bytes reading in the range. */
  min: number
  /** Largest live-bytes reading in the range — the span's peak memory. */
  peak: number
  /** Highest memory-pressure byte in the range (0 = no pressure). */
  maxPressure: number
}

/** Options for `query_trace_spans`. */
export interface TraceQueryOptions {
  /**
   * Optional parent span ID (as returned by a previous query).
   * Omit or set to `null`/`undefined` for root-level spans.
   */
  parent?: string
  /** When `true` (default), aggregate child spans with the same name. */
  aggregated?: boolean
  /**
   * Sort mode: `"value"` for duration descending, `"name"` for alphabetical,
   * `"allocations"` for total allocated bytes descending,
   * `"persistent-allocations"` for `persistentAllocations` descending.
   * Omit for execution order (no sorting).
   */
  sort?: string
  /**
   * Optional substring search query applied to span name/category.
   *
   * Matches anywhere in the parent's subtree. Each result's `id` is the full
   * path from `parent` to the match, so it can be passed back as `parent`.
   *
   * Cost scales with subtree size, so a root search on a large trace walks
   * everything. Setting `parent`, or lowering `maxDepth`, bounds it.
   */
  search?: string
  /**
   * Maximum depth to descend below `parent` for `search` and `depth`.
   * Default `32`, which is also the cap.
   */
  maxDepth?: number
  /**
   * When greater than `1`, each returned span carries this many levels of
   * descendants inline in `children`. Default `1` (no nesting).
   */
  depth?: number
  /** 1-based page number. Default `1`. */
  page?: number
  /** Spans per page. Default `20`, capped at `500`. */
  pageSize?: number
}

/** The result of a `query_trace_spans` call. */
export interface TraceQueryResult {
  spans: Array<TraceSpanInfo>
  /** Current page (1-based). */
  page: number
  /** Total number of pages available. */
  totalPages: number
  /** Total number of matching spans across all pages. */
  totalCount: number
}

/** Information about a single span or aggregated span group. */
export interface TraceSpanInfo {
  /** Span ID. Pass this as `parent` in a follow-up call to get children. */
  id: string
  /** Display name of the span. */
  name: string
  /** Raw CPU total time in internal ticks (100 ticks = 1 µs). */
  cpuDuration: number
  /** Concurrency-corrected total time in internal ticks (100 ticks = 1 µs). */
  correctedDuration: number
  /** Start time relative to parent start, in internal ticks. */
  startRelativeToParent: number
  /** End time relative to parent start, in internal ticks. */
  endRelativeToParent: number
  /** Key-value attributes attached to the span. */
  args: Array<Array<string>>
  /** True if this entry represents an aggregated group of spans. */
  isAggregated: boolean
  /** Number of spans in this aggregated group (only set when `is_aggregated`). */
  count?: number
  /** Sum of CPU duration across all spans in the group. */
  totalCpuDuration?: number
  /** Average CPU duration across spans in the group. */
  avgCpuDuration?: number
  /** Sum of corrected duration across all spans in the group. */
  totalCorrectedDuration?: number
  /** Average corrected duration across spans in the group. */
  avgCorrectedDuration?: number
  /**
   * Raw span ID of the group's example span, whose `cpuDuration`,
   * `correctedDuration` and `memorySamples` are the ones reported here.
   * First in execution order — *not* the largest, so it can badly understate
   * a group's allocations. Use `heaviestSpanId` for those.
   */
  firstSpanId?: string
  /**
   * Raw span ID of the group member with the largest persistent
   * allocations.
   */
  heaviestSpanId?: string
  /**
   * Total bytes allocated by this span and all its children.
   *
   * For aggregated groups this is the group total, unlike `cpuDuration`,
   * `correctedDuration` and `memorySamples`, which describe the example span
   * only. Every allocation field below follows this field, not those.
   */
  allocations: number
  /**
   * Total bytes deallocated by this span and all its children.
   * Group total for aggregated spans.
   */
  deallocations: number
  /**
   * Sum over each span of `max(0, selfAllocations - selfDeallocations)`,
   * for this span and its children. Group total for aggregated spans.
   *
   * **A ranking signal, not retained memory.** TurboMalloc's per-span
   * counters never observe turbo-tasks cell and cache drops, so a
   * whole-trace total far above real peak RSS is expected, not a leak. Use
   * `memorySummary.peak` for absolute memory.
   *
   * The per-span floor at zero is also why this is not
   * `allocations - deallocations`.
   */
  persistentAllocations: number
  /**
   * Number of allocation operations by this span and all its children.
   * Group total for aggregated spans.
   */
  allocationCount: number
  /**
   * Bytes allocated by this span itself, excluding children.
   * Group total for aggregated spans.
   */
  selfAllocations: number
  /**
   * Bytes deallocated by this span itself, excluding children.
   * Group total for aggregated spans.
   *
   * Frees are charged to whichever span was on top of the thread's stack at
   * free time, which is often not the span that allocated. So small
   * `selfAllocations` with large `selfDeallocations` means this span is
   * where a child's arena gets dropped — that arena is bounded, not leaking.
   * The shape to suspect is a large `selfPersistentAllocations` with no such
   * counterpart above it.
   */
  selfDeallocations: number
  /**
   * `max(0, selfAllocations - selfDeallocations)` for this span alone.
   * Group total for aggregated spans.
   */
  selfPersistentAllocations: number
  /**
   * Number of allocation operations by this span itself, excluding children.
   * Group total for aggregated spans.
   */
  selfAllocationCount: number
  /**
   * TurboMalloc memory-usage samples recorded while this span
   * (or its example span, for aggregated groups) was live.
   *
   * **Process-wide, not per-span.** One global series is sliced by the
   * span's time range, so spans that overlap in time report identical values
   * no matter what each allocated. Rank concurrent work by the allocation
   * fields instead.
   *
   * Each entry is `[ts_offset_from_span_start_in_ticks, bytes, pressure]`,
   * where `pressure` is the memory-pressure byte (0 = no pressure, higher
   * = more pressure). `100 ticks = 1 µs`. The offset is always `>= 0` and
   * `<= span_duration`. Capped and downsampled by the store.
   */
  memorySamples: Array<Array<number>>
  /**
   * Summary of `memorySamples`; absent when the span's range holds none.
   * Unlike the allocation counters these are absolute live-heap readings, so
   * `peak` is the figure to quote for memory actually in use.
   */
  memorySummary?: TraceMemorySummary
  /** Descendants of this span, populated only when `depth > 1`. */
  children: Array<TraceSpanInfo>
}

export declare function transform(
  src: string | Buffer | undefined,
  isModule: boolean,
  options: Buffer,
  signal?: AbortSignal | undefined | null
): Promise<unknown>

export interface TransformOutput {
  code: string
  map?: string
  output?: string
  diagnostics: Array<string>
}

/**
 * The JS-facing result of a SWC transform.
 *
 * Optional fields are omitted from the resulting object when `None`.
 */
export interface TransformOutputResult {
  code: string
  map?: string
  eliminatedPackages?: string
  useCacheTelemetryTracker?: string
}

export declare function transformSync(
  src: string | Buffer | undefined,
  isModule: boolean,
  options: Buffer
): TransformOutputResult

export declare function turbopackCacheVersion(nextVersion: string): string

/**
 * Opens the Turbopack persistent cache database at the given path and performs a full compaction.
 *
 * The `path` should point to the `<distDir>/cache/turbopack` directory.
 */
export declare function turbopackDatabaseCompact(
  path: string,
  nextVersion: string
): Promise<void>

/** Arguments for `NapiNextTurbopackCallbacks::throw_turbopack_internal_error`. */
export interface TurbopackInternalErrorOpts {
  message: string
  anonymizedLocation?: string
}

export declare function warnForEdgeRuntime(
  source: string,
  isProduction: boolean
): Promise<NapiSourceDiagnostic[]>
export interface NapiTaskMessage {
  taskId: number
  data: Buffer
}

export interface NapiWorkerCreation {
  options: NapiWorkerOptions
}

export interface NapiWorkerOptions {
  filename: RcStr
  cwd: RcStr
}

export interface NapiWorkerTermination {
  options: NapiWorkerOptions
  workerId: number
}

export declare function recvTaskMessageInWorker(
  workerId: number
): Promise<NapiTaskMessage>

export declare function registerWorkerScheduler(
  creator: (arg: NapiWorkerCreation) => any,
  terminator: (arg: NapiWorkerTermination) => any
): void

export declare function sendTaskMessage(message: NapiTaskMessage): void

export declare function workerCreated(workerId: number): void