flo-mat 3.0.14 → 4.0.1

package/__tests__/cp-node/fs/is-two-prong.spec.ts

@@ -1,7 +1,15 @@
 import { expect, test } from '@jest/globals';
 import { isTwoProng } from '../../../src/cp-node/fs/is-two-prong.js';
+import { getRealProngCount } from '../../../src/cp-node/fs/get-real-prong-count.js';
+import { getAllOnLoop } from '../../../src/cp-node/fs/get-all-on-loop.js';
+import { getMats1 } from '../../get-mats1.js';
 
-test.skip('isTwoProng [STUB]', () => {
-    // TODO: implement test
-    expect(true).toBe(true);
+
+test('isTwoProng', function() {
+    const { cpNode } = getMats1()[0];
+    const allOnLoop = getAllOnLoop(cpNode);
+
+    for (const n of allOnLoop) {
+        expect(isTwoProng(n)).toBe(getRealProngCount(n) === 2);
+    }
 });

package/__tests__/cp-node/fs/is-vertex-special.spec.ts

@@ -1,7 +1,17 @@
 import { expect, test } from '@jest/globals';
 import { isVertexSpecial } from '../../../src/cp-node/fs/is-vertex-special.js';
+import { isVertex } from '../../../src/cp-node/fs/is-vertex.js';
+import { isSpecial } from '../../../src/cp-node/fs/is-special.js';
+import { getAllOnLoop } from '../../../src/cp-node/fs/get-all-on-loop.js';
+import { getMats1 } from '../../get-mats1.js';
 
-test.skip('isVertexSpecial [STUB]', () => {
-    // TODO: implement test
-    expect(true).toBe(true);
+
+test('isVertexSpecial', function() {
+    const { cpNode } = getMats1()[0];
+    const allOnLoop = getAllOnLoop(cpNode);
+
+    // isVertexSpecial === isVertex(isSpecial)
+    for (const n of allOnLoop) {
+        expect(isVertexSpecial(n)).toBe(isVertex(isSpecial)(n));
+    }
 });

package/__tests__/cp-node/fs/is-vertex.spec.ts

@@ -1,7 +1,18 @@
 import { expect, test } from '@jest/globals';
 import { isVertex } from '../../../src/cp-node/fs/is-vertex.js';
+import { isTerminating } from '../../../src/cp-node/fs/is-terminating.js';
+import { getAllOnCircle } from '../../../src/cp-node/fs/get-all-on-circle.js';
+import { getAllOnLoop } from '../../../src/cp-node/fs/get-all-on-loop.js';
+import { getMats1 } from '../../get-mats1.js';
 
-test.skip('isVertex [STUB]', () => {
-    // TODO: implement test
-    expect(true).toBe(true);
+
+test('isVertex', function() {
+    const { cpNode } = getMats1()[0];
+    const allOnLoop = getAllOnLoop(cpNode);
+
+    // isVertex(f)(n) === getAllOnCircle(n).some(f)
+    const isTerminatingVertex = isVertex(isTerminating);
+    for (const n of allOnLoop) {
+        expect(isTerminatingVertex(n)).toBe(getAllOnCircle(n).some(isTerminating));
+    }
 });

package/__tests__/cp-node/fs/iterate-all-on-loop.spec.ts

@@ -1,7 +1,17 @@
 import { expect, test } from '@jest/globals';
 import { iterateAllOnLoop } from '../../../src/cp-node/fs/iterate-all-on-loop.js';
+import { getAllOnLoop } from '../../../src/cp-node/fs/get-all-on-loop.js';
+import { getMats1 } from '../../get-mats1.js';
 
-test.skip('iterateAllOnLoop [STUB]', () => {
-    // TODO: implement test
-    expect(true).toBe(true);
+
+test('iterateAllOnLoop', function() {
+    const { cpNode } = getMats1()[0];
+
+    const iterated = [...iterateAllOnLoop(cpNode)];
+    const expected = getAllOnLoop(cpNode);
+
+    expect(iterated.length).toBe(expected.length);
+    for (let i = 0; i < iterated.length; i++) {
+        expect(iterated[i] === expected[i]).toBe(true);
+    }
 });

package/__tests__/cp-node/fs/traverse-all-forward.spec.ts

@@ -1,7 +1,14 @@
 import { expect, test } from '@jest/globals';
 import { traverseAllForward } from '../../../src/cp-node/fs/traverse-all-forward.js';
+import { getMats1 } from '../../get-mats1.js';
 
-test.skip('traverseAllForward [STUB]', () => {
-    // TODO: implement test
-    expect(true).toBe(true);
+
+test('traverseAllForward', function() {
+    const { cpNode } = getMats1()[0];
+
+    const visited: (typeof cpNode)[] = [];
+    traverseAllForward(cpNode, cp => visited.push(cp));
+
+    expect(visited.length).toBeGreaterThan(0);
+    expect(visited[0] === cpNode).toBe(true);
 });

package/__tests__/cp-node/fs/traverse-cp.spec.ts

@@ -1,7 +1,13 @@
 import { expect, test } from '@jest/globals';
 import { traverseCp } from '../../../src/cp-node/fs/traverse-cp.js';
+import { getMats1 } from '../../get-mats1.js';
 
-test.skip('traverseCp [STUB]', () => {
-    // TODO: implement test
-    expect(true).toBe(true);
+
+test('traverseCp', function() {
+    const { cpNode } = getMats1()[0];
+
+    const visited = traverseCp(cpNode);
+
+    expect(visited.length).toBeGreaterThan(0);
+    expect(visited[0] === cpNode).toBe(true);
 });

package/__tests__/cp-node/fs/traverse-edges.spec.ts

@@ -1,7 +1,17 @@
 import { expect, test } from '@jest/globals';
 import { traverseEdges } from '../../../src/cp-node/fs/traverse-edges.js';
+import { getMats1 } from '../../get-mats1.js';
 
-test.skip('traverseEdges [STUB]', () => {
-    // TODO: implement test
-    expect(true).toBe(true);
+
+test('traverseEdges', function() {
+    const { cpNode } = getMats1()[0];
+
+    const visited: (typeof cpNode)[] = [];
+    traverseEdges(cpNode, cp => visited.push(cp));
+
+    expect(visited.length).toBeGreaterThan(0);
+
+    // traverseEdges uses a `seen` set internally, so no duplicates
+    const visitedSet = new Set(visited);
+    expect(visitedSet.size).toBe(visited.length);
 });

package/__tests__/cp-node/fs/traverse-vertices.spec.ts

@@ -1,7 +1,16 @@
 import { expect, test } from '@jest/globals';
 import { traverseVertices } from '../../../src/cp-node/fs/traverse-vertices.js';
+import { getMats1 } from '../../get-mats1.js';
 
-test.skip('traverseVertices [STUB]', () => {
-    // TODO: implement test
-    expect(true).toBe(true);
+
+test('traverseVertices', function() {
+    const { cpNode } = getMats1()[0];
+
+    const visited: (typeof cpNode)[] = [];
+    traverseVertices(cpNode, cp => visited.push(cp));
+
+    expect(visited.length).toBeGreaterThan(0);
+
+    // cpStart is visited first
+    expect(visited[0] === cpNode).toBe(true);
 });

package/__tests__/cp-node/random-walk.ts

@@ -0,0 +1,33 @@
+import type { CpNode } from "../../src/cp-node/cp-node.js";
+import { squares4 } from 'squares-rng';
+
+
+const NEXT = 0;
+const PREV = 1;
+const NEXT_ON_CIRCLE = 2;
+const PREV_ON_CIRCLE = 3;
+
+function randomWalk(
+        cpNode: CpNode,
+        seed: number,
+        steps: number): CpNode {
+
+    for (let i=0; i<steps; i++) {
+        const direction = squares4(seed + i) % 4;
+
+        if (direction === NEXT) {
+            cpNode = cpNode.next;
+        } else if (direction === PREV) {
+            cpNode = cpNode.prev;
+        } else if (direction === NEXT_ON_CIRCLE) {
+            cpNode = cpNode.nextOnCircle;
+        } else if (direction === PREV_ON_CIRCLE) {
+            cpNode = cpNode.prevOnCircle;
+        }
+    }
+
+    return cpNode;
+}
+
+
+export { randomWalk }

package/__tests__/cp-node/stringification/from-stringifyable.spec.ts

@@ -0,0 +1,3 @@
+import { test } from '@jest/globals';
+
+test.todo('see to-stringifyable.spec.ts');

package/__tests__/cp-node/stringification/loop-from-stringifyable.spec.ts

@@ -0,0 +1,4 @@
+import { test } from '@jest/globals';
+
+test.todo('see loop-to-stringifyable.spec.ts');
+

package/__tests__/cp-node/stringification/loop-to-stringifyable.spec.ts

@@ -0,0 +1,19 @@
+import { expect, test } from '@jest/globals';
+import { loopFromBeziers } from 'flo-boolean';
+import { loopToStringifyable } from '../../../src/cp-node/stringification/loop-to-stringifyable.js';
+import { loopFromStringifyable } from '../../../src/cp-node/stringification/loop-from-stringifyable.js';
+
+
+test('`LoopToStringifyable` and `LoopFromStringifyable`', function() {
+    const beziers = [
+        [[24,8], [34,18], [4,28]]
+    ];
+    const _loop_ = loopFromBeziers(beziers, 3);
+    const loopStringifyable = loopToStringifyable(_loop_);
+
+    expect(loopStringifyable.beziers).toEqual(beziers);
+    expect(loopStringifyable.idx).toEqual(3);
+
+    const loop_ = loopFromStringifyable(loopStringifyable);
+    expect(loop_).toEqual(_loop_);
+});

package/__tests__/cp-node/stringification/to-stringifyable.spec.ts

@@ -0,0 +1,34 @@
+import { expect, test } from '@jest/globals';
+import { toStringifyable } from '../../../src/cp-node/stringification/to-stringifyable.js';
+import { fromStringifyable } from '../../../src/cp-node/stringification/from-stringifyable.js';
+import { getMats1 } from '../../get-mats1.js';
+import { compareCpNodesByValue } from '../compare-cp-nodes-by-value.js';
+
+
+test('`toStringifyable` and `fromStringifyable`', function() {
+    {
+        // Basic test
+        const { cpNode } = getMats1()[0];
+
+        const stringifyable = toStringifyable(cpNode);
+        const cpNode_ = fromStringifyable(stringifyable);
+
+        const r = compareCpNodesByValue(cpNode, cpNode_);
+
+        expect(r).toBe(true);
+    }
+    {
+        // Test that also JSON.stringify and JSON.parse work with the stringifyable format
+        const cpNode = getMats1()[0].cpNode;
+
+        const stringifyable = toStringifyable(cpNode);
+        const jsonStr = JSON.stringify(stringifyable);  // Should not throw
+        const stringifyable_ = JSON.parse(jsonStr) as ReturnType<typeof toStringifyable>;
+
+        const cpNode_ = fromStringifyable(stringifyable_);
+
+        const r = compareCpNodesByValue(cpNode, cpNode_);
+
+        expect(r).toBe(true);
+    }
+});

package/__tests__/get-mats1.ts

@@ -0,0 +1,122 @@
+import type { Mat } from "../src/mat/mat.js";
+import type { CpNodeStringifyable } from "../src/cp-node/stringification/cp-node-stringifyable.js";
+import { findMats } from "../src/find-mat/find-mats.js";
+import { fromStringifyable } from "../src/cp-node/stringification/from-stringifyable.js";
+
+
+
+// Cache; we use this one in tests since it is fixed and not susceptible to
+// small perturbations in the algorithm.
+let mats1: Mat[] | undefined = undefined;
+function getMats1() {
+    const _cpNode: CpNodeStringifyable = {
+        cpNodes: [
+            {
+                id: 0,
+                isHoleClosing: false,
+                isIntersection: false,
+                pointOnShape: {
+                    circle: {
+                        center: [24,8],
+                        radius: 0
+                    },
+                    curveIdx: 0,
+                    loopIdx: 0,
+                    p: [24, 8],
+                    t: 1,
+                    isSource: true,
+                    order: -1,
+                    order2: 0
+                },
+                prev: 11,
+                next: 1,
+                prevOnCircle: 1,
+                nextOnCircle: 1
+            },
+            { id: 1,   isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [24, 8],                           radius: 0                    }, curveIdx: 0, loopIdx: 0, p: [24, 8],                           t: 1,                    isSource: true  , order: 1,                     order2: 0 }, prev: 0,   next: 10,  prevOnCircle: 0,   nextOnCircle: 0   },
+            { id: 10,  isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [46, -5.21425847941623],           radius: 13.21425847941623    }, curveIdx: 1, loopIdx: 0, p: [46, 8],                           t: 1,                    isSource: true  , order: -1,                    order2: 0 }, prev: 1,   next: 144, prevOnCircle: 11,  nextOnCircle: 11  },
+            { id: 144, isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [81.5, -12.641417453935567],       radius: 41.064803841095305   }, curveIdx: 1, loopIdx: 0, p: [46, 8],                           t: 1,                    isSource: false , order: -0.5026547194480646,   order2: 0 }, prev: 10,  next: 147, prevOnCircle: 143, nextOnCircle: 142 },
+            { id: 147, isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [81.5, 18.5],                     radius: 35.5                 }, curveIdx: 2, loopIdx: 0, p: [46, 18.499999999999996],           t: 0.2282608695652173,   isSource: false , order: 0,                     order2: 0 }, prev: 144, next: 2,   prevOnCircle: 146, nextOnCircle: 145 },
+            { id: 2,   isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [46, 54],                         radius: 0                    }, curveIdx: 2, loopIdx: 0, p: [46, 54],                          t: 1,                    isSource: true  , order: -1,                    order2: 0 }, prev: 147, next: 3,   prevOnCircle: 3,   nextOnCircle: 3   },
+            { id: 3,   isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [46, 54],                         radius: 0                    }, curveIdx: 2, loopIdx: 0, p: [46, 54],                          t: 1,                    isSource: true  , order: 1,                     order2: 0 }, prev: 2,   next: 145, prevOnCircle: 2,   nextOnCircle: 2   },
+            { id: 145, isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [81.5, 18.5],                     radius: 35.5                 }, curveIdx: 3, loopIdx: 0, p: [81.5, 54],                        t: 0.5,                  isSource: false , order: 0,                     order2: 0 }, prev: 3,   next: 4,   prevOnCircle: 147, nextOnCircle: 146 },
+            { id: 4,   isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [117, 54],                        radius: 0                    }, curveIdx: 3, loopIdx: 0, p: [117, 54],                         t: 1,                    isSource: true  , order: -1,                    order2: 0 }, prev: 145, next: 5,   prevOnCircle: 5,   nextOnCircle: 5   },
+            { id: 5,   isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [117, 54],                        radius: 0                    }, curveIdx: 3, loopIdx: 0, p: [117, 54],                         t: 1,                    isSource: true  , order: 1,                     order2: 0 }, prev: 4,   next: 146, prevOnCircle: 4,   nextOnCircle: 4   },
+            { id: 146, isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [81.5, 18.5],                     radius: 35.5                 }, curveIdx: 4, loopIdx: 0, p: [117, 18.499999999999996],          t: 0.7717391304347827,   isSource: false , order: 0,                     order2: 0 }, prev: 5,   next: 142, prevOnCircle: 145, nextOnCircle: 147 },
+            { id: 142, isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [81.5, -12.641417453935567],       radius: 41.064803841095305   }, curveIdx: 4, loopIdx: 0, p: [117, 8],                          t: 1,                    isSource: false , order: -0.8644872659655476,   order2: 0 }, prev: 146, next: 148, prevOnCircle: 144, nextOnCircle: 143 },
+            { id: 148, isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [81.68410160768288, -12.970446490933696], radius: 41.07276841516263  }, curveIdx: 4, loopIdx: 0, p: [117, 8],                   t: 1,                    isSource: false , order: -0.8598373023056252,   order2: 0 }, prev: 142, next: 119, prevOnCircle: 150, nextOnCircle: 149 },
+            { id: 119, isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [115.9110440340909, -5.952334953607174], radius: 13.994766012811272  }, curveIdx: 4, loopIdx: 0, p: [117, 8],                   t: 1,                    isSource: false , order: -0.07781165936695383,  order2: 0 }, prev: 148, next: 6,   prevOnCircle: 118, nextOnCircle: 118 },
+            { id: 6,   isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [139, 8],                          radius: 0                    }, curveIdx: 5, loopIdx: 0, p: [139, 8],                          t: 1,                    isSource: true  , order: -1,                    order2: 0 }, prev: 119, next: 7,   prevOnCircle: 7,   nextOnCircle: 7   },
+            { id: 7,   isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [139, 8],                          radius: 0                    }, curveIdx: 5, loopIdx: 0, p: [139, 8],                          t: 1,                    isSource: true  , order: 1,                     order2: 0 }, prev: 6,   next: 118, prevOnCircle: 6,   nextOnCircle: 6   },
+            { id: 118, isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [115.9110440340909, -5.952334953607174], radius: 13.994766012811272  }, curveIdx: 6, loopIdx: 0, p: [128.3125, -12.4375],         t: 0.1875,               isSource: true  , order: 0,                     order2: 0 }, prev: 7,   next: 149, prevOnCircle: 119, nextOnCircle: 119 },
+            { id: 149, isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [81.68410160768288, -12.970446490933696], radius: 41.07276841516263  }, curveIdx: 6, loopIdx: 0, p: [118.08071791640388, -32.003539423017145], t: 0.36700494883501966, isSource: false , order: 0, order2: 0 }, prev: 118, next: 8,   prevOnCircle: 148, nextOnCircle: 150 },
+            { id: 8,   isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [82, -101],                        radius: 0                    }, curveIdx: 6, loopIdx: 0, p: [82, -101],                        t: 1,                    isSource: true  , order: -1,                    order2: 0 }, prev: 149, next: 9,   prevOnCircle: 9,   nextOnCircle: 9   },
+            { id: 9,   isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [82, -101],                        radius: 0                    }, curveIdx: 6, loopIdx: 0, p: [82, -101],                        t: 1,                    isSource: true  , order: 1,                     order2: 0 }, prev: 8,   next: 150, prevOnCircle: 8,   nextOnCircle: 8   },
+            { id: 150, isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [81.68410160768288, -12.970446490933696], radius: 41.07276841516263  }, curveIdx: 0, loopIdx: 0, p: [45.425023320690585, -32.264267964746104],  t: 0.6306030461949899, isSource: false , order: 0, order2: 0 }, prev: 9,   next: 143, prevOnCircle: 149, nextOnCircle: 148 },
+            { id: 143, isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [81.5, -12.641417453935567],         radius: 41.064803841095305   }, curveIdx: 0, loopIdx: 0, p: [45.24795284642707, -31.931497590699145],   t: 0.6336559854064299, isSource: false , order: 0, order2: 0 }, prev: 150, next: 11,  prevOnCircle: 142, nextOnCircle: 144 },
+            { id: 11,  isHoleClosing: false, isIntersection: false, pointOnShape: { circle: { center: [46, -5.21425847941623],            radius: 13.21425847941623    }, curveIdx: 0, loopIdx: 0, p: [34.33444028251029, -11.421620530924521],   t: 0.8218199951291328, isSource: false , order: 0, order2: 0 }, prev: 143, next: 0,   prevOnCircle: 10,  nextOnCircle: 10  }
+        ],
+        loops: [
+            { idx: 0, beziers: [[[82, -101], [24, 8]], [[24, 8], [46, 8]], [[46, 8], [46, 54]], [[46, 54], [117, 54]], [[117, 54], [117, 8]], [[117, 8], [139, 8]], [[139, 8], [82, -101]]] }
+        ]
+    };
+
+    const cpNode = fromStringifyable(_cpNode);
+
+    mats1 = [{ cpNode, meta: {
+        boundingHulls: undefined!,
+        cpTrees: undefined!,
+        loops: undefined!,
+        dullCorners: undefined!,
+        lastInsertId: undefined!,
+        looseBoundingBoxes: undefined!,
+        maxCoordPowerOf2: undefined!,
+        sharpCorners: undefined!,
+        squaredDiagonalLength: undefined!,
+        tightBoundingBoxes: undefined!
+    } }];
+
+    return mats1;
+}
+
+
+/** mat-demo: "achispado" font, "comma" glyph */
+const loops1 = [
+    [
+        [[139, 8], [82, -101]],
+        [[82, -101], [24, 8]],
+        [[24, 8], [46, 8]],
+        [[46, 8], [46, 54]],
+        [[46, 54], [117, 54]],
+        [[117, 54], [117, 8]],
+        [[117, 8], [139, 8]],
+        [[139, 8], [139, 8]]
+    ]
+];
+
+
+// Cache
+let _mats1: Mat[] | undefined = undefined;
+function _getMats1() {
+    if (_mats1) { return _mats1; }
+
+    _mats1 = findMats(loops1, {
+        applySat: false,
+        simplify: true,
+        satScale: 1.675,
+        maxCurviness: 0.05,
+        maxLength: 40,
+        // maxCurviness: 5,
+        // maxLength: 4000,
+        angleIncrement: 15,
+        simplifyTolerance: 2**-1
+    });
+
+    return _mats1;
+}
+
+
+export {
+    getMats1,
+    // _getMats1
+}

