Introduction

@nestbolt/sluggable automatically generates URL-friendly slugs for your NestJS TypeORM entities. Decorate an entity with @Sluggable() and the package handles slug generation, uniqueness, transliteration, and update behavior through a TypeORM subscriber -- no manual work required.

Key Features

• Automatic slug generation -- slugs are generated from one or more source fields on entity insert via a TypeORM subscriber.
• Unique collision handling -- duplicate slugs are automatically resolved by appending -1, -2, etc.
• Transliteration -- non-Latin characters (Arabic, Cyrillic, accented Latin, etc.) are transliterated to ASCII before slugifying.
• Configurable update behavior -- choose whether to keep the original slug or regenerate it when source fields change.
• Entity mixin -- SluggableMixin adds getSlug(), findBySlug(), and regenerateSlug() methods directly on your entity instances.
• Per-entity options -- override separator, max length, unique behavior, and update strategy per entity via the @Sluggable() decorator.
• Event system -- react to slug generation and regeneration events via @nestjs/event-emitter (optional).
• Custom slugField -- store the slug in any column, not just slug.

Architecture

The package is built around several core components:

SluggableModule registers all providers globally. You call SluggableModule.forRoot() or SluggableModule.forRootAsync() once in your root module, and SluggableService becomes available everywhere via dependency injection.

SluggableService is the primary API surface. It provides generateSlug(), generateUniqueSlug(), findBySlug(), and regenerateSlug() methods. It also manages the global configuration options.

SluggableSubscriber is a TypeORM entity subscriber that intercepts beforeInsert and beforeUpdate events to automatically generate or regenerate slugs based on the @Sluggable() decorator metadata.

@Sluggable() decorator stores configuration metadata on your entity class -- which fields to generate from, the slug column name, uniqueness, separator, and update behavior.

SluggableMixin is an optional mixin that adds convenience methods (getSlug(), findBySlug(), regenerateSlug()) directly to your entity instances.

Basic Usage

import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";
import { Sluggable } from "@nestbolt/sluggable";

@Sluggable({ from: "title" })
@Entity("posts")
export class Post {
  @PrimaryGeneratedColumn("uuid")
  id!: string;

  @Column()
  title!: string;

  @Column({ default: "" })
  slug!: string;
}

// When you save:
const post = repo.create({ title: "Hello World" });
await repo.save(post);
console.log(post.slug); // "hello-world"

Next Steps

• Installation -- install the package and its peer dependencies.
• Quick Start -- set up the module, decorate an entity, and generate slugs in minutes.
• Configuration -- all forRoot and forRootAsync options explained.
• Decorator -- @Sluggable() options reference.
• Mixin -- add getSlug(), findBySlug(), and regenerateSlug() to your entities.
• Unique Slugs -- how collision handling works.
• Transliteration -- built-in and custom transliteration support.
• Update Behavior -- control what happens to slugs on entity update.
• Events -- listen to slug generation and regeneration events.