@classytic/stage 0.1.0

package/dist/math/ast.mjs

@@ -0,0 +1,94 @@
+import { CONSTANTS, FN1, FN2 } from "./defs.mjs";
+
+//#region src/math/ast.ts
+/**
+* expr/ast — the Abstract Syntax Tree: node types, evaluation, free-variable
+* collection, and small builder helpers. The AST is the shared representation
+* that evaluation, differentiation, simplification, and LaTeX printing all
+* operate on.
+*/
+const num = (value) => ({
+	type: "num",
+	value
+});
+const variable = (name) => ({
+	type: "var",
+	name
+});
+const neg = (arg) => ({
+	type: "neg",
+	arg
+});
+const bin = (op, left, right) => ({
+	type: "binary",
+	op,
+	left,
+	right
+});
+const add = (l, r) => bin("+", l, r);
+const sub = (l, r) => bin("-", l, r);
+const mul = (l, r) => bin("*", l, r);
+const div = (l, r) => bin("/", l, r);
+const pow = (l, r) => bin("^", l, r);
+const call = (fn, ...args) => ({
+	type: "call",
+	fn,
+	args
+});
+/** Evaluate the AST against a scope of variable values. Returns NaN for unknowns. */
+function evaluate(node, scope) {
+	switch (node.type) {
+		case "num": return node.value;
+		case "var": {
+			const lc = node.name.toLowerCase();
+			return lc in CONSTANTS ? CONSTANTS[lc] ?? NaN : scope[node.name] ?? NaN;
+		}
+		case "neg": return -evaluate(node.arg, scope);
+		case "binary": {
+			const a = evaluate(node.left, scope);
+			const b = evaluate(node.right, scope);
+			switch (node.op) {
+				case "+": return a + b;
+				case "-": return a - b;
+				case "*": return a * b;
+				case "/": return a / b;
+				case "%": return a % b;
+				case "^": return a ** b;
+				default: return NaN;
+			}
+		}
+		case "call": {
+			const f1 = FN1[node.fn];
+			const f2 = FN2[node.fn];
+			if (f1 && node.args[0]) return f1(evaluate(node.args[0], scope));
+			if (f2 && node.args[0] && node.args[1]) return f2(evaluate(node.args[0], scope), evaluate(node.args[1], scope));
+			return NaN;
+		}
+		default: return NaN;
+	}
+}
+/** Free variables referenced (excludes constants & function names). */
+function freeVars(node, into = /* @__PURE__ */ new Set()) {
+	switch (node.type) {
+		case "var":
+			if (!(node.name.toLowerCase() in CONSTANTS)) into.add(node.name);
+			break;
+		case "neg":
+			freeVars(node.arg, into);
+			break;
+		case "binary":
+			freeVars(node.left, into);
+			freeVars(node.right, into);
+			break;
+		case "call":
+			for (const a of node.args) freeVars(a, into);
+			break;
+		default: break;
+	}
+	return into;
+}
+/** Compile to a fast closure (a thin wrapper over `evaluate`). */
+const compileNode = (node) => (scope) => evaluate(node, scope);
+
+//#endregion
+export { add, bin, call, compileNode, div, evaluate, freeVars, mul, neg, num, pow, sub, variable };

package/dist/math/calculus.d.mts

@@ -0,0 +1,9 @@
+import { Node } from "./ast.mjs";
+
+//#region src/math/calculus.d.ts
+/** Exact symbolic derivative, or `null` if a non-differentiable node is present. */
+declare function differentiate(node: Node, x: string): Node | null;
+/** Fold constants and trivial identities so derivative output is readable. */
+declare function simplify(node: Node): Node;
+//#endregion
+export { differentiate, simplify };

package/dist/math/calculus.mjs

