@twardoch/namzy 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# namzy
+
+Generates fun, human-friendly project names. Seeded by timestamp so you get
+fresh names every run — but pass `--seed` for reproducibility.
+
+## Install
+
+```sh
+npm install namzy
+# or run without installing:
+npx namzy
+```
+
+## CLI
+
+```sh
+# One word (default)
+namzy
+
+# PascalCase two-word name
+namzy --shape joined
+
+# Space-separated two words
+namzy --shape spaced
+
+# Generate 5 names
+namzy --count 5 --shape joined
+
+# Fetch words from the web (falls back to offline on failure)
+namzy --online --shape spaced
+
+# Help
+namzy --help
+```
+
+## Library
+
+```ts
+import { generate } from "namzy";
+
+// Single word (default)
+const name = await generate();
+
+// Joined PascalCase
+const joined = await generate({ shape: "joined" });
+
+// Spaced, seeded for reproducibility
+const seeded = await generate({ shape: "spaced", seed: 42 });
+
+// Online mode (falls back to offline)
+const online = await generate({ online: true, shape: "joined" });
+
+console.log(name, joined, seeded, online);
+```
+
+## Modes
+
+| Mode | Description |
+|------|-------------|
+| `--offline` | Uses bundled wordlist (default, always works) |
+| `--online` | Fetches from `random-word-api.herokuapp.com`, falls back offline |
+
+## How it works
+
+Picks words from geographic names (Tokyo, Oslo, Cairo…) and evocative English
+words (ember, flint, willow…), then applies a small phonetic mangling pass
+(e.g. `s→z`, `ph→f`, `oo→u`) for a playful feel. Results are deterministic
+for a given seed.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// this_file: src/cli.ts
+import { generate } from "./index.js";
+const HELP = `
+namzy — generate fun fused project names
+
+Usage:
+  namzy [options]
+
+Options:
+  --online        Fetch words from a public API (falls back to offline)
+  --count <N>     Number of names to generate (default: 1)
+  --help          Show this help
+
+Examples:
+  namzy
+  namzy --count 5
+  namzy --online --count 3
+`.trimStart();
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    const opts = {};
+    let count = 1;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case "--help":
+            case "-h":
+                process.stdout.write(HELP);
+                process.exit(0);
+                break;
+            case "--online":
+                opts.online = true;
+                break;
+            case "--count": {
+                const n = parseInt(args[++i], 10);
+                if (isNaN(n) || n < 1) {
+                    process.stderr.write(`--count must be a positive integer\n`);
+                    process.exit(1);
+                }
+                count = n;
+                break;
+            }
+            default:
+                process.stderr.write(`Unknown flag: ${arg}\nRun namzy --help for usage.\n`);
+                process.exit(1);
+        }
+    }
+    return { opts, count };
+}
+async function main() {
+    const { opts, count } = parseArgs(process.argv);
+    const base = Date.now();
+    for (let i = 0; i < count; i++) {
+        const name = await generate({ ...opts, seed: base + i * 1337 });
+        process.stdout.write(name + "\n");
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { mangle, mulberry32, joinClean } from "./mangle.js";
+export interface NamzyOptions {
+    online?: boolean;
+    seed?: number;
+}
+/**
+ * Generate a single fused, mangled namzy name.
+ * Two raw words → junction-cleaned fusion → consonant rotation → capitalize.
+ */
+export declare function generate(opts?: NamzyOptions): Promise<string>;
+export { mangle, joinClean, mulberry32 };
+export { GEO, COMMON } from "./wordlist.js";

package/dist/index.js

@@ -0,0 +1,48 @@
+// this_file: src/index.ts
+import { GEO, COMMON } from "./wordlist.js";
+import { mangle, mulberry32, joinClean } from "./mangle.js";
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function pick(arr, rng) {
+    return arr[Math.floor(rng() * arr.length)];
+}
+async function fetchOnlineWords() {
+    const url = `https://random-word-api.herokuapp.com/word?number=2&length=6`;
+    const resp = await fetch(url);
+    if (!resp.ok)
+        throw new Error(`HTTP ${resp.status}`);
+    const data = (await resp.json());
+    if (!Array.isArray(data) || data.length < 2)
+        throw new Error("Bad response");
+    return data.slice(0, 2).map((w) => w.toLowerCase().replace(/[^a-z]/g, ""));
+}
+/**
+ * Generate a single fused, mangled namzy name.
+ * Two raw words → junction-cleaned fusion → consonant rotation → capitalize.
+ */
+export async function generate(opts) {
+    const online = opts?.online ?? false;
+    const seed = opts?.seed ?? Date.now();
+    const rng = mulberry32(seed);
+    let w1;
+    let w2;
+    if (online) {
+        try {
+            const words = await fetchOnlineWords();
+            [w1, w2] = words;
+        }
+        catch {
+            w1 = pick(GEO, rng).toLowerCase();
+            w2 = pick(COMMON, rng).toLowerCase();
+        }
+    }
+    else {
+        w1 = pick(GEO, rng).toLowerCase();
+        w2 = pick(COMMON, rng).toLowerCase();
+    }
+    const fused = joinClean(w1, w2);
+    return capitalize(mangle(fused));
+}
+export { mangle, joinClean, mulberry32 };
+export { GEO, COMMON } from "./wordlist.js";

package/dist/mangle.d.ts

@@ -0,0 +1,10 @@
+/** Simple seeded mulberry32 RNG — returns a function that yields [0,1) floats */
+export declare function mulberry32(seed: number): () => number;
+/** Consonant rotation: c→q, f→v, k→c, q→k, s→z, z→s, v→f, w→u. Case-preserving. */
+export declare function mangle(s: string): string;
+/**
+ * Fuse two lowercase words at a clean junction.
+ * Drops the first char of `b` while it duplicates the tail of `a`,
+ * or while the seam is vowel-vowel. Max two trims.
+ */
+export declare function joinClean(a: string, b: string): string;

package/dist/mangle.js

@@ -0,0 +1,54 @@
+// this_file: src/mangle.ts
+/** Simple seeded mulberry32 RNG — returns a function that yields [0,1) floats */
+export function mulberry32(seed) {
+    let s = seed >>> 0;
+    return () => {
+        s += 0x6d2b79f5;
+        let t = Math.imul(s ^ (s >>> 15), 1 | s);
+        t ^= t + Math.imul(t ^ (t >>> 7), 61 | t);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+const ROTATION = {
+    c: "q", f: "v", k: "c", q: "k",
+    s: "z", z: "s", v: "f", w: "u",
+};
+/** Consonant rotation: c→q, f→v, k→c, q→k, s→z, z→s, v→f, w→u. Case-preserving. */
+export function mangle(s) {
+    let out = "";
+    for (const ch of s) {
+        const lower = ch.toLowerCase();
+        const repl = ROTATION[lower];
+        if (repl === undefined) {
+            out += ch;
+        }
+        else {
+            out += ch === lower ? repl : repl.toUpperCase();
+        }
+    }
+    return out;
+}
+const VOWELS = new Set(["a", "e", "i", "o", "u", "y"]);
+/**
+ * Fuse two lowercase words at a clean junction.
+ * Drops the first char of `b` while it duplicates the tail of `a`,
+ * or while the seam is vowel-vowel. Max two trims.
+ */
+export function joinClean(a, b) {
+    let head = a;
+    let tail = b;
+    for (let i = 0; i < 2 && head.length > 0 && tail.length > 0; i++) {
+        const last = head[head.length - 1].toLowerCase();
+        const first = tail[0].toLowerCase();
+        if (last === first) {
+            tail = tail.slice(1);
+        }
+        else if (VOWELS.has(last) && VOWELS.has(first)) {
+            tail = tail.slice(1);
+        }
+        else {
+            break;
+        }
+    }
+    return head + tail;
+}

package/dist/web.d.ts

@@ -0,0 +1,2 @@
+export { generate, mangle, joinClean, mulberry32, GEO, COMMON } from "./index.js";
+export type { NamzyOptions } from "./index.js";

package/dist/web.js

@@ -0,0 +1,3 @@
+// this_file: src/web.ts
+// Browser entry point — exposes namzy.generate() on window.namzy.
+export { generate, mangle, joinClean, mulberry32, GEO, COMMON } from "./index.js";

package/dist/wordlist.d.ts

@@ -0,0 +1,4 @@
+/** Geographic names (A-Za-z only, no diacritics) */
+export declare const GEO: string[];
+/** Common evocative English words */
+export declare const COMMON: string[];

package/dist/wordlist.js

@@ -0,0 +1,17 @@
+// this_file: src/wordlist.ts
+/** Geographic names (A-Za-z only, no diacritics) */
+export const GEO = [
+    "tokyo", "paris", "oslo", "berlin", "lagos", "lima", "boston", "vienna",
+    "cairo", "kyoto", "dubai", "seoul", "milan", "tunis", "perth", "genoa",
+    "porto", "bruges", "ghent", "brest", "minsk", "sofia", "riga", "lyon",
+    "basel", "natal", "recife", "darwin", "hobart", "odessa", "varna", "Split",
+    "kotor", "tiran", "skopje", "bitola", "plovdiv", "gabrovo", "varna", "ruse",
+];
+/** Common evocative English words */
+export const COMMON = [
+    "river", "stone", "ember", "frost", "harbor", "willow", "copper", "marble",
+    "anchor", "lantern", "cedar", "falcon", "coral", "dagger", "flint", "grove",
+    "haven", "iron", "jasper", "kelp", "larch", "mast", "nettle", "oak",
+    "pine", "quill", "reed", "sage", "thorn", "umber", "vale", "wren",
+    "yarrow", "zenith", "amber", "birch", "cliff", "drift", "forge", "glade",
+];

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@twardoch/namzy",
+  "version": "0.1.0",
+  "description": "Generates fun fused human-friendly project names",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "namzy": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:web": "esbuild src/web.ts --bundle --format=iife --global-name=namzy --outfile=../docs/namzy.js --target=es2020",
+    "start": "node dist/cli.js",
+    "dev": "tsx src/cli.ts"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.24.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// this_file: src/cli.ts
+
+import { generate } from "./index.js";
+import type { NamzyOptions } from "./index.js";
+
+const HELP = `
+namzy — generate fun fused project names
+
+Usage:
+  namzy [options]
+
+Options:
+  --online        Fetch words from a public API (falls back to offline)
+  --count <N>     Number of names to generate (default: 1)
+  --help          Show this help
+
+Examples:
+  namzy
+  namzy --count 5
+  namzy --online --count 3
+`.trimStart();
+
+function parseArgs(argv: string[]): { opts: NamzyOptions; count: number } {
+  const args = argv.slice(2);
+  const opts: NamzyOptions = {};
+  let count = 1;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case "--help":
+      case "-h":
+        process.stdout.write(HELP);
+        process.exit(0);
+        break;
+      case "--online":
+        opts.online = true;
+        break;
+      case "--count": {
+        const n = parseInt(args[++i], 10);
+        if (isNaN(n) || n < 1) {
+          process.stderr.write(`--count must be a positive integer\n`);
+          process.exit(1);
+        }
+        count = n;
+        break;
+      }
+      default:
+        process.stderr.write(`Unknown flag: ${arg}\nRun namzy --help for usage.\n`);
+        process.exit(1);
+    }
+  }
+  return { opts, count };
+}
+
+async function main(): Promise<void> {
+  const { opts, count } = parseArgs(process.argv);
+  const base = Date.now();
+  for (let i = 0; i < count; i++) {
+    const name = await generate({ ...opts, seed: base + i * 1337 });
+    process.stdout.write(name + "\n");
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});

package/src/index.ts

@@ -0,0 +1,58 @@
+// this_file: src/index.ts
+
+import { GEO, COMMON } from "./wordlist.js";
+import { mangle, mulberry32, joinClean } from "./mangle.js";
+
+export interface NamzyOptions {
+  online?: boolean;
+  seed?: number;
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function pick<T>(arr: T[], rng: () => number): T {
+  return arr[Math.floor(rng() * arr.length)];
+}
+
+async function fetchOnlineWords(): Promise<string[]> {
+  const url = `https://random-word-api.herokuapp.com/word?number=2&length=6`;
+  const resp = await fetch(url);
+  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+  const data = (await resp.json()) as string[];
+  if (!Array.isArray(data) || data.length < 2) throw new Error("Bad response");
+  return data.slice(0, 2).map((w) => w.toLowerCase().replace(/[^a-z]/g, ""));
+}
+
+/**
+ * Generate a single fused, mangled namzy name.
+ * Two raw words → junction-cleaned fusion → consonant rotation → capitalize.
+ */
+export async function generate(opts?: NamzyOptions): Promise<string> {
+  const online = opts?.online ?? false;
+  const seed = opts?.seed ?? Date.now();
+  const rng = mulberry32(seed);
+
+  let w1: string;
+  let w2: string;
+
+  if (online) {
+    try {
+      const words = await fetchOnlineWords();
+      [w1, w2] = words;
+    } catch {
+      w1 = pick(GEO, rng).toLowerCase();
+      w2 = pick(COMMON, rng).toLowerCase();
+    }
+  } else {
+    w1 = pick(GEO, rng).toLowerCase();
+    w2 = pick(COMMON, rng).toLowerCase();
+  }
+
+  const fused = joinClean(w1, w2);
+  return capitalize(mangle(fused));
+}
+
+export { mangle, joinClean, mulberry32 };
+export { GEO, COMMON } from "./wordlist.js";

package/src/mangle.ts

@@ -0,0 +1,56 @@
+// this_file: src/mangle.ts
+
+/** Simple seeded mulberry32 RNG — returns a function that yields [0,1) floats */
+export function mulberry32(seed: number): () => number {
+  let s = seed >>> 0;
+  return () => {
+    s += 0x6d2b79f5;
+    let t = Math.imul(s ^ (s >>> 15), 1 | s);
+    t ^= t + Math.imul(t ^ (t >>> 7), 61 | t);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const ROTATION: Record<string, string> = {
+  c: "q", f: "v", k: "c", q: "k",
+  s: "z", z: "s", v: "f", w: "u",
+};
+
+/** Consonant rotation: c→q, f→v, k→c, q→k, s→z, z→s, v→f, w→u. Case-preserving. */
+export function mangle(s: string): string {
+  let out = "";
+  for (const ch of s) {
+    const lower = ch.toLowerCase();
+    const repl = ROTATION[lower];
+    if (repl === undefined) {
+      out += ch;
+    } else {
+      out += ch === lower ? repl : repl.toUpperCase();
+    }
+  }
+  return out;
+}
+
+const VOWELS = new Set(["a", "e", "i", "o", "u", "y"]);
+
+/**
+ * Fuse two lowercase words at a clean junction.
+ * Drops the first char of `b` while it duplicates the tail of `a`,
+ * or while the seam is vowel-vowel. Max two trims.
+ */
+export function joinClean(a: string, b: string): string {
+  let head = a;
+  let tail = b;
+  for (let i = 0; i < 2 && head.length > 0 && tail.length > 0; i++) {
+    const last = head[head.length - 1].toLowerCase();
+    const first = tail[0].toLowerCase();
+    if (last === first) {
+      tail = tail.slice(1);
+    } else if (VOWELS.has(last) && VOWELS.has(first)) {
+      tail = tail.slice(1);
+    } else {
+      break;
+    }
+  }
+  return head + tail;
+}

package/src/web.ts

@@ -0,0 +1,5 @@
+// this_file: src/web.ts
+// Browser entry point — exposes namzy.generate() on window.namzy.
+
+export { generate, mangle, joinClean, mulberry32, GEO, COMMON } from "./index.js";
+export type { NamzyOptions } from "./index.js";

package/src/wordlist.ts

@@ -0,0 +1,19 @@
+// this_file: src/wordlist.ts
+
+/** Geographic names (A-Za-z only, no diacritics) */
+export const GEO: string[] = [
+  "tokyo", "paris", "oslo", "berlin", "lagos", "lima", "boston", "vienna",
+  "cairo", "kyoto", "dubai", "seoul", "milan", "tunis", "perth", "genoa",
+  "porto", "bruges", "ghent", "brest", "minsk", "sofia", "riga", "lyon",
+  "basel", "natal", "recife", "darwin", "hobart", "odessa", "varna", "Split",
+  "kotor", "tiran", "skopje", "bitola", "plovdiv", "gabrovo", "varna", "ruse",
+];
+
+/** Common evocative English words */
+export const COMMON: string[] = [
+  "river", "stone", "ember", "frost", "harbor", "willow", "copper", "marble",
+  "anchor", "lantern", "cedar", "falcon", "coral", "dagger", "flint", "grove",
+  "haven", "iron", "jasper", "kelp", "larch", "mast", "nettle", "oak",
+  "pine", "quill", "reed", "sage", "thorn", "umber", "vale", "wren",
+  "yarrow", "zenith", "amber", "birch", "cliff", "drift", "forge", "glade",
+];