Benjamin Lupton's Utility Functions

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` in an ES module context (e.g., an `.mjs` file or a `.js` file in a project with `"type": "module"` in `package.json`).
  fix If your project is an ES module, you cannot directly use `require()`. Change your file to CommonJS (`.js` with no `type` field or `"type": "commonjs"`), or ideally, migrate to a modern utility library that supports ESM `import`.

• TypeError: balUtil.someFunction is not a function

  cause Trying to call a function (`someFunction`) that does not exist on the `balUtil` object, was removed in a specific (though unlikely for this package) version, or is part of a sub-module (e.g., `balUtil.path.join` instead of `balUtil.join`).
  fix Consult the `bal-util` source code or historical documentation to verify the correct function name and its accessibility path. Ensure you are using `balUtil.submodule.functionName` if it's nested.

• npm ERR! engines { 'node': '>=0.12' }

  cause Your current Node.js version does not meet the minimum requirement specified in the `bal-util` package's `engines` field.
  fix Although `npm install` with `--force` or `--legacy-peer-deps` might bypass this, it's not recommended. The core issue is `bal-util`'s extreme age. The best fix is to replace `bal-util` with a modern, actively maintained alternative that supports your current Node.js version.

Warnings

• breaking The package explicitly requires Node.js version `>=0.12`. Using it in modern Node.js environments (v12+, v14+, etc.) will likely lead to compatibility issues or unexpected behavior due to API changes and evolving JavaScript syntax.
  Fix: It is strongly recommended to use modern, maintained utility libraries (e.g., Lodash, native Node.js/JavaScript features) that support current Node.js versions. If absolutely necessary, run in a legacy Node.js environment or transpile meticulously.
• gotcha This package is CommonJS-only. Attempting to use `import` statements directly in an ES module (`.mjs` file or `"type": "module"` in package.json) will result in an `ERR_REQUIRE_ESM` or similar error.
  Fix: Ensure your project or file uses CommonJS (`.js` files with `"type": "commonjs"` or no `type` field) and use `const balUtil = require('bal-util');` for imports. For ES modules, consider using a bundler like Webpack or Rollup, or migrate to a modern utility library.
• gotcha The `bal-util` package has not been updated in approximately nine years. This means it lacks security patches, bug fixes, performance improvements, and support for modern JavaScript features. Relying on an unmaintained dependency can introduce security vulnerabilities (e.g., supply chain attacks) and stability issues into your application.
  Fix: Migrate away from `bal-util` to a actively maintained and up-to-date utility library or utilize native JavaScript and Node.js APIs for similar functionalities.

Install

• npm install bal-util npm
• yarn add bal-util yarn
• pnpm add bal-util pnpm

Imports

• balUtil
  wrong:

  import balUtil from 'bal-util';

  correct:

  const balUtil = require('bal-util');

  This package is CommonJS-only and requires `require()` for module loading. Direct ESM `import` statements will fail.
• extend
  wrong:

  import { extend } from 'bal-util';

  correct:

  const { extend } = require('bal-util');

  Individual utilities are exposed as named exports from the main `bal-util` object, but still accessed via `require()`.
• path

  const { path } = require('bal-util');
  // or
  const balUtil = require('bal-util');
  balUtil.path.join(...);

  `path` is a sub-module of `bal-util`, exposing its own set of utilities like `join`, `resolve`, etc.

Quickstart

Demonstrates requiring the `bal-util` package and using its `extend`, `path.join`, `isArray`, and `isString` utility functions to manipulate objects, paths, and check types.

const balUtil = require('bal-util');

// Example 1: Extending objects
const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { b: { d: 3 }, e: 4 };
const extendedObj = balUtil.extend({}, obj1, obj2, { f: 5 });
console.log('Extended Object:', extendedObj);
// Expected: { a: 1, b: { c: 2, d: 3 }, e: 4, f: 5 } (deep merge might not be default, depending on implementation)

// Example 2: Path manipulation (if `path` module is present)
// This assumes bal-util.path behaves like Node.js's native path module
const fullPath = balUtil.path.join('/users', 'temp', 'data.txt');
console.log('Joined Path:', fullPath);

// Example 3: Type checking
const isArrayCheck = balUtil.isArray([]);
const isStringCheck = balUtil.isString('hello');
console.log('Is [] an array?', isArrayCheck);
console.log('Is "hello" a string?', isStringCheck);