motoko
v3.9.6
Published
Compile and run Motoko smart contracts in Node.js or the browser.
Downloads
2,902
Maintainers
Readme
motoko
Compile and run Motoko smart contracts in Node.js or the browser.
Installation:
npm i --save motoko
Examples:
Basic usage
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
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)
mo.file('Main.mo')
.write('actor Main { public query func getNumber() : async Nat { 5 } }')
.run();
Load dependencies from GitHub
mo.clearPackages();
await mo.installPackages({
base: 'dfinity/motoko-base/master/src', // import "mo:base/...";
});
Generate parse trees
// 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
// Load just the `write()`, `loadPackages()`, `clearPackages()`, and `run()`, operations for a smaller file size:
import mo from 'motoko/interpreter';
API:
Top-level API
// 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)
// Fetch a package from GitHub or jsDelivr
await mo.fetchPackage(name, source);
await mo.fetchPackage('base', 'dfinity/motoko-base/master/src');
// Try to fetch and load packages from GitHub or jsDelivr
await mo.installPackages({ [packageName]: repositoryPath, ... })
// Load a value returned from `fetchPackage()`
mo.loadPackage(package)
// Use a virtual directory as a package
mo.usePackage(packageName, directory)
// Clear loaded packages
mo.clearPackages()
// Ensure that a package is correctly formatted
mo.validatePackage(package)
// Configure the compiler to resolve `import "mo:{alias}";` -> `import "canister:{id}";`
// `directory` should contain `*.did` files for canister dependencies
mo.setAliases(directory, { alias: id, ... })
// Set the public metadata (an array of strings) used by the compiler
mo.setPublicMetadata(strings)
// Set the maximum number of interpreter steps before cancelling a `run()` invocation
mo.setRunStepLimit(limit)
// 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 Candid string
mo.parseCandid(candidString)
// Return the parse tree for a Motoko string
mo.parseMotoko(motokoString)
// Return the typed parse tree for a Motoko file path (or array of paths)
mo.parseMotokoTyped(path)
mo.parseMotokoTyped(paths = [...])
// Find the 'Main.mo' file or an equivalent canister entry point
mo.resolveMain(directory = '')
// Find the 'Lib.mo' file or an equivalent library entry point
mo.resolveLib(directory = '')
// Get the compiler version ('latest' by default)
mo.version
// Access the underlying Motoko compiler
mo.compiler
File API
// 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()
// Parse the file (with types) as a Motoko program
file.parseMotokoTyped()