@razmans/friendly-id

Generate memorable, human-readable identifiers. English and Bahasa Malaysia.

bright-fox-7391
cemerlang-bunga-2104
indah-harimau-8842

Zero runtime dependencies. TypeScript-first. Node 18+.

Install

npm install @razmans/friendly-id

Usage

import { friendlyId, uniqueId, generatePool } from "@razmans/friendly-id";

// Basic
friendlyId();
// => "swift-river-7391"

// With options
friendlyId({ separator: "_" });
// => "brave_falcon_2104"

friendlyId({ capitalize: true });
// => "Golden-Leaf-8842"

friendlyId({ addNumber: false });
// => "quiet-ocean"

// Force specific words
friendlyId({ adjective: "happy", noun: "puppy" });
// => "happy-puppy-4820"

// Bahasa Malaysia words are included naturally
friendlyId();
// => "besar-sungai-1234"
// => "indah-bunga-5678"
// => "gagah-keris-9999"

API

friendlyId(options?)

| Option | Type | Default | Description | |--------|------|---------|-------------| | separator | string | "-" | Word separator | | capitalize | boolean | false | Capitalize each word | | addAdjective | boolean | true | Include an adjective | | addNoun | boolean | true | Include a noun | | addNumber | boolean | true | Append a random number | | maxNumber | number | 9999 | Max value for the number | | minNumber | number | 1 | Min value for the number | | adjective | string | — | Force a specific adjective | | noun | string | — | Force a specific noun |

uniqueId(options?)

Same as friendlyId, but appends a base36 timestamp for near-guaranteed uniqueness.

uniqueId();
// => "calm-wave-4820-lx9q2m"

generatePool(count, options?)

Generate a guaranteed-unique pool of IDs.

generatePool(5);
// => ["red-fox-1234", "blue-moon-5678", ...]

Word Lists

import { ADJECTIVES, NOUNS } from "@razmans/friendly-id";

console.log(ADJECTIVES.length); // 388
console.log(NOUNS.length);      // 740

The library includes ~200 Bahasa Malaysia adjectives and ~500 Bahasa Malaysia nouns mixed naturally with English words. No configuration needed — they appear randomly alongside English words.

TypeScript

Fully typed. Definitions are generated automatically from source.

import { friendlyId, friendlyIdOptions } from "@razmans/friendly-id";

const opts: friendlyIdOptions = { capitalize: true, separator: "_" };
friendlyId(opts); // "Besar_Bunga_1234"

Why?

• Better than UUIDs for shareable links, temp filenames, and test data
• Memorable — humans can actually read and recall these
• Bilingual — naturally supports English and Bahasa Malaysia
• Zero dependencies — tiny footprint

License

MIT