@flolegal-it/numbers 1.0.0

package/README.md

@@ -0,0 +1,96 @@
+# numbers
+
+TypeScript utility library for number handling.
+
+## Installation
+
+```bash
+npm install @flo-legal-it/numbers
+```
+
+## Regex utilities
+
+```typescript
+import { getNumberRegExp } from 'numbers';
+
+// English format (1,000.25)
+const enRegex = getNumberRegExp('en');
+enRegex.test('1,000.25'); // true
+enRegex.test('0.5');      // true
+
+// Dutch/French format (1.000,25)
+const nlRegex = getNumberRegExp('nl');
+nlRegex.test('1.000,25'); // true
+nlRegex.test('0,5');      // true
+
+// Allow negative numbers
+const negRegex = getNumberRegExp('en', true);
+negRegex.test('-1,000.25'); // true
+
+// Disallow empty string
+const strictRegex = getNumberRegExp('en', false, false);
+strictRegex.test(''); // false
+```
+
+## Formula utilities
+
+```typescript
+import { validateFormula, getUsedVars, evalFormula } from '@flo-legal-it/numbers';
+
+// Validate a formula against allowed variables
+const errors = validateFormula('a + b * 2', ['a', 'b']);
+// [] (no errors)
+
+// Get variables used in a formula
+const vars = getUsedVars('a + b * 2');
+// ['a', 'b']
+
+// Evaluate a formula with a variable scope
+const result = evalFormula('a + b * 2', { a: 1, b: 3 });
+// 7
+```
+
+## API
+
+### `getNumberRegExp(language, includeNegativeNumbers?, allowEmpty?)`
+
+Returns a `RegExp` that validates number strings for the given locale.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `language` | `'nl' \| 'en' \| 'fr'` | — | Locale for number formatting |
+| `includeNegativeNumbers` | `boolean` | `false` | Allow negative numbers |
+| `allowEmpty` | `boolean` | `true` | Allow empty string |
+
+### `validateFormula(expr, allowedVars)`
+
+Returns an array of error messages. Empty array means the formula is valid.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `expr` | `string` | Math expression to validate |
+| `allowedVars` | `string[]` | Variable names allowed in the expression |
+
+### `getUsedVars(expr)`
+
+Returns an array of variable names found in the expression, or an empty array if parsing fails.
+
+### `evalFormula(expression, scope)`
+
+Evaluates a math expression with the given variable scope and returns the numeric result. Validate the formula first with `validateFormula`.
+
+## Module formats
+
+This package ships both CommonJS and ESM builds. The correct format is selected automatically based on your project's module system via the `exports` field in `package.json`.
+
+---
+
+## Notes for internal contributers
+This repo is published as a *public* npm package. When publishing a new version, use `npm publish --access public`.
+Don't forget to bump the version number!
+```
+  npm version patch   # 1.0.0 → 1.0.1                                                                                                                                                                                                                                                                                                           
+  npm version minor   # 1.0.0 → 1.1.0                                                                                                                                                                                                                                                                                                           
+  npm version major   # 1.0.0 → 2.0.0
+
+```

package/lib/cjs/formula.d.ts

@@ -0,0 +1,12 @@
+export declare function validateFormula(expr: string, allowedVars: string[]): string[];
+/**
+ * Returns list of currently used vars in formula, or null when formula cannot
+ * be parsed
+ * @param expr
+ */
+export declare function getUsedVars(expr: string): string[];
+/**
+ * Evaluate a math expression with a fixed variable scope
+ * nb. use validateFormula first
+ */
+export declare function evalFormula(expression: string, scope: Record<string, number>): number;

