@jarenjs/calc 0.34.0

package/README.md

@@ -0,0 +1,60 @@
+# @jarenjs/calc
+
+A native, headless **multi-mode calculator** for the jarenjs stack:
+standard / scientific / programmer / financial / converter, with **x·y and
+x·y·z plotting rendered as pure-vnode SVG** through `@jarenjs/view`. The
+calculator *is* an `@jarenjs/app` document (state is JSON, keys are data
+bindings, transitions are copy-on-write RFC-6902 patches), and it is built
+on `@jarenjs/core` — it holds no formulas or unit factors of its own.
+
+Zero runtime dependencies beyond `@jarenjs/*`. No `eval`, no `new
+Function` (CSP-safe). SSR-able and deterministic.
+
+## Two layers
+
+- **Engine** (`@jarenjs/calc`) — pure functions over data. A two-stage
+  expression compiler `parseExpression(text) → ExprAST → compileExpr →
+  (scope) => value`, its canonical printer `toExpression` (a round-trip
+  fixed point), and `plot2d`/`plot3d`/`calcToVnode` (pure-vnode SVG).
+  Imports only `@jarenjs/core` + `@jarenjs/view`.
+- **Component** (`@jarenjs/calc/component`) — the `@jarenjs/app` glue:
+  `createCalcComponent()` → `{ initialState, actions, mode, rules,
+  effects, subs, viewModel, createApp }`, the keypad/panel JSLT view, the
+  financial `@jarenjs/forms` panel, and the live crypto/fiat rates layer.
+
+```js
+import { evaluate, parseExpression, toExpression, plot2d, toSvgString } from '@jarenjs/calc';
+
+evaluate('sin(pi/2) + 2^10').value;          // 1025
+toExpression(parseExpression('a-(b-c)'));    // "a - (b - c)"
+toSvgString(plot2d('sin(x)', { domain: [-6.28, 6.28] })); // standalone SVG
+```
+
+```js
+import { createCalcComponent } from '@jarenjs/calc/component';
+const calc = createCalcComponent({ provider: 'coingecko' });
+const app = calc.createApp({ node: document.getElementById('calc') });
+```
+
+## The numeric kernel lives in `@jarenjs/core`
+
+Reusable primitives were pushed *down* into core, so any package can use
+them: `@jarenjs/core/math` (transcendentals, `word.js` BigInt word math,
+`solve.js` root finders, `mat4`/`project.js` 3D kernel, `format.js`),
+`@jarenjs/core/finance` (TVM, cash-flow, amortization, interest,
+depreciation, bond, indicators, returns) and `@jarenjs/core/convert`
+(fixed-factor dimensional conversion + the pure `convertCurrency` rate-table
+primitive). The calculator's financial mode calls `core/finance`; its
+converter calls `core/convert`. Core is pure and never fetches.
+
+## Live currency (the maturity example)
+
+The converter's currency dimension takes live crypto+fiat rates from free
+public tickers (CoinGecko default, Binance alternative) through an
+`@jarenjs/app` effect + a `when`-gated polling subscription. The **pure
+conversion** is `@jarenjs/core/convert`'s `convertCurrency`; only the
+*fetch* is component-side. A static fallback table keeps the converter,
+SSR and offline tests working with no network; failures route to an error
+action.
+
+See `docs/CALC-FORMAT.md` and `ARCHITECTURE.md` for the full contract.

