{"id":18050,"library":"object-lib","title":"Object Utility Library","description":"object-lib is a utility library for JavaScript that provides a collection of functions for robust object manipulation, particularly focusing on recursive operations, alignment, cloning, deep comparison, and merging. The current stable version is 5.2.4, with frequent patch and minor releases, indicating active maintenance and continuous development. Key differentiators include its integration with `object-scan` syntax for declarative pathing in functions like `clone` and `Merge`, enabling powerful and flexible data transformations. It also offers unique features like `jsonSmartParse` for gracefully handling malformed JSON, often encountered from LLM outputs, and `SafeProxy` for creating proxy objects that enforce strict property access, throwing errors for non-existent keys instead of returning `undefined`. The library is designed for modern Node.js environments, requiring Node.js version 20 or higher since v5.0.0, ensuring compatibility with contemporary JavaScript features.","status":"active","version":"5.2.4","language":"javascript","source_language":"en","source_url":"https://github.com/blackflux/object-lib","tags":["javascript","object","library","toolbox","utility","align","sort","order","keys"],"install":[{"cmd":"npm install object-lib","lang":"bash","label":"npm"},{"cmd":"yarn add object-lib","lang":"bash","label":"yarn"},{"cmd":"pnpm add object-lib","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses named exports. ESM-only since v5.0.0.","wrong":"const align = require('object-lib').align;","symbol":"align","correct":"import { align } from 'object-lib';"},{"note":"Only named exports are provided; there is no default export.","wrong":"import clone from 'object-lib';","symbol":"clone","correct":"import { clone } from 'object-lib';"},{"note":"Note the capitalized 'Merge' for the function name.","wrong":"import { merge } from 'object-lib';","symbol":"Merge","correct":"import { Merge } from 'object-lib';"},{"note":"ESM is the recommended module system for Node.js >= 20.","wrong":"const SafeProxy = require('object-lib').SafeProxy;","symbol":"SafeProxy","correct":"import { SafeProxy } from 'object-lib';"},{"note":"Use named import for `jsonSmartParse` to leverage its intelligent JSON parsing.","symbol":"jsonSmartParse","correct":"import { jsonSmartParse } from 'object-lib';"}],"quickstart":{"code":"import { align, clone, Merge, SafeProxy, jsonSmartParse } from 'object-lib';\n\n// Align object keys to a reference object\nconst objToAlign = { k1: 1, k3: 3, k2: 2 };\nconst ref = { k2: null, k1: null, k4: 4 };\nconst aligned = align(objToAlign, ref);\nconsole.log('Aligned object:', aligned); \n// Expected: { k2: 2, k1: 1 }\n\n// Deep clone with selective referencing/exclusion using object-scan syntax\nconst originalData = { a: { nested: 1 }, b: { nested: 2 }, c: { nested: 3 } };\nconst clonedData = clone(originalData, ['b', '!c']);\nconsole.log('Cloned data:', clonedData);\nconsole.log('Is `a` deep cloned?', clonedData.a !== originalData.a); \n// Expected: true\nconsole.log('Is `b` referenced?', clonedData.b === originalData.b); \n// Expected: true\n\n// Smartly merge objects based on a unique identifier (e.g., 'id')\nconst merged = Merge({ '**[*]': 'id' })(\n  { items: [{ id: 1, val: 'a' }, { id: 2, val: 'b' }] },\n  { items: [{ id: 2, val: 'c' }, { id: 3, val: 'd' }] }\n);\nconsole.log('Merged items:', merged); \n// Expected: { items: [{ id: 1, val: 'a' }, { id: 2, val: 'c' }, { id: 3, val: 'd' }] }\n\n// Create a SafeProxy for strict property access, throwing errors for non-existent keys\nconst config = SafeProxy({ db: { host: 'localhost' } });\ntry {\n  console.log('DB Host:', config.db.host);\n  // Attempting to access a non-existent property will throw\n  // console.log('Non-existent property:', config.db.port);\n} catch (e) {\n  console.error('Caught error from SafeProxy:', e.message);\n}\n\n// Parse potentially invalid JSON strings (e.g., from LLMs)\nconst brokenJson = \"{ name: 'Alice', age: 30, city: 'New York' }\"; // Missing quotes on keys\nconst parsed = jsonSmartParse(brokenJson);\nconsole.log('Smart parsed JSON:', parsed); \n// Expected: { name: 'Alice', age: 30, city: 'New York' }","lang":"javascript","description":"This quickstart demonstrates key features including object alignment, deep cloning with selective referencing, smart merging based on identifiers, using `SafeProxy` for strict property access, and parsing malformed JSON with `jsonSmartParse`."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20 or higher. For projects that cannot upgrade Node.js, consider staying on `object-lib` v4.x.","message":"Version 5.0.0 of object-lib bumped the minimum required Node.js version to 20. Projects running on older Node.js environments will encounter runtime errors or will be unable to install the package.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure all property accesses on `SafeProxy` objects are valid or wrapped in `try...catch` blocks. Alternatively, use `Reflect.has()` or `in` operator to check for property existence before access.","message":"The `SafeProxy` function fundamentally alters JavaScript's default behavior for property access. Instead of returning `undefined` for non-existent properties, it throws a `ReferenceError`. This can be unexpected and requires careful error handling or pre-flight checks if you frequently deal with optional properties.","severity":"gotcha","affected_versions":">=5.1.0"},{"fix":"Thoroughly review the `object-scan` documentation and test your `Merge` configurations with diverse data sets to ensure the desired merging logic is applied correctly.","message":"The `Merge` function's behavior is heavily configured by the `logic` object, which uses `object-scan` syntax. Misunderstanding or misconfiguring this logic can lead to unintended merging outcomes, data loss, or unexpected array concatenations instead of unique item merging.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For inputs where strict JSON adherence is critical, use `JSON.parse` with appropriate error handling. Use `jsonSmartParse` only when expecting and needing to recover from common JSON formatting errors.","message":"The `jsonSmartParse` function is designed to be lenient with invalid JSON, commonly found in LLM outputs. While useful, relying on it for strict JSON parsing could mask underlying data format issues or allow malformed data to be processed if strict validation is required.","severity":"gotcha","affected_versions":">=4.1.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Migrate your module to ESM by using `import` statements and ensuring your `package.json` specifies `\"type\": \"module\"` or files end with `.mjs`.","cause":"Attempting to use `require()` to import `object-lib` in a CommonJS module after v5.0.0.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure all accessed properties exist on the `SafeProxy` object, or wrap access in `try...catch` blocks, or use `Reflect.has()` to check for property existence before attempting to read it.","cause":"Accessing a non-existent nested property on an object wrapped with `SafeProxy`.","error":"TypeError: Cannot read properties of undefined (reading 'someProp')"},{"fix":"Upgrade your Node.js installation to version 20 or a newer compatible version.","cause":"Running `object-lib` v5.x or higher in a Node.js environment older than version 20.","error":"Error: Node.js version 18.x.x is not supported. Please upgrade to Node.js 20 or higher."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}