Merge pull request #33 from jg-rp/export-options

Update docs and export `SerializationOptions`

Author: jg-rp

docs/docs/quick-start.md

@@ -147,6 +147,26 @@ console.log(nodes.values()); // [ 'John', 'Sally', 'Jane' ]
 
 `compile()` is also re-exported to JSON P3's top-level namespace.
 
+### Query serialization
+
+A [compiled `JSONPathQuery`](#compilation) can be serialized back to a string using its [`toString()`](./api/namespaces/jsonpath/classes/JSONPathQuery.md#tostring) method. As of version 2.1.0, the default string representation uses shorthand notation where possible and double quotes for names and string literals rather than single quotes.
+
+```javascript
+import { jsonpath } from "json-p3";
+
+const path = jsonpath.compile("$['users'][?@.score < 100]['name']");
+console.log(path.toString()); // $.users[?@.score < 100].name
+```
+
+To serialize a `JSONPathQuery` using the canonical bracket notation and single quotes, pass a [`SerializationOptions`](./api/namespaces/jsonpath/type-aliases/SerializationOptions.md) object as an argument to `toString()`.
+
+```javascript
+import { jsonpath } from "json-p3";
+
+const path = jsonpath.compile("$.users[?@.score < 100].name");
+console.log(path.toString({ form: "canonical" })); $['users'][?@['score'] < 100]['name']
+```
+
 ## JSON Pointer
 
 Resolve a JSON Pointer ([RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)) against some data using `jsonpointer.resolve()`.

docs/package-lock.json

@@ -14,28 +14,28 @@
     "write-heading-ids": "docusaurus write-heading-ids"
   },
   "dependencies": {
-    "@docusaurus/core": "^3.6.3",
-    "@docusaurus/preset-classic": "^3.6.3",
+    "@docusaurus/core": "^3.7.0",
+    "@docusaurus/preset-classic": "^3.7.0",
     "@mdx-js/react": "^3.1.0",
     "@monaco-editor/react": "^4.6.0",
     "@tsconfig/docusaurus": "^2.0.3",
     "allotment": "^1.20.2",
     "autoprefixer": "^10.4.20",
     "clsx": "^2.1.1",
-    "docusaurus-plugin-typedoc": "^1.1.1",
+    "docusaurus-plugin-typedoc": "^1.2.2",
     "monaco-editor": "^0.52.0",
     "monaco-themes": "^0.4.4",
     "postcss": "^8.4.49",
     "prism-react-renderer": "^2.4.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "tailwindcss": "^3.4.16",
-    "typedoc": "^0.27.4",
-    "typedoc-plugin-markdown": "^4.3.2",
+    "typedoc": "^0.27.6",
+    "typedoc-plugin-markdown": "^4.4.1",
     "typescript": "^5.6.2"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^3.3.2",
+    "@docusaurus/module-type-aliases": "^3.7.0",
     "prettier": "^3.4.2",
     "prettier-plugin-tailwindcss": "^0.6.9"
   },

docs/package.json

@@ -35,8 +35,13 @@ const sidebars = {
   ],
   API: [
     {
-      type: "autogenerated",
-      dirName: "api",
+      type: "category",
+      label: "Typedoc API",
+      link: {
+        type: "doc",
+        id: "api/index",
+      },
+      items: require("./docs/api/typedoc-sidebar.cjs"),
     },
   ],
 };

docs/sidebars.js

@@ -29,7 +29,11 @@ export {
 } from "./errors";
 
 export { Nothing, KEY_MARK } from "./types";
-export type { JSONPathValue, FilterContext } from "./types";
+export type {
+  JSONPathValue,
+  FilterContext,
+  SerializationOptions,
+} from "./types";
 
 export const DEFAULT_ENVIRONMENT = new JSONPathEnvironment();
 

src/path/index.ts

@@ -6,23 +6,18 @@ import { JSONPathSegment, DescendantSegment } from "./segments";
 import { SerializationOptions } from "./types";
 
 /**
- *
+ * A compiled JSONPath query ready to be applied to different data repeatedly.
  */
 export class JSONPathQuery {
-  /**
-   *
-   * @param environment -
-   * @param segments -
-   */
   constructor(
     readonly environment: JSONPathEnvironment,
     readonly segments: JSONPathSegment[],
   ) {}
 
   /**
-   *
-   * @param value -
-   * @returns
+   * Apply this JSONPath query to _value_.
+   * @param value - A JSON-like object to apply this query to.
+   * @returns Nodes matched by applying this query to _value_.
    */
   public query(value: JSONValue): JSONPathNodeList {
     let nodes = [new JSONPathNode(value, [], value)];
@@ -33,9 +28,9 @@ export class JSONPathQuery {
   }
 
   /**
-   *
-   * @param value -
-   * @returns
+   * Apply this JSONPath query to _value_.
+   * @param value - A JSON-like object to apply this query to.
+   * @returns An iterator over nodes matched by applying this query to _value_.
    */
   public lazyQuery(value: JSONValue): IterableIterator<JSONPathNode> {
     let nodes: IterableIterator<JSONPathNode> = [
@@ -66,10 +61,12 @@ export class JSONPathQuery {
    * Return a string representation of this query.
    */
   public toString(options?: SerializationOptions): string {
-    // return this.prettyPath();
     return `$${this.segments.map((s) => s.toString(options)).join("")}`;
   }
 
+  /**
+   * Return `true` if this query is a _singular query_, or `false` otherwise.
+   */
   public singularQuery(): boolean {
     for (const segment of this.segments) {
       if (segment instanceof DescendantSegment) return false;

src/path/path.ts

@@ -9,7 +9,7 @@ export const Nothing = Symbol.for("jsonpath.nothing");
 export type JSONPathValue = JSONValue | typeof Nothing;
 
 /**
- * Object passed to FilterExpression.evaluate().
+ * Object passed to `FilterExpression.evaluate()`.
  */
 export type FilterContext = {
   environment: JSONPathEnvironment;
@@ -31,7 +31,9 @@ export function hasStringKey(
 
 export const KEY_MARK = "\x02";
 
-/** Options for serializing paths */
+/**
+ * Options for serializing paths.
+ */
 export type SerializationOptions = {
   /**
    * `pretty` paths always use:
@@ -50,6 +52,7 @@ export type SerializationOptions = {
    */
   form: "pretty" | "canonical";
 };
+
 export const defaultSerializationOptions: SerializationOptions = {
   form: "pretty",
 };