source-map.d.ts

// Type definitions for source-map 0.7
// Project: https://github.com/mozilla/source-map
// Definitions by: Morten Houston Ludvigsen <https://github.com/MortenHoustonLudvigsen>,
//                 Ron Buckton <https://github.com/rbuckton>,
//                 John Vilk <https://github.com/jvilk>
// Definitions: https://github.com/mozilla/source-map
export type SourceMapUrl = string

export interface StartOfSourceMap {
  file?: string
  sourceRoot?: string
  skipValidation?: boolean
}

export interface RawSourceMap {
  version: number
  sources: string[]
  names: string[]
  sourceRoot?: string
  sourcesContent?: string[]
  mappings: string
  file: string
}

export interface RawIndexMap extends StartOfSourceMap {
  version: number
  sections: RawSection[]
}

export interface RawSection {
  offset: Position
  map: RawSourceMap
}

export interface Position {
  line: number
  column: number
}

export interface NullablePosition {
  line: number | null
  column: number | null
  lastColumn: number | null
}

export interface MappedPosition {
  source: string
  line: number
  column: number
  name?: string
}

export interface NullableMappedPosition {
  source: string | null
  line: number | null
  column: number | null
  name: string | null
}

export interface MappingItem {
  source: string
  generatedLine: number
  generatedColumn: number
  originalLine: number
  originalColumn: number
  name: string
}

export interface Mapping {
  generated: Position
  original: Position
  source: string
  name?: string
}

export interface CodeWithSourceMap {
  code: string
  map: SourceMapGenerator
}

export interface SourceMapConsumer {
  /**
   * Compute the last column for each generated mapping. The last column is
   * inclusive.
   */
  computeColumnSpans(): void

  /**
   * Returns the original source, line, and column information for the generated
   * source's line and column positions provided. The only argument is an object
   * with the following properties:
   *
   *   - line: The line number in the generated source.
   *   - column: The column number in the generated source.
   *   - bias: Either 'SourceMapConsumer.GREATEST_LOWER_BOUND' or
   *     'SourceMapConsumer.LEAST_UPPER_BOUND'. Specifies whether to return the
   *     closest element that is smaller than or greater than the one we are
   *     searching for, respectively, if the exact element cannot be found.
   *     Defaults to 'SourceMapConsumer.GREATEST_LOWER_BOUND'.
   *
   * and an object is returned with the following properties:
   *
   *   - source: The original source file, or null.
   *   - line: The line number in the original source, or null.
   *   - column: The column number in the original source, or null.
   *   - name: The original identifier, or null.
   */
  originalPositionFor(
    generatedPosition: Position & { bias?: number }
  ): NullableMappedPosition

  /**
   * Returns the generated line and column information for the original source,
   * line, and column positions provided. The only argument is an object with
   * the following properties:
   *
   *   - source: The filename of the original source.
   *   - line: The line number in the original source.
   *   - column: The column number in the original source.
   *   - bias: Either 'SourceMapConsumer.GREATEST_LOWER_BOUND' or
   *     'SourceMapConsumer.LEAST_UPPER_BOUND'. Specifies whether to return the
   *     closest element that is smaller than or greater than the one we are
   *     searching for, respectively, if the exact element cannot be found.
   *     Defaults to 'SourceMapConsumer.GREATEST_LOWER_BOUND'.
   *
   * and an object is returned with the following properties:
   *
   *   - line: The line number in the generated source, or null.
   *   - column: The column number in the generated source, or null.
   */
  generatedPositionFor(
    originalPosition: MappedPosition & { bias?: number }
  ): NullablePosition

  /**
   * Returns all generated line and column information for the original source,
   * line, and column provided. If no column is provided, returns all mappings
   * corresponding to a either the line we are searching for or the next
   * closest line that has any mappings. Otherwise, returns all mappings
   * corresponding to the given line and either the column we are searching for
   * or the next closest column that has any offsets.
   *
   * The only argument is an object with the following properties:
   *
   *   - source: The filename of the original source.
   *   - line: The line number in the original source.
   *   - column: Optional. the column number in the original source.
   *
   * and an array of objects is returned, each with the following properties:
   *
   *   - line: The line number in the generated source, or null.
   *   - column: The column number in the generated source, or null.
   */
  allGeneratedPositionsFor(originalPosition: MappedPosition): NullablePosition[]

