motoko 1.0.1 → 2.0.2

package/README.md

@@ -0,0 +1,191 @@
+# Motoko
+
+> ### Compile [Motoko](https://smartcontracts.org/) smart contracts in Node.js and the browser.
+
+---
+
+## Installation:
+
+```sh
+npm i --save motoko
+```
+
+## Examples:
+
+### Basic usage
+
+```js
+import mo from 'motoko';
+// -- OR --
+const mo = require('motoko');
+
+// Create a Motoko script in a virtual file system
+mo.write('Main.mo', `
+actor {
+    public query func hello() : async Text {
+        "Hello, JavaScript!"
+    };
+}
+`);
+
+// Generate the corresponding Candid interface
+console.log(mo.candid('Main.mo'));
+```
+
+### Evaluate a program
+
+```js
+mo.write('Main.mo', `
+actor Main {
+  public query func hello() : async Text {
+    "Hello, world!"
+  };
+};
+
+await Main.hello();
+`)
+mo.run('Main.mo');
+```
+
+### Evaluate a program (shorthand)
+
+```js
+mo.file('Main.mo')
+    .write('actor Main { public query func getNumber() : async Nat { 5 } }')
+    .run();
+```
+
+### Load dependencies from GitHub
+
+```js
+mo.clearPackages();
+await mo.loadPackages({
+    base: 'dfinity/motoko-base/master/src', // import "mo:base/...";
+});
+```
+
+### Generate parse trees
+
+```js
+// Generate a Motoko AST
+console.log(mo.parseMotoko('actor Main { public query func test() : async Nat { 123 } }'));
+
+// Generate a Candid AST
+console.log(mo.parseCandid('service : { test : () -> (nat) }'));
+```
+
+### Optimize for browsers
+
+```js
+// Load just the `write()`, `loadPackages()`, `clearPackages()`, and `run()`, operations for a smaller file size:
+import mo from 'motoko/interpreter';
+```
+
+## API:
+
+### Top-level API
+
+```js
+// Read the contents of a virtual file
+mo.read(path)
+
+// Write a string to a virtual file
+mo.write(path, string)
+
+// Rename a virtual file
+mo.rename(path, newPath)
+
+// Delete a virtual file
+mo.delete(path)
+
+// List the files in a virtual directory
+mo.list(path)
+
+// Try to load packages from GitHub and/or jsDelivr
+await mo.loadPackages({ packageName: repositoryPath, ... })
+
+// Use a virtual directory as a package
+mo.addPackage(packageName, directory)
+
+// Clear loaded packages
+mo.clearPackages()
+
+// Configure the compiler to resolve `import "canister:{alias}";` -> `import "canister:{id}";`
+mo.setAliases({ alias: id, ... })
+
+// Set the public metadata (an array of strings) used by the compiler
+mo.setMetadata(strings)
+
+// Generate errors and warnings for a Motoko program
+mo.check(path)
+
+// Run a Motoko program with optional virtual library paths
+mo.run(path)
+mo.run(path, [libraryPath, ...])
+
+// Generate the Candid interface for a Motoko program
+mo.candid(path)
+
+// Compile a Motoko program to WebAssembly
+mo.wasm(path, 'ic') // IC interface format (default)
+mo.wasm(path, 'wasi') // WASI interface format
+
+// Return the parse tree for a Motoko string
+mo.parseMotoko(motokoString)
+
+// Return the parse tree for a Candid string
+mo.parseCandid(candidString)
+
+// Get the version name
+mo.version
+
+// Access the underlying Motoko compiler
+mo.compiler
+```
+
+### File API
+
+```js
+// Create an object representing a virtual file
+const file = mo.file('Main.mo')
+
+// Get the file path
+file.path
+
+// Get another file object with the same path
+file.clone()
+
+// Read the file as a string
+file.read()
+
+// Write a string to the file
+file.write(string)
+
+// Rename the file
+file.rename(newPath)
+
+// Delete the file
+file.delete()
+
+// List children (if a directory)
+file.list()
+
+// Generate errors and warnings for a Motoko program
+file.check()
+
+// Run the file as a Motoko program
+file.run()
+
+// Generate the Candid interface for a Motoko program
+file.candid()
+
+// Compile the file to WebAssembly (see `mo.wasm()`)
+file.wasm('ic')
+file.wasm('wasi') // note: cannot contain actors
+
+// Parse the file as a Motoko program
+file.parseMotoko()
+
+// Parse the file as a Candid interface
+file.parseCandid()
+```

