Gathering detailed insights and metrics for @alex.garcia/unofficial-observablehq-compiler
Gathering detailed insights and metrics for @alex.garcia/unofficial-observablehq-compiler
An unofficial compiler for Observable notebook syntax
Installations
npm install @alex.garcia/unofficial-observablehq-compilerDeveloper Guide
BETA
Typescript
No
Module System
CommonJS
Releases
Unable to fetch releases
Languages
2
JavaScript
HTML
JavaScript (67.04%)
HTML (32.96%)
Developer
Download Statistics
Total Downloads
9,412
Last Day
3
Last Week
10
Last Month
105
Last Year
1,351
GitHub Statistics
120 Stars
63 Commits
21 Forks
14 Watchers
9 Branches
2 Contributors
Updated on Jun 06, 2025
Maintainers
1
Package Meta Information
Latest Version
0.6.0-alpha.9
Package Id
@alex.garcia/unofficial-observablehq-compiler@0.6.0-alpha.9
Unpacked Size
474.51 kB
Size
116.40 kB
File Count
6
Total Downloads
Cumulative downloads
Total Downloads
9,412
Last Day
200%
3
Compared to previous day
Last Week
-44.4%
10
Compared to previous week
Last Month
-69.9%
105
Compared to previous month
Last Year
-11.8%
1,351
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
unofficial-observablehq-compiler
An unoffical compiler and interpreter for Observable notebooks (the glue between the Observable parser and runtime)
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:
1import { Intepreter } from "@alex.garcia/unofficial-observablehq-compiler"; 2import { Inspector, Runtime } from "@observablehq/runtime"; 3 4async function main() { 5 const runtime = new Runtime(); 6 const main = runtime.module(); 7 const observer = Inspector.into(document.body); 8 const interpret = new Intepreter({ module: main, observer }); 9 10 await interpret.module(` 11import {text} from '@jashkenas/inputs' 12 13viewof name = text({ 14 title: "what's your name?", 15 value: '' 16}) 17 18md\`Hello **\${name}**, it's nice to meet you!\` 19 20`); 21} 22main();
The Compiler will compile "Observable syntax" into javascript source code (as an ES module).
For more live examples and functionality, take a look at the announcement notebook and this test page.
API Reference
new Interpreter(params)
Interpreter is a class that encompasses all logic to interpret Observable js code. params is an optional object with the following allowed configuration:
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
resolveFileAttachments: A function that, given the name of a FileAttachment, returns the URL that the FileAttachment will be fetched from. Defaults to name => name.
defineImportMarkdown: A boolean, whether to define a markdown description cell for imports in the notebook. Defaults true.
observeViewofValues: A boolean, whether to pass in an observer for the value of viewof cells.
module: A default Observable runtime module that will be used in operations such as .cell and .module, if no other module is passed in.
observer: A default Observable runtime observer that will be used in operations such as .cell and .module, if no other observer is passed in.
Keep in mind, there is no sandboxing done, so it has the same security implications as eval().
interpret.cell(source [, module, observer])
Parses the given string source with the Observable 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 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 instead of source code.
interpret.module(source [, module, observer])
Parses the given string source with the Observable 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 that were defined when interpreting the source. source can also be a pre-parsed program instead of source code.
interpret.notebook(source [, module, observer])
TODO
new Compiler(params)
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.
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
resolveFileAttachments: A function that, given the name of a FileAttachment, returns the URL that the FileAttachment will be fetched from. Defaults to name => name.
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.
1 2// This can be unsafe since FileAttachment names can include quotes. 3// Instead, map file attachments names to something deterministic and escape-safe, 4// like SHA hashes. 5const resolveFileAttachments = name => `new URL("./files/${name}", import.meta.url)` 6 7Compiled output when: 8 9// UNSAFE_allowJavascriptFileAttachments == false 10const fileAttachments = new Map([["a", "new URL(\"./files/a\", import.meta.url)"]]); 11 12// UNSAFE_allowJavascriptFileAttachments == true 13const fileAttachments = new Map([["a", new URL("./files/a", import.meta.url)]]); 14 15
defineImportMarkdown - A boolean, whether to define a markdown description cell for imports in the notebook. Defaults true.
observeViewofValues - A boolean, whether or not to pass in the observer function for viewof value cells. Defaults true.
observeMutableValues - A boolean, whether or not to pass in the observer function for mutable value cells. Defaults true.
compile.module(source)
TODO
compile.notebook(source)
TODO
License
This library is MIT, but it relies and gets heavy inspiration from the following libraries licensed under ISC:
Contributing
Feel free to send in PR's as you wish! Take a look at the issues to find something to work on. Just please follow the Contributor Covenant in all your interactions :smile:
No vulnerabilities found.