package/lib/cjs/formula.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateFormula = validateFormula;
+exports.getUsedVars = getUsedVars;
+exports.evalFormula = evalFormula;
+const number_1 = require("mathjs/number");
+// Create a minimal math.js instance
+const math = (0, number_1.create)({
+    evaluateDependencies: number_1.evaluateDependencies,
+    addDependencies: number_1.addDependencies,
+    subtractDependencies: number_1.subtractDependencies,
+    multiplyDependencies: number_1.multiplyDependencies,
+    divideDependencies: number_1.divideDependencies,
+});
+function validateFormula(expr, allowedVars) {
+    const errorMessages = [];
+    try {
+        const vars = new Set(allowedVars);
+        const node = math.parse(expr);
+        node.traverse((n) => {
+            if (n.isSymbolNode && !vars.has(n.name)) {
+                errorMessages.push(`'${n.name}' is geen geldige variable`);
+            }
+            if (n.isOperatorNode && !["+", "-", "*", "/"].includes(n.op)) {
+                errorMessages.push(`'${n.op}' is geen geldige operator`);
+            }
+        });
+    }
+    catch (e) {
+        errorMessages.push(e.message);
+    }
+    return errorMessages;
+}
+/**
+ * Returns list of currently used vars in formula, or null when formula cannot
+ * be parsed
+ * @param expr
+ */
+function getUsedVars(expr) {
+    try {
+        const node = math.parse(expr);
+        const vars = [];
+        node.traverse((n) => {
+            if (n.isSymbolNode) {
+                vars.push(n.name);
+            }
+        });
+        return vars;
+    }
+    catch (e) {
+        return [];
+    }
+}
+/**
+ * Evaluate a math expression with a fixed variable scope
+ * nb. use validateFormula first
+ */
+function evalFormula(expression, scope) {
+    return math.evaluate(expression, scope);
+}

package/lib/cjs/index.d.ts

@@ -0,0 +1,3 @@
+export { getNumberRegExp } from './reg-exp';
+export type { NumberRegExpOptions } from './reg-exp';
+export { validateFormula, getUsedVars, evalFormula } from './formula';

package/lib/cjs/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evalFormula = exports.getUsedVars = exports.validateFormula = exports.getNumberRegExp = void 0;
+var reg_exp_1 = require("./reg-exp");
+Object.defineProperty(exports, "getNumberRegExp", { enumerable: true, get: function () { return reg_exp_1.getNumberRegExp; } });
+var formula_1 = require("./formula");
+Object.defineProperty(exports, "validateFormula", { enumerable: true, get: function () { return formula_1.validateFormula; } });
+Object.defineProperty(exports, "getUsedVars", { enumerable: true, get: function () { return formula_1.getUsedVars; } });
+Object.defineProperty(exports, "evalFormula", { enumerable: true, get: function () { return formula_1.evalFormula; } });

package/lib/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/lib/cjs/reg-exp.d.ts

@@ -0,0 +1,25 @@
+export interface NumberRegExpOptions {
+    useThousandsSeparator: boolean;
+    allowDecimalSeparator: boolean;
+    thousandsSeparator?: ',' | '.' | ' ';
+    decimalSeparator?: '.' | ',';
+}
+/**
+ * Returns a regex that accepts any possible string representation of a positive floating
+ * point number for the given language including '0'.
+ * The regex does not accept power notations.
+ * Negative numbers are optional.
+ *
+ * Examples NL:
+ * 0
+ * 0,5
+ * 1.000
+ * 1.000,25
+ *
+ * Examples EN:
+ * 0
+ * 0.5
+ * 1,000
+ * 1,000.25
+ */
+export declare function getNumberRegExp(language: 'nl' | 'en' | 'fr', includeNegativeNumbers?: boolean, allowEmpty?: boolean): RegExp;