@@ -0,0 +1,188 @@
+import { FN1, FN2 } from "./defs.mjs";
+import { add, call, div, mul, neg, num, pow, sub } from "./ast.mjs";
+
+//#region src/math/calculus.ts
+/**
+* expr/calculus — symbolic differentiation + algebraic simplification on the AST.
+*
+* `differentiate(node, x)` returns the exact derivative as a new AST, or `null`
+* when the expression contains something not symbolically differentiable
+* (floor/round/min/max/…). Callers should fall back to a numerical derivative
+* in that case. `simplify(node)` folds constants and trivial identities so the
+* derivative reads cleanly (e.g. `1*cos(x) + 0` → `cos(x)`).
+*/
+const LN10 = Math.LN10;
+const LN2 = Math.LN2;
+/** Outer derivative of a 1-arg function, given its argument node `u` (pre chain-rule). */
+const DERIV = {
+	sin: (u) => call("cos", u),
+	cos: (u) => neg(call("sin", u)),
+	tan: (u) => div(num(1), pow(call("cos", u), num(2))),
+	cot: (u) => neg(div(num(1), pow(call("sin", u), num(2)))),
+	sec: (u) => mul(call("sec", u), call("tan", u)),
+	csc: (u) => neg(mul(call("csc", u), call("cot", u))),
+	asin: (u) => div(num(1), call("sqrt", sub(num(1), pow(u, num(2))))),
+	acos: (u) => neg(div(num(1), call("sqrt", sub(num(1), pow(u, num(2)))))),
+	atan: (u) => div(num(1), add(num(1), pow(u, num(2)))),
+	sinh: (u) => call("cosh", u),
+	cosh: (u) => call("sinh", u),
+	tanh: (u) => div(num(1), pow(call("cosh", u), num(2))),
+	exp: (u) => call("exp", u),
+	ln: (u) => div(num(1), u),
+	log: (u) => div(num(1), mul(u, num(LN10))),
+	log10: (u) => div(num(1), mul(u, num(LN10))),
+	log2: (u) => div(num(1), mul(u, num(LN2))),
+	sqrt: (u) => div(num(1), mul(num(2), call("sqrt", u))),
+	cbrt: (u) => div(num(1), mul(num(3), pow(call("cbrt", u), num(2)))),
+	abs: (u) => div(u, call("abs", u))
+};
+/** Exact symbolic derivative, or `null` if a non-differentiable node is present. */
+function differentiate(node, x) {
+	switch (node.type) {
+		case "num": return num(0);
+		case "var": return num(node.name === x ? 1 : 0);
+		case "neg": {
+			const d = differentiate(node.arg, x);
+			return d && neg(d);
+		}
+		case "binary": {
+			const { op, left, right } = node;
+			const dl = differentiate(left, x);
+			const dr = differentiate(right, x);
+			if (op === "+") return dl && dr && add(dl, dr);
+			if (op === "-") return dl && dr && sub(dl, dr);
+			if (op === "*") return dl && dr && add(mul(dl, right), mul(left, dr));
+			if (op === "/") return dl && dr && div(sub(mul(dl, right), mul(left, dr)), pow(right, num(2)));
+			if (op === "^") {
+				if (!dl) return null;
+				if (right.type === "num") return mul(mul(num(right.value), pow(left, num(right.value - 1))), dl);
+				return dr && mul(pow(left, right), add(mul(dr, call("ln", left)), div(mul(right, dl), left)));
+			}
+			return null;
+		}
+		case "call": {
+			const rule = DERIV[node.fn];
+			const u = node.args[0];
+			if (!rule || !u || node.fn in FN2) return null;
+			const du = differentiate(u, x);
+			return du && mul(rule(u), du);
+		}
+		default: return null;
+	}
+}
+const isNum = (n, v) => n.type === "num" && (v === void 0 || n.value === v);
+/** Fold constants and trivial identities so derivative output is readable. */
+function simplify(node) {
+	switch (node.type) {
+		case "num":
+		case "var": return node;
+		case "neg": {
+			const a = simplify(node.arg);
+			if (a.type === "num") return num(-a.value);
+			if (a.type === "neg") return a.arg;
+			return neg(a);
+		}
+		case "binary": {
+			const l = simplify(node.left);
+			const r = simplify(node.right);
+			const op = node.op;
+			if (l.type === "num" && r.type === "num") {
+				const v = fold(op, l.value, r.value);
+				if (v !== null && Number.isFinite(v)) return num(v);
+			}
+			switch (op) {
+				case "+":
+					if (isNum(l, 0)) return r;
+					if (isNum(r, 0)) return l;
+					break;
+				case "-":
+					if (isNum(r, 0)) return l;
+					if (isNum(l, 0)) return simplify(neg(r));
+					break;
+				case "*":
+					if (isNum(l, 0) || isNum(r, 0)) return num(0);
+					if (isNum(l, 1)) return r;
+					if (isNum(r, 1)) return l;
+					if (isNum(l, -1)) return simplify(neg(r));
+					if (isNum(r, -1)) return simplify(neg(l));
+					if (l.type === "num" && r.type === "binary" && r.op === "*") {
+						if (r.left.type === "num") return {
+							type: "binary",
+							op: "*",
+							left: num(l.value * r.left.value),
+							right: r.right
+						};
+						if (r.right.type === "num") return {
+							type: "binary",
+							op: "*",
+							left: num(l.value * r.right.value),
+							right: r.left
+						};
+					}
+					if (r.type === "num" && l.type === "binary" && l.op === "*") {
+						if (l.left.type === "num") return {
+							type: "binary",
+							op: "*",
+							left: num(r.value * l.left.value),
+							right: l.right
+						};
+						if (l.right.type === "num") return {
+							type: "binary",
+							op: "*",
+							left: num(r.value * l.right.value),
+							right: l.left
+						};
+					}
+					break;
+				case "/":
+					if (isNum(r, 1)) return l;
+					if (isNum(l, 0)) return num(0);
+					break;
+				case "^":
+					if (isNum(r, 1)) return l;
+					if (isNum(r, 0)) return num(1);
+					if (isNum(l, 1)) return num(1);
+					break;
+				default: break;
+			}
+			return {
+				type: "binary",
+				op,
+				left: l,
+				right: r
+			};
+		}
+		case "call": {
+			const args = node.args.map(simplify);
+			if (args.every((a) => a.type === "num")) {
+				const nums = args.map((a) => a.value);
+				const f1 = FN1[node.fn];
+				const f2 = FN2[node.fn];
+				let v;
+				if (f1 && nums.length === 1) v = f1(nums[0]);
+				else if (f2 && nums.length === 2) v = f2(nums[0], nums[1]);
+				if (v !== void 0 && Number.isFinite(v)) return num(v);
+			}
+			return {
+				type: "call",
+				fn: node.fn,
+				args
+			};
+		}
+		default: return node;
+	}
+}
+function fold(op, a, b) {
+	switch (op) {
+		case "+": return a + b;
+		case "-": return a - b;
+		case "*": return a * b;
+		case "/": return a / b;
+		case "%": return a % b;
+		case "^": return a ** b;
+		default: return null;
+	}
+}
+
+//#endregion
+export { differentiate, simplify };

