@molecule/api-formula-engine 1.0.0

package/dist/sheet.d.ts

@@ -0,0 +1,130 @@
+/**
+ * High-level Sheet engine.
+ *
+ * Wraps the parser, evaluator, and dependency tracker into a small,
+ * stateful container modelled after a single-sheet spreadsheet. All
+ * mutation happens through `setValue` / `setFormula` / `clear`; reads
+ * happen through `getValue` (returns the most recently computed value)
+ * and `getFormula` (returns the formula text, if any).
+ *
+ * Sheets are *pure data containers* — no I/O, no DB, no async. They
+ * are intentionally small so they can be embedded inside a larger
+ * resource (e.g. a `Spreadsheet` resource handler) which is
+ * responsible for persistence.
+ *
+ * @example
+ * ```typescript
+ * import { Sheet } from '@molecule/api-formula-engine'
+ *
+ * const sheet = new Sheet()
+ * sheet.setValue('A1', 10)
+ * sheet.setValue('A2', 20)
+ * sheet.setFormula('A3', '=SUM(A1:A2)')
+ * sheet.getValue('A3') // → 30
+ *
+ * sheet.setValue('A1', 100)
+ * sheet.getValue('A3') // → 120 (auto-recomputed)
+ * ```
+ *
+ * @module
+ */
+import type { CellCoord, CellValue, EvaluateOptions, SheetConfig } from './types.js';
+/**
+ * In-memory single-sheet engine. References use A1 notation (`A1`,
+ * `$A$1`, `BC42`).
+ */
+export declare class Sheet {
+    private readonly cells;
+    /** dependent-of[key] = set of cells that reference `key`. */
+    private readonly dependents;
+    private readonly config;
+    /**
+     * Create a new Sheet with optional dimension limits.
+     *
+     * @param config - Sheet configuration.
+     */
+    constructor(config?: SheetConfig);
+    /**
+     * Set a literal value at a cell.
+     *
+     * @param ref - A1-style cell reference (e.g. `A1`, `$B$3`).
+     * @param value - Literal value (number, string, boolean, Date, or null).
+     * @param options - Evaluation options forwarded to recompute.
+     */
+    setValue(ref: string, value: CellValue, options?: EvaluateOptions): void;
+    /**
+     * Set a formula at a cell. The formula text may include or omit the
+     * leading `=`. The formula is parsed eagerly and `#NAME?` /
+     * `#VALUE!` errors caused by parser failures are stored as the
+     * cell's value.
+     *
+     * @param ref - A1-style cell reference.
+     * @param formula - Formula text (e.g. `=SUM(A1:A10)` or `SUM(A1:A10)`).
+     * @param options - Evaluation options forwarded to recompute.
+     */
+    setFormula(ref: string, formula: string, options?: EvaluateOptions): void;
+    /**
+     * Clear a cell (remove value, formula, and dependency edges).
+     *
+     * @param ref - A1-style cell reference.
+     * @param options - Evaluation options forwarded to recompute.
+     */
+    clear(ref: string, options?: EvaluateOptions): void;
+    /**
+     * Read the most recently computed value for a cell.
+     *
+     * @param ref - A1-style cell reference.
+     * @returns Cell value (`null` if the cell is empty).
+     */
+    getValue(ref: string): CellValue;
+    /**
+     * Return the formula text for a cell, or `null` if the cell holds a
+     * literal value or is empty.
+     *
+     * @param ref - A1-style cell reference.
+     * @returns Formula text (with leading `=`) or `null`.
+     */
+    getFormula(ref: string): string | null;
+    /**
+     * Recompute every formula cell. Useful after bulk edits or when
+     * `now()` semantics change.
+     *
+     * @param options - Evaluation options.
+     */
+    recomputeAll(options?: EvaluateOptions): void;
+    /**
+     * Evaluate a free-standing formula string against this sheet's data.
+     * Does NOT mutate the sheet. Useful for ad-hoc evaluations such as
+     * invoice line-item totals or computed-column previews.
+     *
+     * @param formula - Formula text.
+     * @param options - Evaluation options.
+     * @returns Evaluated cell value.
+     */
+    evaluateFormula(formula: string, options?: EvaluateOptions): CellValue;
+    /**
+     * Parse an A1-style reference string into a validated CellCoord.
+     */
+    private refToCoord;
+    /**
+     * Write a cell record, rewire dependency edges, and trigger downstream recompute.
+     */
+    private assignCell;
+    /**
+     * Recompute all formula cells that transitively depend on the given key.
+     */
+    private recomputeDownstream;
+    /**
+     * Evaluate (or propagate) the computed value for a single cell key.
+     */
+    private evaluateKey;
+}
+/**
+ * Reformat a cell coordinate as A1-style text. Re-exported for
+ * convenience.
+ *
+ * @param coord - Cell coordinate.
+ * @returns A1-style reference text.
+ */
+export declare function refOf(coord: CellCoord): string;
+//# sourceMappingURL=sheet.d.ts.map

