🐌 space-slug

Get a unique string that looks like this wonderful-jabba or this hyperspace-4812.

Generate unique slugs, usernames, numbers, custom words, and more using an intuitive api with zero dependencies.

const { spaceSlug } from 'space-slug';

const slug = spaceSlug();
// Returns: joyful-illusion-30

📡 Install

npm install space-slug

yarn add space-slug

pnpm add space-slug

👋 Hello there! Follow me @linesofcode or visit linesofcode.dev for more cool projects like this one.

🚀 Getting Started

const { spaceSlug, adjective, color, digits, noun } from 'space-slug';

const slug = spaceSlug([color(), adjective(), noun(1), digits(3)], {
  separator: '_'
});
// Returns: blue_celestial_labyrinth_718

📚 Custom dictionaries and locales

const { spaceSlug, word, SpaceSlugDictionary } from 'space-slug';

const dictionary: SpaceSlugDictionary = {
  en: {
    starwars: ['jabba', 'ezra'],
  },
};

const slug = spaceSlug([word('starwars')(2), digits(2)], {
  dictionary,
  locale: 'en',
});
/// Returns: jabba-ezra-39

🗃️ Tracking used slugs

const { uniqueSpaceSlug, color, digits } from 'space-slug';

const slug = await uniqueSpaceSlug([
  color(1),
  digits(4),
], {
  usedSlugs: ['orange-3918']
});
// Returns: a slug that is not orange-3918

✅ Verifying that a slug is a unique

const { uniqueSpaceSlug } from 'space-slug';

await uniqueSpaceSlug([], {
  maxAttempts: 10, // default is 10 attempts before throwing an error
  isUnique: async (slug) => {
    // check database to see if slug is unique
    return true;
  }
});
// Returns: a slug that you have verified is unique

🦄 Making a slug unique

await uniqueSpaceSlug(['jabba'], {
  isUnique: async (slug) => {
    // a db lookup to see if slug is unique
    return false;
  },
  makeUnique: async (slug) => {
    // somehow make the slug unique
    return slug + '-hutt';
  }
});

✨ Transforming a slug

const { spaceSlug } from 'space-slug';

await spaceSlug([], {
  transform: (x) => x.toUpperCase()
});
// Returns: QUAINT-HORIZON-1293

✏️ Using hard-coded values

const { spaceSlug, color, digits } from 'space-slug';

spaceSlug([
  'jabba',
  digits(),
];
// Returns: jabba-1293

spaceSlug([
  color(),
  ['jabba', 'hutt'],
  digits(),
];
// Returns: red-jabba-hutt-3979

:toolbox: Functions

• word
• digits
• cleanString
• uniqueSpaceSlug
• spaceSlug

:gear: word

| Function | Type | | ---------- | ---------- | | word | (type: string) => (count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set<string> |

:gear: digits

| Function | Type | | ---------- | ---------- | | digits | (count?: number or undefined, noConsecutive?: boolean or undefined) => (options: SpaceSlugOptions) => string |

:gear: cleanString

| Function | Type | | ---------- | ---------- | | cleanString | (inputString: string, separator: string) => string |

:gear: uniqueSpaceSlug

| Function | Type | | ---------- | ---------- | | uniqueSpaceSlug | (spaceSlugFn: SpaceSlugInput[], options?: SpaceSlugOptions and UniqueSpaceSlugOptions) => Promise<string> |

:gear: spaceSlug

| Function | Type | | ---------- | ---------- | | spaceSlug | (spaceSlugInputs?: SpaceSlugInput[] or undefined, options?: SpaceSlugOptions) => string |

:wrench: Constants

• spaceSlugDefaultDictionary
• spaceSlugDefaultOptions
• noun
• adjective
• color
• season
• emoji
• verb
• animal
• cosmos

:gear: spaceSlugDefaultDictionary

| Constant | Type | | ---------- | ---------- | | spaceSlugDefaultDictionary | SpaceSlugDictionary |

:gear: spaceSlugDefaultOptions

| Constant | Type | | ---------- | ---------- | | spaceSlugDefaultOptions | Partial<SpaceSlugOptions> |

:gear: noun

| Constant | Type | | ---------- | ---------- | | noun | (count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set<string> |

:gear: adjective

| Constant | Type | | ---------- | ---------- | | adjective | (count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set<string> |

:gear: color

| Constant | Type | | ---------- | ---------- | | color | (count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set<string> |

:gear: season

| Constant | Type | | ---------- | ---------- | | season | (count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set<string> |

:gear: emoji

| Constant | Type | | ---------- | ---------- | | emoji | (count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set<string> |

:gear: verb

| Constant | Type | | ---------- | ---------- | | verb | (count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set<string> |

:gear: animal

| Constant | Type | | ---------- | ---------- | | animal | (count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set<string> |

:gear: cosmos

| Constant | Type | | ---------- | ---------- | | cosmos | (count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set<string> |