package/__tests__/helpers/close-to.ts

@@ -0,0 +1,71 @@
+import type { ObjOrArray } from "./obj-or-array.js";
+
+const { EPSILON: eps, POSITIVE_INFINITY: inf } = Number;
+const abs = Math.abs;
+
+
+/**
+ * @param ulpsOrEps If a number then 2\*\*1 means last bit, 2\*\*2 means last 2 bits, etc... 
+ * else if an array containing a single number then 1 means 1 eps, 2 means 2 eps, etc...
+ */
+function closeTo(ulpsOrEps: number | number[]) {
+    let isUlps = true;
+    if (Array.isArray(ulpsOrEps)) {
+        isUlps = false;
+        ulpsOrEps = ulpsOrEps[0];
+    }
+
+    function check(
+            expected: ObjOrArray<number>,
+            actual: ObjOrArray<number>): boolean {
+
+        if (typeof expected === 'number') {
+            if (typeof actual !== 'number') { return false; }
+            const actual_ = actual as number;
+            if (expected === inf) { return actual_ === inf; }
+            const error = abs((isUlps ? expected : 1)*(ulpsOrEps as number)*eps);
+            
+            return (
+                (actual_ >= expected - error) && 
+                (actual_ <= expected + error)
+            );
+        }
+
+        if (Array.isArray(expected)) {
+            if (!Array.isArray(actual)) { return false; }
+            if (expected.length !== actual.length) { return false; }
+
+            for (let i=0; i<expected.length; i++) {
+                const e = expected[i];
+                const a = actual[i];
+    
+                if (!check(e,a)) { return false; }
+            }
+
+            return true;
+        }
+        
+        if (typeof expected === 'object') {
+            if (typeof actual !== 'object') { return false; }
+            const actual_ = actual as { [key: string]: ObjOrArray<number> };
+            const keys = Object.keys(expected);
+            const keysE = Object.keys(actual_);
+            if (keys.length !== keysE.length) { return false; }
+            for (let key of keys) {
+                const e = expected[key];
+                const a = actual_[key];
+
+                if (!check(e,a)) { return false; }
+            }
+
+            return true;
+        }
+
+        return false;  // unsupported types
+    }
+
+    return check;
+}
+
+
+export { closeTo }

