ModApp Utilities

Common errors

• TypeError: (0, modapp_utils__WEBPACK_IMPORTED_MODULE_0__.debounce) is not a function

  cause Attempting to use a named export like `debounce` after an incorrect import, or if `debounce` was not exported or renamed.
  fix Verify the exact name of the exported function from `modapp-utils`. Ensure you are using named imports: `import { debounce } from 'modapp-utils';`.

• ERR_REQUIRE_ESM: require() of ES Module path/to/node_modules/modapp-utils/index.js from path/to/your/file.js not supported. Instead change the require of index.js to a dynamic import() call.

  cause `modapp-utils` is an ES Module, but it is being imported into a CommonJS module using `require()`.
  fix Either convert your consuming file to an ES Module (by using `import` statements and ensuring your `package.json` has `"type": "module"` or your file ends in `.mjs`), or use dynamic `import('modapp-utils')` if you must remain in CommonJS.

• SyntaxError: Named export 'mergeDeep' not found. The requested module 'modapp-utils' does not provide an export named 'mergeDeep'

  cause The module `modapp-utils` does not export a symbol named `mergeDeep`, or it is exported under a different name, or the module itself is incorrectly structured.
  fix Double-check the `modapp-utils` documentation or its source code to confirm the correct export name for the deep merge utility. It might be named `deepMerge`, `assignDeep`, or similar. Adjust your import statement accordingly.

Warnings

• gotcha As a utility library, `modapp-utils` likely exports numerous functions. Incorrectly importing non-existent functions or attempting to import a default export when only named exports are available will result in runtime errors.
  Fix: Always refer to the official documentation or source code for exact export names and types. Use named imports (`import { funcName } from 'modapp-utils';`) unless a default export is explicitly provided.
• breaking Older versions of `modapp-utils` (prior to major version bumps, if any occurred) might have exclusively used CommonJS. Modern versions are likely ESM-first, which can cause `ERR_REQUIRE_ESM` errors in CommonJS-only Node.js environments.
  Fix: Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or `.mjs` file extension). If using CommonJS, consider transpiling your code or using a bundler that handles ESM imports correctly. Check if a CommonJS build is provided or a legacy version is available if ESM migration is not an option.
• gotcha While utility libraries are often prime candidates for tree-shaking, the effectiveness of tree-shaking for `modapp-utils` depends on its internal structure and how it's bundled. If not properly implemented, unused utility functions might still be included in your final bundle, increasing its size.
  Fix: Use a modern bundler like Webpack, Rollup, or Vite. Verify bundle size with tools like `webpack-bundle-analyzer` and ensure your bundler is configured for production mode to enable tree-shaking and minification. If bundle size remains an issue, consider selectively importing only the specific utilities you need if the library supports subpath imports (which is not guaranteed for generic utility packages).

Install

• npm install modapp-utils npm
• yarn add modapp-utils yarn
• pnpm add modapp-utils pnpm

Imports

• debounce
  wrong:

  const { debounce } = require('modapp-utils');

  correct:

  import { debounce } from 'modapp-utils';

  CommonJS `require` might work in some environments due to transpilation, but native ESM import is the recommended and future-proof approach for modern Node.js and browser environments.
• mergeDeep
  wrong:

  import mergeDeep from 'modapp-utils/mergeDeep';

  correct:

  import { mergeDeep } from 'modapp-utils';

  Individual utilities are typically named exports from the main package entry point. Direct subpath imports are generally not supported unless explicitly documented.
• generateUUID
  wrong:

  import { uuid } from 'modapp-utils';

  correct:

  import { generateUUID } from 'modapp-utils';

  Ensure to use the exact exported name, `generateUUID`, as `uuid` might not be directly exported or could be an internal alias.

Quickstart

This quickstart demonstrates importing and using a `debounce` function for event handling, a `mergeDeep` function for recursively combining objects, and a `generateUUID` function for creating unique identifiers. It sets up a simple debounced search input in the browser and logs merged configuration and a new UUID to the console.

import { debounce, mergeDeep, generateUUID } from 'modapp-utils';

// Example 1: Debouncing a function
const searchInputHandler = (query) => {
  console.log('Searching for:', query);
  // Simulate API call
};
const debouncedSearch = debounce(searchInputHandler, 500);

document.addEventListener('DOMContentLoaded', () => {
  const input = document.createElement('input');
  input.placeholder = 'Type to search (debounced)';
  input.onkeyup = (event) => debouncedSearch(event.target.value);
  document.body.appendChild(input);

  // Example 2: Deep merging objects
  const defaultConfig = { host: 'localhost', port: 8080, db: { user: 'guest', pass: 'guest' } };
  const userConfig = { port: 3000, db: { user: 'admin' }, api: { key: process.env.API_KEY ?? '' } };
  const mergedConfig = mergeDeep(defaultConfig, userConfig);
  console.log('Merged Configuration:', mergedConfig);

  // Example 3: Generating a UUID
  const newId = generateUUID();
  console.log('Generated UUID:', newId);

  // Cleanup for demonstration purposes
  setTimeout(() => {
    console.log('Demonstration complete. Open your browser console.');
    input.remove();
  }, 2000);
});