@mui/internal-docs-infra/pipeline/loadIsomorphicCodeSource/loadIsomorphicCodeSource.d.mts

MUI Infra - internal documentation creation tools.

import type { LoadSource } from "../../CodeHighlighter/types.mjs";
import { type StoreAtMode } from "../loaderUtils/processRelativeImports.mjs";
/**
 * Imports record passed to {@link LoadIsomorphicCodeSourceOptions.resolveImports}.
 *
 * Mirrors the shape produced by `parseImportsAndComments` once names have been
 * flattened, so resolvers can look up each import by its source path.
 */
export type IsomorphicImports = Record<string, {
  url: string;
  names: string[];
  includeTypeDefs?: true;
  positions: Array<{
    start: number;
    end: number;
  }>;
}>;
export interface LoadIsomorphicCodeSourceOptions {
  /**
   * Async fetcher that returns the raw source text for a URL.
   *
   * In server contexts this typically wraps `fs/promises#readFile`, in client
   * contexts it can wrap `fetch`. Required.
   */
  fetchSource: (url: string) => Promise<string>;
  /**
   * Resolve relative JavaScript/TypeScript imports to absolute URLs that can
   * be passed back into a `loadSource` recursion. Returning a `Map` keyed by
   * the import URL lets the caller rewrite identifiers (e.g. `./foo` →
   * `https://.../foo.tsx`).
   *
   * When omitted, JavaScript modules are processed without a resolver: import
   * URLs are used as-is for `extraDependencies` and no rewriting happens.
   */
  resolveImports?: (imports: IsomorphicImports) => Promise<Map<string, string>>;
  /**
   * Cap on the number of recursive load passes. Forwarded to consumers; this
   * function itself only processes a single file.
   */
  maxDepth?: number;
  /** Cap on the total number of files surfaced via `extraFiles`. */
  maxFiles?: number;
  /** When false, skip dependency parsing and return only the raw source. */
  includeDependencies?: boolean;
  /**
   * Controls how imports are stored in `extraFiles`:
   * - 'canonical': Full resolved path (e.g., '../Component/index.js')
   * - 'import': Import path with file extension (e.g., '../Component.js')
   * - 'flat': Flattened to current directory with rewritten imports
   */
  storeAt?: StoreAtMode;
  /**
   * Prefixes for comments that should be stripped from the source output.
   * Comments starting with these prefixes will be removed from the returned
   * source. They can still be collected via `notableCommentsPrefix`.
   */
  removeCommentsWithPrefix?: string[];
  /**
   * Prefixes for notable comments that should be collected and included in
   * the result. Comments starting with these prefixes will be returned in the
   * `comments` field.
   */
  notableCommentsPrefix?: string[];
}
/**
 * Creates a `LoadSource` function that performs all the platform-independent
 * work shared between server-side and client-side source loaders: fetching
 * the file via the supplied `fetchSource`, parsing its imports and comments,
 * reshaping externals, and assembling `extraFiles` / `extraDependencies` for
 * recursive loading.
 *
 * Platform-specific concerns (`fs.readFile`, `fetch`, module resolution
 * against a real filesystem vs. a remote tree) are injected via the
 * `fetchSource` and `resolveImports` options.
 */
export declare function createLoadIsomorphicCodeSource(options: LoadIsomorphicCodeSourceOptions): LoadSource;