package/dist/math/defs.mjs

@@ -0,0 +1,51 @@
+//#region src/math/defs.ts
+/**
+* expr/defs — the function & constant tables shared by the tokenizer, evaluator,
+* differentiator, and LaTeX printer. Pure data; no AST knowledge here.
+*/
+const CONSTANTS = {
+	pi: Math.PI,
+	e: Math.E,
+	tau: Math.PI * 2
+};
+const FN1 = {
+	sin: Math.sin,
+	cos: Math.cos,
+	tan: Math.tan,
+	cot: (x) => 1 / Math.tan(x),
+	sec: (x) => 1 / Math.cos(x),
+	csc: (x) => 1 / Math.sin(x),
+	asin: Math.asin,
+	acos: Math.acos,
+	atan: Math.atan,
+	sinh: Math.sinh,
+	cosh: Math.cosh,
+	tanh: Math.tanh,
+	sqrt: Math.sqrt,
+	cbrt: Math.cbrt,
+	abs: Math.abs,
+	exp: Math.exp,
+	ln: Math.log,
+	log: Math.log10,
+	log2: Math.log2,
+	log10: Math.log10,
+	floor: Math.floor,
+	ceil: Math.ceil,
+	round: Math.round,
+	trunc: Math.trunc,
+	sign: Math.sign
+};
+const FN2 = {
+	pow: Math.pow,
+	atan2: Math.atan2,
+	min: Math.min,
+	max: Math.max,
+	hypot: Math.hypot,
+	mod: (a, b) => a % b
+};
+const isFunction = (name) => name in FN1 || name in FN2;
+/** Declared argument count for a function name, or null if unknown. */
+const arityOf = (name) => name in FN1 ? 1 : name in FN2 ? 2 : null;
+
+//#endregion
+export { CONSTANTS, FN1, FN2, arityOf, isFunction };

