value-story

A small TypeScript library for traceable numeric computations. Each value is a Result with a provenance DAG (how) so every number can be explained and visualized.

Install

npm install value-story

Example Output

Core API

Operators

• add(a, b, unitOverride?, description?)
• sum(results, unitOverride?, description?)
• mul(a, b, unitOverride?, description?)
• scale(a, factor, unitOverride?, description?)
• ifResult(left, operator, right, whenTrue, whenFalse, unitOverride?, description?)
  • supported operators: ==, !=, <, <=, >, >=

Functions

• fromSetting(key, value, unit, description)
• constant(value, unit, description)
• convertUnit(a, newUnit, description?)
• finalResult(a, description?)
• flatten(result)
• explain(result)
• toCytoscape(result)
• renderTraceGraph(container, result, options?)

Function Reference

| Function | Category | Description | |---|---|---| | fromSetting | source | Create a leaf result from an external setting/config value. | | constant | source | Create a leaf constant result. | | add | operator | Add two results and create a trace node. | | sum | operator | Sum an array of results into one result. | | mul | operator | Multiply two results and create a trace node. | | scale | operator | Multiply a result by a numeric or result-based factor. | | ifResult | operator | Select whenTrue or whenFalse using a numeric comparison between two results. | | convertUnit | transform | Relabel unit without changing numeric value. | | finalResult | transform | Mark an explicit final output node. | | flatten | explainability | Return all trace nodes in topological order (inputs before parent). | | explain | explainability | Return a readable multiline explanation of the trace. | | toCytoscape | graph | Convert a result trace to Cytoscape nodes/edges. | | renderTraceGraph | graph | Render an interactive graph (layout, styles, tooltips, zoom). |

renderTraceGraph automatically appends a final result node by default. Disable this with autoFinalResult: false.

Examples

examples/calculations.ts

::include{file=/examples/calculations.ts}

examples/minimal-esm.html

::include{file=/examples/minimal-esm.html}

Run the minimal HTML example

python3 -m http.server 8080

Open: http://localhost:8080/examples/minimal-esm.html

Dev

npm install
npm test
npm run build