package/dist/sheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sheet.d.ts","sourceRoot":"","sources":["../src/sheet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH,OAAO,KAAK,EAAW,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAqB7F;;;GAGG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiC;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAE9C;;;;OAIG;gBACS,MAAM,GAAE,WAAgB;IAIpC;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI;IAK5E;;;;;;;;;OASG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI;IAgB7E;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI;IAavD;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS;IAOhC;;;;;;OAMG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAMtC;;;;;OAKG;IACH,YAAY,CAAC,OAAO,GAAE,eAAoB,GAAG,IAAI;IAWjD;;;;;;;;OAQG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,SAAS;IAY1E;;OAEG;IACH,OAAO,CAAC,UAAU;IASlB;;OAEG;IACH,OAAO,CAAC,UAAU;IAuClB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA0B3B;;OAEG;IACH,OAAO,CAAC,WAAW;CA0BpB;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAE9C"}

package/dist/sheet.js

@@ -0,0 +1,291 @@
+/**
+ * High-level Sheet engine.
+ *
+ * Wraps the parser, evaluator, and dependency tracker into a small,
+ * stateful container modelled after a single-sheet spreadsheet. All
+ * mutation happens through `setValue` / `setFormula` / `clear`; reads
+ * happen through `getValue` (returns the most recently computed value)
+ * and `getFormula` (returns the formula text, if any).
+ *
+ * Sheets are *pure data containers* — no I/O, no DB, no async. They
+ * are intentionally small so they can be embedded inside a larger
+ * resource (e.g. a `Spreadsheet` resource handler) which is
+ * responsible for persistence.
+ *
+ * @example
+ * ```typescript
+ * import { Sheet } from '@molecule/api-formula-engine'
+ *
+ * const sheet = new Sheet()
+ * sheet.setValue('A1', 10)
+ * sheet.setValue('A2', 20)
+ * sheet.setFormula('A3', '=SUM(A1:A2)')
+ * sheet.getValue('A3') // → 30
+ *
+ * sheet.setValue('A1', 100)
+ * sheet.getValue('A3') // → 120 (auto-recomputed)
+ * ```
+ *
+ * @module
+ */
+import { collectReferences, topologicalSort } from './dependencies.js';
+import { evaluate } from './evaluator.js';
+import { parseFormula } from './parser.js';
+import { coordKey, formatCellReference, parseCellReference } from './references.js';
+import { isError, makeError } from './values.js';
+const DEFAULT_CONFIG = Object.freeze({
+    numCols: 16384,
+    numRows: 1048576,
+});
+/**
+ * In-memory single-sheet engine. References use A1 notation (`A1`,
+ * `$A$1`, `BC42`).
+ */
+export class Sheet {
+    cells = new Map();
+    /** dependent-of[key] = set of cells that reference `key`. */
+    dependents = new Map();
+    config;
+    /**
+     * Create a new Sheet with optional dimension limits.
+     *
+     * @param config - Sheet configuration.
+     */
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Set a literal value at a cell.
+     *
+     * @param ref - A1-style cell reference (e.g. `A1`, `$B$3`).
+     * @param value - Literal value (number, string, boolean, Date, or null).
+     * @param options - Evaluation options forwarded to recompute.
+     */
+    setValue(ref, value, options = {}) {
+        const coord = this.refToCoord(ref);
+        this.assignCell(coord, value, null, null, options);
+    }
+    /**
+     * Set a formula at a cell. The formula text may include or omit the
+     * leading `=`. The formula is parsed eagerly and `#NAME?` /
+     * `#VALUE!` errors caused by parser failures are stored as the
+     * cell's value.
+     *
+     * @param ref - A1-style cell reference.
+     * @param formula - Formula text (e.g. `=SUM(A1:A10)` or `SUM(A1:A10)`).
+     * @param options - Evaluation options forwarded to recompute.
+     */
+    setFormula(ref, formula, options = {}) {
+        const coord = this.refToCoord(ref);
+        let ast = null;
+        let parseError = null;
+        try {
+            ast = parseFormula(formula);
+        }
+        catch (e) {
+            parseError = makeError('#VALUE!', e.message);
+        }
+        if (parseError) {
+            this.assignCell(coord, parseError, null, formula, options);
+            return;
+        }
+        this.assignCell(coord, null, ast, formula, options);
+    }
+    /**
+     * Clear a cell (remove value, formula, and dependency edges).
+     *
+     * @param ref - A1-style cell reference.
+     * @param options - Evaluation options forwarded to recompute.
+     */
+    clear(ref, options = {}) {
+        const coord = this.refToCoord(ref);
+        const key = coordKey(coord);
+        const existing = this.cells.get(key);
+        if (existing) {
+            for (const dep of existing.precedents) {
+                this.dependents.get(dep)?.delete(key);
+            }
+        }
+        this.cells.delete(key);
+        this.recomputeDownstream(key, options);
+    }
+    /**
+     * Read the most recently computed value for a cell.
+     *
+     * @param ref - A1-style cell reference.
+     * @returns Cell value (`null` if the cell is empty).
+     */
+    getValue(ref) {
+        const coord = this.refToCoord(ref);
+        const key = coordKey(coord);
+        const cell = this.cells.get(key);
+        return cell ? cell.computed : null;
+    }
+    /**
+     * Return the formula text for a cell, or `null` if the cell holds a
+     * literal value or is empty.
+     *
+     * @param ref - A1-style cell reference.
+     * @returns Formula text (with leading `=`) or `null`.
+     */
+    getFormula(ref) {
+        const coord = this.refToCoord(ref);
+        const key = coordKey(coord);
+        return this.cells.get(key)?.formula ?? null;
+    }
+    /**
+     * Recompute every formula cell. Useful after bulk edits or when
+     * `now()` semantics change.
+     *
+     * @param options - Evaluation options.
+     */
+    recomputeAll(options = {}) {
+        const keys = [...this.cells.keys()];
+        const { order, cycle } = topologicalSort(this.dependents, keys);
+        for (const k of order)
+            this.evaluateKey(k, options, cycle);
+        for (const k of cycle) {
+            const cell = this.cells.get(k);
+            if (!cell)
+                continue;
+            cell.computed = makeError('#CIRC!');
+        }
+    }
+    /**
+     * Evaluate a free-standing formula string against this sheet's data.
+     * Does NOT mutate the sheet. Useful for ad-hoc evaluations such as
+     * invoice line-item totals or computed-column previews.
+     *
+     * @param formula - Formula text.
+     * @param options - Evaluation options.
+     * @returns Evaluated cell value.
+     */
+    evaluateFormula(formula, options = {}) {
+        let ast;
+        try {
+            ast = parseFormula(formula);
+        }
+        catch (e) {
+            return makeError('#VALUE!', e.message);
+        }
+        return evaluate(ast, (coord) => this.cells.get(coordKey(coord))?.computed ?? null, options);
+    }
+    // --- Internals ---
+    /**
+     * Parse an A1-style reference string into a validated CellCoord.
+     */
+    refToCoord(ref) {
+        const coord = parseCellReference(ref);
+        if (!coord)
+            throw new Error(`Invalid cell reference: ${ref}`);
+        if (coord.col >= this.config.numCols || coord.row >= this.config.numRows) {
+            throw new Error(`Reference out of bounds: ${ref}`);
+        }
+        return coord;
+    }
+    /**
+     * Write a cell record, rewire dependency edges, and trigger downstream recompute.
+     */
+    assignCell(coord, value, ast, formula, options) {
+        const key = coordKey(coord);
+        const existing = this.cells.get(key);
+        if (existing) {
+            for (const dep of existing.precedents) {
+                this.dependents.get(dep)?.delete(key);
+            }
+        }
+        const precedents = new Set();
+        if (ast) {
+            for (const c of collectReferences(ast)) {
+                const k = coordKey(c);
+                precedents.add(k);
+                let set = this.dependents.get(k);
+                if (!set) {
+                    set = new Set();
+                    this.dependents.set(k, set);
+                }
+                set.add(key);
+            }
+        }
+        const record = {
+            value,
+            ast,
+            formula,
+            precedents,
+            computed: value,
+        };
+        this.cells.set(key, record);
+        if (ast)
+            this.evaluateKey(key, options, new Set());
+        this.recomputeDownstream(key, options);
+    }
+    /**
+     * Recompute all formula cells that transitively depend on the given key.
+     */
+    recomputeDownstream(rootKey, options) {
+        // Find every transitive dependent of the changed cell.
+        const affected = new Set();
+        const stack = [rootKey];
+        while (stack.length > 0) {
+            const k = stack.pop();
+            const outs = this.dependents.get(k);
+            if (!outs)
+                continue;
+            for (const t of outs) {
+                if (!affected.has(t)) {
+                    affected.add(t);
+                    stack.push(t);
+                }
+            }
+        }
+        if (affected.size === 0)
+            return;
+        const keys = [...affected];
+        const { order, cycle } = topologicalSort(this.dependents, keys);
+        for (const k of order)
+            this.evaluateKey(k, options, cycle);
+        for (const k of cycle) {
+            const cell = this.cells.get(k);
+            if (!cell)
+                continue;
+            cell.computed = makeError('#CIRC!');
+        }
+    }
+    /**
+     * Evaluate (or propagate) the computed value for a single cell key.
+     */
+    evaluateKey(key, options, cycleSet) {
+        const cell = this.cells.get(key);
+        if (!cell)
+            return;
+        if (cycleSet.has(key)) {
+            cell.computed = makeError('#CIRC!');
+            return;
+        }
+        if (!cell.ast) {
+            cell.computed = cell.value;
+            return;
+        }
+        const value = evaluate(cell.ast, (coord) => {
+            const k = coordKey(coord);
+            if (cycleSet.has(k))
+                return makeError('#CIRC!');
+            const target = this.cells.get(k);
+            return target ? target.computed : null;
+        }, options);
+        cell.computed = value;
+        if (isError(value)) {
+            cell.value = value;
+        }
+    }
+}
+/**
+ * Reformat a cell coordinate as A1-style text. Re-exported for
+ * convenience.
+ *
+ * @param coord - Cell coordinate.
+ * @returns A1-style reference text.
+ */
+export function refOf(coord) {
+    return formatCellReference(coord);
+}

