ext: JavaScript Utilities and Polyfills

Common errors

• Command failed with exit code 1

  cause The `postinstall` script, which runs after `npm install`, encountered an error due to environmental factors, shell compatibility, or permissions issues on Windows, Powershell, or certain Linux terminals.
  fix Update Node.js/npm. If the error persists, install with `npm install ext --ignore-scripts`. This bypasses the script but might require manual setup if it performs critical configuration. Consult package GitHub issues for specific workarounds.

• TypeError: Cannot read property 'match' of null (or similar regex errors) when using function#toStringTokens()

  cause Older versions of the library relied on problematic regex patterns, particularly affecting methods that parse function definitions, leading to failures with ES2015+ syntax.
  fix Update the `ext` package to at least `v0.10.63` (or the latest `1.x` series) which includes bug fixes for improved regex robustness and better support for modern JavaScript function definitions.

• Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'ext' imported from ...

  cause This error typically occurs when trying to `import` the package using an incorrect path or if the environment is configured for CommonJS while `ext` is being treated as an ESM module, or vice-versa, specifically for subpath imports.
  fix Verify the exact import path for the specific utility you are trying to use (e.g., `import clear from 'ext/object/clear';`). Ensure your project's module resolution (`package.json#type`) aligns with how you are importing modules.

Warnings

• breaking The package was renamed from `es5-ext` to `ext`. Users migrating from `es5-ext` will need to update all import paths (e.g., `require('es5-ext/object/clear')` becomes `import objectClear from 'ext/object/clear';`). While `es5-ext` still receives maintenance, `ext` is the officially supported name.
  Fix: Update all package references and import/require paths in your codebase to use `ext` instead of `es5-ext`. For example, change `import 'es5-ext/array/#/clear'` to `import arrayClear from 'ext/array/clear'` and then use `arrayClear.call(myArray)`.
• gotcha The package's `postinstall` script has historically caused issues on various operating systems (Windows, specific Linux terminals, Powershell), potentially leading to installation failures or errors. While recent `0.10.x` releases have focused on patching these, environmental-specific problems may still arise.
  Fix: Ensure your Node.js and npm installations are up-to-date. If issues persist, try `npm install ext --ignore-scripts`. If a critical setup is missed, consult the official GitHub issues for specific workarounds or report the problem with detailed environment information.
• gotcha The library primarily promotes granular ESM imports (e.g., `import util from 'ext/path/to/util';`). Attempting to use CommonJS `require()` syntax with modern `ext` versions in an ESM-configured project, or assuming a single top-level default export for multiple utilities, will lead to module resolution errors.
  Fix: Adopt explicit ESM `import` statements for specific utilities from their respective subpaths. Ensure your project is configured to handle ESM imports correctly (e.g., `"type": "module"` in `package.json`).

Install

• npm install ext npm
• yarn add ext yarn
• pnpm add ext pnpm

Imports

• globalThis
  wrong:

  const globalThis = require('ext/global-this');

  correct:

  import globalThis from 'ext/global-this';

  The `ext` package encourages granular ESM imports for specific utilities. CommonJS `require()` is generally discouraged in modern contexts.
• objectClear
  wrong:

  import { clear } from 'ext/object'; // Incorrect path/named import
  import objectClear from 'ext/object/clear.js'; // .js extension is usually not needed

  correct:

  import objectClear from 'ext/object/clear';

  Each utility is typically imported from its specific subpath. There is no single top-level 'object' module export for all its methods.
• camelToHyphen
  wrong:

  import { camelToHyphen } from 'ext/string'; // Incorrect, it's a subpath module
  import 'ext/string/#/camel-to-hyphen'; // Old `es5-ext` path or direct prototype extension side-effect

  correct:

  import camelToHyphen from 'ext/string/camel-to-hyphen';

  For methods that extend prototypes (like String.prototype.camelToHyphen), the library exports the function directly. You can call it with `.call()` or manually extend the prototype if desired, adhering to the 'non-invasive' principle.

Quickstart

Demonstrates importing and using `globalThis`, `objectClear`, `camelToHyphen`, and `identity` utilities. It shows cross-environment `globalThis` access, clearing an object, string case conversion, and a basic identity function.

import globalThis from 'ext/global-this';
import objectClear from 'ext/object/clear';
import camelToHyphen from 'ext/string/camel-to-hyphen';
import identity from 'ext/function/identity';

// Access globalThis reliably across environments
console.log('Is this browser globalThis?', typeof window !== 'undefined' && globalThis === window);
console.log('Is this Node globalThis?', typeof global !== 'undefined' && globalThis === global);

// Clear an object's properties
const data = { a: 1, b: 'two', c: true };
console.log('Original object:', data); // { a: 1, b: 'two', c: true }
objectClear(data);
console.log('Object after clear:', data); // {}

// Convert camelCase to hyphen-case
const camelCaseString = 'myCamelCaseString';
const hyphenatedString = camelToHyphen.call(camelCaseString);
console.log(`'${camelCaseString}' hyphenated: '${hyphenatedString}'`); // 'my-camel-case-string'

// Use a simple identity function
const value = 42;
const transformedValue = identity(value);
console.log(`Identity of ${value} is ${transformedValue}`); // 'Identity of 42 is 42'