@lumilla/star ✨

Star's Transforming And Rewriting

A fully-featured computer algebra system compiled to WebAssembly and packaged for convenience. This README is a stub: this package is primarily intended for the maintainer's own use in their projects and is published on npm for convenience only. This npm package distributes prebuilt WebAssembly (WASM) binaries and TypeScript types only. The original Rust source is proprietary and not included in the package. Feel free to use this package in personal projects (see: UNLICENSED — the maintainer requests that you do not resell or commercially redistribute the package without permission. Contact [email protected] with any questions.).

Features

• Arbitrary precision integers and rationals
• Symbolic expressions with automatic simplification
• Polynomial arithmetic and factorization
• Function support (trigonometric, exponential, logarithmic)
• Calculus operations (differentiation and integration)
• Linear algebra with symbolic matrices
• Pattern matching and substitution
• Complex number support

Quick Start

Installation

For JavaScript/TypeScript consumers, install the prebuilt npm package:

npm install @lumilla/star

Basic Usage (TypeScript)

import init, { JsExpr, packageInfo } from "@lumilla/star";
await init(); // initializes the WASM module

// Parse an expression
const e: JsExpr = JsExpr.parse("x^2 + 2*x + 1");
console.log(e.toString()); // "x^2 + 2*x + 1"

// Convert to LaTeX
console.log(e.toLatex()); // "x^{2} + 2*x + 1"

// Evaluate numerically (returns number or undefined)
console.log(JsExpr.parse("sin(pi/2)").evalf()); // 1

// Package metadata
console.log(packageInfo());

Note: package contents & license

Important: The npm package @lumilla/star contains prebuilt WebAssembly (WASM) binaries and TypeScript declarations only. The Rust source code is proprietary and is not included in the npm package. This package is published primarily for the maintainer's personal convenience and to simplify using the prebuilt WASM in TypeScript/JavaScript projects. You may use it in personal projects per the package's UNLICENSED status; however, the maintainer requests that you do not resell or commercially redistribute the package without express permission.

If you need source access or commercial licensing, please contact the package maintainer.

LaTeX parsing (TypeScript)

The published WASM package includes a conservative LaTeX subset parser (no extra build flags required).

import init, { parseLatex, JsExpr } from "@lumilla/star";
await init();
const lx: JsExpr = parseLatex("\\frac{3}{5} + \\sqrt{x}");
console.log(lx.toString());

Tracing (TypeScript)

The package provides two convenient ways to obtain step-by-step traces for educational or debugging purposes.

1. Quick helper: traceSimplify(expr: string) returns a JsTraceResult object with .result and .steps.

import init, { traceSimplify } from "@lumilla/star";
await init();
const out = traceSimplify("(x+1)^2");
console.log(out.result.toString());
// `out.steps` contains an array of formatted step strings
console.log(out.steps.join("\n"));

2. Structured inspection: JsStepRecorder and JsTraceStep provide a typed, per-step view.

import init, { JsStepRecorder, traceSimplify } from "@lumilla/star";
await init();
const rec = new JsStepRecorder();
rec.setLevel("verbose");

// For full structured traces you can use tracer APIs; the quick helper returns
// a `JsTraceResult` but a recorder allows you to collect steps programmatically.
const out = traceSimplify("sin(x)^2 + cos(x)^2");
const steps = out.steps as any[]; // each item is a JsTraceStep
for (const s of steps) {
  // JsTraceStep has getters: depth, kind, operation, description, expr
  console.log(
    `${s.depth}: ${s.kind} — ${s.operation} — ${s.description} — ${s.expr}`
  );
}

Notes:

• kind is one of "enter" | "exit" | "step" | "note".
• Use JsStepRecorder's formatSteps() for a single formatted string, or steps() for structured JsTraceStep objects.

Step-by-Step Solutions (Educational Mode)

Star provides a step-by-step tracing system intended for educational display and debugging. Two routes are available in the package:

1. Quick helper: traceSimplify(expr: string) — runs a simplification with tracing and returns a JsTraceResult (contains .result and .steps).

import init, { traceSimplify } from "@lumilla/star";
await init();
const out = traceSimplify("(x+1)^2");
console.log(out.result.toString());
console.log(out.steps.join("\n"));

2. Structured inspection: JsStepRecorder and JsTraceStep provide a typed, per-step view for programmatic analysis.

import init, { JsStepRecorder, traceSimplify } from "@lumilla/star";
await init();
const rec = new JsStepRecorder();
rec.setLevel("verbose");

// The quick helper returns a JsTraceResult, suitable for display, while recorder
// usage allows you to programmatically inspect steps when you integrate the
// tracer into your application's control flow.
const out = traceSimplify("sin(x)^2 + cos(x)^2");
for (const s of out.steps as any[]) {
  console.log(
    `${s.depth}: ${s.kind} — ${s.operation} — ${s.description} — ${s.expr}`
  );
}

Key Features:

• Near-zero overhead when disabled
• Low overhead when enabled; suitable for interactive educational use
• Step-by-step recording for simplification and solving

Batteries included

The prebuilt npm package includes parsing, LaTeX input support, tracing, and TypeScript definitions. Consumers installing @lumilla/star from npm get the runtime-ready WASM binary and the generated TypeScript declarations

Prebuilt artifacts

This npm package distributes prebuilt WASM artifacts (star_bg.wasm) together with a JS wrapper and TypeScript declarations (star.js, star.d.ts) ready to use in browsers, (and likely node.js). For usage examples and API details at this time, check the generated TypeScript types file.