package/contrib/hljs.js

@@ -0,0 +1,121 @@
+// Highlight.js configuration
+
+exports.configure = (hljs) => {
+    var string = {
+        className: 'string',
+        variants: [
+            {
+                begin: /r(#*)"(.|\n)*?"\1(?!#)/,
+            },
+            {
+                begin: /b?'\\?(x\w{2}|u\w{4}|U\w{8}|.)'/,
+            },
+        ],
+    };
+    var number = {
+        className: 'number',
+        variants: [
+            {
+                begin: '[+-]?\\b0[xX]([A-Fa-f0-9_]+)',
+            },
+            {
+                begin: '[+-]?\\b(\\d[\\d_]*(\\.[0-9_]+)?([eE][+-]?[0-9_]+)?)',
+            },
+        ],
+        relevance: 0,
+    };
+    hljs.registerLanguage('motoko', function (hljs) {
+        return {
+            name: 'Motoko',
+            aliases: ['mo'],
+            keywords: {
+                $pattern: '[a-zA-Z_]\\w*',
+                keyword:
+                    'actor and await break case catch class' +
+                    ' continue debug do else for func if in import' +
+                    ' module not object or label let loop private' +
+                    ' public return shared try throw query switch' +
+                    ' type var while stable flexible system debug_show assert ignore from_candid to_candid',
+                literal: 'true false null',
+                built_in:
+                    'Any None Null Bool Int Int8 Int16 Int32 Int64' +
+                    ' Nat Nat8 Nat16 Nat32 Nat64 Word8 Word16 Word32 Word64' +
+                    ' Float Char Text Blob Error Principal' +
+                    ' async',
+            },
+            illegal: '</',
+            contains: [
+                hljs.C_LINE_COMMENT_MODE,
+                hljs.COMMENT('/\\*', '\\*/', {
+                    contains: ['self'],
+                }),
+                hljs.inherit(hljs.QUOTE_STRING_MODE, {
+                    begin: /b?"/,
+                    illegal: null,
+                }),
+                string,
+                number,
+                {
+                    className: 'symbol',
+                    begin: '#' + hljs.UNDERSCORE_IDENT_RE,
+                },
+                {
+                    className: 'function',
+                    beginKeywords: 'func',
+                    end: '(\\(|<|=|{)',
+                    excludeEnd: true,
+                    contains: [hljs.UNDERSCORE_TITLE_MODE],
+                },
+                {
+                    className: 'class',
+                    begin: '\\b(actor( class)?|module|object)\\b',
+                    keywords: 'actor class module object',
+                    end: '(\\(|<|{)',
+                    contains: [hljs.UNDERSCORE_TITLE_MODE],
+                    illegal: '[\\w\\d]',
+                },
+                {
+                    className: 'built_in',
+                    beginKeywords: 'import type',
+                    end: '(;|$|=)',
+                    excludeEnd: true,
+                    contains: [
+                        hljs.QUOTE_STRING_MODE,
+                        hljs.C_LINE_COMMENT_MODE,
+                        hljs.COMMENT('/\\*', '\\*/', {
+                            contains: ['self'],
+                        }),
+                    ],
+                },
+            ],
+        };
+    });
+    hljs.registerLanguage('candid', function (hljs) {
+        return {
+            name: 'Candid',
+            aliases: ['did'],
+            keywords: {
+                $pattern: '[a-zA-Z_]\\w*',
+                keyword: 'import service type',
+                built_in:
+                    'opt vec record variant func blob principal' +
+                    ' nat nat8 nat16 nat32 nat64 int int8 int16 int32 int64' +
+                    ' float32 float64 bool text null reserved empty' +
+                    ' oneway query',
+            },
+            illegal: '</',
+            contains: [
+                hljs.C_LINE_COMMENT_MODE,
+                hljs.COMMENT('/\\*', '\\*/', {
+                    contains: ['self'],
+                }),
+                hljs.inherit(hljs.QUOTE_STRING_MODE, {
+                    begin: /b?"/,
+                    illegal: null,
+                }),
+                string,
+                number,
+            ],
+        };
+    });
+};

package/contrib/monaco.js

@@ -0,0 +1,163 @@
+// Monaco editor configuration
+
+const MOTOKO_KEYWORDS = [
+    'actor',
+    'and',
+    'async',
+    'assert',
+    'await',
+    'break',
+    'case',
+    'catch',
+    'class',
+    'continue',
+    'debug',
+    'else',
+    'false',
+    'for',
+    'func',
+    'if',
+    'in',
+    'import',
+    'module',
+    'not',
+    'null',
+    'object',
+    'or',
+    'label',
+    'let',
+    'loop',
+    'private',
+    'public',
+    'return',
+    'shared',
+    'try',
+    'throw',
+    'debug_show',
+    'query',
+    'switch',
+    'true',
+    'type',
+    'var',
+    'while',
+    'stable',
+    'flexible',
+    'system',
+    'ignore',
+];
+
+exports.configure = (monaco) => {
+    monaco.languages.register({ id: 'motoko' });
+    monaco.languages.setLanguageConfiguration('motoko', {
+        comments: {
+            lineComment: '//',
+            blockComment: ['/*', '*/'],
+        },
+        brackets: [
+            ['{', '}'],
+            ['[', ']'],
+            ['(', ')'],
+        ],
+        autoClosingPairs: [
+            { open: '{', close: '}' },
+            { open: '[', close: ']' },
+            { open: '(', close: ')' },
+            { open: '"', close: '"' },
+            { open: '<', close: '>' },
+        ],
+    });
+    monaco.languages.setMonarchTokensProvider('motoko', {
+        defaultToken: '',
+        tokenPostfix: '.mo',
+        // prettier-ignore
+        keywords: MOTOKO_KEYWORDS,
+        accessmodifiers: ['public', 'private', 'shared'],
+        // prettier-ignore
+        typeKeywords: [
+            'Any', 'None', 'Null', 'Bool', 'Int', 'Int8', 'Int16', 'Int32', 'Int64', 'Nat',
+            'Nat8', 'Nat16', 'Nat32', 'Nat64', 'Float',
+            'Char', 'Text', 'Blob', 'Error', 'Principal',
+        ],
+        // prettier-ignore
+        operators: [
+            '=', '<', '>', ':', '<:', '?', '+', '-', '*', '/', '%', '**', '&', '|', '^', '<<', '>>',
+            '#', '==', '!=', '>=', '<=', ':=', '+=', '-=', '*=', '/=', '%=', '**=', '&=', '|=',
+            '^=', '<<=', '>>=', '#=', '->',
+        ],
+        symbols: /[=(){}[\].,:;@#_&\-<>`?!+*\\/]/,
+        // C# style strings
+        escapes:
+            /\\(?:[abfnrtv\\"']|x[0-9A-Fa-f]{1,4}|u[0-9A-Fa-f]{4}|U[0-9A-Fa-f]{8})/,
+        tokenizer: {
+            root: [
+                // identifiers and keywords
+                [
+                    /[a-zA-Z_$][\w$]*/,
+                    {
+                        cases: {
+                            '@typeKeywords': 'keyword.type',
+                            '@keywords': 'keyword',
+                            '@default': 'identifier',
+                        },
+                    },
+                ],
+                // whitespace
+                { include: '@whitespace' },
+
+                // delimiters and operators
+                [/[{}()[\]]/, '@brackets'],
+                [/[<>](?!@symbols)/, '@brackets'],
+                [
+                    /@symbols/,
+                    { cases: { '@operators': 'operator', '@default': '' } },
+                ],
+                // numbers
+                [/\d*\.\d+([eE][-+]?\d+)?/, 'number.float'],
+                [/0[xX][0-9a-fA-F_]+/, 'number.hex'],
+                [/[0-9_]+/, 'number'],
+
+                // delimiter: after number because of .\d floats
+                [/[;,.]/, 'delimiter'],
+
+                // strings
+                [/"([^"\\]|\\.)*$/, 'string.invalid'], // non-teminated string
+                [
+                    /"/,
+                    {
+                        token: 'string.quote',
+                        bracket: '@open',
+                        next: '@string',
+                    },
+                ],
+
+                // characters
+                [/'[^\\']'/, 'string'],
+                [/(')(@escapes)(')/, ['string', 'string.escape', 'string']],
+                [/'/, 'string.invalid'],
+            ],
+
+            comment: [
+                [/[^/*]+/, 'comment'],
+                [/\/\*/, 'comment', '@push'], // nested comment
+                ['\\*/', 'comment', '@pop'],
+                [/[/*]/, 'comment'],
+            ],
+
+            string: [
+                [/[^\\"]+/, 'string'],
+                [/@escapes/, 'string.escape'],
+                [/\\./, 'string.escape.invalid'],
+                [
+                    /"/,
+                    { token: 'string.quote', bracket: '@close', next: '@pop' },
+                ],
+            ],
+
+            whitespace: [
+                [/[ \t\r\n]+/, 'white'],
+                [/\/\*/, 'comment', '@comment'],
+                [/\/\/.*$/, 'comment'],
+            ],
+        },
+    });
+};

package/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+module.exports = require('./lib')(
+    require('./versions/latest/moc.min').Motoko,
+    'latest',
+);

package/interpreter.js

@@ -0,0 +1,6 @@
+'use strict';
+
+module.exports = require('./lib')(
+    require('./versions/latest/moc.min').Motoko,
+    'latest/interpreter',
+);

package/lib/__tests__/index.test.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const mo = require('../..');
+
+const actor = `
+actor Main {
+    public func test() : async Nat {
+        123
+    }
+}
+`;
+
+describe('virtual file system I/O', () => {
+    test('write -> read', () => {
+        const path = 'test__write_read__.txt';
+        const text = 'A\nB';
+        mo.write(path, text);
+        expect(mo.read(path)).toStrictEqual(text);
+    });
+});
+
+describe('check', () => {
+    test('works for a basic example', () => {
+        const path = 'test__check__.mo';
+        mo.write(path, actor);
+        expect(mo.check(path)).toStrictEqual([]);
+    });
+});
+
+describe('run', () => {
+    test('works for a basic example', () => {
+        const path = 'test__run__.mo';
+        mo.write(path, 'let x = 1 + 1; x');
+        expect(mo.run(path)).toStrictEqual({
+            result: 0,
+            stdout: '2 : Nat\n',
+            stderr: '',
+        });
+    });
+});

package/lib/__tests__/interpreter.test.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const mo = require('../../interpreter');
+
+describe('run', () => {
+    test('works for a basic example', () => {
+        const path = 'test__run__.mo';
+        mo.write(path, 'let x = 1 + 1; x');
+        expect(mo.run(path)).toStrictEqual({
+            result: 0,
+            stdout: '2 : Nat\n',
+            stderr: '',
+        });
+    });
+});

package/lib/file.js

@@ -0,0 +1,66 @@
+'use strict';
+
+function getValidPath(path) {
+    if (typeof path !== 'string') {
+        throw new Error('File path must be a string');
+    }
+    if (path.startsWith('/')) {
+        path = path.slice(1);
+    }
+    if (path.endsWith('/')) {
+        path = path.slice(0, -1);
+    }
+    return path;
+}
+
+exports.file = (mo, path) => {
+    path = getValidPath(path);
+    const result = {
+        get path() {
+            return path;
+        },
+        // file(subPath) {
+        //     subPath = getValidPath(subPath);
+        //     return exports.file(`${path}/${subPath}`);
+        // },
+        clone() {
+            return exports.file(path);
+        },
+        read() {
+            return mo.read(path);
+        },
+        write(content) {
+            return mo.write(path, content);
+        },
+        rename(newPath) {
+            let result = mo.rename(path, newPath);
+            path = newPath;
+            return result;
+        },
+        delete() {
+            return mo.delete(path);
+        },
+        list() {
+            return mo.list(path);
+        },
+        check() {
+            return mo.check(path, ...args);
+        },
+        run() {
+            return mo.run(path);
+        },
+        candid() {
+            return mo.candid(path);
+        },
+        wasm(mode) {
+            return mo.wasm(path, mode);
+        },
+        parseMotoko() {
+            return mo.parseMotoko(result.read());
+        },
+        parseCandid() {
+            return mo.parseCandid(result.read());
+        },
+    };
+    return result;
+};