@danielsimonjr/mathts-expression 0.9.0 → 0.10.0

package/README.md

@@ -15,6 +15,7 @@ npm install @danielsimonjr/mathts-expression
 - `createParse` / `createParserClass` / `createParser` — parse to an AST.
 - 16 AST node constructors (`createConstantNode`, `createOperatorNode`, …).
 - `compile` / `createEvaluate` / `compileExpression` — evaluate expressions.
+- `createScalarBuilder` — build a scalar node tree (`number`, `symbol`, `op`, `call`, `from`). `ln` lowers to natural `log` and `log` lowers to `log10`. A formula string is rejected. Evaluate with `evaluateScalar` from `@danielsimonjr/mathts-functions`.
 - AST serializers on every node: `toString()`, `toTex()` (LaTeX), `toHTML()`, and `toMathML()` (MathML).
 - Focused re-exports are also published: `@danielsimonjr/mathts-{parser,ast,evaluator}`.
 

package/dist/index.d.ts

@@ -32,5 +32,7 @@ export { createParenthesisNode } from './node/ParenthesisNode.js';
 export { createRangeNode } from './node/RangeNode.js';
 export { createRelationalNode } from './node/RelationalNode.js';
 export { createSymbolNode } from './node/SymbolNode.js';
+export { createScalarBuilder, SCALAR_FUNCTIONS, SCALAR_FUNCTION_LOWERING, ScalarBuildError, } from './scalar-builder.js';
+export type { LoweredScalarFn, ScalarBuilder, ScalarFunctionName, ScalarNode, ScalarOperator, } from './scalar-builder.js';
 export * from './transform/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC9D,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AAMrC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAG9F,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,4BAA4B,EAAE,MAAM,kCAAkC,CAAC;AAChF,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAKxD,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC9D,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AAMrC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAG9F,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,4BAA4B,EAAE,MAAM,kCAAkC,CAAC;AAChF,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,UAAU,EACV,cAAc,GACf,MAAM,qBAAqB,CAAC;AAK7B,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -12409,6 +12409,161 @@ var createSymbolNode = /* @__PURE__ */ factory(
   { isClass: true, isNode: true }
 );
 
