31:T61c,# Nontrivial Math - Bringing A Library To Observable The source format of Paul Masson's [library of nontrivial mathematical functions](https://github.com/paulmasson/math) doesn't play well with modern environments like Observable. Most of its identifiers leak into the global scope, and it is often unclear if they were meant to be part of the official API. Below we compare various data sources in an effort to find the "best" set of exportable identifiers. ### Data sources Categories are derived from the path and name of the source file in which a declaration was found. ${(t => (t.style.font="15px/1.4 var(--serif)",t))(md` |Column|Description |-|- |Docs| Signatures that have been parsed from the [HTML documentation](https://paulmasson.github.io/math/docs/). |Source| Top-level declarations that were detected in the source files by [periscopic](https://github.com/Rich-Harris/periscopic). |Globals| New properties that were found on the \`window\` object after including the script. |@esperanc| Properties exported by [\`@esperanc/masson-non-trivial-math\` / \`masson\`](https://observablehq.com/@esperanc/masson-non-trivial-math#masson) |@mootari| Properties exported by [\`@mootari/patched-imports\` / \`paulmasson_math\`](https://observablehq.com/@mootari/patched-imports#paulmasson_math) `)} For detailed instructions on how to import the library see the respective notebooks by [`@esperanc`](https://observablehq.com/@esperanc/masson-non-trivial-math#masson) or [`@mootari`](https://observablehq.com/@mootari/patched-imports#paulmasson_math). 32:T6aa,viewof selectedCategories = { const groups = {}; const ucFirst = (s) => s.slice(0, 1).toUpperCase() + s.slice(1); const format = (d) => { d = d.replace(/-/g, " "); const i = d.indexOf("/"); const group = ucFirst(i > -1 ? d.slice(0, i) : "other"); const name = i > -1 ? d.slice(i + 1) : d; const label = html`${name}`; (groups[group] || (groups[group] = [])).push(label); return label; }; const input = Inputs.checkbox(new Set(Object.values(categories)), { format }); const parent = input.lastElementChild; const scope = DOM.uid().id; input.classList.add(`${scope}-input`); const style = html` ${selected .map((d) => d.name) .sort() .map((name) => getPreview(name))} `; return view; function getPreview(name) { const source = getSource(name); if (!source) return html`

No preview available for identifier "${name}".`; const toggleIcons = [ raw(icons.chevron_down_16), raw(icons.chevron_right_16) ]; const toggle = html`

${toggleIcons[0]}`; toggle.onclick = function (e) { toggle.firstChild.replaceWith(toggleIcons.reverse()[0]); block.classList.toggle(scope + "-collapsed"); }; const { path, lines: [start, end] } = source_locations[name]; const href = `https://github.com/paulmasson/math/blob/master${path}#L${start}-L${end}`; const len = end - start + 1; let desc = `${len} ${len === 1 ? "line" : "lines"}`; if (formatSource) desc = `(${desc})`; const header = html`

${toggle} ${name} ${desc} ${path.slice(1)}

View on GitHub `; const block = html`

${header} ${highlightCached(formatSource ? reformat(source) : source)} `; return block; } }35:[] 2f:{"title":"Nontrivial Math - Bringing A Library To Observable","cells":[{"id":0,"value":"$31","pinned":false,"hidden":false,"mode":"md"},{"id":1509,"value":"---\n## Comparison","pinned":false,"hidden":false,"mode":"md"},{"id":1390,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":103,"value":"viewof filterOptions = Inputs.form(\n transformObject(\n {\n docs: `Docs (${keys_docs.size})`,\n source: `Source (${keys_source.size})`,\n globals: `Globals (${keys_globals.size})`,\n esperanc: `@esperanc (${keys_esperanc.size})`,\n mootari: `@mootari (${keys_mootari.size})`\n },\n (entries) =>\n entries.map(([key, label]) => [\n key,\n Inputs.radio([null, true, false], {\n format: (d) => (d === null ? \"any\" : d ? \"yes\" : \"no\"),\n value: null,\n label\n })\n ])\n ),\n {\n template: (inputs) =>\n html`Identifiers in ...

