feat(evaluate): add support for Immutable.js realm

Refs #13

Author: char0n

README.md

@@ -45,6 +45,7 @@
         - [Map/Set](#mapset-evaluation-realm)
         - [Minim](#minim-evaluation-realm)
         - [ApiDOM](#apidom-evaluation-realm)
+        - [Immutable.js]('#immutablejs-evaluation-realm)
         - [Custom](#custom-evaluation-realms)
         - [Composing Realms](#composing-evaluation-realms)
     - [Compilation](#compilation)
@@ -426,6 +427,30 @@ const objectElement = new ObjectElement({
 evaluate(objectElement, '/a/1', { realm: new ApiDOMEvaluationRealm() }); // => StringElement('c')
 ```
 
+###### Immutable.js Evaluation Realm
+
+The [Immutable.js](https://immutable-js.com/) Evaluation Realm is an integration layer that enables
+evaluation of JSON Pointer expressions on Immutable.js structures.
+
+Before using the Immutable.js Evaluation Realm, you need to install the `immutable` packages:
+
+```sh
+ $ npm install --save immutable
+```
+
+```js
+import { fromJS } from 'immutable';
+import { evaluate } from '@swaggerexpert/json-pointer';
+import ImmutableEvaluationRealm from '@swaggerexpert/json-pointer/evaluate/realms/immutable';
+
+const map = fromJS({
+  a: ['b', 'c']
+});
+
+evaluate(map, '/a/1', { realm: new ImmutableEvaluationRealm() }); // => 'c'
+```
+
+
 ###### Custom Evaluation Realms
 
 The evaluation is designed to support **custom evaluation realms**,

package-lock.json

@@ -84,6 +84,7 @@
     "chai": "=5.2.0",
     "cross-env": "^7.0.3",
     "husky": "=9.1.7",
+    "immutable": "^5.1.1",
     "minim": "^0.23.8",
     "mocha": "=11.1.0",
     "npm-watch": "^0.13.0",

package.json

@@ -0,0 +1,41 @@
+import { isMap, isList } from 'immutable';
+
+import EvaluationRealm from '../EvaluationRealm.js';
+
+class ImmutableEvaluationRealm extends EvaluationRealm {
+  name = 'immutable';
+
+  isArray(node) {
+    return isList(node);
+  }
+
+  isObject(node) {
+    return isMap(node);
+  }
+
+  sizeOf(node) {
+    if (this.isArray(node) || this.isObject(node)) {
+      return node.size;
+    }
+    return 0;
+  }
+
+  has(node, referenceToken) {
+    if (this.isArray(node)) {
+      return Number(referenceToken) < this.sizeOf(node);
+    }
+    if (this.isObject(node)) {
+      return node.has(referenceToken);
+    }
+    return false;
+  }
+
+  evaluate(node, referenceToken) {
+    if (this.isArray(node)) {
+      return node.get(Number(referenceToken));
+    }
+    return node.get(referenceToken);
+  }
+}
+
+export default ImmutableEvaluationRealm;

src/evaluate/realms/immutable.js

@@ -0,0 +1,147 @@
+import { assert } from 'chai';
+import { fromJS } from 'immutable';
+
+import {
+  evaluate,
+  JSONPointerIndexError,
+  JSONPointerTypeError,
+  JSONPointerKeyError,
+  JSONPointerEvaluateError,
+  URIFragmentIdentifier,
+} from '../../../src/index.js';
+import ImmutableEvaluationRealm from '../../../src/evaluate/realms/immutable.js';
+
+describe('evaluate', function () {
+  context('Immutable.js realm', function () {
+    const realm = new ImmutableEvaluationRealm();
+    const map = fromJS({
+      foo: ['bar', 'baz'],
+      '': 0,
+      'a/b': 1,
+      'c%d': 2,
+      'e^f': 3,
+      'g|h': 4,
+      'i\\j': 5,
+      'k"l': 6,
+      ' ': 7,
+      'm~n': 8,
+    });
+
+    context('RFC 6901 JSON String tests', function () {
+      const jsonStringRepEntries = [
+        ['', map],
+        ['/foo', map.get('foo')],
+        ['/foo/0', map.getIn(['foo', 0])],
+        ['/', 0],
+        ['/a~1b', 1],
+        ['/c%d', 2],
+        ['/e^f', 3],
+        ['/g|h', 4],
+        ['/i\\j', 5],
+        ['/k"l', 6],
+        ['/ ', 7],
+        ['/m~0n', 8],
+      ];
+
+      jsonStringRepEntries.forEach(([jsonString, expected]) => {
+        specify('should correctly evaluate JSON Pointer from JSON String', function () {
+          const actual = evaluate(map, jsonString, { realm });
+
+          assert.strictEqual(actual, expected);
+        });
+      });
+    });
+
+    context('RFC 6901 URI Fragment Identifier tests', function () {
+      const fragmentRepEntries = [
+        ['#', map],
+        ['#/foo', map.get('foo')],
+        ['#/foo/0', map.getIn(['foo', 0])],
+        ['#/', 0],
+        ['#/a~1b', 1],
+        ['#/c%25d', 2],
+        ['#/e%5Ef', 3],
+        ['#/g%7Ch', 4],
+        ['#/i%5Cj', 5],
+        ['#/k%22l', 6],
+        ['#/%20', 7],
+        ['#/m~0n', 8],
+      ];
+
+      fragmentRepEntries.forEach(([fragment, expected]) => {
+        specify('should correctly evaluate JSON Pointer from URI Fragment Identifier', function () {
+          const actual = evaluate(map, URIFragmentIdentifier.from(fragment), {
+            realm,
+          });
+
+          assert.deepEqual(actual, expected);
+        });
+      });
+    });
+
+    context('invalid JSON Pointers (should throw errors)', function () {
+      specify('should throw JSONPointerEvaluateError for invalid JSON Pointer', function () {
+        assert.throws(() => evaluate(map, 'invalid-pointer', { realm }), JSONPointerEvaluateError);
+      });
+
+      specify(
+        'should throw JSONPointerTypeError for accessing property on non-object/array',
+        function () {
+          assert.throws(() => evaluate(map, '/foo/0/bad', { realm }), JSONPointerTypeError);
+        },
+      );
+
+      specify('should throw JSONPointerKeyError for non-existing key', function () {
+        assert.throws(() => evaluate(map, '/nonexistent', { realm }), JSONPointerKeyError);
+      });
+
+      specify('should throw JSONPointerIndexError for non-numeric array index', function () {
+        assert.throws(() => evaluate(map, '/foo/x', { realm }), JSONPointerIndexError);
+      });
+
+      specify('should throw JSONPointerIndexError for out-of-bounds array index', function () {
+        assert.throws(() => evaluate(map, '/foo/5', { realm }), JSONPointerIndexError);
+      });
+
+      specify('should throw JSONPointerIndexError for leading zero in array index', function () {
+        assert.throws(() => evaluate(map, '/foo/01', { realm }), JSONPointerIndexError);
+      });
+
+      specify('should throw JSONPointerIndexError for "-" when strictArrays is true', function () {
+        assert.throws(
+          () => evaluate(map, '/foo/-', { strictArrays: true, realm }),
+          JSONPointerIndexError,
+        );
+      });
+
+      specify('should return undefined for "-" when strictArrays is false', function () {
+        assert.strictEqual(evaluate(map, '/foo/-', { strictArrays: false, realm }), undefined);
+      });
+
+      specify(
+        'should throw JSONPointerKeyError for accessing chain of object properties that do not exist',
+        function () {
+          assert.throws(() => evaluate(map, '/missing/key', { realm }), JSONPointerKeyError);
+        },
+      );
+
+      specify(
+        'should return undefined accessing object property that does not exist when strictObject is false',
+        function () {
+          assert.isUndefined(evaluate(map, '/missing', { strictObjects: false, realm }));
+        },
+      );
+
+      specify('should throw JSONPointerTypeError when evaluating on primitive', function () {
+        assert.throws(() => evaluate('not-an-object', '/foo', { realm }), JSONPointerTypeError);
+      });
+
+      specify(
+        'should throw JSONPointerTypeError when trying to access deep path on primitive',
+        function () {
+          assert.throws(() => evaluate({ foo: 42 }, '/foo/bar', { realm }), JSONPointerTypeError);
+        },
+      );
+    });
+  });
+});