@locker/compiler

Lightning Web Security module compiler

Installation

$ yarn add @locker/compiler

Usage

The Compiler object:

const { Compiler } = require('@locker/compiler');

// Compile code using `Compiler.compile(input, options)`. The function returns
// an object of `{ code, map, meta }`.
Compiler.compile(input, {
    // The name of the component to compile.
    componentName: undefined,
    // The absolute filename of `input` required for source maps.
    filename: undefined,
    // Specify remapping blue dynamic imports into the red Realm.
    // Valid option values are `true`, `false`, or an options object.
    //     - Use `true` as shorthand for an options object of
    //       `{ strictSpecifier: true }`.
    //     - Use `false` disable remapping dynamic import.
    remapDynamicImport: {
        // Specify whether dynamic imports should be restricted to string
        // literal source specifiers, e.g.
        //     import('./a.js') // allowed
        //     import(a) // not allowed
        //     import(`${a}`) // not allowed
        strictSpecifier: true,
    },
    // The key of the sandbox to evaluate source text in.
    // For more details see https://www.npmjs.com/package/@locker/sandbox#usage.
    sandboxKey: 'sandbox',
    // Specify whether to generate inline source maps.
    sourceMap: false,
    //
    // *** ADVANCED ***
    //
    // Specify a map to use as the memoized compilation cache.
    // See https://en.wikipedia.org/wiki/Memoization for more context.
    compilationCache: new Map(),
    // Specify the name of the sandbox evaluation context identifier.
    sandboxEvalContext: '$lockerEvalContext$',
    // Specify the name of the sandbox evaluation helpers identifier.
    sandboxEvalHelpers: '$lockerEvalHelpers$',
    // Specify the name of the sandbox package identifier.
    sandboxPackage: '@locker/sandbox',
    // Specify the name of the sandbox specifier.
    sandboxSpecifier: 'evaluateInSandbox',
});

// Create a new normalized fully populated `Compiler.compile()` options object
// using `Compiler.createOptions(providedOptions)`.
Compiler.createOptions({
    sandboxKey: 'anotherKey',
});

// Inspect the default options of `Compiler.compile()` using `Compiler.defaultOptions`.
console.log(Compiler.defaultOptions);

The Parser object:

const { Parser } = require('@locker/compiler');

// Create a `Parser` instance using `Parse.create(input, options)`.
const parser = Parse.create(input, {
    // Produce an abstract syntax tree (AST) for use with the custom parser API
    // of Prettier. For more details see https://prettier.io/docs/en/api.html#custom-parser-api.
    prettier: true,
});

// The `parser.parse()` method returns the generated AST object.
let ast = parser.parse();

// Create an AST object representation of parsed `input` without an intermediate
// `parser` instance using `Parser.parse(input, options)`.
ast = Parser.parse(input, options);

// Create a new normalized fully populated `Parser.parse()` options object
// using `Parser.createOptions(providedOptions)`.
Parser.createOptions({
    prettier: true,
});

// Inspect the default options of `Parser.create()` using `Parser.defaultOptions`.
console.log(Parser.defaultOptions);