json-p3 0.1.1 → 0.2.0

package/README.md

@@ -19,101 +19,6 @@ JSONPath, JSON Patch and JSON Pointer for JavaScript.
 
 ---
 
-**Table of Contents**
-
-- [Install](#install)
-- [JSONPath](#jsonpath)
-- [JSON Pointer](#json-pointer)
-- [JSON Patch](#json-patch)
-
-## 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
-
-Download and include JSON P3 in a script tag:
-
-```html
-<script src="path/to/json-p3.iife.min.js"></script>
-<script>
-  const data = {
-    players: [{ name: "Sue" }, { name: "John" }, { name: "Sally" }],
-    visitors: [{ name: "Brian" }, { name: "Roy" }],
-  };
-  const nodes = json_p3.query("$..name");
-  console.log(nodes.values());
-  // [ 'Sue', 'John', 'Sally', 'Brian', 'Roy' ]
-</script>
-```
-
-Or use a CDN:
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/json-p3@0.1.0/dist/json-p3.iife.min.js"></script>
-<script>
-  const data = {
-    players: [{ name: "Sue" }, { name: "John" }, { name: "Sally" }],
-    visitors: [{ name: "Brian" }, { name: "Roy" }],
-  };
-  const nodes = json_p3.query("$..name");
-  console.log(nodes.values());
-  // [ 'Sue', 'John', 'Sally', 'Brian', 'Roy' ]
-</script>
-```
-
-## 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";
 
@@ -130,205 +35,33 @@ 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 document. 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 document.
-- `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());
-```
+## Links
 
-**Output:**
+- Docs: https://jg-rp.github.io/json-p3/
+- Install: https://jg-rp.github.io/json-p3/#install
+- JSONPath syntax: https://jg-rp.github.io/json-p3/guides/jsonpath-syntax
+- API reference: https://jg-rp.github.io/json-p3/api
+- Change log: https://github.com/jg-rp/json-p3/blob/main/CHANGELOG.md
+- NPM: https://www.npmjs.com/package/json-p3
+- Issue tracker: https://github.com/jg-rp/json-p3/issues
 
-```plain
-[
-  [ 'users', 1, 'name' ],
-  [ 'users', 2, 'name' ],
-  [ 'users', 3, 'name' ]
-]
-```
+## Bundles
 
-`JSONPathNodeList` objects are iterable too.
+JSON P3 is written in TypeScript, compiled to JavaScript using [Babel](https://babeljs.io/), and bundled using [Rollup](https://rollupjs.org/introduction/). The following, included bundles target `defaults, maintained node version`, as defined by [Browserslist](https://browsersl.ist/#q=defaults%2C+maintained+node+versions).
 
-```javascript
-// .. continued from above
-for (const node of nodes) {
-  console.log(`${node.value} @ ${node.path}`);
-}
-```
+JSON P3 has zero runtime dependencies.
 
-**Output:**
+| Bundle                | Description                                                                |
+| --------------------- | -------------------------------------------------------------------------- |
+| `json-p3.cjs.js`      | A CommonJS formatted bundle.                                               |
+| `json-p3.esm.js`      | An ECMAScript module formatted bundle.                                     |
+| `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. |
 
-```plain
-John @ $['users'][1]['name']
-Sally @ $['users'][2]['name']
-Jane @ $['users'][3]['name']
-```
+## Contributing
 
-You can also compile a JSONPath query for repeated use against different data.
+Please see [Contributing to JSON P3](https://github.com/jg-rp/json-p3/blob/main/CONTRIBUTING.md)
 
-```javascript
-import { jsonpath } from "json-p3";
+## License
 
-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
-// .. continued from above
-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
-// .. continued from above
-const rv = jsonpointer.resolve("/users/1/age", data, -1);
-console.log(rv); // -1
-```
-
-You can also create an instance of `JSONPointer` then resolve it against different data.
-
-```javascript
-import { JSONPointer } from "json-p3";
-
-const someData = {
-  users: [
-    { name: "Sue", score: 100 },
-    { name: "John", score: 86 },
-    { name: "Sally", score: 84 },
-  ],
-};
-
-const otherData = {
-  users: [{ name: "Brian" }, { name: "Roy" }],
-};
-
-const pointer = new JSONPointer("/users/1");
-console.log(pointer.resolve(someData)); // { name: 'John', score: 86 }
-console.log(pointer.resolve(otherData)); // { name: 'Roy' }
-```
-
-## 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' } } }
-```
-
-`JSONPatch` also offers a builder API for constructing JSON patch documents. We use strings as JSON Pointers in this example, but existing `JSONPointer` objects are OK too.
-
-```javascript
-import { JSONPatch } from "json-p3";
-
-const data = { some: { other: "thing" } };
-
-const patch = new JSONPatch()
-  .add("/some/foo", { foo: [] })
-  .add("/some/foo", { bar: [] })
-  .copy("/some/other", "/some/foo/else")
-  .add("/some/foo/bar/-", "/some/foo/else");
-
-patch.apply(data);
-console.log(JSON.stringify(data, undefined, "  "));
-```
-
-**Output:**
-
-```json
-{
-  "some": {
-    "other": "thing",
-    "foo": {
-      "bar": ["/some/foo/else"],
-      "else": "thing"
-    }
-  }
-}
-```
+`json-p3` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 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 { DEFAULT_ENVIRONMENT, FunctionExpressionType, JSONPath, JSONPathEnvironment, JSONPathError, JSONPathIndexError, JSONPathLexerError, JSONPathNode, JSONPathNodeList, JSONPathSyntaxError, JSONPathTypeError, JSONPathRecursionLimitError, 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 { JSONPointer, RelativeJSONPointer, resolve, UNDEFINED, } from "./pointer";
 export * as jsonpatch from "./patch";
 export { JSONPatch, JSONPatchError, JSONPatchTestFailure, apply, } from "./patch";
 export type { OpObject } from "./patch";