@locker/compiler

@locker/compiler

Locker secure 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 absolute filename of `input` used to generate source maps.
    filename: undefined,
    // The 'remap' option enables remapping Blue features into the Red Realm.
    remap: {
        // 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.
        dynamicImport: {
            // 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',
    // The source map option enables generating source maps.
    sourceMap: {
        // Specify how source maps should be generated.
        // Valid option values are `true`, `false`, or 'hidden'.
        //     - Use `true` to generate two inline source maps:
        //       One for sandboxed code and one for the module.
        //     - Use `false` to disable all source map generation.
        //     - Use 'hidden' to skip the source map for sandbox code and
        //       only generate the source map for the module.
        generate: false,
        // Specify whether mappings should be high-resolution. Hi-res mappings
        // map every single character, meaning devtools can locate the exact line
        // and column of break points. With lo-res mappings devtools can only
        // locate the line, but they're quicker to generate and less bulky.
        hires: false,
    },
    //
    // *** ADVANCED ***
    //
    // Specify the newline character(s) to use in compiled output, i.e. either
    // '\n' or '\r\n'. The default value 'auto' will automatically detect the
    // newline to use based on which occurs more in `input`.
    newline: 'auto',
    // Specify the quote character to use in compiled output, i.e. either
    // '"' or "'". The default value 'auto' will automatically detect the
    // quote character to use based on which occurs more in `input`.
    quoteChar: 'auto',
    // 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);