Registry / serialization / reftools

reftools

JSON →
library2.2.0jsnpmunverified

RefTools is a JavaScript utility library providing a comprehensive set of functions for working with JavaScript objects, particularly focusing on JSON References, JSON Pointers, and various cloning strategies. It offers deep, shallow, and circular-aware cloning, object flattening, and powerful recursion and visitation mechanisms for complex object structures. Currently at version 1.1.9, the library is actively maintained, as evidenced by its integration into the `oas-kit` monorepo, which includes projects like `swagger2openapi`. While `reftools` itself does not have a rapid, independent release cadence, its core features are crucial for OpenAPI/Swagger tooling, ensuring ongoing relevance and updates. Its key differentiators lie in its robust handling of JSON Pointers/References and advanced object traversal features with configurable callbacks, making it suitable for intricate data manipulation and schema processing tasks.

npm install reftools
INSTALL
IMPORT
SIG · REFTOOLS
R
reftools
serializationjavascriptv2.2.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

clone
import { clone } from 'reftools'
const { clone } = require('reftools')
The library primarily uses named exports. While CommonJS `require` might work in some environments, ESM `import` is the idiomatic and recommended approach for modern JavaScript projects.
dereference
import { dereference } from 'reftools'
import dereference from 'reftools'
Functions like `dereference` are named exports. Attempting a default import will result in `undefined` or an error.
jptr
import { jptr } from 'reftools'
const jptr = require('reftools').jptr
Accessing nested properties of the `require` result, instead of destructuring, is less concise and can be less performant in some module loaders. Named imports are preferred.
recurse
import { recurse } from 'reftools'
Used for traversing object properties with a custom callback and state.
visit
import { visit } from 'reftools'
Provides a powerful, callback-driven mechanism for deep object traversal, comparison, and modification.

Demonstrates basic cloning, JSON Reference dereferencing, JSON Pointer (jptr) usage for getting/setting values, and cloning an object with circular references.

import { clone, dereference, jptr, circularClone } from 'reftools'; const originalObject = { a: 1, b: { c: 2 }, d: { $ref: '#/b' }, // JSON Reference e: [], }; originalObject.e.push(originalObject.b); // Introduce a circular reference console.log('Original Object:', JSON.stringify(originalObject, null, 2)); // 1. Basic cloning const clonedObject = clone(originalObject); console.log('\nCloned Object (JSON.parse/stringify):', JSON.stringify(clonedObject, null, 2)); // Note: JSON.parse/stringify cloning loses circular refs and some types // 2. Dereferencing JSON Pointers const dereferencedObject = dereference(originalObject); console.log('\nDereferenced Object (JSON Pointers resolved):', JSON.stringify(dereferencedObject, null, 2)); // 3. Using JSON Pointer (jptr) to get and set values const valueA = jptr(originalObject, '/a'); console.log(`\nValue at '/a': ${valueA}`); jptr(originalObject, '/b/c', 99); console.log('Object after jptr set /b/c to 99:', JSON.stringify(originalObject, null, 2)); // 4. Cloning with circular reference handling const circularHandledClone = circularClone(originalObject); console.log('\nCircular-aware cloned object (inspect for circularity - will be simplified):', circularHandledClone);
Debug
Known issues
gotchaRefTools offers several cloning functions (`clone`, `shallowClone`, `deepClone`, `fastClone`, `circularClone`). Each has distinct behavior regarding prototype properties, deep vs. shallow copies, and handling of circular references. Using the wrong cloning method can lead to unexpected data loss (e.g., `clone` via `JSON.parse/stringify` drops circular references and certain data types) or performance issues.
fix
Carefully select the appropriate cloning function based on your specific requirements for depth, prototype handling, and circular reference management. For circular structures, `circularClone` or `dereference` might be necessary.
affects: >=1.0.0
gotchaWhen working with JSON Pointers (`jptr`, `jpescape`, `jpunescape`), strict adherence to RFC 6901 syntax is required. Incorrectly formatted pointers (e.g., forgetting to escape `~` or `/` with `~0` and `~1` respectively) will result in incorrect paths being resolved or errors, particularly when dealing with property names containing these special characters.
fix
Always use `jpescape` for path segments before constructing a JSON Pointer if the segments might contain `~` or `/`. Ensure all JSON Pointers conform to RFC 6901 specifications.
affects: >=1.0.0
gotchaThe `recurse` and `visit` functions provide powerful object traversal but require careful implementation of callbacks. Improperly written callbacks, especially those that mutate the object structure without caution or fail to handle termination conditions, can lead to infinite loops or unexpected side effects during traversal, particularly with highly interconnected or circular data.
fix
Thoroughly test callbacks for `recurse` and `visit`. Ensure callbacks handle potential circularities, prevent infinite recursion, and correctly manage the state and mutation logic. Consider using `dereference` or `circularClone` beforehand if working with complex, potentially circular structures during traversal.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'someProp')
Attempting to access a property via `jptr` or `dereference` with a JSON Pointer that resolves to a non-existent path or an `undefined` intermediate object.
fix
Verify that the JSON Pointer path is valid and all intermediate objects exist. Add defensive checks or ensure your data structure matches the expected path before calling `jptr` or `dereference`.
RangeError: Maximum call stack size exceeded
Using recursive functions like `dereference` or custom `recurse` callbacks on deeply nested or circularly referenced objects without proper handling for recursion depth or explicit circularity detection.
fix
For circular references, ensure you use `circularClone` or the `dereference` function as intended. When writing custom `recurse` or `visit` callbacks, implement a visited-set mechanism to prevent re-processing already seen objects.
Upgrade
Version history
2.2.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
7 hits · last 30 days
node
6
OpenAI (training)
1
Resources
reftools — npm install reftools · libregistry