Mixme Object Merger

2.0.2 · active · verified Tue Apr 21

Mixme is a JavaScript/TypeScript library (currently at v2.0.2) designed for recursively merging and manipulating JavaScript objects. It provides immutable merging via `merge` and mutable in-place modification via `mutate`. Key differentiators include its zero-dependency footprint, minimal size, and pure function approach for `merge`. It offers comprehensive TypeScript type definitions and supports both ES Modules (ESM) and CommonJS environments. While a specific release cadence isn't explicitly published, the project appears actively maintained with a streamlined release process via GitHub Actions. A notable behavior is that arrays are always overwritten during merges, not recursively combined, which is a common point of confusion for users expecting deep array merging.

Common errors

```
Cannot use import statement outside a module
```
cause Attempting to use `import` syntax in a CommonJS file or a Node.js project not configured for ES Modules.

fix Ensure your `package.json` contains `"type": "module"` for ESM, or rename `.js` files using `import` to `.mjs`. Alternatively, if staying with CommonJS, use `const { merge } = require('mixme');`.
```
TypeError: mixme.merge is not a function
```
cause This typically happens when trying to `require('mixme')` and then calling `mixme.merge()` without destructuring or accessing the named export properly in a CommonJS environment.

fix In CommonJS, you must destructure the named export: `const { merge } = require('mixme');` or access it as a property: `const mixme = require('mixme'); const result = mixme.merge(...);`.
```
ReferenceError: require is not defined
```
cause This occurs when trying to use `require()` in an ES Module context (e.g., a file with `"type": "module"` or `.mjs` extension).

fix Switch to `import` syntax: `import { merge } from 'mixme';` instead of `const { merge } = require('mixme');`. If legacy CommonJS modules are needed in an ESM project, consider dynamic `import()` or specific tools like `createRequire`.

Warnings

gotcha When merging objects with `merge` or `mutate`, arrays are always overwritten by the subsequent object's array value, not recursively merged. This differs from some other deep merge utilities.
Fix: If deep array merging is required, you must preprocess arrays manually before passing them to `mixme` or use a different library designed for deep array merging.
gotcha The `mutate` function directly modifies its first argument. If you need to preserve the original object, always pass a `clone()` of the original object as the first argument to `mutate`.
Fix: Use `const myObjectCopy = clone(myObject); mutate(myObjectCopy, changes);` if you intend to keep the original object intact. Use `merge` for an immutable approach that always returns a new object.
breaking While `mixme` v2 supports both ESM and CommonJS, migrating older CommonJS-only projects to `import` statements may require configuring 'type': 'module' in `package.json` or changing file extensions to `.mjs` for Node.js environments.
Fix: Ensure your project's module system is correctly configured. For ESM, use `import { func } from 'mixme';`. For CJS, use `const { func } = require('mixme');`. Refer to Node.js documentation on ESM/CJS interoperability.

Install

npm install mixme npm
yarn add mixme yarn
pnpm add mixme pnpm

Imports

merge
wrong:
```
const merge = require('mixme').merge;
```
correct:
```
import { merge } from 'mixme';
```
Mixme v2 supports both ESM and CommonJS. For CommonJS, named exports like `merge` must be accessed as properties of the `require` result.
mutate
wrong:
```
import mutate from 'mixme';
```
correct:
```
import { mutate } from 'mixme';
```
All primary functions (`merge`, `mutate`, `clone`, etc.) are named exports, not default exports. Attempting a default import will result in `undefined`.
clone
wrong:
```
const { clone } = require('mixme');
```
correct:
```
import { clone } from 'mixme';
```
While `const { clone } = require('mixme');` works in CommonJS, `const clone = require('mixme').clone;` is also common but slightly less idiomatic for multiple exports.

Quickstart

Demonstrates `merge` for immutable object combination, `mutate` for in-place modification, and `snake_case` utility, highlighting how arrays are overwritten.

import { merge, mutate, clone, snake_case } from 'mixme';

interface Config {
  appName: string;
  version: string;
  settings: {
    theme: string;
    notifications: boolean;
  };
  features: string[];
}

const defaultAppConfig: Config = {
  appName: 'My App',
  version: '1.0.0',
  settings: {
    theme: 'dark',
    notifications: true,
  },
  features: ['dashboard', 'reports'],
};

const userConfig: Partial<Config> = {
  appName: 'My Custom App',
  settings: {
    theme: 'light',
  },
  features: ['dashboard', 'analytics'],
};

// Immutable merge: creates a new object
const finalConfig = merge(defaultAppConfig, userConfig);
console.log('Final Config (merged):', finalConfig);
// Expected: { appName: 'My Custom App', version: '1.0.0', settings: { theme: 'light', notifications: true }, features: ['dashboard', 'analytics'] }

// Mutable merge: modifies the first object
const baseConfigCopy = clone(defaultAppConfig); // Clone to avoid modifying original defaultAppConfig
mutate(baseConfigCopy, userConfig);
console.log('Mutated Config:', baseConfigCopy);
// Expected: { appName: 'My Custom App', version: '1.0.0', settings: { theme: 'light', notifications: true }, features: ['dashboard', 'analytics'] }

// Example of snake_case utility
const camelCaseObject = { userFirstName: 'John', userLastName: 'Doe' };
const snakeCaseObject = snake_case(camelCaseObject);
console.log('Snake Case Object:', snakeCaseObject);
// Expected: { user_first_name: 'John', user_last_name: 'Doe' }

view raw JSON →