TypeScript-as-JSDoc and updates

.gitignore

@@ -9,3 +9,4 @@ reports
 target
 *.log
 coverage
+xunit.xml

.ncurc.cjs

@@ -0,0 +1,8 @@
+'use strict';
+
+module.exports = {
+    reject: [
+        // Until typedoc supports
+        'typescript'
+    ]
+};

.npmignore

@@ -15,11 +15,15 @@ mocha-multi-reporters.json
 .mocharc.cjs
 .github
 .nojekyll
+.ncurc.cjs
 ignore
 pnpm-lock.yaml
+pnpm-workspace.yaml
 eslint.config.js
 .editorconfig
 .eslintignore
 licenseInfo.json
 tsconfig.json
+tsconfig-prod.json
 demo
+xunit.xml

CHANGES.md

@@ -1,9 +1,17 @@
 # CHANGES for jsonpath-plus
 
-## 10.4.1
+## 11.0.0
+
+BREAKING CHANGES
+* chore: various changes in types, particularly with return values changing from any to unknown to ensure type safety (by forcing type casts of the results on the user).
 
 * fix(slice): explicit zero end no longer returns the whole array (#265) (@spokodev)
+* fix: restore `JSONPath.prototype.evaluate`, `safeVm`, and `vm` compatibility
+* refactor: expose JSONPathClass prototype through JSONPath for compatibility
 * chore: pnpm update (@brettz9)
+* refactor: implement TypeScript-as-JSDoc and auto-build declaration files from this (avoiding need for maintaining declaration file manually)
+* chore: update devDeps
+* chore: lint
 * build(deps-dev): bump rollup from 4.53.2 to 4.59.0 (@dependabot[bot])
 * build(deps): bump minimatch from 9.0.5 to 9.0.9 (@dependabot[bot])
 * build(deps): bump serialize-javascript (via audit fix) (@dependabot[bot])

README.md

@@ -195,7 +195,8 @@ evaluate method (as the first argument) include:
   to be returned within results.
 - ***parentProperty*** (**default: null**) - In the event that a query
   could be made to return the root node, this allows the `parentProperty`
-  of that root node to be returned within results.
+  of that root node to be returned within results. This may be a string
+  property name or a numeric array index.
 - ***callback*** (**default: (none)**) - If supplied, a callback will be
   called immediately upon retrieval of an end point value. The three arguments
   supplied will be the value of the payload (according to `resultType`),

bin/jsonpath-cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import {readFile} from 'fs/promises';
-import {JSONPath as jsonpath} from '../dist/index-node-esm.js';
+import {JSONPath as jsonpath} from '../src/jsonpath-node.js';
 
 const file = process.argv[2];
 const path = process.argv[3];
@@ -17,11 +17,16 @@ try {
 }
 
 /**
- * @typedef {any} JSON
+ * @typedef {JSONValue[]} JSONArray
  */
 
 /**
- * @param {JSON} json
+ * @typedef {null|boolean|number|string|
+ *   {[key: string]: JSONValue}|JSONArray} JSONValue
+ */
+
+/**
+ * @param {JSONValue} json
  * @param {string} pth
  * @returns {void}
  */

demo/index.js

@@ -1,6 +1,5 @@
-/// <reference path="./types.d.ts" />
 /* globals JSONPath, LZString -- Test UMD */
-/* eslint-disable import/unambiguous -- Demo */
+/// <reference path="./types.d.ts" />
 
 // Todo: Extract testing example paths/contents and use for a
 //         pulldown that can populate examples
@@ -12,37 +11,51 @@
 // Todo: Could add JSON/JS syntax highlighting in sample and result,
 //   ideally with a jsonpath-plus parser highlighter as well
 
-const $ = (s) => document.querySelector(s);
+/**
+ * @param {string} s
+ * @returns {HTMLElement}
+ */
+const $ = (s) => /** @type {HTMLElement} */ (document.querySelector(s));
 
-const jsonpathEl = $('#jsonpath');
-const jsonSample = $('#jsonSample');
+/**
+ * @param {string} s
+ * @returns {HTMLInputElement}
+ */
+const $i = (s) => /** @type {HTMLInputElement} */ (document.querySelector(s));
+
+const jsonpathEl = $i('#jsonpath');
+const jsonSample = $i('#jsonSample');
 
 const updateUrl = () => {
     const path = jsonpathEl.value;
     const jsonText = LZString.compressToEncodedURIComponent(jsonSample.value);
     const url = new URL(location.href);
     url.searchParams.set('path', path);
     url.searchParams.set('json', jsonText);
-    url.searchParams.set('eval', $('#eval').value);
-    url.searchParams.set('ignoreEvalErrors', $('#ignoreEvalErrors').value);
-    history.replaceState(null, '', url.toString());
+    url.searchParams.set('eval', $i('#eval').value);
+    url.searchParams.set('ignoreEvalErrors', $i('#ignoreEvalErrors').value);
+    history.replaceState(null, '', url.href);
 };
 
 const loadUrl = () => {
     const url = new URL(location.href);
     if (url.searchParams.has('path')) {
-        jsonpathEl.value = url.searchParams.get('path');
+        jsonpathEl.value = /** @type {string} */ (url.searchParams.get('path'));
     }
     if (url.searchParams.has('json')) {
         jsonSample.value = LZString.decompressFromEncodedURIComponent(
-            url.searchParams.get('json')
+            /** @type {string} */ (url.searchParams.get('json'))
         );
     }
     if (url.searchParams.has('eval')) {
-        $('#eval').value = url.searchParams.get('eval');
+        $i('#eval').value = /** @type {string} */ (
+            url.searchParams.get('eval')
+        );
     }
     if (url.searchParams.has('ignoreEvalErrors')) {
-        $('#ignoreEvalErrors').value = url.searchParams.get('ignoreEvalErrors');
+        $i('#ignoreEvalErrors').value = /** @type {string} */ (
+            url.searchParams.get('ignoreEvalErrors')
+        );
     }
 };
 
@@ -52,7 +65,7 @@ const updateResults = () => {
         setTimeout(() => {
             jsonSample.reportValidity();
             jsonpathEl.reportValidity();
-        });
+        }, 0);
     };
     let json;
     jsonSample.setCustomValidity('');
