TypeScript-as-JSDoc and updates

.ncurc.cjs

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

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,6 @@
-/// <reference path="./types.d.ts" />
+/* eslint-disable import-x/unambiguous -- Demo */
 /* 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 +12,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 +66,7 @@ const updateResults = () => {
         setTimeout(() => {
             jsonSample.reportValidity();
             jsonpathEl.reportValidity();
-        });
+        }, 0);
     };
     let json;
     jsonSample.setCustomValidity('');
@@ -61,24 +75,29 @@ 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: $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,7 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "lib": ["es2024", "dom"]
+  },
+  "include": ["."]
+}

dist/Safe-Script.d.ts

@@ -0,0 +1,23 @@
+export type AssignmentExpression = import("@jsep-plugin/assignment").AssignmentExpression;
+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: jsep.Expression;
+    /**
+     * @param {object} context Object whose items will be added
+     *   to evaluation
+     * @returns {EvaluatedResult} Result of evaluated code
+     */
+    runInNewContext(context: object): EvaluatedResult;
+}
+import jsep from 'jsep';
+import type { EvaluatedResult } from './jsonpath.js';