Janiczek / elm-sourcemap / SourceMap

Creation


type SourceMap

Source Map is a collection of mappings from a generated (often minified) file to the original source code (across multiple files if needed).

empty : SourceMap

Create an empty source map.

SourceMap.empty
    |> SourceMap.encode

{-->

{
  "version": 3,
  "sources": [],
  "names": [],
  "mappings": ""
}

-}

Building

withFile : String -> SourceMap -> SourceMap

Add an output filename to a source map.

SourceMap.empty
    |> SourceMap.withFile "hello.js"
    |> SourceMap.encode

{-->

{
  "version": 3,
  "sources": [],
  "names": [],
  "mappings": "",
  "file": "hello.js"
}

-}

withSourceRoot : String -> SourceMap -> SourceMap

Add a source root to a source map. This will be an automatic prefix to all the source paths mentioned in the mappings, and you can use paths relative to the root in all the added mappings.

SourceMap.empty
    |> SourceMap.withSourceRoot "https://example.com/public/js/"
    |> SourceMap.encode

{-->

{
  "version": 3,
  "sources": [],
  "names": [],
  "mappings": "",
  "sourceRoot": "https://example.com/public/js/"
}

-}


type alias Mapping =
{ generatedLine : Basics.Int
, generatedColumn : Basics.Int
, source : String
, originalLine : Basics.Int
, originalColumn : Basics.Int
, name : Maybe String 
}

Mapping points from the generated file to some original source code.

The source field should, when prefixed with the SourceMap's sourceRoot, give a resolvable URL: the browser will try to reach it. (The spec also allows for embedding the source code in the source map, but support for that is currently TODO here.)

The optional name field specifies what was the original name of the variable (it could be mangled or removed during compilation/minification).

Note: all the lines and columns are supposed to be 1-based (which is what elm/parser functions Parser.getRow, getCol and getPosition will give you). The library will automatically convert them to the 0-based format required by the Source Map spec.

addMapping : Mapping -> SourceMap -> SourceMap

Add a mapping to the source map.

SourceMap.empty
    |> SourceMap.addMapping (Mapping 10 35 "foo.js" 33 2 (Just "christopher"))

addMappings : List Mapping -> SourceMap -> SourceMap

Add multiple mappings to the source map at once.

SourceMap.empty
    |> SourceMap.addMappings
        [ Mapping 1 1 "a.js" 2 2 (Just "foo")
        , Mapping 3 3 "b.js" 4 4 (Just "bar")
        ]

Compiling

encode : SourceMap -> Json.Encode.Value

Compile the source map into a JSON value.

SourceMap.empty
    |> SourceMap.withFile "source-mapped.js"
    |> SourceMap.addMapping (Mapping 10 36 "foo.js" 33 3 (Just "christopher"))
    |> SourceMap.encode

{-->

{
  "version": 3,
  "sources": [
    "foo.js"
  ],
  "names": [
    "christopher"
  ],
  "mappings": ";;;;;;;;;mCAgCEA",
  "file": "source-mapped.js"
}

-}

toString : SourceMap -> String

Compile the source map into a stringified JSON.

SourceMap.empty
    |> SourceMap.withFile "source-mapped.js"
    |> SourceMap.addMapping (Mapping 10 36 "foo.js" 33 3 (Just "christopher"))
    |> SourceMap.toString

{-->

{
  "version": 3,
  "sources": [
    "foo.js"
  ],
  "names": [
    "christopher"
  ],
  "mappings": ";;;;;;;;;mCAgCEA",
  "file": "source-mapped.js"
}

-}