This package provides a polymorphic like/favorite system for NestJS that lets users like, favorite, or bookmark any entity with user-scoped uniqueness and like counts.

Once installed, using it is as simple as:

@Entity("posts")
@Likeable()
export class Post extends LikeableMixin(BaseEntity) {
  @PrimaryGeneratedColumn("uuid") id!: string;
  @Column() title!: string;
}

// Like, unlike, toggle
await likeableService.like(Post, postId, userId);
const count = await likeableService.getLikesCount(Post, postId);

Table of Contents

• Installation
• Quick Start
• Module Configuration
  • Static Configuration (forRoot)
  • Async Configuration (forRootAsync)
• Using the @Likeable() Decorator
• Like Operations
• Query Methods
• Entity Mixin
• Events
• Using the Service Directly
• Like Entity
• Testing
• Changelog
• Contributing
• Security
• Credits
• License

Installation

Install the package via npm:

npm install @nestbolt/likeable

Or via yarn:

yarn add @nestbolt/likeable

Or via pnpm:

pnpm add @nestbolt/likeable

Peer Dependencies

This package requires the following peer dependencies, which you likely already have in a NestJS project:

@nestjs/common      ^10.0.0 || ^11.0.0
@nestjs/core        ^10.0.0 || ^11.0.0
@nestjs/typeorm     ^10.0.0 || ^11.0.0
typeorm             ^0.3.0
reflect-metadata    ^0.1.13 || ^0.2.0

Optional

npm install @nestjs/event-emitter   # For like.liked, like.unliked events

Quick Start

1. Register the module in your AppModule

import { LikeableModule } from "@nestbolt/likeable";

@Module({
  imports: [
    TypeOrmModule.forRoot({ /* ... */ }),
    LikeableModule.forRoot(),
  ],
})
export class AppModule {}

2. Mark entities as likeable

import { Likeable, LikeableMixin } from "@nestbolt/likeable";

@Entity("posts")
@Likeable()
export class Post extends LikeableMixin(BaseEntity) {
  @PrimaryGeneratedColumn("uuid") id!: string;
  @Column() title!: string;
}

3. Use the service to like entities

import { LikeableService } from "@nestbolt/likeable";

@Injectable()
export class PostService {
  constructor(private readonly likeableService: LikeableService) {}

  async likePost(postId: string, userId: string) {
    await this.likeableService.like(Post, postId, userId);
  }
}

Module Configuration

The module is registered globally — you only need to import it once.

Static Configuration (forRoot)

LikeableModule.forRoot();

Async Configuration (forRootAsync)

LikeableModule.forRootAsync({
  imports: [ConfigModule],
  inject: [ConfigService],
  useFactory: (config: ConfigService) => ({}),
});

Using the @Likeable() Decorator

The @Likeable() class decorator marks an entity for polymorphic liking:

@Likeable()                       // type defaults to class name
@Likeable({ type: "BlogPost" })   // custom type override

| Option | Type | Default | Description | | ------ | -------- | ---------- | -------------------------------------------- | | type | string | Class name | Override the entity type name in likes table |

Like Operations

// Like an entity (idempotent — won't duplicate)
await likeableService.like(Post, postId, userId);

// Unlike an entity
await likeableService.unlike(Post, postId, userId);

// Toggle — returns true if liked, false if unliked
const isNowLiked = await likeableService.toggle(Post, postId, userId);

Query Methods

// Check if a user liked an entity
const liked = await likeableService.isLikedBy(Post, postId, userId);

// Get total likes count for an entity
const count = await likeableService.getLikesCount(Post, postId);

// Get user IDs who liked an entity
const likerIds = await likeableService.getLikers(Post, postId);

// Get entity IDs liked by a user
const likedPostIds = await likeableService.getUserLikes(Post, userId);

// Get count of entities liked by a user
const userLikesCount = await likeableService.getUserLikesCount(Post, userId);

Entity Mixin

The LikeableMixin adds convenience methods directly on your entity:

@Entity("posts")
@Likeable()
export class Post extends LikeableMixin(BaseEntity) {
  // ...
}

// Usage
const post = await postRepo.findOneBy({ id });
await post.like(userId);
await post.unlike(userId);
const isNowLiked = await post.toggle(userId);
const liked = await post.isLikedBy(userId);
const count = await post.getLikesCount();
const likers = await post.getLikers();

| Method | Returns | Description | | ------------------- | ------------------ | ---------------------------- | | like(userId) | Promise<void> | Like this entity | | unlike(userId) | Promise<void> | Unlike this entity | | toggle(userId) | Promise<boolean> | Toggle like status | | isLikedBy(userId) | Promise<boolean> | Check if user liked entity | | getLikesCount() | Promise<number> | Get total likes count | | getLikers() | Promise<string[]> | Get user IDs of likers |

Events

When @nestjs/event-emitter is installed, the package emits:

| Event | Payload | When | | --------------- | ------------------------------------------- | ----------------------- | | like.liked | { likeableType, likeableId, userId } | After an entity is liked | | like.unliked | { likeableType, likeableId, userId } | After an entity is unliked |

import { LIKEABLE_EVENTS, LikedEvent } from "@nestbolt/likeable";
import { OnEvent } from "@nestjs/event-emitter";

@OnEvent(LIKEABLE_EVENTS.LIKED)
handleLiked(event: LikedEvent) {
  console.log(`${event.likeableType}#${event.likeableId} liked by ${event.userId}`);
}

Using the Service Directly

Inject LikeableService for like management and querying:

import { LikeableService } from "@nestbolt/likeable";

@Injectable()
export class PostService {
  constructor(private readonly likeableService: LikeableService) {}

  async getPostWithLikeStatus(postId: string, userId: string) {
    const post = await this.postRepo.findOneBy({ id: postId });
    const isLiked = await this.likeableService.isLikedBy(Post, postId, userId);
    const likesCount = await this.likeableService.getLikesCount(Post, postId);
    return { ...post, isLiked, likesCount };
  }
}

| Method | Returns | Description | | ----------------------------------------- | ------------------ | ----------------------------- | | like(Entity, entityId, userId) | Promise<void> | Like an entity | | unlike(Entity, entityId, userId) | Promise<void> | Unlike an entity | | toggle(Entity, entityId, userId) | Promise<boolean> | Toggle like status | | isLikedBy(Entity, entityId, userId) | Promise<boolean> | Check if user liked entity | | getLikesCount(Entity, entityId) | Promise<number> | Get total likes count | | getLikers(Entity, entityId) | Promise<string[]> | Get user IDs of likers | | getUserLikes(Entity, userId) | Promise<string[]> | Get entity IDs liked by user | | getUserLikesCount(Entity, userId) | Promise<number> | Count entities liked by user | | isLikeable(Entity) | boolean | Check for @Likeable metadata |

Like Entity

The likes table stores:

| Column | Type | Description | | --------------- | ------------ | --------------------------- | | id | UUID | Primary key | | likeable_type | varchar(255) | Entity type name | | likeable_id | varchar(36) | Entity ID | | user_id | varchar(36) | User who liked | | created_at | timestamp | When the like was created |

A unique index on (user_id, likeable_type, likeable_id) ensures one like per user per entity.

Testing

npm test

Run tests in watch mode:

npm run test:watch

Generate coverage report:

npm run test:cov

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please report them via GitHub Issues with the security label instead of using the public issue tracker.

Credits

• Inspired by Laravel's likeable packages and overtrue/laravel-like

License

The MIT License (MIT). Please see License File for more information.