package/lib/cjs/reg-exp.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNumberRegExp = getNumberRegExp;
+/**
+ * Returns a regex that accepts any possible string representation of a positive floating
+ * point number for the given language including '0'.
+ * The regex does not accept power notations.
+ * Negative numbers are optional.
+ *
+ * Examples NL:
+ * 0
+ * 0,5
+ * 1.000
+ * 1.000,25
+ *
+ * Examples EN:
+ * 0
+ * 0.5
+ * 1,000
+ * 1,000.25
+ */
+function getNumberRegExp(language, includeNegativeNumbers = false, allowEmpty = true) {
+    const variants = [];
+    const baseOptions = {
+        useThousandsSeparator: true,
+        allowDecimalSeparator: true
+    };
+    if (language === 'en') {
+        // English formatting (1,000.50)
+        variants.push(buildNumberPattern({ ...baseOptions, thousandsSeparator: ',', decimalSeparator: '.' }));
+        // International formatting with space (1 000.50)
+        variants.push(buildNumberPattern({ ...baseOptions, thousandsSeparator: ' ', decimalSeparator: '.' }));
+        // Without thousands separator (1000.50)
+        variants.push(buildNumberPattern({ ...baseOptions, useThousandsSeparator: false, decimalSeparator: '.' }));
+    }
+    else {
+        // Dutch / French formatting (1.000,50)
+        variants.push(buildNumberPattern({ ...baseOptions, thousandsSeparator: '.', decimalSeparator: ',' }));
+        // International formatting with space (1 000,50)
+        variants.push(buildNumberPattern({ ...baseOptions, thousandsSeparator: ' ', decimalSeparator: ',' }));
+        // Without thousands separator (1000,50)
+        variants.push(buildNumberPattern({ ...baseOptions, useThousandsSeparator: false, decimalSeparator: ',' }));
+    }
+    // Combine all allowed variants
+    let pattern = variants.join('|');
+    // Optionally allow empty string
+    if (allowEmpty) {
+        pattern += '|';
+    }
+    // Optionally allow negative numbers
+    if (includeNegativeNumbers) {
+        pattern = `-?(?:${pattern})`;
+    }
+    // Add start and end anchors
+    return new RegExp(`^(?:${pattern})$`);
+}
+/**
+ * Builds a regex fragment for a single number formatting configuration.
+ *
+ * Integer part:
+ * - Allows '0'
+ * - Prevents leading zeros like '01'
+ * - Allows properly grouped thousands if enabled
+ *
+ * Fraction part:
+ * - Optional
+ * - Decimal separator followed by one or more digits
+ */
+function buildNumberPattern(options) {
+    let integerPart = '';
+    if (options.useThousandsSeparator && options.thousandsSeparator) {
+        // first digit is 1-9 (unless number is exactly 0)
+        // then maximum two digits (first group)
+        // followed by one or more groups of 3 digits
+        // preceded by the thousands separator
+        switch (options.thousandsSeparator) {
+            case '.':
+                integerPart = '(0|[1-9]\\d{0,2}(?:\\.\\d{3})+|[1-9]\\d*)';
+                break;
+            case ',':
+                integerPart = '(0|[1-9]\\d{0,2}(?:,\\d{3})+|[1-9]\\d*)';
+                break;
+            case ' ':
+                integerPart = '(0|[1-9]\\d{0,2}(?:\\s\\d{3})+|[1-9]\\d*)';
+                break;
+        }
+    }
+    else {
+        // no thousands separator
+        // first position cannot be 0 unless number is exactly 0
+        // remaining positions can be any digit
+        integerPart = '(0|[1-9]\\d*)';
+    }
+    let fractionPart = '';
+    if (options.allowDecimalSeparator && options.decimalSeparator) {
+        // optional fraction group
+        // decimal separator followed by one or more digits
+        switch (options.decimalSeparator) {
+            case '.':
+                fractionPart = '(?:\\.\\d+)?';
+                break;
+            case ',':
+                fractionPart = '(?:,\\d+)?';
+                break;
+        }
+    }
+    return integerPart + fractionPart;
+}

package/lib/esm/formula.d.ts

@@ -0,0 +1,12 @@
+export declare function validateFormula(expr: string, allowedVars: string[]): string[];
+/**
+ * Returns list of currently used vars in formula, or null when formula cannot
+ * be parsed
+ * @param expr
+ */
+export declare function getUsedVars(expr: string): string[];
+/**
+ * Evaluate a math expression with a fixed variable scope
+ * nb. use validateFormula first
+ */
+export declare function evalFormula(expression: string, scope: Record<string, number>): number;

package/lib/esm/formula.js

