@lvlte/ulp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Eric Lavault (https://github.com/lvlte)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cjs/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The smallest positive normal number representable by IEEE-754 float64.
+ */
+export declare const FLOAT64_MIN: number;
+/**
+ * Return the unit in the last place or unit of least precision (ulp) of x, that
+ * is, the distance between two consecutive representable floating-point numbers
+ * at x.
+ *
+ * @param x The input number (default: 1)
+ * @returns The ulp of x, or `NaN` if `x` is not a finite number.
+ */
+export declare function eps(x?: number): number;
+/**
+ * Exponent of a normalized floating-point number x (`Math.log2()` not precise
+ * enough for large numbers).
+ *
+ * NB. This function assumes `x` is a finite, strictly positive number.
+ *
+ * @param x The input number
+ * @returns The largest integer `y` such that `2^y ≤ x`.
+ */
+export declare function exponent(x: number): number;

package/dist/cjs/index.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLOAT64_MIN = void 0;
+exports.eps = eps;
+exports.exponent = exponent;
+const modf_1 = require("@lvlte/modf");
+exports.FLOAT64_MIN = Math.pow(2, -1022);
+function eps(x = 1) {
+    if (Number.isFinite(x)) {
+        x = Math.abs(x);
+        if (x <= exports.FLOAT64_MIN) {
+            return Number.MIN_VALUE;
+        }
+        return Math.pow(2, (exponent(x) - 52));
+    }
+    return NaN;
+}
+function exponent(x) {
+    const [ipart, fpart] = (0, modf_1.modf)(x);
+    if (ipart > 0) {
+        return ipart.toString(2).split('.', 1)[0].length - 1;
+    }
+    return -(fpart.toString(2).split('1', 1)[0].length - 1);
+}

package/dist/cjs/package.json

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

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The smallest positive normal number representable by IEEE-754 float64.
+ */
+export declare const FLOAT64_MIN: number;
+/**
+ * Return the unit in the last place or unit of least precision (ulp) of x, that
+ * is, the distance between two consecutive representable floating-point numbers
+ * at x.
+ *
+ * @param x The input number (default: 1)
+ * @returns The ulp of x, or `NaN` if `x` is not a finite number.
+ */
+export declare function eps(x?: number): number;
+/**
+ * Exponent of a normalized floating-point number x (`Math.log2()` not precise
+ * enough for large numbers).
+ *
+ * NB. This function assumes `x` is a finite, strictly positive number.
+ *
+ * @param x The input number
+ * @returns The largest integer `y` such that `2^y ≤ x`.
+ */
+export declare function exponent(x: number): number;

package/dist/index.js

@@ -0,0 +1,19 @@
+import { modf } from '@lvlte/modf';
+export const FLOAT64_MIN = Math.pow(2, -1022);
+export function eps(x = 1) {
+    if (Number.isFinite(x)) {
+        x = Math.abs(x);
+        if (x <= FLOAT64_MIN) {
+            return Number.MIN_VALUE;
+        }
+        return Math.pow(2, (exponent(x) - 52));
+    }
+    return NaN;
+}
+export function exponent(x) {
+    const [ipart, fpart] = modf(x);
+    if (ipart > 0) {
+        return ipart.toString(2).split('.', 1)[0].length - 1;
+    }
+    return -(fpart.toString(2).split('1', 1)[0].length - 1);
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@lvlte/ulp",
+  "version": "1.0.0",
+  "description": "Compute the unit in last place of a given IEEE-754 64-bit number",
+  "license": "MIT",
+  "author": "Eric Lavault <lvlte.code@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lvlte/ulp"
+  },
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "engines": {
+    "node": ">=18.20"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "jest",
+    "prebuild": "rimraf dist && make-dir dist",
+    "build": "tsc && tsc -p tsconfig-cjs.json",
+    "postbuild": "(echo { && echo   \"type\": \"commonjs\" && echo }) > ./dist/cjs/package.json",
+    "prepublishOnly": "npm test && npm run build && tsc --emitDeclarationOnly true --removeComments false && tsc -p tsconfig-cjs.json --emitDeclarationOnly true --removeComments false"
+  },
+  "keywords": [
+    "number",
+    "epsilon",
+    "function",
+    "precision",
+    "eps",
+    "ulp",
+    "float",
+    "float64",
+    "IEEE-754",
+    "rounding",
+    "tolerance",
+    "compare",
+    "equal",
+    "ULP"
+  ],
+  "devDependencies": {
+    "@lvlte/tsconfig": "^1.0.1",
+    "@types/jest": "^29.5.12",
+    "jest": "^29.7.0",
+    "make-dir-cli": "^4.0.0",
+    "rimraf": "^6.0.1",
+    "ts-jest": "29.2.5",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "@lvlte/modf": "^1.1.0"
+  }
+}

package/readme.md

@@ -0,0 +1,40 @@
+# ulp (epsilon function)
+
+> Compute the [unit of least precision](https://en.wikipedia.org/wiki/Unit_in_the_last_place)
+of a given IEEE-754 64-bit number.
+
+## Install
+
+```sh
+npm install @lvlte/ulp
+```
+
+## Usage
+
+```js
+// ESM
+import { eps } from '@lvlte/ulp';
+```
+```js
+// CJS
+const { eps } = require('@lvlte/ulp');
+```
+```js
+console.log(eps());                             // 2.220446049250313e-16
+console.log(eps() === eps(1));                  // true
+console.log(eps() === Number.EPSILON);          // true
+
+console.log(eps(Number.MAX_SAFE_INTEGER));      // 1
+console.log(eps(Number.MAX_SAFE_INTEGER + 1));  // 2
+
+console.log(eps(0));                            // 5e-324
+console.log(eps(0) === Number.MIN_VALUE);       // true
+
+console.log(eps(Infinity));                     // NaN
+```
+
+## Use case
+
+- Check whether two floating point numbers can be considered equal.
+- Approximate a floating point number x as a rational number.
+- Get the next/previous float on the float64 number line.