json-p3 0.1.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 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
+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/README.md

@@ -0,0 +1,252 @@
+<h1 align="center">JSON P3</h1>
+
+<p align="center">
+JSONPath, JSON Patch and JSON Pointer for JavaScript.
+</p>
+
+<p align="center">
+  <a href="https://github.com/jg-rp/json-p3/blob/main/LICENSE">
+    <img alt="NPM" src="https://img.shields.io/npm/l/json-p3">
+  </a>
+  <a href="https://github.com/jg-rp/json-p3/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/jg-rp/json-p3/tests.yaml?branch=main&label=tests&style=flat-square" alt="Tests">
+  </a>
+  <br>
+</p>
+
+---
+
+## Install
+
+### Node.js
+
+Use npm:
+
+```console
+npm install --save json-p3
+```
+
+Or yarn:
+
+```console
+yarn add json-p3
+```
+
+Or pnpm:
+
+```console
+pnpm add json-p3
+```
+
+And use ES module imports:
+
+```javascript
+import { query } from "json-p3";
+
+const data = {
+  players: [{ name: "Sue" }, { name: "John" }, { name: "Sally" }],
+  visitors: [{ name: "Brian" }, { name: "Roy" }],
+};
+
+const nodes = query("$..name", data);
+console.log(nodes.values());
+// [ 'Sue', 'John', 'Sally', 'Brian', 'Roy' ]
+```
+
+Or CommonJS modules:
+
+```javascript
+const { query } = require("json-p3");
+
+const data = {
+  players: [{ name: "Sue" }, { name: "John" }, { name: "Sally" }],
+  visitors: [{ name: "Brian" }, { name: "Roy" }],
+};
+
+const nodes = query("$..name", data);
+console.log(nodes.values());
+// [ 'Sue', 'John', 'Sally', 'Brian', 'Roy' ]
+```
+
+### Browser
+
+TODO:
+
+## JSONPath
+
+Retrieve values from JSON-like data using JSONPath query expressions. We strictly follow standards described in the [IETF JSONPath draft](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-20).
+
+```javascript
+import { jsonpath } from "json-p3";
+
+const data = {
+  users: [
+    { name: "Sue", score: 100 },
+    { name: "John", score: 86 },
+    { name: "Sally", score: 84 },
+    { name: "Jane", score: 55 },
+  ],
+};
+
+const nodes = jsonpath.query("$.users[?@.score < 100].name", data);
+console.log(nodes.values()); // [ 'John', 'Sally', 'Jane' ]
+```
+
+The result of `jsonpath.query()` is an instance of `JSONPathNodeList`. That is a list of `JSONPathNode` objects, one node for each value in the target JSON document matching the query. Each node has a:
+
+- `value` - The value found in the target JSON value. This could be an array, object or primitive value.
+- `location` - An array of property names and array indices that were required to reach the node's value in the target JSON value.
+- `path` - The normalized JSONPath to this node in the target JSON document.
+
+Use `JSONPathNodeList.paths()` to retrieve all node paths.
+
+```javascript
+// .. continued from above
+console.log(nodes.paths());
+```
+
+**Output:**
+
+```plain
+[
+  "$['users']['1']['name']",
+  "$['users']['2']['name']",
+  "$['users']['3']['name']"
+]
+```
+
+And `JSONPathNodeList.locations()` to get an array of node locations.
+
+```javascript
+// .. continued from above
+console.log(nodes.locations());
+```
+
+**Output:**
+
+```plain
+[
+  [ 'users', 1, 'name' ],
+  [ 'users', 2, 'name' ],
+  [ 'users', 3, 'name' ]
+]
+```
+
+TODO: node lists are iterable
+
+You can also compile a JSONPath query for repeated use against different data.
+
+```javascript
+import { jsonpath } from "json-p3";
+
+const data = {
+  users: [
+    { name: "Sue", score: 100 },
+    { name: "John", score: 86 },
+    { name: "Sally", score: 84 },
+    { name: "Jane", score: 55 },
+  ],
+};
+
+const path = jsonpath.compile("$.users[?@.score < 100].name");
+const nodes = path.query(data);
+console.log(nodes.values()); // [ 'John', 'Sally', 'Jane' ]
+```
+
+## JSON Pointer
+
+Identify a single value in JSON-like data, as per RFC 6901. Use `jsonpointer.resolve()` to retrieve the value.
+
+```javascript
+import { jsonpointer } from "json-p3";
+
+const data = {
+  users: [
+    { name: "Sue", score: 100 },
+    { name: "John", score: 86 },
+    { name: "Sally", score: 84 },
+    { name: "Jane", score: 55 },
+  ],
+};
+
+const rv = jsonpointer.resolve("/users/1", data);
+console.log(rv); // { name: 'John', score: 86 }
+```
+
+If the pointer can't be resolved against the argument JSON value, one of `JSONPointerIndexError`, `JSONPointerKeyError` or `JSONPointerTypeError` is thrown. All three exceptions inherit from `JSONPointerResolutionError`.
+
+```javascript
+import { jsonpointer } from "json-p3";
+
+const data = {
+  users: [
+    { name: "Sue", score: 100 },
+    { name: "John", score: 86 },
+    { name: "Sally", score: 84 },
+    { name: "Jane", score: 55 },
+  ],
+};
+
+const rv = jsonpointer.resolve("/users/1/age", data);
+// JSONPointerKeyError: no such property ("/users/1/age")
+```
+
+A fallback value can be given as a third argument, which will be returned in the event of a `JSONPointerResolutionError`.
+
+```javascript
+import { jsonpointer } from "json-p3";
+
+const data = {
+  users: [
+    { name: "Sue", score: 100 },
+    { name: "John", score: 86 },
+    { name: "Sally", score: 84 },
+    { name: "Jane", score: 55 },
+  ],
+};
+
+const rv = jsonpointer.resolve("/users/1/age", data, -1);
+console.log(rv); // -1
+```
+
+TODO: "compile" a pointer for later use
+
+## JSON Patch
+
+Apply a JSON Patch ([RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902)) to some data. A JSON Patch defines update operation to perform on a JSON document. **Data is modified in place.**.
+
+```javascript
+import { jsonpatch } from "json-p3";
+
+const ops = [
+  { op: "add", path: "/some/foo", value: { foo: {} } },
+  { op: "add", path: "/some/foo", value: { bar: [] } },
+  { op: "copy", from: "/some/other", path: "/some/foo/else" },
+  { op: "add", path: "/some/foo/bar/-", value: 1 },
+];
+
+const data = { some: { other: "thing" } };
+jsonpatch.apply(ops, data);
+console.log(data);
+// { some: { other: 'thing', foo: { bar: [Array], else: 'thing' } } }
+```
+
+Use the `JSONPatch` class to create a patch for repeated application.
+
+```javascript
+import { JSONPatch } from "json-p3";
+
+const patch = new JSONPatch([
+  { op: "add", path: "/some/foo", value: { foo: {} } },
+  { op: "add", path: "/some/foo", value: { bar: [] } },
+  { op: "copy", from: "/some/other", path: "/some/foo/else" },
+  { op: "add", path: "/some/foo/bar/-", value: 1 },
+]);
+
+const data = { some: { other: "thing" } };
+patch.apply(data);
+console.log(data);
+// { some: { other: 'thing', foo: { bar: [Array], else: 'thing' } } }
+```
+
+TODO: patch builder api

package/dist/deep_equals.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Deep equality of JSON-like values.
+ *
+ * No attempt is made to handle function objects, recursive data
+ * structures, NaNs, sparse arrays, primitive wrapper objects....
+ *
+ * We're not using JSON.stringify because we want objects with the same
+ * entries in a different order to compare equal.
+ */
+export declare function deepEquals(a: unknown, b: unknown): boolean;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export declare const version = "__VERSION__";
+export * as jsonpath from "./path";
+export { FunctionExpressionType, JSONPath, JSONPathEnvironment, JSONPathError, JSONPathIndexError, JSONPathLexerError, JSONPathNode, JSONPathNodeList, JSONPathSyntaxError, JSONPathTypeError, Token, TokenKind, Nothing, query, compile, } from "./path";
+export type { JSONPathEnvironmentOptions, FilterFunction } from "./path";
+export * as jsonpointer from "./pointer";
+export { JSONPointer, resolve, UNDEFINED } from "./pointer";
+export * as jsonpatch from "./patch";
+export { JSONPatch, JSONPatchError, JSONPatchTestFailure, apply, } from "./patch";
+export type { OpObject } from "./patch";
+export type { JSONValue } from "./types";