package/__tests__/helpers/jest-extend-nearly.ts

@@ -0,0 +1,39 @@
+import type { MatcherContext, SyncExpectationResult } from 'expect';
+import { closeTo } from "./close-to.js";
+import { ObjOrArray } from "./obj-or-array.js";
+
+
+/**
+ * Jest custom matcher equivalent of the old Chai `nearly` plugin.
+ *
+ * Register once (e.g. in a setup file or at the top of a spec) via:
+ *     expect.extend(nearly);
+ *
+ * Then use as:
+ *     expect(received).toBeNearly(2**4, expectedValue);
+ *     expect(received).not.toBeNearly([2], expectedValue);
+ */
+const nearly = {
+    toBeNearly(
+        this: MatcherContext,
+        received: ObjOrArray<number>,
+        ulpsOrEps: number | number[],
+        value: ObjOrArray<number>,
+    ): SyncExpectationResult {
+        const isUlps = !Array.isArray(ulpsOrEps);
+
+        // Preserve the original argument order: `received` plays the role of
+        // `expected` in `closeTo` (it scales the ulp error), `value` the `actual`.
+        const pass = closeTo(ulpsOrEps)(received, value);
+
+        return {
+            pass,
+            message: () =>
+                `expected \n${JSON.stringify(received)}\n to ${this.isNot ? 'not ' : ''}be nearly ` +
+                `(${ulpsOrEps} ${isUlps ? 'ulps' : 'eps'}) \n${JSON.stringify(value)}`,
+        };
+    },
+};
+
+
+export { nearly }

