core-decorators

core-decorators.js

Library of ES2016 (ES7) decorators inspired by languages that come with built-ins like @​override, @​deprecate, etc, similar to pre-defined Annotations in Java. Note that unlike Java annotations, decorators are functions which are applied at runtime.

Get It

A version compiled to ES5 in CJS format is published to npm as core-decorators

npm install core-decorators --save

This form could be consumed by any ES2016 (ES7) transpiler that supports decorators like babel.js with babel --optional es7.decorators,es7.objectRestSpread or babel --stage 1 or using the recent iterations of TypeScript.

*note that the compiled code is intentionally not checked into this repo

Decorators

• @autobind
• @readonly
• @override
• @deprecate
• @suppressWarnings
• @memoize

Proposed (not implemented, PRs welcome!):

• @mixin
• @instrument/profile
• @debounce
• @throttle
• @private
• @nonenumerable

Docs

@autobind

Forces invocations of this function to always have this refer to the class instance, even if the function is passed around or would otherwise lose its this context. e.g. var fn = context.method;

import { autobind } from 'core-decorators';

class Person {
  @autobind
  getPerson() {
  	return this;
  }
}

let person = new Person();
let getPerson = person.getPerson;

getPerson() === person;
// true

@readonly

Marks a property or method as not being writable.

import { readonly } from 'core-decorators';

class Hobbit {
  @readonly
  name = 'Bilbo Baggins';
}

var bilbo = new Hobbit();
bilbo.name = 'Frodo Baggins';
// Cannot assign to read only property 'name' of [object Object]

@override

Checks that the marked method indeed overrides a function with the same signature somewhere on the prototype chain.

Works with methods and getters/setters. Will ensure name, parameter count, as well as descriptor type (accessor/data). Provides a suggestion if it finds a method with a similar signature, including slight misspellings.

import { override } from 'core-decorators';

class Parent {
  kickDog(first, second) {}
}

class Child extends Parent {
  @override
  kickDog() {}
  // SyntaxError: Child#kickDog() does not properly override Parent#kickDog(first, second)
}

// or

class Child extends Parent {
  @override
  kickDogs() {}
  // SyntaxError: No descriptor matching Child#kickDogs() was found on the prototype chain.
  //
  //   Did you mean "kickDog"?
}

@deprecate (alias: @deprecated)

Calls console.warn() with a deprecation message. Provide a custom message to override the default one. You can also provide an options hash with a url, for further reading.

import { deprecate } from 'core-decorators';

class Person {
  @deprecate
  kickDog() {}

  @deprecate('We stopped animal abuse')
  kickDogHard() {}

  @deprecate('We stopped animal abuse', { url: 'http://humanesociety.org/issues/abuse_neglect/' })
  kickDogHarder() {}
}

let person = new Person();

person.kickDog();
// DEPRECATION Person#kickDog: This function will be removed in future versions.

person.kickDogHard();
// DEPRECATION Person#kickDogHard: We stopped animal abuse

person.kickDogHarder();
// DEPRECATION Person#kickDogHarder: We stopped animal abuse
//
//     See http://humanesociety.org/issues/abuse_neglect/ for more details.
//

@suppressWarnings

Suppresses any JavaScript console.warn() call while the decorated function is called. (i.e. on the stack)

Will not suppress warnings triggered in any async code within.

import { suppressWarnings } from 'core-decorators';

class Person {
  @deprecated
  kickDog() {}

  @suppressWarnings
  kickDogWithoutWarning() {
    this.kickDog();
  }
}

let person = new Person();

person.kickDogWithoutWarning();
// no warning is logged

@memoize

Initial implementation included, likely slow. WIP.

Disclaimer

Please don't kick dogs. It's not nice.