object-refs

library0.4.0jsnpmunverified

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.

serialization database

npm install object-refs

github ↗package ↗

INSTALL

IMPORT

SIG · OBJECT-REFS

object-refs

serializationjavascriptv0.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

Refs

✓ import { Refs } from 'object-refs';

✗ import Refs from 'object-refs'; const Refs = require('object-refs').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)

✓ const { Refs } = require('object-refs');

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

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: []

Debug

Known issues

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

affects: >=0.0.0

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

affects: <0.4.0

gotchaVersion `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.

affects: >=0.4.0

Errors

Common errors & fixes

TypeError: (0 , object_refs__WEBPACK_IMPORTED_MODULE_0__.Refs) is not a constructor

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

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

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/bpmn-io/object-refs ↗

packagehttps://www.npmjs.com/package/object-refs ↗