In-app notifications

Once the database channel persists notifications, you render them in-app — an unread badge, a dropdown, a "mark all as read" button. NotificationsQueryService is the read side: it wraps the store with the methods you actually reach for. Mount the bundled REST controller and you have an inbox API with zero glue code.

Inject the query service

NotificationsQueryService is provided by DatabaseChannelModule (and its forFeature()), so it's injectable anywhere the module is in scope:

import { Injectable } from '@nestjs/common';
import { NotificationsQueryService } from '@dudousxd/nestjs-notifications-database';

@Injectable()
export class InboxService {
  constructor(private readonly notifications: NotificationsQueryService) {}

  async feed(user: User) {
    const items = await this.notifications.all(user);
    const badge = await this.notifications.unreadCount(user);
    return { items, badge };
  }
}

Every method that reads "whose notifications" accepts a target: either a notifiable (anything with toNotifiableRef()) or a plain { type, id } reference.

types is an optional string[] that restricts results to matching type values (the same value notificationName() persisted — a notificationType() override, @Notification({ name }), or the class name). Omit it, or pass an empty array, and every type matches — purely additive, existing calls are unaffected:

// Only the two file-export notification types for this user's feed.
await this.notifications.unread(user, { types: ['FILE_EXPORT_RUNNING', 'FILE_EXPORT_DONE'] });

Pass a ref directly when you only have an id at hand — handy in a controller where the user comes off the request:

await this.notifications.unreadCount({ type: 'User', id: req.user.id });

The REST controller

DatabaseChannelModule.forRoot() auto-mounts the inbox controller by default — you get GET/POST/DELETE /notifications out of the box, with the current notifiable resolved from req.user ({ type: 'User', id: req.user.id }, 401 when there is no req.user.id). Customize the resolver, or turn it off:

// Default: routes on, resolveRef reads req.user.
DatabaseChannelModule.forRoot();

// Custom resolver (e.g. a different id field or notifiable type):
DatabaseChannelModule.forRoot({
  controller: { resolveRef: (req) => ({ type: 'User', id: req.auth.sub }) },
});

// Authentication + a custom base path (avoids colliding with a `/notifications` page
// route under a shared global prefix):
DatabaseChannelModule.forRoot({
  controller: { path: 'notifications-inbox' },
  decorators: [UseGuards(AuthenticationGuard)],
});

// Off — mount it yourself, or expose your own endpoints:
DatabaseChannelModule.forRoot({ routes: false });

Mounting it yourself

When you pass routes: false (or want it in a specific module), createNotificationsController() builds the same @Controller('notifications'). Tell it how to resolve the current notifiable from the request, then add the returned class to a module's controllers:

import { Module } from '@nestjs/common';
import {
  DatabaseChannelModule,
  createNotificationsController,
} from '@dudousxd/nestjs-notifications-database';

const NotificationsController = createNotificationsController({
  resolveRef: (req) => ({ type: 'User', id: req.user.id }),
});

@Module({
  // `routes: false` — without it you get this controller AND the auto-mounted one.
  imports: [DatabaseChannelModule.forFeature({ routes: false })],
  controllers: [NotificationsController],
})
export class InboxModule {}

resolveRef receives the request and returns a { type, id } ref (it may be async) — wire it to whatever your auth layer puts on req.user. The controller exposes:

?type= accepts a comma-separated list of types (e.g. ?type=FILE_EXPORT_RUNNING,FILE_EXPORT_DONE); entries are trimmed and blank entries dropped. Absent, or empty after parsing, means no filter — every type matches.

Authorization

Decide who reaches the inbox with @nestjs/authentication / @nestjs/authorization: pass decorators (e.g. [UseGuards(AuthenticationGuard), Can(InboxPolicy, 'read')]) to DatabaseChannelModule.forRoot()/forFeature() or createNotificationsController(), or mount the controller yourself with routes: false. See Authorization of the mounted routes.

Ownership scoping and custom stores

The ownership check runs in the store. Every bundled adapter (in-memory, TypeORM, MikroORM, Prisma) implements it, pushing the notifiable into the WHERE clause so there's no read-then-write window.

If you wrote your own NotificationStore, implement either the scoped mutations or findById:

owner is a { notifiableType, notifiableId, tenantId? } ref; an absent tenantId matches any tenant. All three are optional, so existing stores keep compiling — but a store implementing none of them cannot verify ownership, and the library logs a warning saying so rather than failing quietly.

Calling notifications.delete(id) or markAsRead(id) without a target stays unscoped, so programmatic callers acting outside a request are unaffected.