  /**
   * Return true if we have the source content for every source in the source
   * map, false otherwise.
   */
  hasContentsOfAllSources(): boolean

  /**
   * Returns the original source content. The only argument is the url of the
   * original source file. Returns null if no original source content is
   * available.
   */
  sourceContentFor(source: string, returnNullOnMissing?: boolean): string | null

  /**
   * Iterate over each mapping between an original source/line/column and a
   * generated line/column in this source map.
   *
   * @param callback
   *        The function that is called with each mapping.
   * @param context
   *        Optional. If specified, this object will be the value of `this` every
   *        time that `aCallback` is called.
   * @param order
   *        Either `SourceMapConsumer.GENERATED_ORDER` or
   *        `SourceMapConsumer.ORIGINAL_ORDER`. Specifies whether you want to
   *        iterate over the mappings sorted by the generated file's line/column
   *        order or the original's source/line/column order, respectively. Defaults to
   *        `SourceMapConsumer.GENERATED_ORDER`.
   */
  eachMapping(
    callback: (mapping: MappingItem) => void,
    context?: any,
    order?: number
  ): void
  /**
   * Free this source map consumer's associated wasm data that is manually-managed.
   * Alternatively, you can use SourceMapConsumer.with to avoid needing to remember to call destroy.
   */
  destroy(): void
}

export interface SourceMapConsumerConstructor {
  prototype: SourceMapConsumer

  GENERATED_ORDER: number
  ORIGINAL_ORDER: number
  GREATEST_LOWER_BOUND: number
  LEAST_UPPER_BOUND: number

  new (
    rawSourceMap: RawSourceMap,
    sourceMapUrl?: SourceMapUrl
  ): Promise<BasicSourceMapConsumer>
  new (
    rawSourceMap: RawIndexMap,
    sourceMapUrl?: SourceMapUrl
  ): Promise<IndexedSourceMapConsumer>
  new (
    rawSourceMap: RawSourceMap | RawIndexMap | string,
    sourceMapUrl?: SourceMapUrl
  ): Promise<BasicSourceMapConsumer | IndexedSourceMapConsumer>

  /**
   * Create a BasicSourceMapConsumer from a SourceMapGenerator.
   *
   * @param sourceMap
   *        The source map that will be consumed.
   */
  fromSourceMap(
    sourceMap: SourceMapGenerator,
    sourceMapUrl?: SourceMapUrl
  ): Promise<BasicSourceMapConsumer>

  /**
   * Construct a new `SourceMapConsumer` from `rawSourceMap` and `sourceMapUrl`
   * (see the `SourceMapConsumer` constructor for details. Then, invoke the `async
   * function f(SourceMapConsumer) -> T` with the newly constructed consumer, wait
   * for `f` to complete, call `destroy` on the consumer, and return `f`'s return
   * value.
   *
   * You must not use the consumer after `f` completes!
   *
   * By using `with`, you do not have to remember to manually call `destroy` on
   * the consumer, since it will be called automatically once `f` completes.
   *
   * ```js
   * const xSquared = await SourceMapConsumer.with(
   *   myRawSourceMap,
   *   null,
   *   async function (consumer) {
   *     // Use `consumer` inside here and don't worry about remembering
   *     // to call `destroy`.
   *
   *     const x = await whatever(consumer);
   *     return x * x;
   *   }
   * );
   *
   * // You may not use that `consumer` anymore out here; it has
   * // been destroyed. But you can use `xSquared`.
   * console.log(xSquared);
   * ```
   */
  with<T>(
    rawSourceMap: RawSourceMap | RawIndexMap | string,
    sourceMapUrl: SourceMapUrl | null | undefined,
    callback: (
      consumer: BasicSourceMapConsumer | IndexedSourceMapConsumer
    ) => Promise<T> | T
  ): Promise<T>
}

