Petname

Petname is a TypeScript library and CLI for human-readable job names. It generates sortable UTC-prefixed names such as 202607241430-calm-otter.

CLI

Run the package without installing it:

npx @osolmaz/petname
# 202607241430-calm-otter

The package requires Node.js 22 or newer. Install it as a dependency when using the library API:

npm install @osolmaz/petname

The remaining examples use the locally installed binary. Generate several names for one batch:

npx petname --count 8

A seed reproduces a name, which is useful in tests and job manifests:

npx petname --date 2026-07-24T14:30:59Z --seed demo
# 202607241430-eager-emu

Use --words 3 for adjective-color-animal names. --no-datetime returns only the petname. Run petname --help for the complete option list.

Library

import { generatePetname, generatePetnames } from "@osolmaz/petname";

const job = generatePetname();
const batch = generatePetnames(8);

The default format is:

YYYYMMDDHHmm-adjective-animal

The timestamp is always UTC and records creation time. A batch captures the time once so all of its names share the same sortable prefix. The default word space contains more than 44,000 combinations per minute.

Pass custom word lists when a project needs its own vocabulary:

const job = generatePetname({
  wordLists: {
    qualities: ["calm"],
    colors: ["amber"],
    animals: ["otter"],
  },
});

Custom words must contain lowercase ASCII letters. Generated names work as path components and shell arguments. They are also safe in URLs and common job APIs without escaping.

Petnames are practical human labels. They do not provide cryptographic identity. Systems that require a hard uniqueness guarantee should enforce one in storage and generate another name after a conflict.

License

MIT