Decorators

BackendFrontendTooling

Experimental decorators for common patterns.

Installation#

yarn add @boost/decorators

Decorators may also be imported from @boost/common.

@Bind#

Bind(): MethodDecorator

Automatically binds a class method's this context to its current instance, even when the method is dereferenced, which is the primary use-case for this decorator. This is an alternative to manually bind()ing within the constructor, or using class properties with anonymous functions.

import { Bind } from '@boost/decorators';
class Example {
@Bind()
static test() {
return this; // Class constructor
}
@Bind()
test() {
return this; // Class instance
}
}
const example = new Example();
const { test } = example;
example.test() = test(); // true

@Debounce#

Debounce(delay: number): MethodDecorator

Delays the execution of the class method by the provided time in milliseconds. If another method call occurs within this timeframe, the execution delay will be reset.

import { Debounce } from '@boost/decorators';
class Example {
@Debounce(250)
log() {
console.log('Fired!');
}
}
const example = new Example();
example.log(); // Will not log
example.log(); // Will not log
example.log(); // Will log after 250ms

Debouncing only works on methods with no return.

@Deprecate#

Deprecate(message?: string): Decorator

Marks a class declaration, class method, class property, or method parameter as deprecated by logging a deprecation message to the console. Works for both static and instance members.

import { Deprecate } from '@boost/decorators';
@Deprecate()
class Example {
@Deprecate()
static property = 123;
@Deprecate('Can provide a custom message')
method() {}
}

@Memoize#

Memoize(options?: MemoizeHasher | MemoizeOptions): MethodDecorator

Caches the return value of a class method or getter to consistently and efficiently return the same value. By default, hashes the method's arguments to determine a cache key, but can be customized with a unique hashing function.

Memoization also works on async/promise based methods by caching the promise itself. However, if the promise is rejected, the cache will be deleted so that subsequent calls can refresh itself.

import { Memoize } from '@boost/decorators';
class Example {
@Memoize()
someExpensiveOperation() {
// Return some value
}
@Memoize({ expires: 3600 })
async fetchInBackground() {
// Return some async value with an expiration time
}
}
const example = new Example();
example.someExpensiveOperation(); // Will run and cache result
example.someExpensiveOperation(); // Will return cached result
example.someExpensiveOperation(); // Will return cached result

The memoize decorator supports the following options:

  • cache (MemoizeCache<T>) - A custom Map instance to store cached values. Can also be used to pre-cache expected values.
  • expires (number) - Time in milliseconds in which to keep the cache alive (TTL). Pass 0 to cache indefinitely. Defaults to 0.
  • hasher (MemoizeHasher) - A hashing function to determine the cache key. Is passed the method's arguments and must return a string. If not provided, arguments are hashed using JSON.stringify().

@Throttle#

Throttle(delay: number): MethodDecorator

Throttles the execution of a class method to only fire once within every delay timeframe (in milliseconds). Will always fire on the first invocation.

import { Throttle } from '@boost/decorators';
class Example {
@Throttle(100)
log() {
console.log('Fired!');
}
}
const example = new Example();
example.log(); // Will log
example.log(); // Will not log
example.log(); // Will not log
// 100ms pass
example.log(); // Will log

Throttling only works on methods with no return.