json-p3 0.3.1 → 1.1.0

package/LICENCE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 James Prior
+Copyright (c) 2024 James Prior
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,6 +2,8 @@
 
 <p align="center">
 JSONPath, JSON Patch and JSON Pointer for JavaScript.
+<br>
+We follow <a href="https://datatracker.ietf.org/doc/html/rfc9535">RFC 9535</a> and test against the <a href="https://github.com/jsonpath-standard/jsonpath-compliance-test-suite">JSONPath Compliance Test Suite</a>.
 </p>
 
 <p align="center">
@@ -59,6 +61,15 @@ JSON P3 has zero runtime dependencies.
 | `json-p3-iife.js`     | A bundle formatted as an Immediately Invoked Function Expression.          |
 | `json-p3-iife.min.js` | A minified bundle formatted as an Immediately Invoked Function Expression. |
 
+## Compliance Environment Variables
+
+These environment variables control the location of the compliance test suite under test and if nondeterministic object iteration is enabled for those tests.
+
+| Environment Variable          | Description                                                                                                           |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `JSONP3_CTS_PATH`             | The path to `cts.json` used by `compliance.test.ts`. Defaults to `tests/path/cts/cts.json`.                           |
+| `JSONP3_CTS_NONDETERMINISTIC` | When set to `true`, enables nondeterministic iteration of JSON objects for `compliance.test.ts`. Defaults to `false`. |
+
 ## Contributing
 
 Please see [Contributing to JSON P3](https://github.com/jg-rp/json-p3/blob/main/CONTRIBUTING.md)

package/dist/json-p3.cjs.js

@@ -1,10 +1,10 @@
 /*
- * json-p3 version 0.3.1
+ * json-p3 version 1.1.0
  * https://github.com/jg-rp/json-p3
  * 
  * MIT License
  * 
- * Copyright (c) 2023 James Prior
+ * Copyright (c) 2024 James Prior
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -222,7 +222,7 @@ function deepEquals(a, b) {
 
 /**
  * The type of a JSONPath filter function parameter or return value, as
- * described in See section 2.4.1 of draft-ietf-jsonpath-base-20.
+ * described in See section 2.4.1 of RFC 9535.
  */
 let FunctionExpressionType = /*#__PURE__*/function (FunctionExpressionType) {
   FunctionExpressionType["ValueType"] = "ValueType";
@@ -508,7 +508,7 @@ const RE_INT = /(0|[1-9][0-9]*)/;
 /**
  * A relative JSON Pointer.
  *
- * See https://www.ietf.org/id/draft-hha-relative-json-pointer-00.html
+ * See https://datatracker.ietf.org/doc/html/draft-hha-relative-json-pointer
  */
 class RelativeJSONPointer {
   /**
@@ -1927,7 +1927,7 @@ class WildcardSelector extends JSONPathSelector {
           rv.push(new JSONPathNode(node.value[i], node.location.concat(i), node.root));
         }
       } else if (isObject(node.value)) {
-        for (const [key, value] of Object.entries(node.value)) {
+        for (const [key, value] of this.environment.entries(node.value)) {
           rv.push(new JSONPathNode(value, node.location.concat(key), node.root));
         }
       }
@@ -1942,7 +1942,7 @@ class WildcardSelector extends JSONPathSelector {
           yield new JSONPathNode(node.value[i], node.location.concat(i), node.root);
         }
       } else if (isObject(node.value)) {
-        for (const [key, value] of Object.entries(node.value)) {
+        for (const [key, value] of this.environment.entries(node.value)) {
           yield new JSONPathNode(value, node.location.concat(key), node.root);
         }
       }
@@ -2002,7 +2002,7 @@ class RecursiveDescentSegment extends JSONPathSelector {
             }
           }
         } else if (isObject(currentNode.value)) {
-          for (const [key, value] of Object.entries(currentNode.value)) {
+          for (const [key, value] of this.environment.entries(currentNode.value)) {
             const __node = new JSONPathNode(value, currentNode.location.concat(key), currentNode.root);
             yield __node;
             if (isObject(__node.value)) {
@@ -2035,7 +2035,7 @@ class RecursiveDescentSegment extends JSONPathSelector {
         }
       }
     } else if (isObject(node.value)) {
-      for (const [key, value] of Object.entries(node.value)) {
+      for (const [key, value] of this.environment.entries(node.value)) {
         const _node = new JSONPathNode(value, node.location.concat(key), node.root);
         rv.push(_node);
         for (const __node of this.visit(_node, depth + 1)) {
@@ -2072,7 +2072,7 @@ class FilterSelector extends JSONPathSelector {
           }
         }
       } else if (isObject(node.value)) {
-        for (const [key, value] of Object.entries(node.value)) {
+        for (const [key, value] of this.environment.entries(node.value)) {
           const filterContext = {
             environment: this.environment,
             currentValue: value,
@@ -2105,7 +2105,7 @@ class FilterSelector extends JSONPathSelector {
           }
         }
       } else if (isObject(node.value)) {
-        for (const [key, value] of Object.entries(node.value)) {
+        for (const [key, value] of this.environment.entries(node.value)) {
           const filterContext = {
             environment: this.environment,
             currentValue: value,
@@ -2237,8 +2237,8 @@ class JSONPath {
 }
 
 const PRECEDENCE_LOWEST = 1;
-const PRECEDENCE_LOGICAL_AND = 4;
-const PRECEDENCE_LOGICAL_OR = 5;
+const PRECEDENCE_LOGICAL_OR = 4;
+const PRECEDENCE_LOGICAL_AND = 5;
 const PRECEDENCE_COMPARISON = 6;
 const PRECEDENCE_PREFIX = 7;
 const PRECEDENCES = new Map([[TokenKind.AND, PRECEDENCE_LOGICAL_AND], [TokenKind.EQ, PRECEDENCE_COMPARISON], [TokenKind.GE, PRECEDENCE_COMPARISON], [TokenKind.GT, PRECEDENCE_COMPARISON], [TokenKind.LE, PRECEDENCE_COMPARISON], [TokenKind.LT, PRECEDENCE_COMPARISON], [TokenKind.NE, PRECEDENCE_COMPARISON], [TokenKind.NOT, PRECEDENCE_PREFIX], [TokenKind.OR, PRECEDENCE_LOGICAL_OR], [TokenKind.RPAREN, PRECEDENCE_LOWEST]]);
@@ -2568,6 +2568,10 @@ class JSONPathEnvironment {
    * can visit before a `JSONPathRecursionLimitError` is thrown.
    */
 
+  /**
+   * If `true`, enable nondeterministic ordering when iterating JSON object data.
+   */
+
   /**
    * A map of function names to objects implementing the {@link FilterFunction}
    * interface. You are free to set or delete custom filter functions directly.
@@ -2582,6 +2586,7 @@ class JSONPathEnvironment {
     this.maxIntIndex = options.maxIntIndex ?? Math.pow(2, 53) - 1;
     this.minIntIndex = options.maxIntIndex ?? -Math.pow(2, 53) - 1;
     this.maxRecursionDepth = options.maxRecursionDepth ?? 50;
+    this.nondeterministic = options.nondeterministic ?? false;
     this.parser = new Parser(this);
     this.setupFilterFunctions();
   }
@@ -2690,6 +2695,29 @@ class JSONPathEnvironment {
     }
     return args;
   }
+
+  /**
+   * Return an array of key/values of the enumerable properties in _obj_.
+   *
+   * If you want to introduce some nondeterminism to iterating JSON-like
+   * objects, do it here. The wildcard selector, descendent segment and
+   * filter selector all use `this.environment.entries`.
+   *
+   * @param obj - A JSON-like object.
+   */
+  entries(obj) {
+    function shuffle(entries) {
+      for (let i = entries.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [entries[i], entries[j]] = [entries[j], entries[i]];
+      }
+      return entries;
+    }
+    if (this.nondeterministic) {
+      return shuffle(Object.entries(obj));
+    }
+    return Object.entries(obj);
+  }
 }
 
 var index$2 = /*#__PURE__*/Object.freeze({
@@ -3278,7 +3306,7 @@ var index = /*#__PURE__*/Object.freeze({
   apply: apply
 });
 
-const version = "0.3.1";
+const version = "1.1.0";
 
 exports.DEFAULT_ENVIRONMENT = DEFAULT_ENVIRONMENT;
 exports.FunctionExpressionType = FunctionExpressionType;

package/dist/json-p3.esm.js

@@ -1,10 +1,10 @@
 /*
- * json-p3 version 0.3.1
+ * json-p3 version 1.1.0
  * https://github.com/jg-rp/json-p3
  * 
  * MIT License
  * 
- * Copyright (c) 2023 James Prior
+ * Copyright (c) 2024 James Prior
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -220,7 +220,7 @@ function deepEquals(a, b) {
 
 /**
  * The type of a JSONPath filter function parameter or return value, as
- * described in See section 2.4.1 of draft-ietf-jsonpath-base-20.
+ * described in See section 2.4.1 of RFC 9535.
  */
 let FunctionExpressionType = /*#__PURE__*/function (FunctionExpressionType) {
   FunctionExpressionType["ValueType"] = "ValueType";
@@ -506,7 +506,7 @@ const RE_INT = /(0|[1-9][0-9]*)/;
 /**
  * A relative JSON Pointer.
  *
- * See https://www.ietf.org/id/draft-hha-relative-json-pointer-00.html
+ * See https://datatracker.ietf.org/doc/html/draft-hha-relative-json-pointer
  */
 class RelativeJSONPointer {
   /**
@@ -1925,7 +1925,7 @@ class WildcardSelector extends JSONPathSelector {
           rv.push(new JSONPathNode(node.value[i], node.location.concat(i), node.root));
         }
       } else if (isObject(node.value)) {
-        for (const [key, value] of Object.entries(node.value)) {
+        for (const [key, value] of this.environment.entries(node.value)) {
           rv.push(new JSONPathNode(value, node.location.concat(key), node.root));
         }
       }
@@ -1940,7 +1940,7 @@ class WildcardSelector extends JSONPathSelector {
           yield new JSONPathNode(node.value[i], node.location.concat(i), node.root);
         }
       } else if (isObject(node.value)) {
-        for (const [key, value] of Object.entries(node.value)) {
+        for (const [key, value] of this.environment.entries(node.value)) {
           yield new JSONPathNode(value, node.location.concat(key), node.root);
         }
       }
@@ -2000,7 +2000,7 @@ class RecursiveDescentSegment extends JSONPathSelector {
             }
           }
         } else if (isObject(currentNode.value)) {
-          for (const [key, value] of Object.entries(currentNode.value)) {
+          for (const [key, value] of this.environment.entries(currentNode.value)) {
             const __node = new JSONPathNode(value, currentNode.location.concat(key), currentNode.root);
             yield __node;
             if (isObject(__node.value)) {
@@ -2033,7 +2033,7 @@ class RecursiveDescentSegment extends JSONPathSelector {
         }
       }
     } else if (isObject(node.value)) {
-      for (const [key, value] of Object.entries(node.value)) {
+      for (const [key, value] of this.environment.entries(node.value)) {
         const _node = new JSONPathNode(value, node.location.concat(key), node.root);
         rv.push(_node);
         for (const __node of this.visit(_node, depth + 1)) {
@@ -2070,7 +2070,7 @@ class FilterSelector extends JSONPathSelector {
           }
         }
       } else if (isObject(node.value)) {
-        for (const [key, value] of Object.entries(node.value)) {
+        for (const [key, value] of this.environment.entries(node.value)) {
           const filterContext = {
             environment: this.environment,
             currentValue: value,
@@ -2103,7 +2103,7 @@ class FilterSelector extends JSONPathSelector {
           }
         }
       } else if (isObject(node.value)) {
-        for (const [key, value] of Object.entries(node.value)) {
+        for (const [key, value] of this.environment.entries(node.value)) {
           const filterContext = {
             environment: this.environment,
             currentValue: value,
@@ -2235,8 +2235,8 @@ class JSONPath {
 }
 
 const PRECEDENCE_LOWEST = 1;
-const PRECEDENCE_LOGICAL_AND = 4;
-const PRECEDENCE_LOGICAL_OR = 5;
+const PRECEDENCE_LOGICAL_OR = 4;
+const PRECEDENCE_LOGICAL_AND = 5;
 const PRECEDENCE_COMPARISON = 6;
 const PRECEDENCE_PREFIX = 7;
 const PRECEDENCES = new Map([[TokenKind.AND, PRECEDENCE_LOGICAL_AND], [TokenKind.EQ, PRECEDENCE_COMPARISON], [TokenKind.GE, PRECEDENCE_COMPARISON], [TokenKind.GT, PRECEDENCE_COMPARISON], [TokenKind.LE, PRECEDENCE_COMPARISON], [TokenKind.LT, PRECEDENCE_COMPARISON], [TokenKind.NE, PRECEDENCE_COMPARISON], [TokenKind.NOT, PRECEDENCE_PREFIX], [TokenKind.OR, PRECEDENCE_LOGICAL_OR], [TokenKind.RPAREN, PRECEDENCE_LOWEST]]);
@@ -2566,6 +2566,10 @@ class JSONPathEnvironment {
    * can visit before a `JSONPathRecursionLimitError` is thrown.
    */
 
+  /**
+   * If `true`, enable nondeterministic ordering when iterating JSON object data.
+   */
+
   /**
    * A map of function names to objects implementing the {@link FilterFunction}
    * interface. You are free to set or delete custom filter functions directly.
@@ -2580,6 +2584,7 @@ class JSONPathEnvironment {
     this.maxIntIndex = options.maxIntIndex ?? Math.pow(2, 53) - 1;
     this.minIntIndex = options.maxIntIndex ?? -Math.pow(2, 53) - 1;
     this.maxRecursionDepth = options.maxRecursionDepth ?? 50;
+    this.nondeterministic = options.nondeterministic ?? false;
     this.parser = new Parser(this);
     this.setupFilterFunctions();
   }
@@ -2688,6 +2693,29 @@ class JSONPathEnvironment {
     }
     return args;
   }
+
+  /**
+   * Return an array of key/values of the enumerable properties in _obj_.
+   *
+   * If you want to introduce some nondeterminism to iterating JSON-like
+   * objects, do it here. The wildcard selector, descendent segment and
+   * filter selector all use `this.environment.entries`.
+   *
+   * @param obj - A JSON-like object.
+   */
+  entries(obj) {
+    function shuffle(entries) {
+      for (let i = entries.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [entries[i], entries[j]] = [entries[j], entries[i]];
+      }
+      return entries;
+    }
+    if (this.nondeterministic) {
+      return shuffle(Object.entries(obj));
+    }
+    return Object.entries(obj);
+  }
 }
 
 var index$2 = /*#__PURE__*/Object.freeze({
@@ -3276,6 +3304,6 @@ var index = /*#__PURE__*/Object.freeze({
   apply: apply
 });
 
-const version = "0.3.1";
+const version = "1.1.0";
 
 export { DEFAULT_ENVIRONMENT, FunctionExpressionType, JSONPatch, JSONPatchError, JSONPatchTestFailure, JSONPath, JSONPathEnvironment, JSONPathError, JSONPathIndexError, JSONPathLexerError, JSONPathNode, JSONPathNodeList, JSONPathRecursionLimitError, JSONPathSyntaxError, JSONPathTypeError, JSONPointer, Nothing, RelativeJSONPointer, Token, TokenKind, UNDEFINED, apply, compile, index as jsonpatch, index$1 as jsonpath, index$3 as jsonpointer, lazyQuery, query, resolve, version };

package/dist/json-p3.iife.js

@@ -1,10 +1,10 @@
 /*
- * json-p3 version 0.3.1
+ * json-p3 version 1.1.0
  * https://github.com/jg-rp/json-p3
  * 
  * MIT License
  * 
- * Copyright (c) 2023 James Prior
+ * Copyright (c) 2024 James Prior
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -223,7 +223,7 @@ var json_p3 = (function (exports) {
 
   /**
    * The type of a JSONPath filter function parameter or return value, as
-   * described in See section 2.4.1 of draft-ietf-jsonpath-base-20.
+   * described in See section 2.4.1 of RFC 9535.
    */
   let FunctionExpressionType = /*#__PURE__*/function (FunctionExpressionType) {
     FunctionExpressionType["ValueType"] = "ValueType";
@@ -509,7 +509,7 @@ var json_p3 = (function (exports) {
   /**
    * A relative JSON Pointer.
    *
-   * See https://www.ietf.org/id/draft-hha-relative-json-pointer-00.html
+   * See https://datatracker.ietf.org/doc/html/draft-hha-relative-json-pointer
    */
   class RelativeJSONPointer {
     /**
@@ -1928,7 +1928,7 @@ var json_p3 = (function (exports) {
             rv.push(new JSONPathNode(node.value[i], node.location.concat(i), node.root));
           }
         } else if (isObject(node.value)) {
-          for (const [key, value] of Object.entries(node.value)) {
+          for (const [key, value] of this.environment.entries(node.value)) {
             rv.push(new JSONPathNode(value, node.location.concat(key), node.root));
           }
         }
@@ -1943,7 +1943,7 @@ var json_p3 = (function (exports) {
             yield new JSONPathNode(node.value[i], node.location.concat(i), node.root);
           }
         } else if (isObject(node.value)) {
-          for (const [key, value] of Object.entries(node.value)) {
+          for (const [key, value] of this.environment.entries(node.value)) {
             yield new JSONPathNode(value, node.location.concat(key), node.root);
           }
         }
@@ -2003,7 +2003,7 @@ var json_p3 = (function (exports) {
               }
             }
           } else if (isObject(currentNode.value)) {
-            for (const [key, value] of Object.entries(currentNode.value)) {
+            for (const [key, value] of this.environment.entries(currentNode.value)) {
               const __node = new JSONPathNode(value, currentNode.location.concat(key), currentNode.root);
               yield __node;
               if (isObject(__node.value)) {
@@ -2036,7 +2036,7 @@ var json_p3 = (function (exports) {
           }
         }
       } else if (isObject(node.value)) {
-        for (const [key, value] of Object.entries(node.value)) {
+        for (const [key, value] of this.environment.entries(node.value)) {
           const _node = new JSONPathNode(value, node.location.concat(key), node.root);
           rv.push(_node);
           for (const __node of this.visit(_node, depth + 1)) {
@@ -2073,7 +2073,7 @@ var json_p3 = (function (exports) {
             }
           }
         } else if (isObject(node.value)) {
-          for (const [key, value] of Object.entries(node.value)) {
+          for (const [key, value] of this.environment.entries(node.value)) {
             const filterContext = {
               environment: this.environment,
               currentValue: value,
@@ -2106,7 +2106,7 @@ var json_p3 = (function (exports) {
             }
           }
         } else if (isObject(node.value)) {
-          for (const [key, value] of Object.entries(node.value)) {
+          for (const [key, value] of this.environment.entries(node.value)) {
             const filterContext = {
               environment: this.environment,
               currentValue: value,
@@ -2238,8 +2238,8 @@ var json_p3 = (function (exports) {
   }
 
   const PRECEDENCE_LOWEST = 1;
-  const PRECEDENCE_LOGICAL_AND = 4;
-  const PRECEDENCE_LOGICAL_OR = 5;
+  const PRECEDENCE_LOGICAL_OR = 4;
+  const PRECEDENCE_LOGICAL_AND = 5;
   const PRECEDENCE_COMPARISON = 6;
   const PRECEDENCE_PREFIX = 7;
   const PRECEDENCES = new Map([[TokenKind.AND, PRECEDENCE_LOGICAL_AND], [TokenKind.EQ, PRECEDENCE_COMPARISON], [TokenKind.GE, PRECEDENCE_COMPARISON], [TokenKind.GT, PRECEDENCE_COMPARISON], [TokenKind.LE, PRECEDENCE_COMPARISON], [TokenKind.LT, PRECEDENCE_COMPARISON], [TokenKind.NE, PRECEDENCE_COMPARISON], [TokenKind.NOT, PRECEDENCE_PREFIX], [TokenKind.OR, PRECEDENCE_LOGICAL_OR], [TokenKind.RPAREN, PRECEDENCE_LOWEST]]);
@@ -2569,6 +2569,10 @@ var json_p3 = (function (exports) {
      * can visit before a `JSONPathRecursionLimitError` is thrown.
      */
 
+    /**
+     * If `true`, enable nondeterministic ordering when iterating JSON object data.
+     */
+
     /**
      * A map of function names to objects implementing the {@link FilterFunction}
      * interface. You are free to set or delete custom filter functions directly.
@@ -2583,6 +2587,7 @@ var json_p3 = (function (exports) {
       this.maxIntIndex = options.maxIntIndex ?? Math.pow(2, 53) - 1;
       this.minIntIndex = options.maxIntIndex ?? -Math.pow(2, 53) - 1;
       this.maxRecursionDepth = options.maxRecursionDepth ?? 50;
+      this.nondeterministic = options.nondeterministic ?? false;
       this.parser = new Parser(this);
       this.setupFilterFunctions();
     }
@@ -2691,6 +2696,29 @@ var json_p3 = (function (exports) {
       }
       return args;
     }
+
+    /**
+     * Return an array of key/values of the enumerable properties in _obj_.
+     *
+     * If you want to introduce some nondeterminism to iterating JSON-like
+     * objects, do it here. The wildcard selector, descendent segment and
+     * filter selector all use `this.environment.entries`.
+     *
+     * @param obj - A JSON-like object.
+     */
+    entries(obj) {
+      function shuffle(entries) {
+        for (let i = entries.length - 1; i > 0; i--) {
+          const j = Math.floor(Math.random() * (i + 1));
+          [entries[i], entries[j]] = [entries[j], entries[i]];
+        }
+        return entries;
+      }
+      if (this.nondeterministic) {
+        return shuffle(Object.entries(obj));
+      }
+      return Object.entries(obj);
+    }
   }
 
   var index$2 = /*#__PURE__*/Object.freeze({
@@ -3279,7 +3307,7 @@ var json_p3 = (function (exports) {
     apply: apply
   });
 
-  const version = "0.3.1";
+  const version = "1.1.0";
 
   exports.DEFAULT_ENVIRONMENT = DEFAULT_ENVIRONMENT;
   exports.FunctionExpressionType = FunctionExpressionType;