TypeScript-as-JSDoc and updates

[brettz9]

PR description

@80avin : If you could take a look, I figure with you maintaining now, that I should get your approval first. There is a lot of diff noise, but I think it is worth adopting.

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).

Other changes:

• refactor: expose JSONPathClass prototype through JSONPath for compatibility
• refactor: implement TypeScript-as-JSDoc and auto-build declaration files from this (avoiding need for maintaining declaration file manually)
• chore: update devDeps
• chore: lint

Fixes #114 ; closes #113 ; closes #115 .

Checklist

• - Added tests
• - Ran npm test, ensuring linting passes
• - Adjust README documentation if relevant

[Copilot]

Pull request overview

This PR modernizes the project’s TypeScript typing story (via TypeScript-as-JSDoc + generated declaration files) while refactoring the runtime to expose a JSONPathClass for monkey-patching, alongside dependency/tooling updates and corresponding test adjustments.

Changes:

• Refactor core runtime to use a JSONPathClass implementation (and update Node/browser adapters and tests accordingly).
• Adopt TS checking for JS (allowJs/checkJs) and switch from a hand-written src/jsonpath.d.ts to generated dist/*.d.ts (including *.d.cts for CJS typing).
• Update lint/build config and dev dependencies; refresh/expand tests to align with stricter typings.

Reviewed changes

Copilot reviewed 29 out of 47 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tsconfig.json	Enables JS type-checking and declaration generation settings for the repo.
tsconfig-prod.json	Adds a production TS config to emit declaration files.
test/test.type-operators.js	Updates tests to use imported callback types and tighter JSDoc annotations.
test/test.toPath.js	Uses Chai lengthOf assertion style for array length checks.
test/test.safe-eval.js	Adds JSDoc imports/types and TS-expect-error markers for VM/security tests.
test/test.performance.js	Refactors test data setup and adds JSDoc types to satisfy checkJs.
test/test.path_expressions.js	Updates reference URL to HTTPS.
test/test.intermixed.arr.js	Adds type casts for spread use under checkJs.
test/test.examples.js	Updates reference URL, refactors expected building, and adds JSDoc typing.
test/test.eval.js	Updates VM access to JSONPathClass.prototype.* and adds JSDoc imports/types.
test/test.errors.js	Adds TS-expect-error for intentionally invalid argument test.
test/test.cli.js	Adds cast for stderr typing under checkJs.
test/test.callback.js	Tightens callback param typing and result typing for checkJs.
test/test.at_and_dollar.js	Avoids implicit globals by typing globalThis usage for tests.
test/test.api.js	Adds many new regression tests and types jsonpath() results as JSONPathClass.
test/test.all.js	Re-formats expected objects (likely lint/style driven).
test-helpers/node-env.js	Exposes JSONPathClass on globalThis for tests.
test-helpers/checkVM.js	Introduces VmType typedef and type annotations for VM iteration.
src/Safe-Script.js	Adds JSDoc typing throughout safe-eval implementation and improves error construction.
src/jsonpath.js	Major refactor: introduces JSONPathClass, moves methods, tightens types, and changes monkey-patching surface.
src/jsonpath.d.ts	Removes the old hand-authored declaration file in favor of generated typings.
src/jsonpath-node.js	Moves vm monkey-patching target to JSONPathClass.prototype and adds typedef re-exports.
src/jsonpath-node.cts	Adds CJS typing entry for Node build.
src/jsonpath-browser.js	Moves browser Script monkey-patching to JSONPathClass.prototype and adds typedef re-exports.
rollup.config.js	Updates JSDoc typing for Rollup config and TS checking compatibility.
pnpm-workspace.yaml	Adds minimumReleaseAgeExclude exceptions for specific packages.
package.json	Updates exports/types mapping to generated dist typings; updates devDeps; adds build/attw scripts.
eslint.config.js	Updates config typing, import plugin rule names (import-x/*), and test globals.
dist/Safe-Script.d.ts	Adds generated declaration output for Safe-Script.
dist/jsonpath.d.ts	Adds generated declaration output for the main entry.
dist/jsonpath-node.d.ts	Adds generated declaration output for the Node entry.
dist/jsonpath-node.d.cts	Adds generated CJS declaration entry for Node.
dist/jsonpath-browser.d.ts	Adds generated declaration output for the browser entry.
dist/index-browser-umd.min.cjs	Updates built/minified UMD bundle output.
dist/index-browser-esm.min.js	Updates built/minified ESM bundle output.
demo/tsconfig.json	Adds demo-specific TS config (DOM libs) for checkJs friendliness.
demo/index.js	Tightens DOM element typing and adjusts URL/history usage for type checking.
bin/jsonpath-cli.js	Switches CLI to import the Node implementation from src/ and adds JSONValue typing.
badges/tests-badge.svg	Updates test badge counts.
.ncurc.cjs	Adds npm-check-updates configuration.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[brettz9]

@80avin : If you need more time to review that's fine, but I think it'd really be a good idea to get this merged before there is too much diff noise from any other PRs that come our way.

[80avin]

Hey @brettz9 , sorry for delaying it this much. I've been in some events for the last few weeks, got free around 2 days back only.

The PR looks good overall but I haven't had a thorough look. I'll review it by tomorrow.

[80avin]

Also, if you don't mind, here are some more issues found by AI.

I've verified them, but would accept it if you want to deprioritise any.

---

• wrap:false single type-operator result now wraps in an array (src/jsonpath.js:827-831): the @type() retObj now carries hasArrExpr, flipping the unwrap condition. $..*@Number() wrap:false on {a:1} → MAIN 1, NEW [1] — contradicts the README's documented unwrap guarantee. Also adds a hasArrExpr own-key to resultType:'all' type-op results (MAIN had none).
• evaluate() null-coalescing silently overrides explicit nulls (src/jsonpath.js:430-432,451-456): flatten ?? …, parent ?? …, parentProperty ?? … fall back to instance values when the caller explicitly passes null/undefined. Verified via @parent/@parentProperty filters and flatten:null; wrap is inconsistent (no ??). README documents these as per-call-settable null-defaulted options.
• new JSONPath({...}) with a scalar result silently returns an empty object instead of throwing (src/jsonpath.js:243-249): MAIN throws the documented NewError ("JSONPath should not be called with new..."); NEW returns {} (a new-created wrapper discards the returned primitive). Consumers guarding on the documented throw break silently.
• JSONPath.prototype.{evaluate, safeVm, vm} removed (src/jsonpath-node.js:74, jsonpath-browser.js:160): monkey-patching and prototype access now silently undefined. This is announced as a breaking change, but nothing in README/CHANGES documents it, and it contradicts the prior documented pattern the library's own tests used.
• typeof import("node:vm") leaks into every declaration (dist/jsonpath.d.ts:33, re-exported by the browser entry): consumer projects without @types/node (including pure-browser TS setups) get TS2591. attw does not catch it. Cleanest fix: keep node:vm only in the node-specific .d.ts.
• JSONPathType deleted with no replacement (demo/types.d.ts:2 still imports it → TS2724); parentProperty now rejects numeric values (TS2769) though runtime accepts them; PreferredOutput collapses to unknown (meaningless exported type); monkey-patch typing (SafeScriptType) requires the internal ast field (TS2419); jsep typings now leak into consumers (TS1203) — introduced by this PR.
• README.md and CHANGES.md have zero changes (diff empty) despite the PR body ticking "Adjust README if relevant" and listing breaking changes. Committed docs/ts/ (22 files, the published API docs) still reference deleted src/jsonpath.d.ts and deleted JSONPathType/JSONPathCallable.
• xunit.xml (57.8 kB CI artifact, absolute local paths) ships in the npm tarball — neither gitignored nor npmignored. Dev tooling (.ncurc.cjs, tsconfig-prod.json, pnpm-workspace.yaml) ships too.
• No test catches the C1 regression, and the new $[(undefined)] test masks a behavior change: it asserts [] for a fixture where MAIN throws (a real fix), but a query targeting a literal "undefined" key silently changes ['X']→[] with no test defending either direction. 10 of the 13 new tests are behavior-preserving (pass on MAIN), and the _getPreferredOutput string-path fix (a genuine MAIN bug) is tested only via direct private-method calls, never through the public resultType:'path'/'pointer' + callback path.

[brettz9]

I think the AI-inspired issues should now all be fixed...