package/dist/tokenizer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Formula tokenizer.
+ *
+ * Lexes a formula string into a flat token stream consumable by the
+ * recursive-descent parser. Pure function — no I/O, no globals.
+ *
+ * @module
+ */
+import type { FormulaErrorCode } from './types.js';
+/**
+ * Lexical token kinds.
+ */
+export type TokenKind = 'number' | 'string' | 'boolean' | 'error' | 'identifier' | 'reference' | 'range' | 'op' | 'lparen' | 'rparen' | 'comma';
+/**
+ * Lexical token. `value` is the raw source text; `op` carries the
+ * normalized operator string for `kind: 'op'` tokens.
+ */
+export interface Token {
+    readonly kind: TokenKind;
+    readonly value: string;
+    readonly position: number;
+    readonly errorCode?: FormulaErrorCode;
+}
+/**
+ * Tokenize a formula string. The leading `=` (if present) is stripped
+ * by the caller — pass the *body* of the formula here.
+ *
+ * @param input - Raw formula text (no leading `=`).
+ * @returns Flat token list.
+ */
+export declare function tokenize(input: string): Token[];
+//# sourceMappingURL=tokenizer.d.ts.map

package/dist/tokenizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenizer.d.ts","sourceRoot":"","sources":["../src/tokenizer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,OAAO,GACP,YAAY,GACZ,WAAW,GACX,OAAO,GACP,IAAI,GACJ,QAAQ,GACR,QAAQ,GACR,OAAO,CAAA;AAEX;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAA;CACtC;AAeD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE,CA2J/C"}