package/dist/math/index.d.mts

@@ -0,0 +1,26 @@
+import { BinOp, Node, compileNode, evaluate, freeVars } from "./ast.mjs";
+import { parse } from "./parse.mjs";
+import { differentiate, simplify } from "./calculus.mjs";
+import { toLatex } from "./latex.mjs";
+
+//#region src/math/index.d.ts
+interface CompiledExpr {
+  /** Evaluate against a scope of variable values (unknown vars → NaN). */
+  readonly fn: (scope: Record<string, number>) => number;
+  /** Free variables referenced (excludes constants & functions), e.g. `['x','a']`. */
+  readonly vars: string[];
+  /** The parsed syntax tree — for differentiation, LaTeX, or analysis. */
+  readonly ast: Node;
+  readonly error?: undefined;
+}
+interface ExprError {
+  readonly error: string;
+  readonly fn?: undefined;
+  readonly vars?: undefined;
+  readonly ast?: undefined;
+}
+type ExprResult = CompiledExpr | ExprError;
+/** Compile a formula string. Returns `{ fn, vars, ast }` or `{ error }` — never throws. */
+declare function compileExpr(src: string): ExprResult;
+//#endregion
+export { type BinOp, CompiledExpr, ExprError, ExprResult, type Node, compileExpr, compileNode, differentiate, evaluate, freeVars, parse, simplify, toLatex };

package/dist/math/index.mjs

@@ -0,0 +1,42 @@
+import { compileNode, evaluate, freeVars } from "./ast.mjs";
+import { parse } from "./parse.mjs";
+import { differentiate, simplify } from "./calculus.mjs";
+import { toLatex } from "./latex.mjs";
+
+//#region src/math/index.ts
+/**
+* expr — a tiny, safe, dependency-free symbolic math engine.
+*
+* Pipeline: `tokenize → parse (AST) → evaluate`. On top of the AST it offers
+* exact `differentiate`, `simplify`, and `toLatex`, so the same typed formula
+* can be plotted, differentiated for an exact tangent, and rendered beautifully.
+* No `eval`/`new Function`.
+*
+* `compileExpr(src)` is the stable, simple entry point (returns a fast `fn` plus
+* the free `vars` and the parsed `ast`); the lower-level pieces are exported for
+* widgets that need the tree (derivative explorers, LaTeX labels, step-by-step).
+*
+* Supports: numbers (incl. `1.5e3`), variable `x` + named params, constants
+* (`pi`/`e`/`tau`), operators `+ - * / % ^` (^ right-assoc) and unary minus,
+* implicit multiplication (`2x`, `3sin(x)`), and functions `sin cos tan cot sec
+* csc asin acos atan sinh cosh tanh sqrt cbrt abs exp ln log log2 log10 floor
+* ceil round sign` (+ 2-arg `pow atan2 min max mod hypot`).
+*/
+/** Compile a formula string. Returns `{ fn, vars, ast }` or `{ error }` — never throws. */
+function compileExpr(src) {
+	if (!src || !src.trim()) return { error: "Empty expression" };
+	let ast;
+	try {
+		ast = parse(src);
+	} catch (e) {
+		return { error: e instanceof Error ? e.message : "Parse error" };
+	}
+	return {
+		fn: (scope) => evaluate(ast, scope),
+		vars: [...freeVars(ast)],
+		ast
+	};
+}
+
+//#endregion
+export { compileExpr, compileNode, differentiate, evaluate, freeVars, parse, simplify, toLatex };

