or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-randomstring

A module for generating random strings with customizable character sets, lengths, and formatting options

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/randomstring@1.3.x

To install, run

npx @tessl/cli install tessl/npm-randomstring@1.3.0

index.mddocs/

randomstring

randomstring is a Node.js module for generating random strings with customizable character sets, lengths, and formatting options. It provides both synchronous and asynchronous APIs with cryptographically secure random byte generation and graceful fallback to Math.random() for compatibility.

Package Information

  • Package Name: randomstring
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install randomstring

Core Imports

const randomstring = require("randomstring");

For ES modules (Node.js with type: "module"):

import randomstring from "randomstring";

Basic Usage

const randomstring = require("randomstring");

// Generate default 32-character alphanumeric string
const str1 = randomstring.generate();
// >> "XwPp9xazJ0ku5CZnlmgAx2Dld8SHkAeT"

// Generate string with specific length
const str2 = randomstring.generate(12);
// >> "kJh3Md9xB2nP"

// Generate string with options
const str3 = randomstring.generate({
  length: 8,
  charset: 'alphabetic',
  capitalization: 'lowercase'
});
// >> "abcdefgh"

// Generate async with callback
randomstring.generate({ length: 16, charset: 'hex' }, (err, result) => {
  if (err) throw err;
  console.log(result); // >> "a1b2c3d4e5f67890"
});

Architecture

randomstring is built around several key components:

  • Random Generation Engine: Uses Node.js randombytes library for cryptographically secure randomness with automatic fallback to Math.random() for compatibility
  • Charset System: Flexible character set management supporting predefined sets (alphanumeric, hex, etc.) and custom character strings or arrays
  • Dual API: Both synchronous and asynchronous generation modes with consistent option handling
  • CLI Interface: Command-line tool with flexible argument parsing supporting both positional and key-value parameters

Capabilities

Random String Generation

Generates random strings with extensive customization options including character sets, length, capitalization, and readability filtering.

/**
 * Generate a random string with specified options
 * @param {number|object} options - Length (number) or options object
 * @param {function} [callback] - Optional callback for async generation
 * @returns {string|undefined} Generated string (sync) or undefined (async)
 */
function generate(options, callback);

// Options object properties:
interface GenerateOptions {
  /** Length of the generated string (default: 32) */
  length?: number;
  
  /** Character set to use for generation (default: 'alphanumeric') */
  charset?: string | string[];
  
  /** Exclude poorly readable characters (0OIl) (default: false) */
  readable?: boolean;
  
  /** Force case transformation (default: null) */
  capitalization?: 'uppercase' | 'lowercase';
}

Supported Character Sets:

  • 'alphanumeric' - [0-9 a-z A-Z] (62 characters)
  • 'alphabetic' - [a-z A-Z] (52 characters)
  • 'numeric' - [0-9] (10 characters)
  • 'hex' - [0-9 a-f] (16 characters)
  • 'binary' - [01] (2 characters)
  • 'octal' - [0-7] (8 characters)
  • Custom string - Any string of characters to use
  • Array of charsets - Combines multiple character sets

Usage Examples:

// Simple length specification
randomstring.generate(10);

// Numeric-only string
randomstring.generate({
  length: 16,
  charset: 'numeric'
});

// Readable alphanumeric (excludes 0OIl)
randomstring.generate({
  length: 20,
  charset: 'alphanumeric',
  readable: true
});

// Custom character set
randomstring.generate({
  length: 12,
  charset: 'abc123'
});

// Array of character sets
randomstring.generate({
  length: 15,
  charset: ['numeric', '!@#$']
});

// Uppercase only
randomstring.generate({
  length: 8,
  charset: 'alphabetic',
  capitalization: 'uppercase'
});

// Async generation
randomstring.generate({
  length: 24,
  charset: 'hex'
}, (err, result) => {
  if (err) {
    console.error('Generation failed:', err);
    return;
  }
  console.log('Generated:', result);
});

Command Line Interface

The package includes a command-line interface for generating random strings:

# Install globally
npm install -g randomstring

# Basic usage
randomstring
# >> "sKCx49VgtHZ59bJOTLcU0Gr06ogUnDJi"

# Specify length
randomstring 12
# >> "CpMg433xB2nP"

# Use options (key=value format)
randomstring length=16 charset=hex readable
# >> "a1b2c3d4e5f67890"

# Mixed usage - positional length + options
randomstring 20 charset=alphabetic capitalization=uppercase
# >> "ABCDEFGHIJKLMNOPQRST"

# Available options:
# length=N - Set string length (or use as first positional argument)
# charset=TYPE - Set character set (alphanumeric, alphabetic, numeric, hex, binary, octal, or custom)
# capitalization=CASE - Set case transformation (uppercase/lowercase)
# readable - Enable readable mode (excludes 0OIl characters)

Error Handling

  • Synchronous mode: No explicit error handling - uses fallback to Math.random() if crypto fails
  • Asynchronous mode: Callback receives error as first parameter if randombytes fails
  • Cryptographic fallback: Automatically falls back to Math.random() when secure random bytes are unavailable
// Async error handling
randomstring.generate({ length: 100 }, (err, result) => {
  if (err) {
    console.error('Random generation error:', err.message);
    return;
  }
  // Use result
  console.log(result);
});

Types

// Main export
const randomstring = {
  generate: function(options, callback)
};

// Options interface (TypeScript-style for documentation)
interface GenerateOptions {
  length?: number;
  charset?: string | string[];
  readable?: boolean;
  capitalization?: 'uppercase' | 'lowercase';
}

// Callback signature
type GenerateCallback = (error: Error | null, result?: string) => void;