motoko 0.1.5 → 2.0.2

package/README.md

@@ -7,10 +7,12 @@
 ## Installation:
 
 ```sh
-npm install -S motoko
+npm i --save motoko
 ```
 
-## Basic Example:
+## Examples:
+
+### Basic usage
 
 ```js
 import mo from 'motoko';
@@ -18,11 +20,11 @@ import mo from 'motoko';
 const mo = require('motoko');
 
 // Create a Motoko script in a virtual file system
-mo.addFile('Main.mo', `
+mo.write('Main.mo', `
 actor {
-    public func hello() : async Text {
+    public query func hello() : async Text {
         "Hello, JavaScript!"
-    }
+    };
 }
 `);
 
@@ -30,18 +32,160 @@ actor {
 console.log(mo.candid('Main.mo'));
 ```
 
-## Advanced Usage:
+### 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
+### Load dependencies from GitHub
+
+```js
+mo.clearPackages();
 await mo.loadPackages({
-    base: 'dfinity/motoko-base/master/src',
+    base: 'dfinity/motoko-base/master/src', // import "mo:base/...";
 });
+```
+
+### Generate parse trees
 
+```js
 // Generate a Motoko AST
-console.log(mo.parse('actor Main { public func test() : async Nat { 123 } }'));
+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

@@ -1,122 +1,121 @@
 // Highlight.js configuration
 
-export const configure = (hljs) => {
+exports.configure = (hljs) => {
     var string = {
-      className: 'string',
-      variants: [
-        {
-          begin: /r(#*)"(.|\n)*?"\1(?!#)/,
-        },
-        {
-          begin: /b?'\\?(x\w{2}|u\w{4}|U\w{8}|.)'/,
-        },
-      ],
+        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,
+        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,
+        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.QUOTE_STRING_MODE,
-              hljs.C_LINE_COMMENT_MODE,
-              hljs.COMMENT('/\\*', '\\*/', {
-                contains: ['self'],
-              }),
+                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,
-        ],
-      };
+        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

@@ -1,6 +1,6 @@
 // Monaco editor configuration
 
-export const MOTOKO_KEYWORDS = [
+const MOTOKO_KEYWORDS = [
     'actor',
     'and',
     'async',
@@ -46,7 +46,7 @@ export const MOTOKO_KEYWORDS = [
     'ignore',
 ];
 
-export const configure = (monaco) => {
+exports.configure = (monaco) => {
     monaco.languages.register({ id: 'motoko' });
     monaco.languages.setLanguageConfiguration('motoko', {
         comments: {

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;
+};