@nestbolt/sortable: Installation

Install the Package

Install @nestbolt/sortable using your preferred package manager:

npm install @nestbolt/sortable

yarn add @nestbolt/sortable

pnpm add @nestbolt/sortable

Peer Dependencies

The following packages are required peer dependencies. In a typical NestJS project, most of these are already installed:

Package	Required Version	Purpose
`@nestjs/common`	`^10.0.0 \|\| ^11.0.0`	NestJS core decorators and utilities
`@nestjs/core`	`^10.0.0 \|\| ^11.0.0`	NestJS application core
`typeorm`	`^0.3.0`	ORM used for the underlying repositories, transactions, and subscribers
`reflect-metadata`	`^0.1.13 \|\| ^0.2.0`	Metadata reflection for the `@Sortable()` decorator

Install any missing peer dependencies:

npm install @nestjs/common @nestjs/core typeorm reflect-metadata

Database Setup

@nestbolt/sortable does not ship its own table -- it operates on an integer column you add to each sortable entity. Add a position column (or whatever you configure) typed as an integer:

@Column({ type: "int", default: 0 })
position!: number;

The package only reads and writes the configured position column (and the groupBy column when defined). It never touches created_at, updated_at, or any other columns.

Optional: UNIQUE Constraints

If you want the database to enforce gap-free / no-duplicate positioning, add a UNIQUE constraint:

@Index(["position"], { unique: true })
@Entity("tasks")
export class Task { /* ... */ }

When groupBy is configured, scope the constraint to the group column instead:

@Index(["listId", "position"], { unique: true })
@Entity("tasks")
export class Task { /* ... */ }

The moveTo() and reorder() algorithms are designed to be safe under these constraints -- they park the moving row(s) at scratch positions above the current max before settling, so a UNIQUE check never fires mid-shift.

Optional Dependencies

Event Emitter (Position-Change Lifecycle Events)

Required if you want to listen to sortable.position-changed and sortable.reordered events.

npm install @nestjs/event-emitter

Supported versions: ^2.0.0 || ^3.0.0

You also need to register the EventEmitterModule in your application:

import { EventEmitterModule } from "@nestjs/event-emitter";

@Module({
  imports: [
    EventEmitterModule.forRoot(),
    // ... other imports
  ],
})
export class AppModule {}

If @nestjs/event-emitter is not installed or EventEmitterModule is not registered, the package works normally but no events are emitted. The event emitter is resolved lazily and treated as fully optional.

Verifying the Installation

After installing, verify everything is wired correctly by importing the module in your root AppModule:

import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";
import { SortableModule } from "@nestbolt/sortable";

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: "postgres",
      // ... your database config
      autoLoadEntities: true,
      synchronize: true, // development only
    }),
    SortableModule.forRoot(),
  ],
})
export class AppModule {}

If the application starts without errors and you see SortableService initialized in the logs, the installation is complete. Continue to the Quick Start guide to reorder your first record.

Installation