als-hooks-manager v0.5.0

ALS Hooks Manager

als-hooks-manager is a powerful event management library, enabling you to add pre- and post-event hooks to your JavaScript functions. It's built on an EventEmitter pattern and supports asynchronous operations through promises.

Installation

To install als-hooks-manager, use npm:

npm install als-hooks-manager

Usage

How it works

By creating new instance, you creating event emitter. Unlike regular event emitter, there are two types of events ^pre events which runs before the main function and post events which runs after. Another difference, is on emit method, which gets the main function to run after pre events and before post events. emit method return promise and the whole process is running as chain, by calling next to call next function, or resolve/reject to resolve or reject the promise. The last next resolves the promise.

In addition, you can set timeout for promise and collect all errors to array.

Creating a HookManager Instance

const HookManager = require("als-hooks-manager");
const timeout = 1000; // timeout for promise
const hookManager = new HookManager(timeout);

Registering Hooks

Register a 'before' hook using the prefix ^ with your event name:

const preHook = async (args, {next}, result) => {
  // Your before-hook logic here
  next();
}
hookManager.on("^eventName", preHook);

Register an 'after' hook by simply using the event name:

const postHook = async (args, context, result) => {
  const { next, resolve, reject, errors } = context
  // Your after-hook logic here
  next();
}
hookManager.on("eventName",postHook);

Emitting Events

To emit an event, use the emit method with the event name and the main function. The main function should be an async function:

const mainFn = async (args,context,result) => {
  // Your main function logic
  context.resolve(result); // Use resolve to return a result
  return result // or just return the result
}
const args = []; // The arguments for all hooks and main function
const errors = []; // The array for collecting errors
const timeout = 1000; // timeout for resolving promise (throws timeout error if promise not resolved before this time)
hookManager.emit("eventName", mainFn,args,errors=[],timeout);

Each function in the event cycle (including the main function and hooks) receives a context object. This object includes methods such as next, resolve, and reject.

If the returned result from any function in the cycle is defined and next has not been explicitly called, the system will automatically call next(result). This feature simplifies scenarios where the result is immediately ready and there's no need for additional processing before moving to the next hook.

The result parameter is the argument in next function.

Handling Results and Errors

The emit method returns a promise, allowing you to handle results and errors:

hookManager
  .emit("eventName", async (context) => {
    context.resolve();
  })
  .then((result) => {
    // Handle result
  })
  .catch((error) => {
    // Handle error
  });

API Reference

constructor(timeout)

• timeout (Number): Optional. Global timeout for all hooks in milliseconds.

on(eventName, listener)

• eventName (String): Name of the event. Use ^eventName for 'before' hooks.
• listener (Function): The function to be executed when the event is emitted.

emit(eventName, func,args,errors=[],timeout = this.timeout)

• eventName (String): Name of the event to emit.
• func (Function): The main function to be executed in the event cycle.
• args (Any): The arguments for all hooks
• errors (Array): array for collecting errors
• timeout (Number): number of milisaconds to reject promise if not resolved before this time.
  • default value this.timeout - argument in constructor

once(eventName, listener)

• eventName (String): Name of the event. The listener will be removed after its first invocation.

removeListener(listener)

• listener (Function): The listener function to remove.

Context Object

Each hook function receives a context object with the following methods:

• next(result): Proceeds to the next hook or resolves the main function.
• resolve(result): Resolves the main promise with a result.
• reject(error): Rejects the main promise with an error.
• errors: The errors array for collecting errors

Example

const hookManager = new HookManager();

// Register a before hook
hookManager.on("^myEvent", async (args,context) => {
  console.log("Before main function");
  context.next();
});

// Register an after hook
hookManager.on("myEvent", async (args,context) => {
  console.log("After main function");
  context.next();
});

// Emit event
hookManager
  .emit("myEvent", async (args,context) => {
    console.log("Main function");
    context.resolve("Success");
    context.next();
  })
  .then((result) => {
    console.log(result); // Output: 'Success'
  })
  .catch((error) => {
    console.error(error);
  });