synth-project-name

synth-project-name

Zero-config project name generation, validation, and uniqueness tracking.

Generate adj-noun names from your own pools, validate against constraints, track uniqueness — all without hardcoded data.

---

Table of Contents

• Install
• Quick Start
• Modules
  • name
  • unique
  • filter
  • validate
  • transform
  • pool
• API Reference
• License

---

Install

npm install synth-project-name

---

Quick Start

import { uniqueFromPool, createMemoryStore } from "synth-project-name";

const store = createMemoryStore();
const name = await uniqueFromPool(store, {
  adjectives: ["fast", "cool", "bold"],
  nouns: ["api", "core", "node"],
});

// → "bold-core"

---

Modules

name.ts — Generate

Generate adj-noun names from caller-provided pools. Supports language-specific noun overrides.

import { generateName, generateShortName, sanitizeKebabName, randomSuffix } from "synth-project-name";

const pools = { adjectives: ["fast", "cool"], nouns: ["api", "core"] };

generateShortName(pools);
// → "fast-core"

generateName(
  { pools, langNouns: { TypeScript: ["vault", "prism"] }, fallbackLang: "TypeScript" },
  "TypeScript"
);
// → "cool-vault"

sanitizeKebabName("My Cool App!");
// → "my-cool-app"

randomSuffix(4);
// → "a3f1"

---

unique.ts — Uniqueness

Track used names via a pluggable NameStore interface. Built-in memory store for testing.

import { uniqueName, uniqueFromPool, createMemoryStore } from "synth-project-name";

const store = createMemoryStore();

await uniqueName(store, "my-app");
// → "my-app"

await uniqueName(store, "my-app");
// → "my-app-3a7f"

Function	Description
uniqueName(store, candidate)	Returns candidate if unique, appends suffix otherwise
uniqueFromPool(store, pools)	Random pick from pool, falls back to suffix on collision
createMemoryStore()	In-memory store for tests

---

filter.ts — Filtering

Composable pattern-based filters with negate, combine, and compound modes.

import { createCompoundFilter, negateFilter } from "synth-project-name";

const isSuspicious = createCompoundFilter({
  exclude: [/internal/i, /debug/i],
  minLength: 5,
  allowedChars: /^[a-z0-9-]+$/,
});

isSuspicious("my-app");     // → true
isSuspicious("internal-x"); // → false

const isClean = negateFilter(isSuspicious);

Function	Logic
createPatternFilter(patterns)	any pattern matches
createAllPatternFilter(patterns)	all patterns match
createCompoundFilter(opts)	include → exclude → length → chars → custom
negateFilter(filter)	Inverts result
combineFilters(...filters)	AND logic

---

validate.ts — Validation

Constraint-based validation with structured error reporting.

import { validateName, isValidName } from "synth-project-name";

isValidName("my-app", { minLength: 3, allowedChars: /^[a-z-]+$/ });
// → true

validateName("ab", { minLength: 3 });
// → { valid: false, errors: [{ rule: "minLength", message: "..." }] }

Supported constraints:

Constraint	Type	Description
minLength	number	Minimum character count
maxLength	number	Maximum character count
pattern	RegExp	Must match
allowedChars	RegExp	Every character must pass
blockPatterns	RegExp[]	Must not match any
requirePatterns	RegExp[]	Must match at least one
prefix	string	Must start with
suffix	string	Must end with
allowedCases	string[]	kebab, snake, camel, pascal, upper, lower

---

transform.ts — Transform

Case conversion, smart truncation, and prefix/suffix helpers.

import { normalizeName, truncateName, addAffix } from "synth-project-name";

normalizeName("My Cool App", { caseStyle: "camel" });
// → "myCoolApp"

truncateName("my-cool-app-name", 10, "smart");
// → "my-cool"

addAffix("core", { prefix: "my-", suffix: "-app" });
// → "my-core-app"

Case Style	Input	Output
kebab	My Cool App	my-cool-app
snake	My Cool App	my_cool_app
camel	My Cool App	myCoolApp
pascal	My Cool App	MyCoolApp
lower	My Cool App	mycoolapp
upper	My Cool App	MYCOOLAPP

---

pool.ts — Sampling

Random sampling, weighted picks, and shuffling.

import { samplePool, weightedPickPool, shuffle } from "synth-project-name";

samplePool(["a", "b", "c"], 2);
// → ["c", "a"]

weightedPickPool([
  { item: "a", weight: 10 },
  { item: "b", weight: 1 },
]);
// → "a" (91% probability)

shuffle([1, 2, 3]);
// → [2, 3, 1] (random order)

Function	Description
samplePool(pool, count)	Sample with replacement
sampleUniquePool(pool, count)	Sample without replacement
weightedPickPool(items)	Weighted single pick
weightedSamplePool(items, count)	Weighted with replacement
shuffle(arr)	Fisher-Yates shuffle
pickRandom(pool)	Single random pick

---

API Reference

All exports and type definitions are in src/index.ts. See source for full type signatures.

---

License

MIT mra1k3r0