@wavelace/formula 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026 Daniele Moraschi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @wavelace/formula
+
+Paste a formula as a textbook prints it, get a fast JavaScript function back. The formula layer of
+[Wavelace](https://www.wavelace.com), the animated maths visualiser, published on its own: LaTeX in,
+a plain expression out, a compiled function of real numbers, and a printer for showing it back.
+
+```js
+import {compile, bindable, pretty} from "@wavelace/formula";
+
+const f = compile("\\frac{\\sin(kx - \\omega t)}{x}", {k: 2, ω: 3});
+f(0.7, 0, 0, 0, 0, 0, 0, 0.1);                 // a number
+
+const wave = bindable("A \\sin(kx - \\omega t)");
+wave.names;                                    // ["A", "k", "ω"]: one slider each
+const g = wave.bind({A: 2});                   // rebinding is one call, never a recompile
+
+pretty("\\int_0^x \\cos(u^2) du");             // "∫₀^x cos(u²) du"
+```
+
+## What it reads
+
+`\frac`, `\sqrt`, powers in braces, `\sin x` without brackets, `\cos^2 x`, `\sin^{-1}`, the Greek
+letters, subscripts (`x_0`, `\omega_0`), `90^\circ`, `\left( … \right)`, `\begin{cases}`,
+`\int_a^b … du`, `\sum_{k=1}^{n}`, `\prod`, `\frac{d}{dx}`, `x!`, and the silent products a textbook
+writes: `2x`, `2\pi x`, `\sin x \cos y`, `kx`. Pasted symbols work too: `π`, `θ`, `²`, `·`, `−`, `√`.
+The whole language is documented at [wavelace.com/documentation](https://www.wavelace.com/documentation).
+
+A single letter the language does not claim (`a`, `k`, `ω`, `x_0`) is a **free name**: it takes its
+value from the values you pass, and is 1 until you do. A longer unknown name is refused rather than
+guessed at, so a mistyped `sni(x)` says so instead of growing three free names.
+
+## The one signature
+
+Every formula compiles to the same function, `(x, y, z, r, th, u, v, t) => number`, whatever it names:
+`th` is the polar angle θ, and a caller feeds the variables it has. That is Wavelace's own choice, kept
+as it is; `readsVars` says which of the eight a formula actually reads.
+
+## Beside the other libraries
+
+Fifteen textbook formulas, each value checked against the arithmetic (27 September 2026; the script
+that produced this is in this repository, so the numbers can be rerun rather than trusted):
+
+| | right of 15 | size, minified and gzipped |
+|---|---|---|
+| @wavelace/formula | 15 | 10 KB |
+| Compute Engine 0.138.0 | 15 | 974 KB |
+| math-expressions 3.0.0-alpha.1 | 9 | 4 MB unpacked |
+| evaluatex 2.2.0 | 5 | 3.6 KB |
+
+Compute Engine does far more (symbolic algebra, simplification, units); this does the real-valued
+case, and compiles about twenty times faster.
+
+## One thing to know
+
+`compile` builds its function with `new Function`, which is what makes it fast. A page with a strict
+Content Security Policy must allow `'unsafe-eval'` for it to run.
+
+## Licence
+
+MIT. This package is generated from the Wavelace source, the same two files the site runs, byte for
+byte; their comments speak of the app (its renderers, its rail, its plate) because that is where they
+live. Changes are made there, so issues are welcome here and pull requests are ported upstream by hand.

package/index.d.ts

@@ -0,0 +1,49 @@
+/* @wavelace/formula: the public API. tools/pkg.js reads the exported names off this file, so a name
+ * declared here is exported by the package and a name missing here is not. */
+
+/** A compiled formula: every formula is a function of the same eight variables, and a caller feeds
+ *  the ones it has. th is the polar angle θ; the rest are as named. */
+export type Formula = (x: number, y: number, z: number, r: number, th: number, u: number, v: number, t: number) => number;
+
+/** What the free names (a single letter the language does not claim, like a or ω) are worth. */
+export type Values = Readonly<Record<string, number>>;
+
+/** A formula compiled once with its free names still open. */
+export interface Bindable {
+  /** The free names, in order of first appearance. */
+  readonly names: readonly string[];
+  /** The formula with each free name bound to values[name], or FREE_DEFAULT. Cheap: no recompile. */
+  bind(values?: Values): Formula;
+  /** The normalized source. */
+  readonly text: string;
+}
+
+/** A LaTeX subset translated into the formula language: \frac, \sqrt, \sin x, \int_a^b … du, \sum,
+ *  \frac{d}{dx}, cases, and the silent products (2x, \sin x \cos y). Throws with a readable message. */
+export function fromLatex(src: string): string;
+/** fromLatex, with pasted symbols (π, θ, ², ·, −) read first and a run of letters like kx read as a
+ *  product. What compile reads. Throws with a readable message. */
+export function normalize(src: string): string;
+/** The formula as it reads on a plate: 3x, θ, π, · for products, superscript powers, ∫ with limits. */
+export function pretty(src: string): string;
+/** One name as the plate prints it: th as θ, x_1 as x₁. */
+export function prettyName(name: string): string;
+/** Compile once, bind many times. Throws with a readable message. */
+export function bindable(src: string): Bindable;
+/** Compile and bind in one call. Throws with a readable message. */
+export function compile(src: string, values?: Values): Formula;
+/** Which of the eight variables a formula names. Conservative: a bound dummy called v counts as v. */
+export function readsVars(src: string): Set<string>;
+/** Whether a name would be a free name, and so take a value from Values. */
+export function isFreeName(name: string): boolean;
+
+/** The eight variables, in the order a Formula takes them. */
+export const VARS: readonly ["x", "y", "z", "r", "th", "u", "v", "t"];
+/** The functions and constants a formula may name, by name. */
+export const ENV: Readonly<Record<string, unknown>>;
+/** The four binders (integral, sum, prod, diff): their parts and the LaTeX that pastes as each. */
+export const BINDERS: Readonly<Record<string, {readonly parts: readonly string[]; readonly paste: string}>>;
+/** The Greek commands a formula may use as letters, and the glyph each becomes: \omega is ω. */
+export const GREEK: Readonly<Record<string, string>>;
+/** What a free name is worth until it is given a value. */
+export const FREE_DEFAULT: number;