package/dist/tokenizer.js

@@ -0,0 +1,187 @@
+/**
+ * Formula tokenizer.
+ *
+ * Lexes a formula string into a flat token stream consumable by the
+ * recursive-descent parser. Pure function — no I/O, no globals.
+ *
+ * @module
+ */
+const ERROR_CODES = [
+    '#DIV/0!',
+    '#VALUE!',
+    '#REF!',
+    '#NAME?',
+    '#NUM!',
+    '#N/A',
+    '#CIRC!',
+];
+const TWO_CHAR_OPS = new Set(['<=', '>=', '<>']);
+const SINGLE_OPS = new Set(['+', '-', '*', '/', '^', '&', '=', '<', '>', '%']);
+/**
+ * Tokenize a formula string. The leading `=` (if present) is stripped
+ * by the caller — pass the *body* of the formula here.
+ *
+ * @param input - Raw formula text (no leading `=`).
+ * @returns Flat token list.
+ */
+export function tokenize(input) {
+    const tokens = [];
+    let i = 0;
+    while (i < input.length) {
+        const ch = input[i];
+        // Whitespace
+        if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+            i++;
+            continue;
+        }
+        // String literal
+        if (ch === '"') {
+            const start = i;
+            i++;
+            let value = '';
+            while (i < input.length) {
+                const c = input[i];
+                if (c === '"') {
+                    // Escaped quote ""
+                    if (input[i + 1] === '"') {
+                        value += '"';
+                        i += 2;
+                        continue;
+                    }
+                    break;
+                }
+                value += c;
+                i++;
+            }
+            if (input[i] !== '"') {
+                throw new Error(`Unterminated string literal at position ${start}`);
+            }
+            i++; // closing quote
+            tokens.push({ kind: 'string', value, position: start });
+            continue;
+        }
+        // Error literal (`#DIV/0!`, etc.)
+        if (ch === '#') {
+            const start = i;
+            let matched = null;
+            for (const code of ERROR_CODES) {
+                if (input.startsWith(code, i)) {
+                    matched = code;
+                    break;
+                }
+            }
+            if (matched) {
+                tokens.push({
+                    kind: 'error',
+                    value: matched,
+                    position: start,
+                    errorCode: matched,
+                });
+                i += matched.length;
+                continue;
+            }
+            throw new Error(`Unrecognized error code at position ${start}`);
+        }
+        // Number literal — integer or decimal, optional exponent.
+        if (isDigit(ch) || (ch === '.' && isDigit(input[i + 1] ?? ''))) {
+            const start = i;
+            while (i < input.length && isDigit(input[i]))
+                i++;
+            if (input[i] === '.') {
+                i++;
+                while (i < input.length && isDigit(input[i]))
+                    i++;
+            }
+            if (input[i] === 'e' || input[i] === 'E') {
+                i++;
+                if (input[i] === '+' || input[i] === '-')
+                    i++;
+                while (i < input.length && isDigit(input[i]))
+                    i++;
+            }
+            tokens.push({
+                kind: 'number',
+                value: input.slice(start, i),
+                position: start,
+            });
+            continue;
+        }
+        // Identifier / reference / range / boolean
+        if (isLetter(ch) || ch === '$' || ch === '_') {
+            const start = i;
+            // Consume an identifier-like blob: letters, digits, $, :, _, .
+            while (i < input.length &&
+                (isLetter(input[i]) ||
+                    isDigit(input[i]) ||
+                    input[i] === '$' ||
+                    input[i] === '_' ||
+                    input[i] === '.' ||
+                    input[i] === ':')) {
+                i++;
+            }
+            const text = input.slice(start, i);
+            if (/^TRUE$/i.test(text)) {
+                tokens.push({ kind: 'boolean', value: 'TRUE', position: start });
+                continue;
+            }
+            if (/^FALSE$/i.test(text)) {
+                tokens.push({ kind: 'boolean', value: 'FALSE', position: start });
+                continue;
+            }
+            // Range like A1:B5
+            if (/^\$?[A-Za-z]+\$?\d+:\$?[A-Za-z]+\$?\d+$/.test(text)) {
+                tokens.push({ kind: 'range', value: text, position: start });
+                continue;
+            }
+            // Single reference like A1, $A$1
+            if (/^\$?[A-Za-z]+\$?\d+$/.test(text)) {
+                tokens.push({ kind: 'reference', value: text, position: start });
+                continue;
+            }
+            // Otherwise treat as function/identifier name
+            tokens.push({ kind: 'identifier', value: text, position: start });
+            continue;
+        }
+        // Two-char operators
+        if (i + 1 < input.length && TWO_CHAR_OPS.has(input.slice(i, i + 2))) {
+            tokens.push({ kind: 'op', value: input.slice(i, i + 2), position: i });
+            i += 2;
+            continue;
+        }
+        // Single-char operators
+        if (SINGLE_OPS.has(ch)) {
+            tokens.push({ kind: 'op', value: ch, position: i });
+            i++;
+            continue;
+        }
+        if (ch === '(') {
+            tokens.push({ kind: 'lparen', value: '(', position: i });
+            i++;
+            continue;
+        }
+        if (ch === ')') {
+            tokens.push({ kind: 'rparen', value: ')', position: i });
+            i++;
+            continue;
+        }
+        if (ch === ',') {
+            tokens.push({ kind: 'comma', value: ',', position: i });
+            i++;
+            continue;
+        }
+        throw new Error(`Unexpected character '${ch}' at position ${i}`);
+    }
+    return tokens;
+}
+/**
+ * Returns true if the character is an ASCII decimal digit (0–9).
+ */
+function isDigit(ch) {
+    return ch >= '0' && ch <= '9';
+}
+/**
+ * Returns true if the character is an ASCII letter (A–Z or a–z).
+ */
+function isLetter(ch) {
+    return (ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z');
+}