Minimal Bi-directional Object References

0.4.0 · active · verified Sun Apr 19

object-refs is a minimalist JavaScript library designed to establish and manage bi-directional references between objects. It's particularly useful in scenarios where maintaining explicit links between related objects, where one object's reference to another implies a reciprocal reference, is critical for data integrity or graph-like structures. The current stable version is 0.4.0. Given its `0.x.x` versioning, it likely follows an agile release cadence, introducing features and potentially breaking changes in minor versions. Its key differentiator is its focus on being minimal and providing robust type definitions for TypeScript users since `v0.4.0`, enabling safer refactoring and development compared to manual reference management.

Common errors

```
TypeError: (0 , object_refs__WEBPACK_IMPORTED_MODULE_0__.Refs) is not a constructor
```
cause Attempting to use `import Refs from 'object-refs';` or a similar default import pattern in an ESM environment when `Refs` is a named export.

fix Change the import statement to use named destructuring: `import { Refs } from 'object-refs';`
```
TypeError: Cannot read properties of undefined (reading 'bind')
```
cause Trying to call `bind` on `require('object-refs')` directly, implying `Refs` was not correctly extracted from the CommonJS module.

fix Ensure `Refs` is properly destructured from the CommonJS `require`: `const { Refs } = require('object-refs');`

Warnings

breaking The package is in a `0.x.x` version series, meaning semantic versioning is not strictly adhered to. Minor versions (e.g., `0.4.0` to `0.5.0`) may introduce breaking changes without a major version bump, requiring careful review of changelogs during upgrades.
Fix: Always review the `CHANGELOG.md` file or release notes when upgrading `object-refs` to any new `0.x.x` version to identify potential breaking changes in API surface or behavior.
gotcha Prior to `v0.4.0`, TypeScript type definitions were not officially shipped, requiring users to rely on `@types/object-refs` or declare modules manually. While `v0.4.0` now includes types, older projects might still be configured incorrectly or rely on outdated type declarations.
Fix: Ensure `object-refs` is at least `v0.4.0`. Remove any `@types/object-refs` dependency if present, as the types are now bundled with the package directly. Verify `tsconfig.json` paths and `typeRoots` are correctly configured if issues persist.
gotcha Version `0.4.0` introduced separate ESM and CommonJS bundles. While designed for broader compatibility, some older bundler configurations or specific import paths might require adjustment to correctly resolve the desired module format, especially in mixed environments or when migrating from older toolchains.
Fix: If encountering module resolution errors, explicitly configure your bundler (e.g., Webpack, Rollup) or Node.js environment to prefer ESM or CJS as needed, or ensure your `package.json`'s `type` field and import statements are consistent with the module system being used.

Install

npm install object-refs npm
yarn add object-refs yarn
pnpm add object-refs pnpm

Imports

Refs
wrong:
```
import Refs from 'object-refs';
const Refs = require('object-refs').Refs;
```
correct:
```
import { Refs } from 'object-refs';
```
The `Refs` class/factory is the primary named export for creating reference collections. Since `v0.4.0`, both ESM and CommonJS bundles are provided, ensuring compatibility across module systems.
Refs (CommonJS)
wrong:
```
const Refs = require('object-refs');
```
correct:
```
const { Refs } = require('object-refs');
```
For CommonJS environments, `Refs` is a named export. Attempting to `require` the package directly without destructuring will not yield the `Refs` constructor/factory.
Type definitions
```
import type { RefCollection, Reference } from 'object-refs';
```
The package ships with TypeScript type definitions since `v0.4.0`, allowing for strong typing of reference collections and individual references. Specific type names might vary based on internal structure.

Quickstart

Demonstrates how to create a `Refs` instance, define reference properties, and establish/remove bi-directional links between two objects.

import { Refs } from 'object-refs';

// Define the properties that will hold the bi-directional references
const LEFT_REF = 'left';
const RIGHT_REF = 'right';

// Create a new reference collection for 'connection' type references
const connectionRefs = new Refs({ 
  name: 'connection',
  collection: 'connections',
  target: LEFT_REF,
  source: RIGHT_REF
});

// Example objects
const nodeA = { id: 'nodeA', connections: [] };
const nodeB = { id: 'nodeB', connections: [] };

// Add a bi-directional reference between nodeA and nodeB
// This will add nodeA to nodeB.connections and nodeB to nodeA.connections (via the ref properties)
connectionRefs.bind(nodeA, nodeB);

console.log('Node A connections:', nodeA.connections.map(c => c.id));
// Expected: Node A connections: [ 'nodeB' ]

console.log('Node B connections:', nodeB.connections.map(c => c.id));
// Expected: Node B connections: [ 'nodeA' ]

// Clean up references
connectionRefs.unbind(nodeA, nodeB);

console.log('Node A connections after unbind:', nodeA.connections.map(c => c.id));
// Expected: Node A connections after unbind: []

view raw JSON →