json-p3 0.1.0 → 0.2.0

package/README.md

@@ -6,76 +6,19 @@ JSONPath, JSON Patch and JSON Pointer for JavaScript.
 
 <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">
+    <img alt="LICENSE" src="https://img.shields.io/npm/l/json-p3?style=flat-square">
   </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>
+  <a href="https://www.npmjs.com/package/json-p3">
+    <img alt="NPM" src="https://img.shields.io/npm/v/json-p3?style=flat-square">
+  </a>
+  <img alt="npm type definitions" src="https://img.shields.io/npm/types/json-p3?style=flat-square">
 </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";
 
@@ -92,161 +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 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:**
+## Links
 
-```plain
-[
-  "$['users']['1']['name']",
-  "$['users']['2']['name']",
-  "$['users']['3']['name']"
-]
-```
+- 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
 
-And `JSONPathNodeList.locations()` to get an array of node locations.
+## Bundles
 
-```javascript
-// .. continued from above
-console.log(nodes.locations());
-```
+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).
 
-**Output:**
+JSON P3 has zero runtime dependencies.
 
-```plain
-[
-  [ 'users', 1, 'name' ],
-  [ 'users', 2, 'name' ],
-  [ 'users', 3, 'name' ]
-]
-```
+| 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. |
 
-TODO: node lists are iterable
+## 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";
-
-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' } } }
-```
+## License
 
-TODO: patch builder api
+`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";