package/dist/math/latex.d.mts

@@ -0,0 +1,7 @@
+import { Node } from "./ast.mjs";
+
+//#region src/math/latex.d.ts
+/** Render an AST as a LaTeX string (no surrounding `$`). */
+declare function toLatex(node: Node): string;
+//#endregion
+export { toLatex };

package/dist/math/latex.mjs

@@ -0,0 +1,115 @@
+//#region src/math/latex.ts
+const GREEK = new Set([
+	"alpha",
+	"beta",
+	"gamma",
+	"delta",
+	"epsilon",
+	"zeta",
+	"eta",
+	"theta",
+	"iota",
+	"kappa",
+	"lambda",
+	"mu",
+	"nu",
+	"xi",
+	"pi",
+	"rho",
+	"sigma",
+	"tau",
+	"phi",
+	"chi",
+	"psi",
+	"omega"
+]);
+const NAMED_FN = new Set([
+	"sin",
+	"cos",
+	"tan",
+	"cot",
+	"sec",
+	"csc",
+	"sinh",
+	"cosh",
+	"tanh",
+	"log",
+	"ln",
+	"exp"
+]);
+function texVar(name) {
+	return GREEK.has(name) ? `\\${name}` : name;
+}
+function texNum(v) {
+	if (!Number.isFinite(v)) return v > 0 ? "\\infty" : "-\\infty";
+	return String(+v.toFixed(6));
+}
+function texP(node) {
+	switch (node.type) {
+		case "num": return {
+			s: texNum(node.value),
+			prec: node.value < 0 ? 1 : 4
+		};
+		case "var": return {
+			s: texVar(node.name),
+			prec: 4
+		};
+		case "neg": return {
+			s: `-${wrap(node.arg, 2)}`,
+			prec: 2
+		};
+		case "call": return {
+			s: texCall(node),
+			prec: 4
+		};
+		case "binary": {
+			const { op } = node;
+			if (op === "/") return {
+				s: `\\frac{${wrap(node.left, 0)}}{${wrap(node.right, 0)}}`,
+				prec: 4
+			};
+			if (op === "^") return {
+				s: `${wrap(node.left, 4)}^{${wrap(node.right, 0)}}`,
+				prec: 3
+			};
+			if (op === "+" || op === "-") return {
+				s: `${wrap(node.left, 1)} ${op} ${wrap(node.right, 1)}`,
+				prec: 1
+			};
+			if (op === "%") return {
+				s: `${wrap(node.left, 2)} \\bmod ${wrap(node.right, 2)}`,
+				prec: 2
+			};
+			const sep = node.right.type === "num" ? " \\cdot " : "";
+			return {
+				s: `${wrap(node.left, 2)}${sep}${wrap(node.right, 2)}`,
+				prec: 2
+			};
+		}
+		default: return {
+			s: "",
+			prec: 4
+		};
+	}
+}
+function wrap(node, parentPrec) {
+	const { s, prec } = texP(node);
+	return prec < parentPrec ? `\\left(${s}\\right)` : s;
+}
+function texCall(node) {
+	const a0 = node.args[0];
+	if (!a0) return `\\operatorname{${node.fn}}()`;
+	if (node.fn === "sqrt") return `\\sqrt{${wrap(a0, 0)}}`;
+	if (node.fn === "cbrt") return `\\sqrt[3]{${wrap(a0, 0)}}`;
+	if (node.fn === "abs") return `\\left|${wrap(a0, 0)}\\right|`;
+	if (node.fn === "exp") return `e^{${wrap(a0, 0)}}`;
+	const args = node.args.map((a) => wrap(a, 0)).join(", ");
+	return `${NAMED_FN.has(node.fn) ? `\\${node.fn}` : `\\operatorname{${node.fn}}`}\\left(${args}\\right)`;
+}
+/** Render an AST as a LaTeX string (no surrounding `$`). */
+function toLatex(node) {
+	return texP(node).s;
+}
+
+//#endregion
+export { toLatex };

