https://github.com/timmikeladze/space-slug
🐌 Generate unique slugs like `wonderful-jabba` or `hyperspace-4812` using a customizable api with zero dependencies.
https://github.com/timmikeladze/space-slug
random random-slug random-word random-word-generator random-words slug slug-generator slugifier slugify slugs to-slug unique-slug unique-slug-generator unique-words username-generator
Last synced: 9 days ago
JSON representation
🐌 Generate unique slugs like `wonderful-jabba` or `hyperspace-4812` using a customizable api with zero dependencies.
- Host: GitHub
- URL: https://github.com/timmikeladze/space-slug
- Owner: TimMikeladze
- License: mit
- Created: 2023-08-10T09:25:50.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-04-07T22:33:24.000Z (15 days ago)
- Last Synced: 2025-04-08T09:12:30.727Z (15 days ago)
- Topics: random, random-slug, random-word, random-word-generator, random-words, slug, slug-generator, slugifier, slugify, slugs, to-slug, unique-slug, unique-slug-generator, unique-words, username-generator
- Language: TypeScript
- Homepage:
- Size: 485 KB
- Stars: 9
- Watchers: 3
- Forks: 1
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# 🐌 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.
```tsx
const { spaceSlug } from 'space-slug';
const slug = spaceSlug();
// Returns: joyful-illusion-30
```
## 📡 Install
```console
npm install space-slug
yarn add space-slug
pnpm add space-slug
```
> 👋 Hello there! Follow me [@linesofcode](https://twitter.com/linesofcode) or visit [linesofcode.dev](https://linesofcode.dev) for more cool projects like this one.
## 🚀 Getting Started
```ts
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
```ts
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
```ts
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
```ts
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
```ts
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
```tsx
const { spaceSlug } from 'space-slug';
await spaceSlug([], {
transform: (x) => x.toUpperCase()
});
// Returns: QUAINT-HORIZON-1293
```
## ✏️ Using hard-coded values
```tsx
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](#gear-word)
- [digits](#gear-digits)
- [cleanString](#gear-cleanstring)
- [uniqueSpaceSlug](#gear-uniquespaceslug)
- [spaceSlug](#gear-spaceslug)
### :gear: word
| Function | Type |
| ---------- | ---------- |
| `word` | `(type: string) => (count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set` |
### :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` |
### :gear: spaceSlug
| Function | Type |
| ---------- | ---------- |
| `spaceSlug` | `(spaceSlugInputs?: SpaceSlugInput[] or undefined, options?: SpaceSlugOptions) => string` |
## :wrench: Constants
- [spaceSlugDefaultDictionary](#gear-spaceslugdefaultdictionary)
- [spaceSlugDefaultOptions](#gear-spaceslugdefaultoptions)
- [noun](#gear-noun)
- [adjective](#gear-adjective)
- [color](#gear-color)
- [season](#gear-season)
- [emoji](#gear-emoji)
- [verb](#gear-verb)
- [animal](#gear-animal)
- [cosmos](#gear-cosmos)
### :gear: spaceSlugDefaultDictionary
| Constant | Type |
| ---------- | ---------- |
| `spaceSlugDefaultDictionary` | `SpaceSlugDictionary` |
### :gear: spaceSlugDefaultOptions
| Constant | Type |
| ---------- | ---------- |
| `spaceSlugDefaultOptions` | `Partial` |
### :gear: noun
| Constant | Type |
| ---------- | ---------- |
| `noun` | `(count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set` |
### :gear: adjective
| Constant | Type |
| ---------- | ---------- |
| `adjective` | `(count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set` |
### :gear: color
| Constant | Type |
| ---------- | ---------- |
| `color` | `(count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set` |
### :gear: season
| Constant | Type |
| ---------- | ---------- |
| `season` | `(count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set` |
### :gear: emoji
| Constant | Type |
| ---------- | ---------- |
| `emoji` | `(count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set` |
### :gear: verb
| Constant | Type |
| ---------- | ---------- |
| `verb` | `(count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set` |
### :gear: animal
| Constant | Type |
| ---------- | ---------- |
| `animal` | `(count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set` |
### :gear: cosmos
| Constant | Type |
| ---------- | ---------- |
| `cosmos` | `(count?: number or undefined, _words?: string[] or undefined) => (options: SpaceSlugOptions) => Set` |