+// src/scalar-builder.ts
+var SCALAR_FUNCTION_LOWERING = {
+  exp: "exp",
+  ln: "log",
+  log: "log10",
+  log2: "log2",
+  log10: "log10",
+  sin: "sin",
+  cos: "cos",
+  tan: "tan",
+  sinh: "sinh",
+  cosh: "cosh",
+  tanh: "tanh",
+  abs: "abs"
+};
+var SCALAR_FUNCTIONS = [
+  "exp",
+  "ln",
+  "log",
+  "log2",
+  "log10",
+  "sin",
+  "cos",
+  "tan",
+  "sinh",
+  "cosh",
+  "tanh",
+  "abs"
+];
+var LOWERED_FUNCTIONS = new Set(Object.values(SCALAR_FUNCTION_LOWERING));
+var ScalarBuildError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ScalarBuildError";
+  }
+};
+var OPERATORS = /* @__PURE__ */ new Set(["+", "-", "*", "/", "^"]);
+function isOperator(op) {
+  return OPERATORS.has(op);
+}
+function isScalarFunctionName(fn) {
+  return Object.prototype.hasOwnProperty.call(SCALAR_FUNCTION_LOWERING, fn);
+}
+function isLoweredScalarFn(fn) {
+  return LOWERED_FUNCTIONS.has(fn);
+}
+function isCanonicalNode(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const kind = value.kind;
+  return kind === "number" || kind === "symbol" || kind === "op" || kind === "call";
+}
+function readRecord(node) {
+  if (typeof node === "string") {
+    throw new ScalarBuildError(
+      "scalar builder reads a typed node. A formula string is not accepted."
+    );
+  }
+  if (typeof node !== "object" || node === null || Array.isArray(node)) {
+    throw new ScalarBuildError("scalar builder reads a typed node");
+  }
+  return node;
+}
+function createScalarBuilder() {
+  function number(value) {
+    if (typeof value !== "number") {
+      throw new ScalarBuildError("scalar number node requires a number value");
+    }
+    return { kind: "number", value };
+  }
+  function symbol(name47) {
+    if (typeof name47 !== "string") {
+      throw new ScalarBuildError("scalar symbol node requires a string name");
+    }
+    return { kind: "symbol", name: name47 };
+  }
+  function call(fn, arg) {
+    if (!isScalarFunctionName(fn)) {
+      throw new ScalarBuildError(`unknown scalar function '${String(fn)}'`);
+    }
+    if (!isCanonicalNode(arg)) {
+      throw new ScalarBuildError("scalar call argument must be a scalar node");
+    }
+    return { kind: "call", fn: SCALAR_FUNCTION_LOWERING[fn], arg };
+  }
+  function op(operator, args) {
+    if (!isOperator(operator)) {
+      throw new ScalarBuildError(`unknown scalar operator '${String(operator)}'`);
+    }
+    if (!Array.isArray(args)) {
+      throw new ScalarBuildError("scalar operator args must be an array of scalar nodes");
+    }
+    const copied = [];
+    for (const arg of args) {
+      if (!isCanonicalNode(arg)) {
+        throw new ScalarBuildError("scalar operator argument must be a scalar node");
+      }
+      copied.push(arg);
+    }
+    if (operator === "^" && copied.length !== 2) {
+      throw new ScalarBuildError(`'^' needs exactly 2 args, got ${copied.length}`);
+    }
+    return { kind: "op", op: operator, args: copied };
+  }
+  function from(node) {
+    const record = readRecord(node);
+    const kind = record.kind;
+    if (typeof kind !== "string") {
+      throw new ScalarBuildError("scalar node is missing a string kind");
+    }
+    switch (kind) {
+      case "number":
+        return number(record.value);
+      case "symbol":
+        return symbol(record.name);
+      case "op": {
+        const operator = record.op;
+        if (typeof operator !== "string" || !isOperator(operator)) {
+          throw new ScalarBuildError(`unknown scalar operator '${String(operator)}'`);
+        }
+        const args = record.args;
+        if (!Array.isArray(args)) {
+          throw new ScalarBuildError("scalar operator node is missing args");
+        }
+        return op(
+          operator,
+          args.map((arg) => from(arg))
+        );
+      }
+      case "call": {
+        const fn = record.fn;
+        if (typeof fn !== "string" || !isLoweredScalarFn(fn)) {
+          throw new ScalarBuildError(
+            `scalar call '${String(fn)}' must already use a lowered MathTS name`
+          );
+        }
+        return { kind: "call", fn, arg: from(record.arg) };
+      }
+      case "transcendental": {
+        const fn = record.fn;
+        if (typeof fn !== "string" || !isScalarFunctionName(fn)) {
+          throw new ScalarBuildError(`unknown scalar function '${String(fn)}'`);
+        }
+        return call(fn, from(record.arg));
+      }
+      case "abs":
+        return call("abs", from(record.arg));
+      default:
+        throw new ScalarBuildError(
+          `scalar builder: node kind '${kind}' is out of scope (symbol, op, transcendental, abs)`
+        );
+    }
+  }
+  return { number, symbol, op, call, from };
+}
+
 // src/transform/and.transform.ts
 var name21 = "and";
 var dependencies21 = ["and"];
