@readable-code/english

English-like pronounceable word generator for readable-code share codes.

Generates easy-to-read, easy-to-say pseudo-words — not dictionary words, not secret tokens.

Install

npm install @readable-code/english

Usage

import { word } from "@readable-code/english";

word(4).dash().digits(4).build();
// "mivo-4821"

word(4).dash().word(8).dash().digits(4).build();
// "teva-pifoluna-7520"

build() is the finalizer. It joins the chained fragments and returns the code string.

How words are generated

English-like codes use pseudo-words rather than a dictionary. The generator alternates consonants and vowels into a pronounceable shape:

consonant + vowel + consonant + vowel  →  mivo, rane, coru

Ambiguous letters (q, x, y) are excluded.

API

word(length, options?)

Primary fluent API. Returns a builder with one pseudo-word already added, so you can keep chaining.

word(6).build();              // "mivora"
word(4, { casing: "upper" }); // "MIVO..."

Builder methods: word(length), dash(), digits(length) / nums(length), add(value), build(), toString().

engWord(length, options?) => string

Lower-level helper that generates one pseudo-word and returns it as a plain string — no builder, no chaining, no separators or digits attached. Where word() starts a fluent chain, engWord() is the raw primitive underneath it: word(n) is essentially code().add(engWord(n)).

Reach for engWord() when you want the bare word to drop into your own composition — a custom template, an existing string, a non-CodeBuilder pipeline, or when you only need the word itself with no suffix.

import { engWord } from "@readable-code/english";

engWord(4);                      // "mivo"
engWord(6, { casing: "upper" }); // "MIVORA"
engWord(0);                      // "" — length 0 yields an empty string

Compose it manually via the core builder, or just use plain string ops:

import { code } from "@readable-code/core";
import { engWord } from "@readable-code/english";

// Equivalent to word(4).dash().digits(4)
code().add(engWord(4)).dash().digits(4).build();

// Or your own format, no builder at all:
`order-${engWord(5)}`;           // "order-teruk"

Parameters

• length (number, required) — number of characters. Must be a non-negative integer; odd lengths still start on a consonant (engWord(1) → one consonant). Throws RangeError otherwise.

Options

• casing?: "lower" | "upper" — output case. Defaults to lower. Applies to the generated letters only.
• random?: RandomSource — custom random source from @readable-code/core for deterministic output (see below). Defaults to secureRandom (crypto.getRandomValues).

Deterministic output

Pass a custom RandomSource from @readable-code/core for reproducible tests:

import { type RandomSource } from "@readable-code/core";
import { word } from "@readable-code/english";

const random: RandomSource = () => 0;
word(4, { random }).dash().digits(4).build();

Concept

Readable public share codes, not secret tokens. Keep uniqueness separate from the readable part — store codes under a database UNIQUE constraint and retry on collision.

License

MIT