package/dist/types/ast.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @file The expression AST. Monomorphic node
+ * constructors — one plain-object shape per kind — so the compiler and
+ * printer branch on a single `type` tag and the reconciler/`deepEqual`
+ * round-trip stays cheap. The AST is **geometry-free**: it carries no
+ * layout, no source formatting (not even a literal's original radix), so
+ * that `parseExpression(toExpression(ast))` deep-equals `ast`. Meaning is
+ * imposed later — by `compileExpr` (evaluation) or the plotter
+ * (projection), never by the parser.
+ */
+export declare const CALC_AST_VERSION = "0.13.0";
+/** Numeric literal (value only — the radix/format is not preserved). */
+export declare function num(value: any): {
+    type: string;
+    value: number;
+};
+/** A named constant (`pi`, `e`, `phi`, `tau`, `inf`, `nan`). */
+export declare function constant(name: any): {
+    type: string;
+    name: any;
+};
+/** A variable / free identifier (`x`, `y`, `ans`, `mem`). */
+export declare function variable(name: any): {
+    type: string;
+    name: any;
+};
+/** A prefix unary node (`-`, `+`, `~`). */
+export declare function unary(op: any, arg: any): {
+    type: string;
+    op: any;
+    arg: any;
+};
+/** A postfix node (`!` factorial, `%` percent). */
+export declare function postfix(op: any, arg: any): {
+    type: string;
+    op: any;
+    arg: any;
+};
+/** A binary node (`+ - * / ^ & | << >>`). */
+export declare function binary(op: any, left: any, right: any): {
+    type: string;
+    op: any;
+    left: any;
+    right: any;
+};
+/** A function call (`sin(x)`, `log(2, 8)`, `xor(a, b)`). */
+export declare function call(name: any, args: any): {
+    type: string;
+    name: any;
+    args: any;
+};
+/**
+ * Free identifiers that always denote a constant rather than a variable.
+ * @type {Record<string, number>}
+ */
+export declare const CONSTANTS: Record<string, number>;
+/** Is `name` a known constant identifier? */
+export declare function isConstant(name: any): boolean;
+/**
+ * Structural equality for ASTs (used by the round-trip fixed-point
+ * tests). NaN compares equal to NaN so `nan` literals round-trip.
+ * @param {any} a @param {any} b
+ * @returns {boolean}
+ */
+export declare function astEqual(a: any, b: any): boolean;

package/dist/types/compile.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file `compileExpr(ast, opts) → (scope) => number`. The second stage of
+ * the two-stage compiler: every dispatch decision — which operator
+ * closure, which function, whether an identifier is a constant — is made
+ * once, here, and baked into a nested closure. Evaluation then does no
+ * lookups on the hot path. No `eval`, no `new Function` (CSP-safe).
+ *
+ * `evaluate(source, scope?, opts?)` is the error-safe front door: it
+ * parses, compiles and runs, returning a tagged `{ ok, value } | { ok:
+ * false, error }` result so the app/render path never throws.
+ */
+/**
+ * Compile an AST against an environment.
+ * @param {any} ast
+ * @param {{ env?: any }} [opts]
+ * @returns {(scope?: any) => number}
+ */
+export declare function compileExpr(ast: any, opts?: {
+    env?: any;
+}): (scope?: any) => number;
+export type EvalOk = {
+    ok: true;
+    value: number;
+};
+export type EvalErr = {
+    ok: false;
+    error: {
+        message: string;
+        line?: number;
+        column?: number;
+    };
+};
+/**
+ * @typedef {object} EvalOk
+ * @property {true} ok
+ * @property {number} value
+ */
+/**
+ * @typedef {object} EvalErr
+ * @property {false} ok
+ * @property {{ message: string, line?: number, column?: number }} error
+ */
+/**
+ * Parse + compile + evaluate a source expression, error-safe.
+ * @param {string} source
+ * @param {any} [scope]
+ * @param {{ env?: any }} [opts]
+ * @returns {EvalOk | EvalErr}
+ */
+export declare function evaluate(source: string, scope?: any, opts?: {
+    env?: any;
+}): EvalOk | EvalErr;

package/dist/types/component/index.d.ts

@@ -0,0 +1,259 @@
+/**
+ * @file The Calculator COMPONENT — part two of the package. Everything
+ * here is presentation + app glue; the engine knows none of it. `createCalcComponent(options)` returns the
+ * pieces the site (and a standalone `createApp`) compose into one
+ * `@jarenjs/app` document:
+ *
+ *  - `initialState()` — the plain-JSON `$.calc` slice (immutable, COW).
+ *  - `actions` — key/mode/plot/converter action query documents + the
+ *    financial `@jarenjs/forms` write actions.
+ *  - `mode` + `rules` — the JSLT `calculator` view (keypad, display, tape,
+ *    mode menu, plot panel, financial form, converter).
+ *  - `effects` / `subs` / `subEntry` — the live-rates effect + `when`-gated
+ *    poll; the pure conversion stays in `@jarenjs/core/convert`.
+ *  - `viewModel(state)` (a.k.a. `contributeCalcViewModel`) — the derivation
+ *    boundary: display string, live result, four-base views, plot vnode,
+ *    forms model, converter options — none of it stored in state.
+ *  - `createApp()` — a standalone app document for reuse outside the site.
+ *
+ * The boundary is one-way: the component imports the engine, never the
+ * reverse.
+ */
+/**
+ * Namespaced form action names so the financial panel never collides with
+ * another `@jarenjs/forms` instance on the same page (e.g. the website's
+ * schema playground, which also spreads `createFormActions`).
+ */
+export declare const FORM_ACTIONS: {
+    input: string;
+    check: string;
+    number: string;
+    add: string;
+    remove: string;
+};
+/** The financial form's view rules (mode 'calculator'), reusable by the site. */
+export declare const calcFormViewRules: any[];
+/**
+ * The initial `$.calc` state slice.
+ * @returns {any}
+ */
+export declare function calcInitialState(): any;
+/**
+ * The action query documents. `dataPointer` for the financial form is
+ * `/calc/fin`.
+ * @returns {Record<string, any>}
+ */
+export declare const calcActions: {
+    'calc/key': {
+        patch: {
+            op: string;
+            path: string;
+            value: {
+                $concat: string[];
+            };
+        }[];
+    };
+    'calc/clear': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'calc/set-entry': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'calc/back': {
+        effects: {
+            run: string;
+            with: {
+                entry: string;
+            };
+        }[];
+    };
+    'calc/equals': {
+        effects: {
+            run: string;
+            with: {
+                entry: string;
+                mode: string;
+                angleMode: string;
+                wordBits: string;
+                signed: string;
+                ans: string;
+                memory: string;
+            };
+        }[];
+    };
+    'calc/commit': {
+        patch: ({
+            op: string;
+            path: string;
+            value: string;
+        } | {
+            op: string;
+            path: string;
+            value: {
+                expr: string;
+                result: string;
+            };
+        })[];
+    };
+    'calc/mode': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'calc/angle': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'calc/base': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'calc/word': {
+        patch: {
+            op: string;
+            path: string;
+            value: {
+                $number: string;
+            };
+        }[];
+    };
+    'calc/sign': {
+        patch: {
+            op: string;
+            path: string;
+            value: {
+                $if: (string | boolean)[];
+            };
+        }[];
+    };
+    'calc/mem-add': {
+        patch: {
+            op: string;
+            path: string;
+            value: {
+                $add: string[];
+            };
+        }[];
+    };
+    'calc/mem-clear': {
+        patch: {
+            op: string;
+            path: string;
+            value: number;
+        }[];
+    };
+    'calc/plot-expr': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'calc/plot-kind': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'calc/conv-dim': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'calc/conv-from': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'calc/conv-to': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'calc/conv-value': {
+        patch: {
+            op: string;
+            path: string;
+            value: {
+                $number: string;
+            };
+        }[];
+    };
+    'calc/conv-swap': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'calc/rates-refresh': {
+        effects: {
+            run: string;
+            with: {
+                force: boolean;
+            };
+        }[];
+    };
+    'calc/rates-ok': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'calc/rates-err': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+};
+/** All calculator view rules (the calculator UI + the financial form). */
+export declare const calcViewRules: any[];
+export { createRatesLayer, FALLBACK_RATES, CURRENCY_CODES } from './rates/index.js';
+/** The `calc-edit` (backspace) and `calc-eval` (=) JS effect handlers. */
+export declare const calcEditEffects: {
+    'calc-edit': (props: any, dispatch: any) => void;
+    'calc-eval': (props: any, dispatch: any) => void;
+};
+/**
+ * The viewModel derivation for the calculator (`contributeCalcViewModel`).
+ * Pure: state in, UI document out, no dispatching.
+ * @param {any} state
+ * @param {{ theme?: any }} [options] plot theme (name, overrides, or
+ *   `'host'` to follow the embedding host's tokens)
+ * @returns {any}
+ */
+export declare function contributeCalcViewModel(state: any, options?: {
+    theme?: any;
+}): any;
+/**
+ * Create the calculator component.
+ * @param {import('./rates/index.js').RatesLayerOptions} [options]
+ * @returns {any}
+ */
+export declare function createCalcComponent(options?: import('./rates/index.js').RatesLayerOptions): any;

package/dist/types/component/rates/binance.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file The Binance rate adapter (alternative provider). Reads
+ * `/api/v3/ticker/price` (crypto USDT pairs), no key. Same one-way rule:
+ * fetch + normalize only; conversion is core's `convertCurrency`.
+ */
+/**
+ * Normalize a Binance ticker list into `{ base, rates, at }`. Only
+ * `*USDT` pairs are used; the base is USDT (≈ USD, also mapped to USD 1).
+ * @param {Array<{symbol:string, price:string|number}>} data @param {number} at
+ * @returns {{ base: string, rates: Record<string, number>, at: number }}
+ */
+export declare function normalizeBinance(data: Array<{
+    symbol: string;
+    price: string | number;
+}>, at?: number): {
+    base: string;
+    rates: Record<string, number>;
+    at: number;
+};
+/**
+ * Fetch and normalize Binance rates.
+ * @param {string[]} codes
+ * @param {{ fetch?: typeof globalThis.fetch, endpoint?: string, at?: number }} [opts]
+ * @returns {Promise<{ base: string, rates: Record<string, number>, at: number }>}
+ */
+export declare function fetchBinance(codes: string[], opts?: {
+    fetch?: typeof globalThis.fetch;
+    endpoint?: string;
+    at?: number;
+}): Promise<{
+    base: string;
+    rates: Record<string, number>;
+    at: number;
+}>;

package/dist/types/component/rates/coingecko.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file The CoinGecko rate adapter. The **only**
+ * network code path for the default provider — it fetches and normalizes,
+ * nothing more. The pure conversion is `@jarenjs/core/convert`'s
+ * `convertCurrency`, never here. No API key; fiat *and* crypto in one
+ * call, everything priced through a USD base. `fetch` is injectable for
+ * tests; `endpoint` is overridable.
+ */
+/** Known CoinGecko ids ↔ ticker symbols. */
+export declare const COINGECKO_IDS: {
+    bitcoin: string;
+    ethereum: string;
+    tether: string;
+    binancecoin: string;
+    solana: string;
+    cardano: string;
+    ripple: string;
+    dogecoin: string;
+};
+/**
+ * Normalize a `/simple/price` response into the common
+ * `{ base, rates, at }` shape. Crypto prices are USD directly; fiat rates
+ * are derived through the bitcoin pivot (rate[FIAT] = btc_usd / btc_fiat
+ * = value of one FIAT unit in USD).
+ * @param {any} data @param {string[]} codes @param {number} at
+ * @returns {{ base: string, rates: Record<string, number>, at: number }}
+ */
+export declare function normalizeCoinGecko(data: any, codes: string[], at?: number): {
+    base: string;
+    rates: Record<string, number>;
+    at: number;
+};
+/**
+ * Fetch and normalize rates for `codes`.
+ * @param {string[]} codes
+ * @param {{ fetch?: typeof globalThis.fetch, endpoint?: string, at?: number }} [opts]
+ * @returns {Promise<{ base: string, rates: Record<string, number>, at: number }>}
+ */
+export declare function fetchCoinGecko(codes: string[], opts?: {
+    fetch?: typeof globalThis.fetch;
+    endpoint?: string;
+    at?: number;
+}): Promise<{
+    base: string;
+    rates: Record<string, number>;
+    at: number;
+}>;

package/dist/types/component/rates/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @file The rates layer — the component's impure
+ * half. It owns the `rates-fetch` effect and the `rates-poll`
+ * subscription, choosing a provider adapter, debouncing to a min refresh
+ * interval, and routing success/failure to app actions. It normalizes a
+ * rate table into `$.calc.rates`; the **conversion itself** is
+ * `@jarenjs/core/convert`'s pure `convertCurrency`, never here.
+ *
+ * Resilience is the point: a static `FALLBACK_RATES` table keeps the
+ * converter, SSR and offline tests working with no network; live rates
+ * layer on top only when a fetch succeeds; failures route to an error
+ * action.
+ */
+export { fetchCoinGecko, normalizeCoinGecko, COINGECKO_IDS } from './coingecko.js';
+export { fetchBinance, normalizeBinance } from './binance.js';
+/** The currency codes the converter offers (fiat + crypto). */
+export declare const CURRENCY_CODES: string[];
+/**
+ * The static last-resort table (value of one unit in USD). Deterministic,
+ * so tests / SSR / offline all render a real conversion with no network.
+ * @type {{ base: string, rates: Record<string, number>, at: number, stale: boolean, status: string }}
+ */
+export declare const FALLBACK_RATES: {
+    base: string;
+    rates: Record<string, number>;
+    at: number;
+    stale: boolean;
+    status: string;
+};
+export type RatesLayerOptions = {
+    provider?: 'coingecko' | 'binance' | ((codes: string[], o: any) => Promise<any>);
+    /**
+     * minimum interval between live fetches (debounce)
+     */
+    refreshMs?: number;
+    fetch?: typeof globalThis.fetch;
+    endpoint?: string;
+    codes?: string[];
+    /**
+     * clock (injectable for tests)
+     */
+    now?: () => number;
+    fallbackRates?: any;
+};
+/**
+ * @typedef {object} RatesLayerOptions
+ * @property {'coingecko'|'binance'|((codes:string[],o:any)=>Promise<any>)} [provider]
+ * @property {number} [refreshMs] minimum interval between live fetches (debounce)
+ * @property {typeof globalThis.fetch} [fetch]
+ * @property {string} [endpoint]
+ * @property {string[]} [codes]
+ * @property {() => number} [now] clock (injectable for tests)
+ * @property {any} [fallbackRates]
+ */
+/**
+ * Build the rates layer: the `rates-fetch` effect handler, the
+ * `rates-poll` subscription handler, the subscription entry and the
+ * fallback table.
+ * @param {RatesLayerOptions} [options]
+ */
+export declare function createRatesLayer(options?: RatesLayerOptions): {
+    effects: {
+        /** `{ run: 'rates-fetch', with?: { force?: boolean } }`. */
+        'rates-fetch': (props: any, dispatch: any) => void;
+    };
+    subs: {
+        /**
+         * `rates-poll`: kicks an immediate fetch and repeats every
+         * `refreshMs`; the cleanup stops the timer. The app only starts it
+         * while the `when` gate holds (converter + currency).
+         */
+        'rates-poll': (props: any, dispatch: any) => () => void;
+    };
+    subEntry: {
+        run: string;
+        when: {
+            $and: {
+                $eq: string[];
+            }[];
+        };
+    };
+    fallbackRates: any;
+    codes: string[];
+};