AdonisJS Notifications

A Laravel-inspired notifications provider for AdonisJS v6.

This package gives your application a notifications service that can dispatch a notification through one or more configured channels. Channels are plain classes, so you can install a community channel package or write one for your own transport.

Requirements

• Node.js 20 or newer
• AdonisJS 6.2 or newer

Installation

Install the package with your package manager.

npm install @benhepburn/adonis-notifications

pnpm add @benhepburn/adonis-notifications

yarn add @benhepburn/adonis-notifications

Then configure it inside your AdonisJS application.

node ace configure @benhepburn/adonis-notifications

The configure command publishes config/notifications.ts and registers the provider in adonisrc.ts.

Configuration

Register every channel your notifications may use in config/notifications.ts. The keys in this map are the same strings returned from a notification's via() method.

import { defineConfig } from '@benhepburn/adonis-notifications'
import { AwsSnsChannel } from '@benhepburn/adonis-notifications-aws-sns-channel'

const notificationsConfig = defineConfig({
  channels: {
    sms: AwsSnsChannel,
  },
})

export default notificationsConfig

If a notification returns a channel key that is not configured, the service throws ChannelNotBoundException.

Sending Notifications

Create a notification by extending Notification. Use via() to choose the channels for that notification, and add channel-specific methods for the channel classes to read.

import { Notification } from '@benhepburn/adonis-notifications'
import type { NotifiableMobile } from '@benhepburn/adonis-notifications/types'

type User = NotifiableMobile & {
  name: string
}

export class WelcomeSms extends Notification<User> {
  via() {
    return ['sms']
  }

  toSms(user: User) {
    return {
      to: user.notificationGetMobile(),
      message: `Welcome, ${user.name}`,
    }
  }
}

Send the notification with the notifications service.

import notifications from '@benhepburn/adonis-notifications/service'
import { WelcomeSms } from '#notifications/welcome_sms'

await notifications.sendNotification(user, new WelcomeSms())

You may pass a single notifiable object or an array of notifiable objects. The notification instance receives the recipients on its notifiable property before it is sent.

await notifications.sendNotification([userA, userB], new WelcomeSms())

If any channel rejects while sending, the service throws NotificationFailedException. The exception includes the notification instance, the settled promise results, and a stringified version of those results.

Writing a Channel

Channels extend NotificationChannel and implement send(). Optional boot() and shutdown() hooks are called when the handler starts and when the Adonis provider shuts down.

import {
  Notification,
  NotificationChannel,
} from '@benhepburn/adonis-notifications'

type SmsNotification = Notification<any> & {
  toSms(notifiable: any): {
    to: string
    message: string
  }
}

export class SmsChannel extends NotificationChannel {
  boot() {
    // Initialize a client or connection here.
  }

  async send(notification: Notification<any>) {
    const smsNotification = notification as SmsNotification

    for (const notifiable of smsNotification.notifiable ?? []) {
      const payload = smsNotification.toSms(notifiable)

      await sendSms(payload.to, payload.message)
    }
  }

  shutdown() {
    // Close connections or flush resources here.
  }
}

Register the channel class in config/notifications.ts.

import { defineConfig } from '@benhepburn/adonis-notifications'
import { SmsChannel } from '#notifications/channels/sms_channel'

export default defineConfig({
  channels: {
    sms: SmsChannel,
  },
})

Testing

Use fake mode to prevent real channel classes from sending notifications. The fake handler records sent notification instances and exposes assertion helpers.

import notifications from '@benhepburn/adonis-notifications/service'
import { WelcomeSms } from '#notifications/welcome_sms'

const fake = notifications.fake()

fake.assertNotSent(WelcomeSms)

await notifications.sendNotification(user, new WelcomeSms())

fake.assertSent(WelcomeSms, 'sms')

fake.clear('sms')
fake.assertNotSent(WelcomeSms)

notifications.restore()

Available fake assertions include:

• assertSent(NotificationClass, via?)
• assertNotSent(NotificationClass, via?)
• clear(via?)

The via argument can be a channel key, an array of channel keys, or omitted to target all configured channels.

Exports

The package exports:

• @benhepburn/adonis-notifications: configure, defineConfig, Notification, and NotificationChannel
• @benhepburn/adonis-notifications/service: default notifications service
• @benhepburn/adonis-notifications/types: shared TypeScript types
• @benhepburn/adonis-notifications/errors: package exceptions
• @benhepburn/adonis-notifications/notifications_provider: AdonisJS provider

Available Channels

• AWS SNS channel for SMS

License

MIT