aliasforge

Generate readable random usernames from adjective, noun, and number patterns.

aliasforge is a small TypeScript utility for creating friendly usernames such as BraveRiver42, calm-lake-07, or HAPPY_FOX_99.

Installation

npm install aliasforge

yarn add aliasforge

pnpm add aliasforge

Usage

import { generateUsername } from "aliasforge";

const username = generateUsername();

console.log(username);
// Example: "BrightForest42"

Options

import { generateUsername } from "aliasforge";

const username = generateUsername({
  separator: "dash",
  casing: "lower",
  digits: 3,
});

console.log(username);
// Example: "gentle-river-204"

separator

Controls how username parts are joined.

Available values:

"none" | "dash" | "underscore" | "dot" | "space";

Examples:

generateUsername({ separator: "none" });
// "BraveRiver42"

generateUsername({ separator: "dash" });
// "Brave-River-42"

generateUsername({ separator: "underscore" });
// "Brave_River_42"

generateUsername({ separator: "dot" });
// "Brave.River.42"

generateUsername({ separator: "space" });
// "Brave River 42"

Default: "none"

casing

Controls the casing applied to the generated username.

Available values:

"pascal" | "camel" | "lower" | "upper";

Examples:

generateUsername({ casing: "pascal" });
// "BraveRiver42"

generateUsername({ casing: "camel" });
// "braveRiver42"

generateUsername({ casing: "lower" });
// "braveriver42"

generateUsername({ casing: "upper" });
// "BRAVERIVER42"

Default: "pascal"

digits

Controls how many random digits are appended to the username.

generateUsername({ digits: 4 });
// Example: "BraveRiver2048"

generateUsername({ digits: 0 });
// Example: "BraveRiver"

digits must be a non-negative integer.

Default: 2

adjectives and nouns

You can provide custom word lists.

generateUsername({
  adjectives: ["quiet", "bright"],
  nouns: ["forest", "river"],
});

By default, aliasforge includes:

• 200 adjectives
• 300 nouns

random

You can provide a custom random function for deterministic output, useful for testing or seeded generation.

generateUsername({
  adjectives: ["calm", "bold"],
  nouns: ["lake", "fox"],
  digits: 2,
  random: () => 0,
});
// "CalmLake00"

The function must return a number from 0 to 1, similar to Math.random().

Default: Math.random

API

generateUsername(options?)

Generates a readable random username.

import { generateUsername } from "aliasforge";

const username = generateUsername({
  separator: "underscore",
  casing: "upper",
  digits: 2,
});

GenerateUsernameOptions

type GenerateUsernameOptions = {
  separator?: UsernameSeparator;
  casing?: UsernameCasing;
  digits?: number;
  adjectives?: readonly string[];
  nouns?: readonly string[];
  random?: () => number;
};

UsernameSeparator

type UsernameSeparator = "none" | "dash" | "underscore" | "dot" | "space";

UsernameCasing

type UsernameCasing = "pascal" | "camel" | "lower" | "upper";

Data exports

The default word lists are also exported.

import { adjectives, nouns } from "aliasforge";

console.log(adjectives.length); // 200
console.log(nouns.length); // 300

Development

Install dependencies:

yarn install

Run tests:

yarn test

Build the package:

yarn build

License

MIT