package/dist/math/parse.d.mts

@@ -0,0 +1,6 @@
+import { Node } from "./ast.mjs";
+
+//#region src/math/parse.d.ts
+declare function parse(src: string): Node;
+//#endregion
+export { parse };

package/dist/math/parse.mjs

@@ -0,0 +1,91 @@
+import { arityOf } from "./defs.mjs";
+import { tokenize } from "./tokenize.mjs";
+import { bin, call, neg, num, variable } from "./ast.mjs";
+
+//#region src/math/parse.ts
+/**
+* expr/parse — token stream → AST, via precedence-climbing (Pratt).
+*
+* Binary precedence: `+ -` < `* / %` < `^` (right-assoc). Unary minus binds
+* looser than `^` (so `-2^2 = -(2^2) = -4`) but tighter than `*`. Throws a
+* descriptive Error on malformed input — the parser is the single source of
+* truth for "is this expression well-formed?".
+*/
+const BIN_PREC = {
+	"+": 2,
+	"-": 2,
+	"*": 3,
+	"/": 3,
+	"%": 3,
+	"^": 5
+};
+const RIGHT = new Set(["^"]);
+const UNARY_PREC = 4;
+function parse(src) {
+	const toks = tokenize(src);
+	let pos = 0;
+	const peek = () => toks[pos];
+	const next = () => toks[pos++];
+	const expect = (t) => {
+		const tok = next();
+		if (!tok || tok.t !== t) throw new Error(`Expected ${t}`);
+	};
+	function parsePrimary() {
+		const t = next();
+		if (!t) throw new Error("Unexpected end of expression");
+		if (t.t === "num") return num(t.v);
+		if (t.t === "var") return variable(t.v);
+		if (t.t === "fn") {
+			expect("lp");
+			const args = [];
+			if (peek()?.t !== "rp") {
+				args.push(parseExpr(0));
+				while (peek()?.t === "comma") {
+					next();
+					args.push(parseExpr(0));
+				}
+			}
+			expect("rp");
+			const a = arityOf(t.v);
+			if (a !== null && args.length !== a) throw new Error(`${t.v}() expects ${a} argument(s), got ${args.length}`);
+			return call(t.v, ...args);
+		}
+		if (t.t === "lp") {
+			const e = parseExpr(0);
+			expect("rp");
+			return e;
+		}
+		throw new Error("Unexpected token");
+	}
+	function parseUnary() {
+		const t = peek();
+		if (t && t.t === "op" && t.v === "-") {
+			next();
+			return neg(parseExpr(UNARY_PREC));
+		}
+		if (t && t.t === "op" && t.v === "+") {
+			next();
+			return parseUnary();
+		}
+		return parsePrimary();
+	}
+	function parseExpr(minPrec) {
+		let left = parseUnary();
+		for (;;) {
+			const t = peek();
+			if (!t || t.t !== "op") break;
+			const prec = BIN_PREC[t.v];
+			if (prec === void 0 || prec < minPrec) break;
+			next();
+			const nextMin = RIGHT.has(t.v) ? prec : prec + 1;
+			left = bin(t.v, left, parseExpr(nextMin));
+		}
+		return left;
+	}
+	const node = parseExpr(0);
+	if (pos !== toks.length) throw new Error("Unexpected trailing input");
+	return node;
+}
+
+//#endregion
+export { parse };