@@ -0,0 +1,57 @@
+import { create, evaluateDependencies, addDependencies, subtractDependencies, multiplyDependencies, divideDependencies,
+// @ts-ignore
+ } from 'mathjs/number';
+// Create a minimal math.js instance
+const math = create({
+    evaluateDependencies,
+    addDependencies,
+    subtractDependencies,
+    multiplyDependencies,
+    divideDependencies,
+});
+export function validateFormula(expr, allowedVars) {
+    const errorMessages = [];
+    try {
+        const vars = new Set(allowedVars);
+        const node = math.parse(expr);
+        node.traverse((n) => {
+            if (n.isSymbolNode && !vars.has(n.name)) {
+                errorMessages.push(`'${n.name}' is geen geldige variable`);
+            }
+            if (n.isOperatorNode && !["+", "-", "*", "/"].includes(n.op)) {
+                errorMessages.push(`'${n.op}' is geen geldige operator`);
+            }
+        });
+    }
+    catch (e) {
+        errorMessages.push(e.message);
+    }
+    return errorMessages;
+}
+/**
+ * Returns list of currently used vars in formula, or null when formula cannot
+ * be parsed
+ * @param expr
+ */
+export function getUsedVars(expr) {
+    try {
+        const node = math.parse(expr);
+        const vars = [];
+        node.traverse((n) => {
+            if (n.isSymbolNode) {
+                vars.push(n.name);
+            }
+        });
+        return vars;
+    }
+    catch (e) {
+        return [];
+    }
+}
+/**
+ * Evaluate a math expression with a fixed variable scope
+ * nb. use validateFormula first
+ */
+export function evalFormula(expression, scope) {
+    return math.evaluate(expression, scope);
+}

package/lib/esm/index.d.ts

@@ -0,0 +1,3 @@
+export { getNumberRegExp } from './reg-exp';
+export type { NumberRegExpOptions } from './reg-exp';
+export { validateFormula, getUsedVars, evalFormula } from './formula';

package/lib/esm/index.js

@@ -0,0 +1,2 @@
+export { getNumberRegExp } from './reg-exp';
+export { validateFormula, getUsedVars, evalFormula } from './formula';

package/lib/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/lib/esm/reg-exp.d.ts

@@ -0,0 +1,25 @@
+export interface NumberRegExpOptions {
+    useThousandsSeparator: boolean;
+    allowDecimalSeparator: boolean;
+    thousandsSeparator?: ',' | '.' | ' ';
+    decimalSeparator?: '.' | ',';
+}
+/**
+ * Returns a regex that accepts any possible string representation of a positive floating
+ * point number for the given language including '0'.
+ * The regex does not accept power notations.
+ * Negative numbers are optional.
+ *
+ * Examples NL:
+ * 0
+ * 0,5
+ * 1.000
+ * 1.000,25
+ *
+ * Examples EN:
+ * 0
+ * 0.5
+ * 1,000
+ * 1,000.25
+ */
+export declare function getNumberRegExp(language: 'nl' | 'en' | 'fr', includeNegativeNumbers?: boolean, allowEmpty?: boolean): RegExp;

package/lib/esm/reg-exp.js

