{"id":12273,"library":"ul","title":"Minimalist Utility Library (ul)","description":"ul is a minimalist JavaScript utility library, currently at version 5.2.16, providing essential object manipulation functions such as one-level merging (`merge`), deep merging (`deepMerge`), and deep cloning (`clone`), alongside a cross-platform helper for retrieving the user's home directory (`home`). Its release cadence is primarily focused on documentation updates and maintainer support links, indicating a stable and mature project rather than one under rapid feature development. Key differentiators include its small footprint and straightforward API for common utility tasks, making it suitable for projects that prefer to avoid larger utility libraries like Lodash for basic operations.","status":"maintenance","version":"5.2.16","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/IonicaBizau/node-ul","tags":["javascript","util","nodejs","minimalist"],"install":[{"cmd":"npm install ul","lang":"bash","label":"npm"},{"cmd":"yarn add ul","lang":"bash","label":"yarn"},{"cmd":"pnpm add ul","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While the library primarily uses CommonJS `require`, modern Node.js environments can typically import it using ESM syntax. Ensure your project configuration (e.g., `type: 'module'` in package.json) supports interop for CommonJS modules. The `Ul` object contains all utility functions.","wrong":"const Ul = require('ul');","symbol":"Ul","correct":"import Ul from 'ul';"},{"note":"All utility functions are properties of the main `Ul` object, not named exports directly from the package. Attempting to destructure them will result in a runtime error.","wrong":"import { deepMerge } from 'ul';","symbol":"Ul.deepMerge","correct":"import Ul from 'ul';\nconst mergedObject = Ul.deepMerge(obj1, obj2);"},{"note":"Like `deepMerge`, `home` is accessed as a method of the `Ul` object. `Ul.HOME_DIR` also provides a cached path to the home directory.","wrong":"import { home } from 'ul';","symbol":"Ul.home","correct":"import Ul from 'ul';\nconst userHomeDir = Ul.home();"}],"quickstart":{"code":"import Ul from 'ul';\n\n// Input data\nlet obj = {\n       n: null,\n       v: 1\n    };\n  , def = {\n        n: 1,\n        v: 10,\n        a: 20\n    };\n  , tmp = null;\n\n\n// Merge the two objects and store the result in tmp\nconsole.log('Deep Merge Result:', tmp = Ul.deepMerge(obj, def));\n// Expected output: { n: null, v: 1, a: 20 }\n// Illustrates how `null` values in `obj` are preserved even if `def` has a non-null value.\n\n// Clone the tmp object -- the clone will have a different reference\nconst clonedTmp = Ul.clone(tmp);\nconsole.log('Cloned Object:', clonedTmp);\nconsole.log('Is clone identical to original reference?', tmp === clonedTmp);\n// Expected output: false (demonstrates deep cloning creates a new reference)\n\n// Show the absolute path to the home directory\nconsole.log('Home Directory (function call):', Ul.home());\nconsole.log('Home Directory (property access):', Ul.HOME_DIR);\n// Path will vary by OS, e.g., /home/user or C:\\Users\\user\n\n// One level merge\nconsole.log('One-Level Merge Result:', Ul.merge({\n    foo: {\n        bar: 42\n    }\n}, {\n    foo: {\n        bar: 1,\n        baz: 7\n    }\n}));\n// Expected output: { foo: { bar: 42 } } (demonstrates shallow merge behavior, inner 'foo' object from first arg is preserved)\n","lang":"javascript","description":"This example demonstrates `ul`'s core functionalities: `deepMerge` for recursive object merging, `clone` for creating deep copies, and `home()` or `HOME_DIR` for retrieving the user's home directory path. It also highlights the behavior of `merge` for shallow merging."},"warnings":[{"fix":"For deep, recursive merging, always use `Ul.deepMerge()`. Understand the difference between shallow and deep merging for your specific use case.","message":"The `Ul.merge()` function performs a shallow, one-level merge. It will only merge top-level properties and will not deeply merge nested objects. This can lead to unexpected results if deep merging is intended.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be explicit about handling `null` values. If you want `null` properties to be overwritten by defaults, you may need to preprocess your objects or use a different utility that provides configurable merge behavior.","message":"When using `Ul.deepMerge()`, properties with a `null` value in the destination object (`dst`) will *not* be overwritten by non-null values from the source object (`src`). This deviates from some other merge utilities that treat `null` as 'empty' and would overwrite it.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If encountering import issues in an ESM project, consider using dynamic `import('ul')` or ensure your build tools (e.g., Webpack, Rollup) are configured to correctly handle CommonJS interop. The CommonJS `const Ul = require('ul');` remains the most robust import method for Node.js.","message":"The `ul` library is primarily a CommonJS module. While it can often be imported using ESM syntax (`import Ul from 'ul';`) in modern Node.js environments, there is no explicit `type: 'module'` in its `package.json` or dual CommonJS/ESM packaging. This could lead to issues in stricter ESM contexts or older bundlers.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you import the main `Ul` object first and then access its methods: `import Ul from 'ul'; const merged = Ul.deepMerge(obj1, obj2);`","cause":"Attempting to destructure utility functions like `deepMerge` directly from the `ul` package (e.g., `import { deepMerge } from 'ul'`) when they are properties of the default `Ul` object.","error":"TypeError: Ul.deepMerge is not a function"},{"fix":"In CommonJS, use `const Ul = require('ul');`. In ESM, use `import Ul from 'ul';` at the top of your file.","cause":"The `ul` package was not correctly imported or required, or the variable `Ul` was not assigned the module's export.","error":"ReferenceError: Ul is not defined"}],"ecosystem":"npm"}