# space-slug

> Generate unique slugs, usernames, numbers and more. If you need a unique string that looks like this `hyperspace-4812` or `blue-whimsical-summer` using an intuitive api with zero dependencies.

Latest version **2.1.0** (published 2024-10-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install space-slug
pnpm add space-slug
yarn add space-slug
bun add space-slug
```

## Health

**Score 45/100 (D)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2024-10-01 |
| First published | 2023-08-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14.0.0 |
| Dependencies | 0 |
| Unpacked size | 102.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11 |
| Author | Tim Mikeladze |
| Maintainers | tmikeladze |
| Keywords | slug, random, unique, generator, random slug, slug generator, username generator |

## Links

- npm: https://www.npmjs.com/package/space-slug
- Repository: https://github.com/TimMikeladze/space-slug
- Homepage: https://github.com/TimMikeladze/space-slug#readme
- Issues: https://github.com/TimMikeladze/space-slug/issues
- npm.io page: https://npm.io/package/space-slug

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 2.1.0 (latest) — 2024-10-01
- 2.0.2 — 2024-02-17
- 2.0.1 — 2024-02-17
- 2.0.0 — 2024-02-17
- 1.1.0 — 2023-09-18
- 1.0.9 — 2023-08-11
- 1.0.8 — 2023-08-11
- 1.0.7 — 2023-08-11
- 1.0.6 — 2023-08-10
- 1.0.5 — 2023-08-10
- 1.0.4 — 2023-08-10
- 1.0.3 — 2023-08-10
- 1.0.2 — 2023-08-10
- 1.0.1 — 2023-08-10
- 1.0.0 — 2023-08-10

## 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
```

<!-- TSDOC_START -->

## :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<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](#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<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>` |



<!-- TSDOC_END -->

---
_Source: https://npm.io/package/space-slug · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._