imagic-utils

Collection of general-purpose utility functions for arrays, numbers, strings, random values, IDs, hashing, and async helpers.

Install

npm install imagic-utils

Quick Start

import { getRandInteger, getRandString, generateId, wait } from 'imagic-utils'

const id = generateId()            // '3f2a1b4c...' (32 hex chars)
const n  = getRandInteger(1, 100)  // e.g. 42
const s  = getRandString(8)        // e.g. 'aX9kPq2Z'

await wait(500)                    // pause for 500 ms

API

Arrays

getRandArrayItem(array) → any

Returns a random element from the array. Returns undefined if the array is empty.

getRandArrayItem(array: any[]): any

• array — must be an Array; throws TypeError if not

Alias: getRandomArrayItem

chunkArray(array, chunkSize) → any[][]

Splits an array into sub-arrays of the given size. The last chunk may be smaller than chunkSize.

chunkArray(array: any[], chunkSize: number): any[][]

• array — must be an Array; throws TypeError if not
• chunkSize — must be a positive integer; throws if not

shuffle(variable) → any[]

Returns a new array with elements in random order (Fisher-Yates algorithm). Does not mutate the original.

shuffle(variable: any[]): any[]

• variable — must be an Array; throws TypeError if not

Numbers

getRandInteger(min, max) → number

Returns a random integer in the inclusive range [min, max].

getRandInteger(min: number, max: number): number

• min, max — must be finite numbers; throws TypeError if not
• Throws RangeError if there is no integer in [min, max]

Alias: getRandomInteger

getRandFloat(min, max, decimalPoint?) → number

Returns a random floating-point number in [min, max], rounded to decimalPoint decimal places.

getRandFloat(min: number, max: number, decimalPoint?: number): number

• min, max — numeric bounds
• decimalPoint — integer 0–15; default 5; throws RangeError if outside that range

Alias: getRandomFloat

chance(percent) → boolean

Returns true with percent% probability.

chance(percent: number): boolean

• 0 always returns false; 100 always returns true
• Throws TypeError if percent is not a finite number

Strings

getRandString(length?, charSet?) → string

Returns a random string composed of characters from charSet.

getRandString(length?: number, charSet?: string): string

• length — default 16
• charSet — default A-Za-z0-9 (62 characters); throws if an empty string is provided

Alias: getRandomString

isJSON(json) → boolean

Returns true if the argument is a string containing valid JSON; false for any other input (including non-strings).

isJSON(json: any): boolean

Random Bytes / IDs

getRandomBytes(length) → Uint8Array

Returns cryptographically random bytes. Uses crypto.getRandomValues when available (browser / Node.js ≥ 15), otherwise falls back to node:crypto.

getRandomBytes(length: number): Uint8Array

• length — must be a positive integer; throws TypeError if not

generateId() → string

Returns a 32-character lowercase hex string generated from 16 random bytes.

generateId(): string

Alias: generateHexId

generateBigId() → string

Returns a UUIDv4-formatted string (xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx).

generateBigId(): string

Alias: generateUuidV4

md5(data) → string

Returns the 32-character lowercase hex MD5 hash of the input.

md5(data: string | Buffer | Uint8Array): string

Promises

wait(milliseconds) → Promise<void>

Resolves after the given number of milliseconds.

wait(milliseconds: number): Promise<void>

• milliseconds — must be a non-negative number; throws TypeError if not

Node.js-only

The following exports are available in src/index.js but not in src/browser.js. Calling the browser stubs throws an explicit error.

getLocalAddress() → string

Returns the first non-loopback IPv4 address of the current machine.

getLocalAddresses() → string[]

Returns all non-loopback IPv4 addresses of the current machine.

getCPUUsage() → number

Returns the current CPU usage as a percentage in the range 0–100.

Aliases

| Alias | Canonical name | |-------|---------------| | getRandomArrayItem | getRandArrayItem | | getRandomFloat | getRandFloat | | getRandomInteger | getRandInteger | | getRandomString | getRandString | | generateUuidV4 | generateBigId | | generateHexId | generateId |

Error Handling

| Function | Error type | Condition | |----------|-----------|-----------| | getRandArrayItem | TypeError | argument is not an Array | | chunkArray | TypeError | array is not an Array | | chunkArray | TypeError / RangeError | chunkSize is not a positive integer | | shuffle | TypeError | argument is not an Array | | getRandInteger | TypeError | min or max is not a finite number | | getRandInteger | RangeError | no integer exists in [min, max] | | getRandFloat | RangeError | decimalPoint is outside 0–15 | | chance | TypeError | percent is not a finite number | | getRandString | Error | charSet is an empty string | | getRandomBytes | TypeError | length is not a positive integer | | wait | TypeError | milliseconds is not a non-negative number | | Node-only in browser | Error | called in a browser environment |

Examples

See the examples/ directory for runnable scripts:

node examples/basic.js

License

MIT © iMagicKey