Minimalist Utility Library (ul)

Common errors

• TypeError: Ul.deepMerge is not a function

  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.
  fix Ensure you import the main `Ul` object first and then access its methods: `import Ul from 'ul'; const merged = Ul.deepMerge(obj1, obj2);`

• ReferenceError: Ul is not defined

  cause The `ul` package was not correctly imported or required, or the variable `Ul` was not assigned the module's export.
  fix In CommonJS, use `const Ul = require('ul');`. In ESM, use `import Ul from 'ul';` at the top of your file.

Warnings

• gotcha 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.
  Fix: For deep, recursive merging, always use `Ul.deepMerge()`. Understand the difference between shallow and deep merging for your specific use case.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install ul npm
• yarn add ul yarn
• pnpm add ul pnpm

Imports

• Ul
  wrong:

  const Ul = require('ul');

  correct:

  import Ul from 'ul';

  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.
• Ul.deepMerge
  wrong:

  import { deepMerge } from 'ul';

  correct:

  import Ul from 'ul';
  const mergedObject = Ul.deepMerge(obj1, obj2);

  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.
• Ul.home
  wrong:

  import { home } from 'ul';

  correct:

  import Ul from 'ul';
  const userHomeDir = Ul.home();

  Like `deepMerge`, `home` is accessed as a method of the `Ul` object. `Ul.HOME_DIR` also provides a cached path to the home directory.

Quickstart

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.

import Ul from 'ul';

// Input data
let obj = {
       n: null,
       v: 1
    };
  , def = {
        n: 1,
        v: 10,
        a: 20
    };
  , tmp = null;


// Merge the two objects and store the result in tmp
console.log('Deep Merge Result:', tmp = Ul.deepMerge(obj, def));
// Expected output: { n: null, v: 1, a: 20 }
// Illustrates how `null` values in `obj` are preserved even if `def` has a non-null value.

// Clone the tmp object -- the clone will have a different reference
const clonedTmp = Ul.clone(tmp);
console.log('Cloned Object:', clonedTmp);
console.log('Is clone identical to original reference?', tmp === clonedTmp);
// Expected output: false (demonstrates deep cloning creates a new reference)

// Show the absolute path to the home directory
console.log('Home Directory (function call):', Ul.home());
console.log('Home Directory (property access):', Ul.HOME_DIR);
// Path will vary by OS, e.g., /home/user or C:\Users\user

// One level merge
console.log('One-Level Merge Result:', Ul.merge({
    foo: {
        bar: 42
    }
}, {
    foo: {
        bar: 1,
        baz: 7
    }
}));
// Expected output: { foo: { bar: 42 } } (demonstrates shallow merge behavior, inner 'foo' object from first arg is preserved)