RefTools

Common errors

• TypeError: Cannot read properties of undefined (reading 'someProp')

  cause 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

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

Warnings

• gotcha RefTools 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.
• gotcha When 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.
• gotcha The `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.

Install

• npm install reftools npm
• yarn add reftools yarn
• pnpm add reftools pnpm

Imports

• clone
  wrong:

  const { clone } = require('reftools')

  correct:

  import { clone } from '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
  wrong:

  import dereference from 'reftools'

  correct:

  import { dereference } from 'reftools'

  Functions like `dereference` are named exports. Attempting a default import will result in `undefined` or an error.
• jptr
  wrong:

  const jptr = require('reftools').jptr

  correct:

  import { jptr } from 'reftools'

  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.

Quickstart

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