@@ -61,24 +74,31 @@ const updateResults = () => {
     try {
         json = JSON.parse(jsonSample.value);
     } catch (err) {
-        jsonSample.setCustomValidity('Error parsing JSON: ' + err.toString());
+        jsonSample.setCustomValidity(
+            'Error parsing JSON: ' +
+            /** @type {Error} */ (err).toString()
+        );
         reportValidity();
         return;
     }
     try {
         const result = new JSONPath.JSONPath({
             path: jsonpathEl.value,
             json,
-            eval: $('#eval').value === 'false' ? false : $('#eval').value,
-            ignoreEvalErrors: $('#ignoreEvalErrors').value === 'true'
+            eval: /** @type {'safe'|'native'|boolean} */ (
+                $i('#eval').value === 'false' ? false : $i('#eval').value
+            ),
+            ignoreEvalErrors: $i('#ignoreEvalErrors').value === 'true'
         });
-        $('#results').value = JSON.stringify(result, null, 2);
+        $i('#results').value = JSON.stringify(result, null, 2);
     } catch (err) {
         jsonpathEl.setCustomValidity(
-            'Error executing JSONPath: ' + err.toString()
+            'Error executing JSONPath: ' +
+            /** @type {Error} */
+            (err).toString()
         );
         reportValidity();
-        $('#results').value = '';
+        $i('#results').value = '';
     }
 };
 

demo/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "lib": ["es2024", "dom"]
+  },
+  "include": ["."],
+  "exclude": ["node-import-test.js"]
+}

demo/types.d.ts

@@ -1,12 +1,11 @@
-import '../src/jsonpath.d.ts'
-import type { JSONPathType } from 'jsonpath-plus';
+import type {JSONPathClass} from 'jsonpath-plus';
 
 declare global {
     var LZString: {
         decompressFromEncodedURIComponent: (value: string) => string;
         compressToEncodedURIComponent: (value: string) => string;
     };
     var JSONPath: {
-        JSONPath: JSONPathType
+        JSONPath: typeof JSONPathClass
     }
 }

dist/Safe-Script.d.ts

@@ -0,0 +1,22 @@
+export type AssignmentExpression = any;
+export type Substitution = any;
+export type AnyParameter = any;
+export type Substitutions = Record<string, Substitution>;
+/**
+ * A replacement for NodeJS' VM.Script which is also {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP | Content Security Policy} friendly.
+ */
+export class SafeScript {
+    /**
+     * @param {string} expr Expression to evaluate
+     */
+    constructor(expr: string);
+    code: string;
+    ast: unknown;
+    /**
+     * @param {object} context Object whose items will be added
+     *   to evaluation
+     * @returns {EvaluatedResult} Result of evaluated code
+     */
+    runInNewContext(context: object): EvaluatedResult;
+}
+import type { EvaluatedResult } from './jsonpath.js';