export const SourceMapConsumer: SourceMapConsumerConstructor

export interface BasicSourceMapConsumer extends SourceMapConsumer {
  file: string
  sourceRoot: string
  sources: string[]
  sourcesContent: string[]
}

export interface BasicSourceMapConsumerConstructor {
  prototype: BasicSourceMapConsumer

  new (rawSourceMap: RawSourceMap | string): Promise<BasicSourceMapConsumer>

  /**
   * Create a BasicSourceMapConsumer from a SourceMapGenerator.
   *
   * @param sourceMap
   *        The source map that will be consumed.
   */
  fromSourceMap(sourceMap: SourceMapGenerator): Promise<BasicSourceMapConsumer>
}

export const BasicSourceMapConsumer: BasicSourceMapConsumerConstructor

export interface IndexedSourceMapConsumer extends SourceMapConsumer {
  sources: string[]
}

export interface IndexedSourceMapConsumerConstructor {
  prototype: IndexedSourceMapConsumer

  new (rawSourceMap: RawIndexMap | string): Promise<IndexedSourceMapConsumer>
}

export const IndexedSourceMapConsumer: IndexedSourceMapConsumerConstructor

export class SourceMapGenerator {
  constructor(startOfSourceMap?: StartOfSourceMap)

  /**
   * Creates a new SourceMapGenerator based on a SourceMapConsumer
   *
   * @param sourceMapConsumer The SourceMap.
   */
  static fromSourceMap(sourceMapConsumer: SourceMapConsumer): SourceMapGenerator

  /**
   * Add a single mapping from original source line and column to the generated
   * source's line and column for this source map being created. The mapping
   * object should have the following properties:
   *
   *   - generated: An object with the generated line and column positions.
   *   - original: An object with the original line and column positions.
   *   - source: The original source file (relative to the sourceRoot).
   *   - name: An optional original token name for this mapping.
   */
  addMapping(mapping: Mapping): void

  /**
   * Set the source content for a source file.
   */
  setSourceContent(sourceFile: string, sourceContent: string): void

  /**
   * Applies the mappings of a sub-source-map for a specific source file to the
   * source map being generated. Each mapping to the supplied source file is
   * rewritten using the supplied source map. Note: The resolution for the
   * resulting mappings is the minimium of this map and the supplied map.
   *
   * @param sourceMapConsumer The source map to be applied.
   * @param sourceFile Optional. The filename of the source file.
   *        If omitted, SourceMapConsumer's file property will be used.
   * @param sourceMapPath Optional. The dirname of the path to the source map
   *        to be applied. If relative, it is relative to the SourceMapConsumer.
   *        This parameter is needed when the two source maps aren't in the same
   *        directory, and the source map to be applied contains relative source
   *        paths. If so, those relative source paths need to be rewritten
   *        relative to the SourceMapGenerator.
   */
  applySourceMap(
    sourceMapConsumer: SourceMapConsumer,
    sourceFile?: string,
    sourceMapPath?: string
  ): void

  toString(): string

  toJSON(): RawSourceMap
}

export class SourceNode {
  children: SourceNode[]
  sourceContents: any
  line: number
  column: number
  source: string
  name: string

  constructor()
  constructor(
    line: number | null,
    column: number | null,
    source: string | null,
    chunks?: Array<string | SourceNode> | SourceNode | string,
    name?: string
  )

  static fromStringWithSourceMap(
    code: string,
    sourceMapConsumer: SourceMapConsumer,
    relativePath?: string
  ): SourceNode

  add(chunk: Array<string | SourceNode> | SourceNode | string): SourceNode

  prepend(chunk: Array<string | SourceNode> | SourceNode | string): SourceNode

  setSourceContent(sourceFile: string, sourceContent: string): void

  walk(fn: (chunk: string, mapping: MappedPosition) => void): void

  walkSourceContents(fn: (file: string, content: string) => void): void

  join(sep: string): SourceNode

  replaceRight(pattern: string, replacement: string): SourceNode

  toString(): string

  toStringWithSourceMap(startOfSourceMap?: StartOfSourceMap): CodeWithSourceMap
}