e: Modern TypeScript Utility Library

Common errors

• TypeError: require is not a function

  cause Attempting to use `require()` to import `e` in an ES Module context, or in a Node.js project not configured for CommonJS compatibility.
  fix Change `const { symbol } = require('e');` to `import { symbol } from 'e';`. Ensure your `package.json` has `"type": "module"` if you are in an ESM project, or use a build tool to transpile.

• TS2305: Module ''e'' has no exported member 'MyFunction'.

  cause Attempting to import a symbol (e.g., `MyFunction`) that either does not exist, is misspelled, or is not a named export from the 'e' package.
  fix Verify the symbol name against the 'e' documentation or source code. Ensure it is a named export, as 'e' does not use default exports. For example, use `import { correctFunctionName } from 'e';`.

• TypeError: Cannot read properties of undefined (reading 'length')

  cause This error can occur if you pass `undefined` or `null` to a function expecting an array, or if you call a method on the result of an immutable operation without reassigning it, expecting the original to be modified.
  fix Always ensure arguments passed to 'e' functions are of the expected type. Also, remember that 'e' functions are immutable; always capture their return value: `const newArray = shuffleArr(myArray);`

Warnings

• breaking As a 0.x.x version library, the API of 'e' is considered unstable and subject to frequent breaking changes with minor version updates. Always review the changelog before upgrading.
  Fix: Pin to exact versions in your `package.json` (e.g., `"e": "0.2.33"` instead of `"^0.2.33"`) and manually update after reviewing release notes.
• gotcha All functions in 'e' are designed to be immutable, meaning they return new instances (e.g., a new array after shuffling) rather than modifying the input arguments. Failing to reassign the return value can lead to using stale data.
  Fix: Always assign the return value of 'e' functions to a new variable or explicitly reassign it to the original variable if mutation is desired (though not recommended for 'e' patterns). For example: `const newArr = shuffleArr(oldArr);`
• gotcha The library is primarily built for ES Modules (ESM) environments. Using CommonJS `require()` in a Node.js project not configured for dual-package mode might result in import errors or unexpected behavior.
  Fix: Ensure your project uses `import` statements and is configured for ESM. If you must use CommonJS, consider a transpilation step or a tool like `cjstoesm` if available, or check for dual-packaging support in future versions.

Install

• npm install e npm
• yarn add e yarn
• pnpm add e pnpm

Imports

• sleep
  wrong:

  const { sleep } = require('e');

  correct:

  import { sleep } from 'e';

  The 'e' library is primarily designed for ES Modules (ESM). CommonJS `require()` is not officially supported and may lead to issues.
• randFloat
  wrong:

  import randFloat from 'e';

  correct:

  import { randFloat } from 'e';

  All utilities are named exports; there is no default export from the 'e' package.
• shuffleArr

  import { shuffleArr } from 'e';

Quickstart

Demonstrates core functionalities like asynchronous delays, random number generation, and array shuffling, emphasizing the library's non-mutating design philosophy.

import { sleep, randFloat, shuffleArr } from 'e';

async function demonstrateE() {
  console.log('Starting e library demonstration...');

  // Demonstrate asynchronous delay
  console.log('Pausing for 1000 milliseconds...');
  await sleep(1000);
  console.log('Resumed after sleep.');

  // Generate a random floating-point number
  const randomNumericValue = randFloat();
  console.log(`Generated a random float between 0 and 1: ${randomNumericValue.toFixed(4)}`);

  // Shuffle an array without mutating the original
  const originalNumbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
  console.log('Original array:', originalNumbers);
  const shuffledNumbers = shuffleArr(originalNumbers);
  console.log('Shuffled array (new instance):', shuffledNumbers);
  console.log('Original array remains unchanged:', originalNumbers);

  // Verify non-mutation explicitly
  if (originalNumbers === shuffledNumbers) {
    console.error('CRITICAL ERROR: Array mutation detected! This should not happen in \'e\'.');
  } else {
    console.log('Non-mutation confirmed: original and shuffled arrays are distinct instances.');
  }
  console.log('e library demonstration complete.');
}

demonstrateE().catch(console.error);