import { Qified, MemoryMessageProvider } from 'qified';// Create a new Qified instance with a memory providerconst qified = new Qified({ messageProviders: new MemoryMessageProvider()});// Subscribe to a topicawait qified.subscribe('notifications', { id: 'notificationHandler', handler: async (message) => { console.log('Received:', message.data); }});// Publish a messageawait qified.publish('notifications', { id: 'msg-1', data: { text: 'Hello, World!' }});// Clean upawait qified.disconnect();
Constructor
new Qified(options?: QifiedOptions)
Options:
messageProviders?: MessageProvider | MessageProvider[] - a provider or Array of message providers to use
taskProviders?: TaskProvider[] - Array of task providers to use
Example:
import { Qified, MemoryMessageProvider } from 'qified';const qified = new Qified({ messageProviders: new MemoryMessageProvider()});
Properties
messageProviders: MessageProvider[]
Get or set the array of message providers. This property allows you to dynamically manage which message providers are active in your Qified instance.
Type:MessageProvider[]
Access: Read/Write
Description:
Getter: Returns the current array of message providers being used
Setter: Replaces all current message providers with a new array
Use Cases:
Inspect which providers are currently configured
Add or remove providers dynamically at runtime
Replace all providers with a new set
Migrate from one provider to another
Example:
import { Qified, MemoryMessageProvider } from 'qified';import { NatsMessageProvider } from '@qified/nats';import { RedisMessageProvider } from '@qified/redis';const qified = new Qified({ messageProviders: new MemoryMessageProvider()});// Get current providersconst providers = qified.messageProviders;console.log(`Currently using ${providers.length} provider(s)`);// Add another providerqified.messageProviders = [ new MemoryMessageProvider(), new NatsMessageProvider()];// Replace all providersqified.messageProviders = [ new RedisMessageProvider({ uri: 'redis://localhost:6379' })];// Access provider propertiesqified.messageProviders.forEach(provider => { console.log('Provider ID:', provider.id);});
Important Notes:
Setting this property does not automatically disconnect existing providers
You should call disconnect() on old providers before replacing them to clean up resources
All message operations (subscribe, publish, unsubscribeMessage) will execute across all message providers in this array
taskProviders: TaskProvider[]
Get or set the array of task providers. Works the same way as messageProviders — getter returns the active providers, setter replaces them.
Type:TaskProvider[]
Access: Read/Write
Example:
import { Qified, MemoryTaskProvider } from 'qified';import { RedisTaskProvider } from '@qified/redis';const qified = new Qified({ taskProviders: new MemoryTaskProvider()});// Replace with a Redis-backed task providerqified.taskProviders = [ new RedisTaskProvider({ uri: 'redis://localhost:6379' })];
All task operations (enqueue, dequeue, unsubscribeTask) execute across every task provider in this array.
Methods
subscribe
Subscribe to a topic to receive messages. If multiple message providers are configured, this will subscribe on all of them.
Parameters:
topic: string - The topic to subscribe to
handler: TopicHandler - Object containing an optional id and a handler function
Unsubscribe a message handler from a topic. If an id is provided, only that handler is unsubscribed. Otherwise, all handlers for the topic are unsubscribed.
Parameters:
topic: string - The topic to unsubscribe from
id?: string - Optional handler ID. If not provided, all handlers are unsubscribed
Example:
// Unsubscribe a specific handlerawait qified.unsubscribeMessage('user-events', 'userEventHandler');// Unsubscribe all handlers for a topicawait qified.unsubscribeMessage('user-events');
enqueue
Enqueue a task to a queue. If multiple task providers are configured, this will enqueue on all of them and return the id assigned by each provider (in provider order).
Parameters:
queue: string - The queue to enqueue to
task: EnqueueTask - The task payload. id and timestamp are assigned by the provider
Returns:Promise<string[]> - The task ids from each provider
Register a handler to process tasks from a queue. If multiple task providers are configured, this registers the handler on all of them. The handler receives the task and a TaskContext with ack(), reject(), and extend() methods.
Parameters:
queue: string - The queue to dequeue from
handler: TaskHandler - Object containing an optional id and a handler(task, context) function
Unsubscribe a task handler from a queue. If an id is provided, only that handler is unsubscribed. Otherwise, all handlers for the queue are unsubscribed.
Parameters:
queue: string - The queue to unsubscribe from
id?: string - Optional handler ID. If not provided, all handlers are unsubscribed
Example:
// Unsubscribe a specific handlerawait qified.unsubscribeTask('image-processing', 'resizer');// Unsubscribe all handlers for a queueawait qified.unsubscribeTask('image-processing');
disconnect
Disconnect from all providers and clean up resources.
Example:
await qified.disconnect();
Events
Qified extends Hookified and emits events for all major operations. You can listen to these events to add custom logging, monitoring, or error handling.
Available Events
The following events are available via the QifiedEvents enum:
QifiedEvents.publish - Emitted after a message is successfully published
QifiedEvents.subscribe - Emitted after successfully subscribing to a topic
QifiedEvents.unsubscribeMessage - Emitted after successfully unsubscribing a message handler from a topic
QifiedEvents.enqueue - Emitted after a task is successfully enqueued
QifiedEvents.dequeue - Emitted after successfully registering a task handler on a queue
QifiedEvents.unsubscribeTask - Emitted after successfully unsubscribing a task handler from a queue
QifiedEvents.disconnect - Emitted after successfully disconnecting from all providers
QifiedEvents.error - Emitted when an error occurs during any operation
QifiedEvents.info - Emitted for informational messages
QifiedEvents.warn - Emitted for warning messages
Listening to Events
Use the on() method to listen to events:
import { Qified, MemoryMessageProvider, QifiedEvents } from 'qified';const qified = new Qified({ messageProviders: new MemoryMessageProvider()});// Listen for publish eventsawait qified.on(QifiedEvents.publish, async (data) => { console.log('Message published to topic:', data.topic); console.log('Message:', data.message);});// Listen for subscribe eventsawait qified.on(QifiedEvents.subscribe, async (data) => { console.log('Subscribed to topic:', data.topic); console.log('Handler ID:', data.handler.id);});// Listen for unsubscribeMessage eventsawait qified.on(QifiedEvents.unsubscribeMessage, async (data) => { console.log('Unsubscribed from topic:', data.topic); if (data.id) { console.log('Handler ID:', data.id); }});// Listen for enqueue eventsawait qified.on(QifiedEvents.enqueue, async (data) => { console.log('Task enqueued to queue:', data.queue); console.log('Assigned ids:', data.ids);});// Listen for dequeue eventsawait qified.on(QifiedEvents.dequeue, async (data) => { console.log('Handler registered on queue:', data.queue); console.log('Handler ID:', data.handler.id);});// Listen for unsubscribeTask eventsawait qified.on(QifiedEvents.unsubscribeTask, async (data) => { console.log('Unsubscribed from queue:', data.queue); if (data.id) { console.log('Handler ID:', data.id); }});// Listen for disconnect eventsawait qified.on(QifiedEvents.disconnect, async () => { console.log('Disconnected from all providers');});// Listen for errorsawait qified.on(QifiedEvents.error, async (error) => { console.error('Error occurred:', error);});// Now perform operationsawait qified.subscribe('events', { id: 'handler1', handler: async (message) => { console.log('Received:', message.data); }});await qified.publish('events', { id: 'msg-1', data: { text: 'Hello!' }});await qified.unsubscribeMessage('events', 'handler1');await qified.disconnect();
Error Handling with Events
Events provide a centralized way to handle errors across all operations:
import { Qified, QifiedEvents } from 'qified';import { NatsMessageProvider } from '@qified/nats';const qified = new Qified({ messageProviders: new NatsMessageProvider()});// Centralized error handlerawait qified.on(QifiedEvents.error, async (error) => { console.error('Qified error:', error.message); // Send to error tracking service // Log to file // Send alert});// Errors from publish, subscribe, etc. will be caught and emittedawait qified.publish('topic', { id: '1', data: { test: true } });
Hooks
Qified provides before and after hooks for all major operations, allowing you to intercept and modify data before an operation executes, or perform actions after it completes. Hooks are powered by Hookified.
Available Hooks
The following hooks are available via the QifiedHooks enum:
Hook
Description
Context Properties
beforeSubscribe
Called before subscribing to a topic
{ topic, handler }
afterSubscribe
Called after subscribing to a topic
{ topic, handler }
beforePublish
Called before publishing a message
{ topic, message }
afterPublish
Called after publishing a message
{ topic, message }
beforeUnsubscribeMessage
Called before unsubscribing a message handler
{ topic, id }
afterUnsubscribeMessage
Called after unsubscribing a message handler
{ topic, id }
beforeEnqueue
Called before enqueueing a task
{ queue, task }
afterEnqueue
Called after enqueueing a task
{ queue, task, ids }
beforeDequeue
Called before registering a task handler
{ queue, handler }
afterDequeue
Called after registering a task handler
{ queue, handler }
beforeUnsubscribeTask
Called before unsubscribing a task handler
{ queue, id }
afterUnsubscribeTask
Called after unsubscribing a task handler
{ queue, id }
beforeDisconnect
Called before disconnecting from providers
{ messageProviderCount, taskProviderCount }
afterDisconnect
Called after disconnecting from providers
{ messageProviderCount, taskProviderCount }
Using Hooks
Use the onHook() method to register a hook handler. Hooks use the IHook object format from Hookified:
import { Qified, MemoryMessageProvider, QifiedHooks } from 'qified';const qified = new Qified({ messageProviders: new MemoryMessageProvider()});// Register a before hook using IHook objectqified.onHook({ event: QifiedHooks.beforePublish, handler: async (context) => { console.log('About to publish to:', context.topic); }});// Register an after hook with an id for later removalqified.onHook({ id: 'publish-logger', event: QifiedHooks.afterPublish, handler: async (context) => { console.log('Published message:', context.message.id); }});// Register with options to control positionqified.onHook({ event: QifiedHooks.beforePublish, handler: async (context) => { console.log('This runs first'); }}, { position: 'Top' });
Modifying Data with Before Hooks
Before hooks receive a mutable context object. Any changes you make to the context will be applied to the operation:
import { Qified, MemoryMessageProvider, QifiedHooks } from 'qified';const qified = new Qified({ messageProviders: new MemoryMessageProvider()});// Add timestamp and headers to all messagesqified.onHook({ event: QifiedHooks.beforePublish, handler: async (context) => { // Add timestamp if not present context.message.timestamp = context.message.timestamp ?? Date.now(); // Add custom headers context.message.headers = { ...context.message.headers, 'x-processed-by': 'qified', 'x-environment': process.env.NODE_ENV }; }});// Modify message dataqified.onHook({ event: QifiedHooks.beforePublish, handler: async (context) => { // Add metadata to the message data context.message.data = { ...context.message.data, _meta: { version: '1.0', source: 'api' } }; }});// Subscribe to receive messagesawait qified.subscribe('events', { id: 'handler1', handler: async (message) => { // Message will have timestamp, headers, and modified data console.log('Timestamp:', message.timestamp); console.log('Headers:', message.headers); console.log('Data:', message.data); }});// Publish a message - hooks will modify it before sendingawait qified.publish('events', { id: 'msg-1', data: { text: 'Hello!' }});
Modifying Topics with Before Hooks
You can also modify the topic in before hooks:
// Route all messages to a prefixed topicqified.onHook({ event: QifiedHooks.beforePublish, handler: async (context) => { context.topic = `production/${context.topic}`; }});// Subscribe to the prefixed topicawait qified.subscribe('production/events', { id: 'handler1', handler: async (message) => { console.log('Received:', message.data); }});// This publishes to 'production/events' due to the hookawait qified.publish('events', { id: 'msg-1', data: { text: 'Hello!' }});
Multiple Hooks
Multiple hooks for the same event execute in the order they were registered:
// First hook - runs first (default position is 'Bottom')qified.onHook({ event: QifiedHooks.beforePublish, handler: async (context) => { context.message.timestamp = Date.now(); }});// Second hook - runs second, can see changes from first hookqified.onHook({ event: QifiedHooks.beforePublish, handler: async (context) => { context.message.headers = { 'x-timestamp': String(context.message.timestamp) }; }});// Third hook - runs thirdqified.onHook({ event: QifiedHooks.beforePublish, handler: async (context) => { console.log('Final message:', context.message); }});// Use position option to insert at the topqified.onHook({ event: QifiedHooks.beforePublish, handler: async (context) => { console.log('This runs before all other hooks'); }}, { position: 'Top' });
Hooks vs Events
Both hooks and events are available, but they serve different purposes:
Feature
Hooks
Events
Timing
Before and after operations
After operations only
Data modification
Yes (before hooks)
No
Use case
Intercepting/transforming data
Logging, monitoring, side effects
// Hook - can modify the message before it's publishedqified.onHook({ event: QifiedHooks.beforePublish, handler: async (context) => { context.message.timestamp = Date.now(); }});// Event - notified after publish completes (cannot modify)qified.on(QifiedEvents.publish, async (data) => { console.log('Published:', data.message.id);});
Providers
There are multiple providers available to use:
Memory - this is built into the current qified library as MemoryMessageProvider and MemoryTaskProvider.