random-string-token

Tiny, secure random string and token generator for Node.js projects.

random-string-token uses Node.js crypto APIs for cryptographically secure randomness and provides a small, beginner-friendly API.

Installation

npm install random-string-token

Quick Start

import {
  randomString,
  randomToken,
  randomHex,
  randomNumeric,
  randomUrlSafe
} from 'random-string-token';

const id = randomString(16);
const sessionToken = randomToken();
const otp = randomNumeric(6);
const hex = randomHex(32);
const shareCode = randomUrlSafe(24);

API

randomString(length, options?)

Generate a random string with exact length.

randomString(length: number, options?: RandomStringOptions): string

RandomStringOptions:

• lowercase?: boolean
• uppercase?: boolean
• numbers?: boolean
• symbols?: boolean
• charset?: string

Behavior:

• If charset is provided, it is used directly.
• Otherwise, charset is built from boolean flags.
• If no flags are provided, defaults to alphanumeric (a-zA-Z0-9).

randomToken(options?)

Generate a token with default length 32.

randomToken(options?: RandomTokenOptions): string

RandomTokenOptions includes all RandomStringOptions plus:

• length?: number

randomHex(length?)

Generate a lowercase hex token.

randomHex(length?: number): string

randomNumeric(length)

Generate a numeric-only string (OTP-like code).

randomNumeric(length: number): string

randomUrlSafe(length)

Generate a URL-safe token using a-zA-Z0-9-_.

randomUrlSafe(length: number): string

Examples

Alphanumeric token

import { randomToken } from 'random-string-token';

const token = randomToken({ length: 24 });

Numeric OTP-like code

import { randomNumeric } from 'random-string-token';

const otp = randomNumeric(6);

Hex token

import { randomHex } from 'random-string-token';

const token = randomHex(64);

URL-safe token

import { randomUrlSafe } from 'random-string-token';

const token = randomUrlSafe(32);

Custom charset

import { randomString } from 'random-string-token';

const code = randomString(10, { charset: 'ABC123' });

Validation and Errors

The package validates all inputs and throws deterministic error messages for invalid options:

• invalid length values (non-number, non-integer, or <= 0)
• invalid or empty charset
• no available characters when all flags are explicitly false

Security Note

This package uses cryptographically secure randomness from Node.js crypto (randomInt) and does not use Math.random.

Important Scope Note

This package is intended for secure random token/string generation only. It is not a complete authentication, authorization, or session-management solution.

Development

npm run check

License

MIT