@@ -13184,6 +13339,9 @@ var createVarianceTransform = /* @__PURE__ */ factory(
   { isTransformFunction: true }
 );
 export {
+  SCALAR_FUNCTIONS,
+  SCALAR_FUNCTION_LOWERING,
+  ScalarBuildError,
   compile,
   compileExpression,
   createAccessorNode,
@@ -13227,6 +13385,7 @@ export {
   createRangeTransform,
   createRelationalNode,
   createRowTransform,
+  createScalarBuilder,
   createStdTransform,
   createSubsetTransform,
   createSumTransform,

package/dist/scalar-builder.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Public scalar-expression builder.
+ *
+ * UPT lowers an `ExprNode` numeric tree onto this API instead of printing a
+ * formula and parsing it. `call('ln', x)` and a `transcendental` node whose
+ * `fn` is `ln` store MathTS natural `log`. `call('log', x)` and `fn: 'log'`
+ * store `log10`. `log10` and `log2` stay themselves.
+ *
+ * The node returned by {@link ScalarBuilder.call} and {@link ScalarBuilder.from}
+ * already carries the lowered MathTS name on `fn`. Passing that node through
+ * `from` again keeps natural `log`; it does not treat it as base-10.
+ *
+ * @packageDocumentation
+ */
+/** Operators on the scalar numeric path (`+ - * / ^`). */
+export type ScalarOperator = '+' | '-' | '*' | '/' | '^';
+/**
+ * Input names accepted by {@link ScalarBuilder.call} and by a
+ * `transcendental` node. `ln` and `log` are in this set; the stored node uses
+ * the lowered name from {@link SCALAR_FUNCTION_LOWERING}.
+ */
+export declare const SCALAR_FUNCTION_LOWERING: {
+    readonly exp: 'exp';
+    readonly ln: 'log';
+    readonly log: 'log10';
+    readonly log2: 'log2';
+    readonly log10: 'log10';
+    readonly sin: 'sin';
+    readonly cos: 'cos';
+    readonly tan: 'tan';
+    readonly sinh: 'sinh';
+    readonly cosh: 'cosh';
+    readonly tanh: 'tanh';
+    readonly abs: 'abs';
+};
+/** Names a caller may pass to {@link ScalarBuilder.call}. */
+export type ScalarFunctionName = keyof typeof SCALAR_FUNCTION_LOWERING;
+/** MathTS function stored on a built call node. */
+export type LoweredScalarFn = (typeof SCALAR_FUNCTION_LOWERING)[ScalarFunctionName];
+/**
+ * Input names, in lowering-table order. Present so a consumer can see the
+ * scalar set without parsing a formula.
+ */
+export declare const SCALAR_FUNCTIONS: readonly ScalarFunctionName[];
+/** A scalar node. Call `fn` is the lowered MathTS name. */
+export type ScalarNode = {
+    readonly kind: 'number';
+    readonly value: number;
+} | {
+    readonly kind: 'symbol';
+    readonly name: string;
+} | {
+    readonly kind: 'op';
+    readonly op: ScalarOperator;
+    readonly args: readonly ScalarNode[];
+} | {
+    readonly kind: 'call';
+    readonly fn: LoweredScalarFn;
+    readonly arg: ScalarNode;
+};
+/** Builds {@link ScalarNode} values. Each call returns a new builder. */
+export interface ScalarBuilder {
+    /** A numeric leaf. `value` must be a number (finite or not). */
+    number(value: number): ScalarNode;
+    /** A named leaf. Resolution of the name happens at evaluation. */
+    symbol(name: string): ScalarNode;
+    /**
+     * An operator node. `^` requires exactly two arguments. `+`, `-`, `*`, and
+     * `/` may be empty or n-ary; evaluation folds them left to right.
+     */
+    op(op: ScalarOperator, args: readonly ScalarNode[]): ScalarNode;
+    /**
+     * A unary call. `ln` is stored as `log` (natural). `log` is stored as
+     * `log10`.
+     */
+    call(fn: ScalarFunctionName, arg: ScalarNode): ScalarNode;
+    /**
+     * Normalize a typed tree. Accepts builder nodes and the scalar arms
+     * `symbol`, `op`, `transcendental`, and `abs`. A string is rejected.
+     */
+    from(node: unknown): ScalarNode;
+}
+/** A node or name the builder cannot represent. */
+export declare class ScalarBuildError extends Error {
+    constructor(message: string);
+}
+/**
+ * A builder of scalar nodes. Safe to call more than once; builders share no
+ * mutable state.
+ */
+export declare function createScalarBuilder(): ScalarBuilder;
+//# sourceMappingURL=scalar-builder.d.ts.map

package/dist/scalar-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalar-builder.d.ts","sourceRoot":"","sources":["../src/scalar-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,0DAA0D;AAC1D,MAAM,MAAM,cAAc,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;aACnC,GAAG,EAAE,KAAK;aACV,EAAE,EAAE,KAAK;aACT,GAAG,EAAE,OAAO;aACZ,IAAI,EAAE,MAAM;aACZ,KAAK,EAAE,OAAO;aACd,GAAG,EAAE,KAAK;aACV,GAAG,EAAE,KAAK;aACV,GAAG,EAAE,KAAK;aACV,IAAI,EAAE,MAAM;aACZ,IAAI,EAAE,MAAM;aACZ,IAAI,EAAE,MAAM;aACZ,GAAG,EAAE,KAAK;CACF,CAAC;AAEX,6DAA6D;AAC7D,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AAEvE,mDAAmD;AACnD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,kBAAkB,CAAC,CAAC;AAEpF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,kBAAkB,EAahD,CAAC;AAIX,2DAA2D;AAC3D,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,GAC1F;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;CAAE,CAAC;AAEtF,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;IAClC,kEAAkE;IAClE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IACjC;;;OAGG;IACH,EAAE,CAAC,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,CAAC;IAChE;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,kBAAkB,EAAE,GAAG,EAAE,UAAU,GAAG,UAAU,CAAC;IAC1D;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAAC;CACjC;AAED,mDAAmD;AACnD,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAkCD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAgGnD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/mathts-expression",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Expression parser and evaluator for MathTS",
   "author": "Daniel Simon Jr.",
   "license": "MIT",