package/__tests__/helpers/jest.setup.ts

@@ -0,0 +1,6 @@
+import { expect } from '@jest/globals';
+import { nearly } from './jest-extend-nearly.js';
+
+
+// Register custom matchers globally for all test files.
+expect.extend(nearly);

package/__tests__/helpers/obj-or-array.ts

@@ -0,0 +1,8 @@
+
+type ObjOrArray<T> = 
+    | T
+    | ObjOrArray<T>[]
+    | { [key:string]: ObjOrArray<T> };
+
+    
+export { ObjOrArray }

package/__tests__/jest-extensions.d.ts

@@ -0,0 +1,26 @@
+
+declare global {
+    namespace jest {
+        interface Matchers<R, T = {}> {
+            /**
+             * @param ulps If a number then 2\*\*1 means last bit, 2\*\*2 means last 2 bits, etc...
+             * else if an array containing a single number then 1 means 1 eps, 2 means 2 eps, etc...
+             */
+            toBeNearly(ulps: number | number[], value: T): R;
+        }
+    }
+}
+
+
+// Augment the matchers exposed by `@jest/globals` / `expect`.
+declare module 'expect' {
+    interface Matchers<R extends void | Promise<void>, T = unknown> {
+        /**
+         * @param ulps If a number then 2\*\*1 means last bit, 2\*\*2 means last 2 bits, etc...
+         * else if an array containing a single number then 1 means 1 eps, 2 means 2 eps, etc...
+         */
+        toBeNearly(ulps: number | number[], value: T): R;
+    }
+}
+
+export {};