|
| 1 | +# unofficial-observablehq-compiler |
| 2 | + |
| 3 | +An unoffical compiler _and_ interpreter for Observable notebooks (the glue between the Observable parser and runtime) |
| 4 | + |
| 5 | +This library has two parts: The Interpreter and the Compiler. The Interpreter will interpret "Observable syntax" into "javascript syntax" live in a javascript environment. For example: |
| 6 | + |
| 7 | +```javascript |
| 8 | +import { Intepreter } from "@alex.garcia/unofficial-observablehq-compiler"; |
| 9 | +import { Inspector, Runtime } from "@observablehq/runtime"; |
| 10 | + |
| 11 | +async function main() { |
| 12 | + const runtime = new Runtime(); |
| 13 | + const main = runtime.module(); |
| 14 | + const observer = Inspector.into(document.body); |
| 15 | + const interpret = new Intepreter({ module: main, observer }); |
| 16 | + |
| 17 | + await interpret.module(` |
| 18 | +import {text} from '@jashkenas/inputs' |
| 19 | +
|
| 20 | +viewof name = text({ |
| 21 | + title: "what's your name?", |
| 22 | + value: '' |
| 23 | +}) |
| 24 | +
|
| 25 | +md\`Hello **\${name}**, it's nice to meet you!\` |
| 26 | +
|
| 27 | +`); |
| 28 | +} |
| 29 | +main(); |
| 30 | +``` |
| 31 | + |
| 32 | +The Compiler will compile "Observable syntax" into javascript source code (as an ES module). |
| 33 | + |
| 34 | +For more live examples and functionality, take a look at the [announcement notebook](https://observablehq.com/d/74f872c4fde62e35) |
| 35 | +and this [test page](https://github.com/asg017/unofficial-observablehq-compiler/blob/master/test/test.html). |
| 36 | + |
| 37 | +## API Reference |
| 38 | + |
| 39 | +### new Interpreter(_params_) |
| 40 | + |
| 41 | +`Interpreter` is a class that encompasses all logic to interpret Observable js code. _params_ is an optional object with the following allowed configuration: |
| 42 | + |
| 43 | +`resolveImportPath(path, specifers)`: An async function that resolves to the `define` definition for a notebook. _path_ is the string provided in the import statement, and _specifiers_ is a array of string if the imported cell name specifiers in the statement (cells inside `import {...}`). _specifiers_ is useful when implementing tree-shaking. For example, `import {chart as CHART} from "@d3/bar-chart"` would supply `path="@d3/bar-chart"` and `specifiers=["chart"]`. Default imports from observablehq.com, eg `https://api.observablehq.com/@d3/bar-chart.js?v=3` |
| 44 | +`resolveFileAttachments`: A function that, given the name of a FileAttachment, returns the URL that the FileAttachment will be fetched from. Defaults to `name => name`. |
| 45 | +`defineImportMarkdown`: A boolean, whether to define a markdown description cell for imports in the notebook. Defaults true. |
| 46 | +`observeViewofValues`: A boolean, whether to pass in an _observer_ for the value of viewof cells. |
| 47 | +`module`: A default Observable runtime [module](https://github.com/observablehq/runtime#modules) that will be used in operations such as `.cell` and `.module`, if no other module is passed in. |
| 48 | +`observer`: A default Observable runtime [observer](https://github.com/observablehq/runtime#observer) that will be used in operations such as `.cell` and `.module`, if no other observer is passed in. |
| 49 | + |
| 50 | +Keep in mind, there is no sandboxing done, so it has the same security implications as `eval()`. |
| 51 | + |
| 52 | +interpret.**cell**(_source_ [, *module*, *observer*]) |
| 53 | + |
| 54 | +Parses the given string _source_ with the Observable parser [`.parseCell()`](https://github.com/observablehq/parser#parseCell) and interprets the source, passing it and the _observer_ along to the Observable _module_. Returns a Promise that resolves to an array of runtime [variables](https://github.com/observablehq/runtime#variables) that were defined when interpreting the source. More than one variable can be defined with a single cell, like with `viewof`, `mutable`, and `import` cells. _source_ can also be a pre-parsed [cell](https://github.com/observablehq/parser#cell) instead of source code. |
| 55 | + |
| 56 | +interpret.**module**(_source_ [, *module*, *observer*]) |
| 57 | + |
| 58 | +Parses the given string _source_ with the Observable parser [`.parseModule()`](https://github.com/observablehq/parser#parseModule) and interprets the source, passing it and the _observer_ along to the Observable _module_. Returns a Promise that resolves to an array of an array of runtime [variables](https://github.com/observablehq/runtime#variables) that were defined when interpreting the source. _source_ can also be a pre-parsed [program](https://github.com/observablehq/parser#program) instead of source code. |
| 59 | + |
| 60 | +interpret.**notebook**(_source_ [, *module*, *observer*]) |
| 61 | + |
| 62 | +TODO |
| 63 | + |
| 64 | +new **Compiler**(_params_) |
| 65 | + |
| 66 | +`Compiler` is a class that encompasses all logic to compile Observable javascript code into vanilla Javascript code, as an ES module. _params_ is an optional object with the following allowed configuration. |
| 67 | + |
| 68 | +`resolveImportPath(path, specifers)`: A function that returns a URL to where the notebook is defined. _path_ is the string provided in the import statement, and _specifiers_ is a array of string if the imported cell name specifiers in the statement (cells inside `import {...}`). _specifiers_ is useful when implementing tree-shaking. For example, `import {chart as CHART} from "@d3/bar-chart"` would supply `path="@d3/bar-chart"` and `specifiers=["chart"]`. Default imports from observablehq.com, eg `https://api.observablehq.com/@d3/bar-chart.js?v=3` |
| 69 | + |
| 70 | +`resolveFileAttachments`: A function that, given the name of a FileAttachment, returns the URL that the FileAttachment will be fetched from. Defaults to `name => name`. |
| 71 | + |
| 72 | +`UNSAFE_allowJavascriptFileAttachments` A boolean. When true, the `resolveFileAttachments` function will resolve to raw JavaScript when calculating the value of a FileAttachment reference. This is useful if you need to use `new URL` or `import.meta.url` when determining where a FileAttachment url should resolve too. This is unsafe because the Compiler will not escape any quotes when including it in the compiled output, so do use with extreme caution when dealing with user input. |
| 73 | + |
| 74 | +```javascript |
| 75 | + |
| 76 | +// This can be unsafe since FileAttachment names can include quotes. |
| 77 | +// Instead, map file attachments names to something deterministic and escape-safe, |
| 78 | +// like SHA hashes. |
| 79 | +const resolveFileAttachments = name => `new URL("./files/${name}", import.meta.url)` |
| 80 | + |
| 81 | +Compiled output when: |
| 82 | + |
| 83 | +// UNSAFE_allowJavascriptFileAttachments == false |
| 84 | +const fileAttachments = new Map([["a", "new URL(\"./files/a\", import.meta.url)"]]); |
| 85 | + |
| 86 | +// UNSAFE_allowJavascriptFileAttachments == true |
| 87 | +const fileAttachments = new Map([["a", new URL("./files/a", import.meta.url)]]); |
| 88 | + |
| 89 | + |
| 90 | +``` |
| 91 | +
|
| 92 | +`defineImportMarkdown` - A boolean, whether to define a markdown description cell for imports in the notebook. Defaults true. |
| 93 | +
|
| 94 | +`observeViewofValues` - A boolean, whether or not to pass in the `observer` function for viewof value cells. Defaults true. |
| 95 | +
|
| 96 | +`observeMutableValues` - A boolean, whether or not to pass in the `observer` function for mutable value cells. Defaults true. |
| 97 | +
|
| 98 | +compile.**module**(_source_) |
| 99 | +
|
| 100 | +TODO |
| 101 | +
|
| 102 | +compile.**notebook**(_source_) |
| 103 | +
|
| 104 | +TODO |
| 105 | +
|
| 106 | +## License |
| 107 | +
|
| 108 | +This library is MIT, but it relies and gets heavy inspiration from the following |
| 109 | +libraries licensed under ISC: |
| 110 | +
|
| 111 | +- [@observablehq/runtime](https://github.com/observablehq/runtime) |
| 112 | +- [@observablehq/stdlib](https://github.com/observablehq/stdlib) |
| 113 | +- [@observablehq/inspector](https://github.com/observablehq/inspector) |
| 114 | +- [@observablehq/parser](https://github.com/observablehq/parser) |
| 115 | +
|
| 116 | +## Contributing |
| 117 | +
|
| 118 | +Feel free to send in PR's as you wish! Take a look at the [issues](https://github.com/asg017/unofficial-observablehq-compiler/issues) |
| 119 | +to find something to work on. Just please follow the [Contributor Covenant](https://www.contributor-covenant.org/) |
| 120 | +in all your interactions :smile: |
0 commit comments