Hexoid ID Generator

2.0.0 · active · verified Sun Apr 19

Hexoid is a minimalist (190B) and high-performance utility designed for generating fixed-length, randomized hexadecimal IDs in JavaScript environments, including Node.js and browsers. The current stable version is 2.0.0, which introduced significant changes for improved module interoperability. It is primarily used when a quick, unique string identifier is needed, but cryptographic security is not a requirement. Key differentiators include its extreme speed, small footprint, and focus on simple hexadecimal output, contrasting with larger, more feature-rich UUID libraries. While it provides good collision resistance for common use cases, users must be aware it is not cryptographically secure and the risk of collisions increases with shorter lengths, as detailed by the Birthday Problem.

Common errors

```
TypeError: (0 , hexoid__WEBPACK_IMPORTED_MODULE_0__.default) is not a function
```
cause Attempting to use a default import for `hexoid` after v2.0.0 when it is now a named export in an ESM context.

fix Change your import statement from `import hexoid from 'hexoid';` to `import { hexoid } from 'hexoid';`.
```
TypeError: hexoid is not a function (when using CommonJS require)
```
cause Attempting to use `require('hexoid')` directly as a function call after v2.0.0 when `hexoid` is now a named export in CommonJS.

fix Change your CommonJS import from `const hexoid = require('hexoid');` to `const { hexoid } = require('hexoid');`.

Warnings

breaking The default export has been replaced with a named `hexoid` export. Direct default imports will no longer work.
Fix: Update your imports from `import hexoid from 'hexoid';` to `import { hexoid } from 'hexoid';` for ESM, and from `const hexoid = require('hexoid');` to `const { hexoid } = require('hexoid');` for CommonJS.
breaking The package now uses an `exports` map for native ESM support, which may affect bundlers or older Node.js versions not configured for `node16` or `nodenext` module resolution.
Fix: Ensure your project's `tsconfig.json` (if using TypeScript) or bundler configuration supports `node16` or `nodenext` module resolution if experiencing module resolution issues.
gotcha Hexoid is not a cryptographically secure random number generator (CSPRNG). It should not be used for security-sensitive applications where unpredictable uniqueness is paramount.
Fix: For security-sensitive ID generation (e.g., session tokens, password resets), use a CSPRNG-backed library like `crypto.randomUUID()` in Node.js or `window.crypto.getRandomValues()` in browsers.
gotcha Collision risk (Birthday Problem): Shorter ID lengths significantly increase the probability of generating duplicate IDs. While hexoid is fast, its internal counter can eventually wrap around.
Fix: Always consider the required number of unique IDs and choose a sufficiently long ID length. The README provides a formula `256 ** (len/2)` for calculating maximum combinations to assess collision risk.

Install

npm install hexoid npm
yarn add hexoid yarn
pnpm add hexoid pnpm

Imports

hexoid
wrong:
```
import hexoid from 'hexoid';
```
correct:
```
import { hexoid } from 'hexoid';
```
Since v2.0.0, hexoid is a named export for both ESM and CommonJS to standardize import patterns and improve TypeScript compatibility.
hexoid (CommonJS)
wrong:
```
const hexoid = require('hexoid');
```
correct:
```
const { hexoid } = require('hexoid');
```
For CommonJS, use destructuring assignment to access the named 'hexoid' export, aligning with ESM usage since v2.0.0.
hexoid (TypeScript type)
```
import type { HexoidFn } from 'hexoid';
```
The library ships with TypeScript types, and the generator function's type is exported as HexoidFn.

Quickstart

Demonstrates how to import the `hexoid` function and generate IDs with default and custom lengths.

import { hexoid } from 'hexoid';

// Create a generator for default length (16 characters)
const generateDefaultId = hexoid();
console.log('Default ID:', generateDefaultId());
// Example output: '52032fedb951da00'

// Create a generator for a custom length (e.g., 25 characters)
const generateCustomId = hexoid(25);
console.log('Custom length ID:', generateCustomId());
// Example output: '065359875047c63a037200e00'

// Create multiple IDs from the same generator
const toID = hexoid();
console.log('ID 1:', toID());
console.log('ID 2:', toID());
console.log('ID 3:', toID());

view raw JSON →