@@ -0,0 +1,105 @@
+/**
+ * Returns a regex that accepts any possible string representation of a positive floating
+ * point number for the given language including '0'.
+ * The regex does not accept power notations.
+ * Negative numbers are optional.
+ *
+ * Examples NL:
+ * 0
+ * 0,5
+ * 1.000
+ * 1.000,25
+ *
+ * Examples EN:
+ * 0
+ * 0.5
+ * 1,000
+ * 1,000.25
+ */
+export function getNumberRegExp(language, includeNegativeNumbers = false, allowEmpty = true) {
+    const variants = [];
+    const baseOptions = {
+        useThousandsSeparator: true,
+        allowDecimalSeparator: true
+    };
+    if (language === 'en') {
+        // English formatting (1,000.50)
+        variants.push(buildNumberPattern({ ...baseOptions, thousandsSeparator: ',', decimalSeparator: '.' }));
+        // International formatting with space (1 000.50)
+        variants.push(buildNumberPattern({ ...baseOptions, thousandsSeparator: ' ', decimalSeparator: '.' }));
+        // Without thousands separator (1000.50)
+        variants.push(buildNumberPattern({ ...baseOptions, useThousandsSeparator: false, decimalSeparator: '.' }));
+    }
+    else {
+        // Dutch / French formatting (1.000,50)
+        variants.push(buildNumberPattern({ ...baseOptions, thousandsSeparator: '.', decimalSeparator: ',' }));
+        // International formatting with space (1 000,50)
+        variants.push(buildNumberPattern({ ...baseOptions, thousandsSeparator: ' ', decimalSeparator: ',' }));
+        // Without thousands separator (1000,50)
+        variants.push(buildNumberPattern({ ...baseOptions, useThousandsSeparator: false, decimalSeparator: ',' }));
+    }
+    // Combine all allowed variants
+    let pattern = variants.join('|');
+    // Optionally allow empty string
+    if (allowEmpty) {
+        pattern += '|';
+    }
+    // Optionally allow negative numbers
+    if (includeNegativeNumbers) {
+        pattern = `-?(?:${pattern})`;
+    }
+    // Add start and end anchors
+    return new RegExp(`^(?:${pattern})$`);
+}
+/**
+ * Builds a regex fragment for a single number formatting configuration.
+ *
+ * Integer part:
+ * - Allows '0'
+ * - Prevents leading zeros like '01'
+ * - Allows properly grouped thousands if enabled
+ *
+ * Fraction part:
+ * - Optional
+ * - Decimal separator followed by one or more digits
+ */
+function buildNumberPattern(options) {
+    let integerPart = '';
+    if (options.useThousandsSeparator && options.thousandsSeparator) {
+        // first digit is 1-9 (unless number is exactly 0)
+        // then maximum two digits (first group)
+        // followed by one or more groups of 3 digits
+        // preceded by the thousands separator
+        switch (options.thousandsSeparator) {
+            case '.':
+                integerPart = '(0|[1-9]\\d{0,2}(?:\\.\\d{3})+|[1-9]\\d*)';
+                break;
+            case ',':
+                integerPart = '(0|[1-9]\\d{0,2}(?:,\\d{3})+|[1-9]\\d*)';
+                break;
+            case ' ':
+                integerPart = '(0|[1-9]\\d{0,2}(?:\\s\\d{3})+|[1-9]\\d*)';
+                break;
+        }
+    }
+    else {
+        // no thousands separator
+        // first position cannot be 0 unless number is exactly 0
+        // remaining positions can be any digit
+        integerPart = '(0|[1-9]\\d*)';
+    }
+    let fractionPart = '';
+    if (options.allowDecimalSeparator && options.decimalSeparator) {
+        // optional fraction group
+        // decimal separator followed by one or more digits
+        switch (options.decimalSeparator) {
+            case '.':
+                fractionPart = '(?:\\.\\d+)?';
+                break;
+            case ',':
+                fractionPart = '(?:,\\d+)?';
+                break;
+        }
+    }
+    return integerPart + fractionPart;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@flolegal-it/numbers",
+  "version": "1.0.0",
+  "description": "Contains utility functions for working with numbers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FLO-Legal-IT/numbers.git"
+  },
+  "keywords": [
+    "number",
+    "regex"
+  ],
+  "author": "FloLegal IT",
+  "license": "ISC",
+  "main": "lib/cjs/index.js",
+  "module": "lib/esm/index.js",
+  "types": "lib/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/cjs/index.d.ts",
+      "import": "./lib/esm/index.js",
+      "require": "./lib/cjs/index.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "rm -rf lib && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && echo '{\"type\":\"commonjs\"}' > lib/cjs/package.json && echo '{\"type\":\"module\"}' > lib/esm/package.json",
+    "test": "ts-node node_modules/.bin/tape 'src/**/*.test.ts'",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "mathjs": "^15.1.1"
+  },
+  "devDependencies": {
+    "@types/tape": "^5.8.1",
+    "tape": "^5.9.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}