@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 `source` used to generate source maps.
    filename: undefined,
    // 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 `source`.
    newline: 'auto',
    // The 'remap' option enables remapping Blue features into the Red Realm.
    remap: {
        // Enable remapping Blue dynamic `import()` into the Red Realm.
        dynamicImport: false,
    },
    // 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 `source`.
    quoteChar: 'auto',
    // 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 source map support as either `true`, `false`, or 'hidden'.
    //     - By default two inline source maps are generated:
    //       one for sandboxed code and one for the entire module.
    //     - Use `false` to disable all source map generation.
    //     - Use 'hidden' to skip generating the sandboxed code source map.
    sourceMap: true,
    //
    // *** ADVANCED ***
    // Sandbox package specific options you'll likely not need to touch.
    sandboxEvalContext: '$lockerEvalContext$',
    sandboxEvalHelpers: '$lockerEvalHelpers$',
    sandboxPackage: '@locker/sandbox',
    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: false,
    // The start position of the tokenizer in `input`.
    startPos: 0,
    // For details on the following options and more see
    // https://github.com/acornjs/acorn/tree/master/acorn#interface.
    allowAwaitOutsideFunction: true,
    allowHashBang: true,
    allowReserved: true,
    allowReturnOutsideFunction: true,
    ecmaVersion: 'latest',
    sourceType: 'module',
});

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

// Create an AST object representation of parsed `input` without an intermediate
// `parser` instance using `Parser.parse(input, options)`.
const 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);