Surrogate

Easily create Pre and Post hooks on JavaScript objects.

Install

npm install surrogate

or

yarn add surrogate

Usage

There are a couple ways to manage Surrogate. The first is to utilize an exposed helper function, wrapSurrogate, to wrap objects and register pre and post methods through it.

import { wrapSurrogate, Surrogate, NextHandler } from 'surrogate';

const guitar: Surrogate<Guitar> = wrapSurrogate(new Guitar(), options);

guitar.getSurrogate().registerPreHook('play', ({ next }: NextHandler<Guitar>) => {
  // do things before running 'play'

  next.next();
});

Check examples for expanded samples.

SurrogateOptions

SurrogateMethods

After wrapping your instance with Surrogate new methods are available, getSurrogate, which, when called will return an instance of Surrogate Event Manager that allows management of pre and post methods and disposeSurrogate which will restore all methods, deregister hooks and remove the current instance from Surrogate management.

SurrogateEventManager

SurrogateHandler is any function that accepts a NextHandler object which can be used to control flow through pre and post hooks.

NextHandler

NextHandler is passed to all hook handlers. It can supply the unwrapped or surrogate wrapped instance to the current handler. An INext object provides functionality to skip hooks or continue to the next hook for execution.

Next Options

SurrogateHandlerOptions

When registering a hook you may provide any of the following options.

RunCondition

A RunCondition is a function that receives RunConditionParameters and returns a boolean indicating if the current handler should be executed(true) or skipped(false). All run conditions are executed synchronously and all conditions must be true for the handler to execute.

Decorators

Perhaps a more convenient way to register hooks is with decorators.

import { SurrogateDelegate } from 'surrogate';

@SurrogateDelegate()
class Guitar {}

SurrogateDelegate registers your class and will automatically wrap instances of that class with Surrogate.
It supports all options from SurrogateOptions as well as option locateWith which may be provided to assist Surrogate in locating method decorators for a particular class. Should only be necessary if multiple class decorators are utilized.

import { SurrogateDelegate } from 'surrogate';

@SurrogateDelegate({
  locateWith: Guitar,
})
@MyOtherClassDecorator()
class Guitar {}

If you wish to use Surrogate methods on your class instance you must extend SurrogateMethods interface.

import { SurrogateDelegate, SurrogateMethods } from 'surrogate';

export interface Guitar extends SurrogateMethods<Guitar> {}

@SurrogateDelegate()
export class Guitar {}

Registering hooks:

import { NextHandler, SurrogatePre, SurrogatePost, SurrogateDelegate } from 'surrogate';

@SurrogateDelegate()
class Guitar {
  @SurrogatePre(({ next }: NextHandler<Guitar>) => {
    console.log(`Tuning guitar`);

    next.next();
  })
  @SurrogatePost<Guitar>({
    handler: () => {
      console.log(`Put guitar away`);
    },
    options: {
      useNext: false,
    },
  })
  play() {
    console.log(`playing guitar`);
  }
}

SurrogateDecoratorOptions

All Surrogate[Async](Pre|Post) decorators accept SurrogateDecoratorOptions or an array of options and must decorate the intended hooked method.

NextDecoratorOptions

All Next[Async](Pre|Post) decorators accept NextDecoratorOptions or an array of options. Any method decorated with Next* will be registered as a Surrogate handler. Therefore, you must supply the target method the Next* method will run with.

@SurrogateDelegate({
  locateWith: Account,
})
@Table({
  timestamps: true,
})
class Account extends Model<Account> {
  @NextAsyncPreAndPost<Account>({
    action: ['update', 'save'],
    options: {
      useNext: false,
    },
  })
  protected async logActions({
    instance: model,
    originalArgs,
    hookType,
    action,
  }: NextHandler<Account>) {
    const keys = (model.changed() || []) as (keyof Account)[];
    const changes = keys.reduce(
      (changed, key) => ({
        ...changed,
        [key]: {
          current: model.getDataValue(key),
          previous: model.previous(key),
        },
      }),
      {},
    );

    telemetry.trackEvent({
      name: `${hookType}|${action}|Logging`,
      properties: {
        action,
        changes,
        hookType,
        model: model.toJSON(),
        arguments: originalArgs,
      },
    });
  }
}

Acknowledgements

Many thanks to Dale for transferring the npm package name.