@readable-code/core

Builder, random helpers, digits, and separators for readable-code share-code generators.

This is the shared foundation. For end-user generators, use @readable-code/english or @readable-code/korean.

Install

npm install @readable-code/core

Usage

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

code().add("abc").dash().digits(4).build();
// "abc-4821"

build() is the finalizer. It joins the accumulated fragments and returns the code string. toString() returns the same value.

Builder

The core builder is a small chainable string composer.

• add(value) appends a custom string.
• dash() appends -.
• digits(length) appends length random decimal digits.
• nums(length) is an alias for digits(length).
• build() returns the final string.
• toString() also returns the final string.

Helpers

import { digits, pick, secureRandom, type RandomSource } from "@readable-code/core";

digits(4);            // "3396" — random decimal digits
pick(["a", "b", "c"]); // one element, uniformly at random
secureRandom(10);     // integer in [0, 10)

Randomness

Randomness uses crypto.getRandomValues by default (uniform via rejection sampling). Pass a custom RandomSource when you need deterministic tests:

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

const random: RandomSource = () => 0; // (maxExclusive) => integer in [0, maxExclusive)
code(random).digits(4).build();

Concept

These are readable public share codes, not secret tokens. Uniqueness is kept separate from the readable part — store generated codes under a database UNIQUE constraint and retry on collision. The builder only composes string fragments; uniqueness, retry, persistence, and denylist policy live outside it.

License

MIT