{"id":11481,"library":"object-refs","title":"Minimal Bi-directional Object References","description":"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.","status":"active","version":"0.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/bpmn-io/object-refs","tags":["javascript","object","bidirectional","references","refs","ref","property","binding","typescript"],"install":[{"cmd":"npm install object-refs","lang":"bash","label":"npm"},{"cmd":"yarn add object-refs","lang":"bash","label":"yarn"},{"cmd":"pnpm add object-refs","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import Refs from 'object-refs';\nconst Refs = require('object-refs').Refs;","symbol":"Refs","correct":"import { Refs } from 'object-refs';"},{"note":"For CommonJS environments, `Refs` is a named export. Attempting to `require` the package directly without destructuring will not yield the `Refs` constructor/factory.","wrong":"const Refs = require('object-refs');","symbol":"Refs (CommonJS)","correct":"const { Refs } = require('object-refs');"},{"note":"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.","symbol":"Type definitions","correct":"import type { RefCollection, Reference } from 'object-refs';"}],"quickstart":{"code":"import { Refs } from 'object-refs';\n\n// Define the properties that will hold the bi-directional references\nconst LEFT_REF = 'left';\nconst RIGHT_REF = 'right';\n\n// Create a new reference collection for 'connection' type references\nconst connectionRefs = new Refs({ \n  name: 'connection',\n  collection: 'connections',\n  target: LEFT_REF,\n  source: RIGHT_REF\n});\n\n// Example objects\nconst nodeA = { id: 'nodeA', connections: [] };\nconst nodeB = { id: 'nodeB', connections: [] };\n\n// Add a bi-directional reference between nodeA and nodeB\n// This will add nodeA to nodeB.connections and nodeB to nodeA.connections (via the ref properties)\nconnectionRefs.bind(nodeA, nodeB);\n\nconsole.log('Node A connections:', nodeA.connections.map(c => c.id));\n// Expected: Node A connections: [ 'nodeB' ]\n\nconsole.log('Node B connections:', nodeB.connections.map(c => c.id));\n// Expected: Node B connections: [ 'nodeA' ]\n\n// Clean up references\nconnectionRefs.unbind(nodeA, nodeB);\n\nconsole.log('Node A connections after unbind:', nodeA.connections.map(c => c.id));\n// Expected: Node A connections after unbind: []","lang":"typescript","description":"Demonstrates how to create a `Refs` instance, define reference properties, and establish/remove bi-directional links between two objects."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.4.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change the import statement to use named destructuring: `import { Refs } from 'object-refs';`","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.","error":"TypeError: (0 , object_refs__WEBPACK_IMPORTED_MODULE_0__.Refs) is not a constructor"},{"fix":"Ensure `Refs` is properly destructured from the CommonJS `require`: `const { Refs } = require('object-refs');`","cause":"Trying to call `bind` on `require('object-refs')` directly, implying `Refs` was not correctly extracted from the CommonJS module.","error":"TypeError: Cannot read properties of undefined (reading 'bind')"}],"ecosystem":"npm"}