stencila-js

stencila/js : Stencila for Javascript

This package contains code that is shared amongst other Stencila Javascript-based packages: node (the package for Node.js) and web (the package for web browsers):

• a JsSession class for executing chunks of Javascript code
• data pack and unpack functions for transferring data over the wire and between languages

See this blog post for more on the approach and how it's used within Stencila Documents.

The JsSession.execute() method is really just a fancy eval with some extra functionality including:

• transpiles Javascript to ES2015(ES6)
• provides a global scope for persistence of session variables across calls
• unpacks input arguments into a local scope for each call
• returns errors by line number
• provides a require function for requiring NPM modules when in the browser

Install

npm install stencila-js --save

Use

const stencilaJs = require('stencila-js')

// Create a session
let session = new stencilaJs.JsSession()

// Evaluate an expression...
session.execute('6*7') // { errors: {}, output: { type: 'int', format: 'text', value: '42' } }

// Output is the value of the last line
session.execute('let x = 6\nx*7') // { errors: {}, output: { type: 'int', format: 'text', value: '42' } }

// If the last line is blank there is no output 
// (this is intended for code chunks that have side effects e.g. set up data)
session.execute('let x = 6\nx*7\n\n') // { errors: {}, output: null }

// You can specify input variables (that are local to that call) as a data pack
session.execute('Math.PI*radius', {radius: pack(21.4)}) // { errors: {}, output: { type: 'flt', format: 'text', value: '67.23008278682157' } }
session.execute('radius') // { errors: { '1': 'ReferenceError: radius is not defined' }, output: null }

// You can also assign global variables which are available in subsequent calls
session.execute('globals.foo = "bar"\n\n') // { errors: {}, output: null }
session.execute('foo') // { errors: {}, output: { type: 'str', format: 'text', value: 'bar' } }

More documentation is available at https://stencila.github.io/js.

Discuss

We love feedback. Create a new issue, add to existing issues or chat with members of the community.

Develop

Want to help out with development? Great, there's a lot to do! To get started, read our contributor code of conduct, then get in touch or checkout the platform-wide, cross-repository kanban board.

Most development tasks can be run directly from npm or via make wrapper recipes.

Task	npm	make
Install and setup dependencies	npm install	make setup
Check code for lint	npm run lint	make lint
Get test documents	npm run test-documents	make test-documents
Run tests	npm test	make test
Run tests in the browser	npm run test-browser	make test-browser
Run tests with coverage	npm run cover	make cover
Build documentation	npm run docs	make docs
Serve and watch docs for updates	npm run docs-serve	make docs-serve
Clean		make clean

Tests live in the tests folder and are written using the tape test harness. Some of the tests use test documents from the stencila/stencila repo which you can get using make test-documents.

And, in further breathtaking displays of naming logic, documentation lives in the docs folder and uses documentation.js. Docs are published using Github Pages, so to update them after making changes run make docs, commit the updated docs and do a git push.