${Object.values(\n inputs\n )}`\n }\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":208,"value":"$33","pinned":false,"hidden":false,"mode":"ojs"},{"id":770,"value":"$${more(`Select a table row to view its declaration.`)}","pinned":false,"hidden":false,"mode":"md"},{"id":824,"value":"viewof formatSource = Inputs.toggle({ label: \"Reformat source\", value: true })","pinned":false,"hidden":false,"mode":"ojs"},{"id":169,"value":"$34","pinned":false,"hidden":false,"mode":"ojs"},{"id":373,"value":"---\n\n## Source code","pinned":false,"hidden":false,"mode":"md"},{"id":313,"value":"$${Object.entries(sources).map(([path, source]) => html`

\n ${path.slice(5)}\n ${iconGitHub(16)}\n

Declarations: ${[...declarations[path].keys()].sort().join(\", \")}

\n ${highlight(source, {\n pre: {style: 'border:1px solid #aaa; height:300px;overflow:auto;resize:vertical'},\n code: {style: 'font-size:13px'}}\n )}\n `)}","pinned":false,"hidden":false,"mode":"html"},{"id":255,"value":"---\n## Data","pinned":false,"hidden":false,"mode":"md"},{"id":59,"value":"keys_merged = new Set(\n [\n ...keys_esperanc,\n ...keys_mootari,\n ...keys_docs,\n ...keys_source,\n ...keys_globals\n ].sort()\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":845,"value":"table_items = Array.from(keys_merged, (name) => ({\n name,\n category: categories[name] ?? \"\",\n docs: keys_docs.has(name),\n source: keys_source.has(name),\n globals: keys_globals.has(name),\n esperanc: keys_esperanc.has(name),\n mootari: keys_mootari.has(name)\n}))","pinned":false,"hidden":false,"mode":"ojs"},{"id":263,"value":"### Exports: @esperanc/masson-non-trivial-math\n","pinned":false,"hidden":false,"mode":"md"},{"id":16,"value":"import { masson as mathEsperanc } from \"@esperanc/masson-non-trivial-math\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":21,"value":"keys_esperanc = new Set(Object.keys(mathEsperanc).sort())","pinned":false,"hidden":false,"mode":"ojs"},{"id":150,"value":"aliases_esperanc = transformObject(aliases(mathEsperanc), (e) => e.sort())","pinned":false,"hidden":false,"mode":"ojs"},{"id":640,"value":"### Exports: @mootari/patched-imports\n","pinned":false,"hidden":false,"mode":"md"},{"id":9,"value":"import { paulmasson_math as mathMootari } from \"@mootari/patched-imports\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":19,"value":"keys_mootari = new Set(Object.keys(mathMootari).sort())","pinned":false,"hidden":false,"mode":"ojs"},{"id":146,"value":"aliases_mootari = transformObject(aliases(mathMootari), (e) => e.sort())","pinned":false,"hidden":false,"mode":"ojs"},{"id":552,"value":"### Globals\n\n${more(`Detected global declarations.`)}","pinned":false,"hidden":false,"mode":"md"},{"id":556,"value":"keys_globals = detectLeaks(\n \"https://cdn.jsdelivr.net/gh/paulmasson/math@master/build/math.js\"\n).then((d) => new Set(d.sort()))","pinned":false,"hidden":false,"mode":"ojs"},{"id":126,"value":"### Files\n\n${more(`A list of all repository files, retrieved via the [JSDelivr API](https://github.com/jsdelivr/data.jsdelivr.com#list-package-files).`)}","pinned":false,"hidden":false,"mode":"md"},{"id":470,"value":"jsdelivr_path = \"gh/paulmasson/math@master\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":462,"value":"// Index of all repository files.\nfiles_index = ((path) =>\n fetch(`https://data.jsdelivr.com/v1/package/${path}/flat`)\n .then((r) => r.json())\n .then((d) => d.files))(jsdelivr_path)","pinned":false,"hidden":false,"mode":"ojs"},{"id":483,"value":"### Sources\n\n${more(`Declarations and categories extracted from the source files.`)}","pinned":false,"hidden":false,"mode":"md"},{"id":274,"value":"// File paths mapped to file contents.\nsources = Object.fromEntries(\n await Promise.all(\n files_index\n .filter((d) => d.name.startsWith(\"/src/\"))\n .map((d) =>\n fetch(`https://cdn.jsdelivr.net/${jsdelivr_path}${d.name}`)\n .then((r) => r.text())\n .then((s) => [d.name, s])\n )\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":388,"value":"// File paths mapped to declaration AST nodes, including locations.\ndeclarations = transformObject(sources, (entries) =>\n entries\n .filter(([path]) => path.startsWith(\"/src/\"))\n .map(([path, source]) => {\n const ast = acorn.parse(source, {\n ecmaVersion: \"latest\",\n locations: true\n });\n const scope = periscopic.analyze(ast).scope;\n return [path, scope.declarations];\n })\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":670,"value":"// Identifiers mapped to their source file, range and line numbers.\nsource_locations = transformObject(declarations, (entries) =>\n entries.flatMap(([path, declarations]) => {\n return Array.from(declarations.entries(), ([name, node]) => [\n name,\n {\n path,\n range: [node.start, node.end],\n lines: [node.loc.start.line, node.loc.end.line]\n }\n ]);\n })\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":399,"value":"categories = transformObject(declarations, (entries) =>\n entries.flatMap(([path, declarations]) => {\n const cat = path.slice(5, -3);\n return Array.from(declarations.keys(), (n) => [n, cat]);\n })\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":535,"value":"keys_source = new Set([...Object.keys(categories)].sort())","pinned":false,"hidden":false,"mode":"ojs"},{"id":415,"value":"// Ensure that there are no duplicate declarations across different files.\nduplicates = {\n const unique = new Map();\n const duplicate = [];\n for (const [path, names] of Object.entries(declarations)) {\n for (const name of names) {\n if (unique.has(name))\n duplicate.push({ name, path, first: unique.get(name) });\n else unique.set(name);\n }\n }\n return duplicate;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":486,"value":"### Documentation\n\n${more(`Function names extracted from the [HTML documentation](https://paulmasson.github.io/math/docs/).`)}","pinned":false,"hidden":false,"mode":"md"},{"id":479,"value":"docs = Object.fromEntries(\n await Promise.all(\n files_index\n .filter((d) => d.name.startsWith(\"/docs/\") && d.name.endsWith(\".html\"))\n .map((d) =>\n fetch(`https://cdn.jsdelivr.net/${jsdelivr_path}${d.name}`)\n .then((r) => r.text())\n .then((s) => [d.name, s])\n )\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":498,"value":"signatures = new Map(\n Object.entries(docs).flatMap(([path, markup]) =>\n Array.from(\n raw(markup).querySelectorAll(\n \"p>b:first-child,p>a:first-child>b:first-child\"\n ),\n (n) => [\n n.textContent,\n n.parentElement.localName === \"a\"\n ? path.replace(/\\/[^/]+$/, \"/\") + n.parentElement.getAttribute(\"href\")\n : path\n ]\n ).sort(([a], [b]) => a.localeCompare(b))\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":25,"value":"keys_docs = new Set(\n Array.from(signatures.keys(), (s) => s.slice(0, s.indexOf(\"(\"))).sort()\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":1515,"value":"doc_links = Array.from(signatures.entries()).reduce((map, [sig, path]) => {\n const name = sig.slice(0, sig.indexOf(\"(\"));\n if (map.has(name)) return map;\n const url = new URL(\"https://paulmasson.github.io/math\");\n url.pathname += path;\n url.hash = \":~:text=\" + name;\n map.set(name, `${url}`);\n return map;\n}, new Map())","pinned":false,"hidden":false,"mode":"ojs"},{"id":55,"value":"---\n## Utilities","pinned":false,"hidden":false,"mode":"md"},{"id":294,"value":"### UI","pinned":false,"hidden":false,"mode":"md"},{"id":69,"value":"formatBool = (d) => (d ? \"✔️\" : \"\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":85,"value":"// Make an element vertically resizable.\nresizable = (t) => {\n t.style.resize = \"vertical\";\n return t;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1371,"value":"// From https://observablehq.com/@mootari/observable-ast#more\nfunction more(content) {\n const scope = DOM.uid(\"more\").id;\n return html`

\n💡\n

${content instanceof Element ? content : md`${content}`}\n