monocle-decorators

Tiny library with most common/useful decorators. Think of it as
underscore.js, but with class.

Table of contents

• Decorators for classes
  • freeze
  • mixin
  • seal
• Decorators for instance methods/properties
  • bind
  • debounce
  • throttle
  • deprecate

Installation

npm install monocle-decorators --save

Decorators for classes

@_o.mixin

Extends decorated class with all enumerable properties from ArrayOfMixins
passed as argument.

💡 Tip

Prefer composability over inheritance.

As decorator @_o.mixin(ArrayOfMixins)

import _o from 'monocle-decorators'
class Walkable {
  walk() {
    const speed = 5
    this.distanceFromOrigin += speed
  }
}
class Runnable {
  run() {
    const speed = 10
    this.distanceFromOrigin += speed
  }
}
@_o.mixin([Walkable, Runnable])
class Thing {
  constructor() {
    this.distanceFromOrigin = 0
  }
}
const foo = new Thing()
foo.walk() // method from Walkable class
foo.run() // method from Runnable class
foo.distanceFromOrigin // => 15

💡 Tip

Array of mixins can also be an array of objects, if you don’t feel classy.

import _o from 'monocle-decorators'
const walkable = {
  walk() {
    const speed = 5
    this.distanceFromOrigin += speed
  }
}
const runnable = {
  run() {
    const speed = 10
    this.distanceFromOrigin += speed
  }
}
@_o.mixin([walkable, runnable])
class Thing {
  constructor() {
    this.distanceFromOrigin = 0
  }
}
const foo = new Thing()
foo.walk() // method from Walkable class
foo.run() // method from Runnable class
foo.distanceFromOrigin // => 15

As function _o.mixin(TargetClass, ArrayOfMixins)

import _o from 'monocle-decorators'
_o.mixin(Thing, [Walkable, Runnable])
const foo = new Thing()
foo.walk() // method from Walkable class
foo.run() // method from Runnable class
foo.distanceFromOrigin // => 15

@_o.freeze

Freezes every new instance of decorated class.

A frozen object prevents:

• new properties from being added to it
• existing properties from being removed
• existing properties, or their enumerability, configurability, or
  writability, from being changed

💡 Tip

@_o.seal and @_o.freeze makes it easier to work with objects, since you
have to declare beforehand all properties and methods an object has and will
have in it’s lifecycle, concentrating in one single place the definition of
the object structure.

As decorator @_o.freeze

import _o from 'monocle-decorators'
@_o.freeze
class Dummy {
  constructor() {
    this.a = 1
    this.b = 2
  }
}
const foo = new Dummy()
foo.c = 3 // throws Error

As function _o.freeze(TargetClass)

import _o from 'monocle-decorators'
const DummyFrozen = _o.freeze(Dummy)
const foo = new DummyFrozen()
foo.c = 3 // throws Error

@_o.seal

Seals every new instance of decorated class.

A sealed object prevents:

• new properties from being added to it
• marking all existing properties as non-configurable

Values of present properties can still be changed as long as they are writable.

💡 Tip

@_o.seal and @_o.freeze makes it easier to work with objects, since you
have to declare beforehand all properties and methods an object has and will
have in it’s lifecycle, concentrating in one single place the definition of
the object structure.

As decorator @_o.seal

import _o from 'monocle-decorators'
@_o.seal
class Dummy {
  constructor() {
    this.a = 1
    this.b = 2
  }
}
const foo = new Dummy()
foo.c = 3 // throws Error

As function _o.freeze(TargetClass)

import _o from 'monocle-decorators'
const DummySealed = _o.seal(Dummy)
foo.c = 3 // throws Error

Decorators for instance methods/properties

@_o.bind

Autobind the decorated method to it’s owner, so this will always refer to the
object that owns the method.

💡 Tip

This decorator avoids the verbose <button onClick={this.handleClick.bind(this)}></button> idiom,
using only <button onClick={this.handleClick}></button>.

As decorator @_o.bind

import _o from 'monocle-decorators'
class Dummy {
  @_o.bind
  handleClick() {
    // ...
  }
  render() {
    return (
      <div onClick={this.handleClick}>Lorem ipsum</div>
    )
  }
}

As function _o.bind(targetMethod, context)

import _o from 'monocle-decorators'
const obj = {
  handleClick() {
    // ...
  }
}
_o.bind(obj.handleClick, obj)
element.addEventListener('click', obj.handleClick)

@_o.debounce

Debounces decorated method, which will postpone its execution until after
wait milliseconds have elapsed since the last time it was invoked.

💡 Tip

Useful for implementing behavior that should only happen after the input has
stopped arriving. For example: rendering a preview of a Markdown comment,
recalculating a layout after the window has stopped being resized, and so on.

As decorator @_o.debounce(wait)

import _o from 'monocle-decorators'
class Dummy {
  @_o.debounce(150)
  onScroll() {
    // ...
  }
}

As function _o.debounce(targetMethod, wait)

import _o from 'monocle-decorators'
const onScroll = _o.debounce(() => {
  // ...
}, 150)

@_o.throttle

Throttles decorated method, that, when invoked repeatedly, will only actually
call the original function at most once per every wait milliseconds.

💡 Tip

Useful for rate-limiting events that occur faster than you can keep up with.

As decorator @_o.throttle(wait)

import _o from 'monocle-decorators'
class Dummy {
  @_o.throttle(150)
  onScroll() {
    // ...
  }
}

💡 Tip

To have the same behavior as a hypothetical @_o.once,
use @_o.throttle(Infinity).

As function _o.throttle(targetMethod, wait)

import _o from 'monocle-decorators'
const onScroll = _o.throttle(() => {
  // ...
}, 150)

@_o.deprecate

Calls opts.logger with msg as depreciation message.
By default opts.logger is console.warn and msg is ${target.constructor.name}.${key} is deprecated.. Both are optional.

As decorator @_o.deprecate(msg, { logger })

import _o from 'monocle-decorators'
class Dummy {
  a() {
    // ...
  }
  @_o.deprecate('`dummy.b` is deprecated. Use `dummy.a`')
  b() {
    // ...
  }
}

As function _o.deprecate(target, key, msg, { logger })

import _o from 'monocle-decorators'
const dummy = _o.deprecate({
  a() {},
  b() {}
}, 'b', '`dummy.b` is deprecated. Use `dummy.a`')

Why monocle?

Because you import it as _o and use it as @_o.
Classy decorators.

Reference

• Icon by Ben Iconator from The Noun Prokect

Sponsor

If you found this library useful and are willing to donate, consider
transferring some bitcoins to 1BqqKiZA8Tq43CdukdBEwCdDD42jxuX9UY.

caiogondim.com ·
GitHub @caiogondim ·
Twitter @caio_gondim