Min-dash: Minimal Utility Toolbelt

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` syntax in an environment where min-dash v5.0.0+ is loaded as an ES Module.
  fix Switch to ESM `import` statements: `import { utility } from 'min-dash';`.

• SyntaxError: Named export 'find' not found. The requested module 'min-dash' does not provide an export named 'find'.

  cause This error occurs if your project is configured as CommonJS, but attempts to import `min-dash@^5.0.0` using ESM `import` syntax, or if a bundler isn't correctly resolving ESM exports for a CJS project.
  fix Ensure your project is configured for ESM (`"type": "module"` in `package.json`) when using `min-dash@^5.0.0`. Alternatively, if you must use CommonJS, downgrade to `min-dash@^4.0.0`.

• TypeError: 'this' is undefined or TypeError: Cannot read properties of undefined (reading 'property')

  cause This can occur when passing `null` or `undefined` as a target object to `assign` or other object manipulation functions, especially if not explicitly handling such cases or if expecting a specific object structure.
  fix Always provide a valid object as the first argument to `assign` (e.g., `assign({}, source)`). Ensure inputs to other utilities are of the expected type, or add explicit checks (`if (input == null) return defaultValue;`) where necessary.

Warnings

• breaking Min-dash v5.0.0 and later are exclusively ESM (ECMAScript Modules). Projects using CommonJS (`require()`) must either migrate to ESM or stick to min-dash v4.x.x.
  Fix: Migrate your project to use ESM imports (`import ... from 'min-dash';`) and ensure your `package.json` has `"type": "module"` or files use `.mjs` extension. For CommonJS-only environments, use `min-dash@^4.0.0`.
• gotcha When using `min-dash` with module bundlers, ensure your setup correctly applies tree-shaking to only include the specific utilities your application requires. Unoptimized bundling can lead to larger than necessary bundle sizes.
  Fix: Modern bundlers like Webpack, Rollup, or esbuild usually handle tree-shaking automatically for ESM imports. If using CommonJS, consider tools like `common-shake` (though not applicable for v5+).
• gotcha Prior to v4.2.2, some language utilities might not gracefully handle `undefined` inputs, potentially leading to runtime errors. Specifically, `findIndex` had a type definition fix in v4.2.2 and `isNil`/`isArray` in v4.2.1.
  Fix: Upgrade to `min-dash@^4.2.2` or newer to ensure robust handling of `undefined` inputs and correct type definitions across all utilities.

Install

• npm install min-dash npm
• yarn add min-dash yarn
• pnpm add min-dash pnpm

Imports

• find
  wrong:

  const { find } = require('min-dash');

  correct:

  import { find } from 'min-dash';

  Min-dash v5.0.0 and later are ESM-only. CommonJS `require` will result in an error. For tree-shaking, import individual utilities.
• * as minDash
  wrong:

  const minDash = require('min-dash');

  correct:

  import * as minDash from 'min-dash';

  This imports all utilities under a namespace. While functional, it might hinder tree-shaking if your bundler isn't configured for it. ESM-only since v5.0.0.
• assign
  wrong:

  import assign from 'min-dash/lib/assign';

  correct:

  import { assign } from 'min-dash';

  All utilities are exported directly from the main package entry point. Importing from internal paths (`lib/assign`) is discouraged and not guaranteed to be stable across versions. ESM-only since v5.0.0.

Quickstart

Demonstrates importing and using `find`, `sortBy`, and `assign` utilities for common data manipulation tasks with an emphasis on ESM syntax.

import { find, sortBy, assign } from 'min-dash';

const users = [
  { id: 1, name: 'Alice', age: 30 },
  { id: 2, name: 'Bob', age: 25 },
  { id: 3, name: 'Charlie', age: 35 }
];

// Find a user based on a condition
const oldestUser = find(users, user => user.age > 30);
console.log('Oldest user:', oldestUser); // Output: Oldest user: { id: 3, name: 'Charlie', age: 35 }

// Sort users by a property
const sortedUsers = sortBy(users, 'age');
console.log('Sorted users:', sortedUsers); // Output: Sorted users: [ { id: 2, name: 'Bob', age: 25 }, { id: 1, name: 'Alice', age: 30 }, { id: 3, name: 'Charlie', age: 35 } ]

// Assign properties from source objects to a target object
const defaultOptions = { theme: 'dark', logging: true };
const userOptions = { logging: false, debug: true };
const mergedOptions = assign({}, defaultOptions, userOptions);
console.log('Merged options:', mergedOptions); // Output: Merged options: { theme: 'dark', logging: false, debug: true }