core-decorators

0.20.0 verified Fri May 01 auth: no javascript maintenance

Library of JavaScript stage-0 decorators (ES2016/ES7 proposal) inspired by Java annotations, providing commonly used decorators like @override, @deprecate, @autobind, @mixin, @readonly, @nonconfigurable, @decorate, @extendDescriptor, @time, @deprecated, @suppressWarnings. Current stable version is 0.20.0. This library targets the original stage-0 decorator proposal (not the current stage-2 spec) and is intended for use with Babel 5 or Babel 6 with babel-plugin-transform-decorators-legacy. Key differentiator: lightweight, focused on fundamental JavaScript decorators, framework-agnostic (React, Angular, etc.). TypeScript definitions are included but there are known incompatibilities with TypeScript's decorator implementation. Similar to lodash-decorators but more minimal. Release cadence is low (last release 0.20.0 in 2020).

Common errors

error Uncaught TypeError: Class constructor MyClass cannot be invoked without 'new' ↓

cause Using @autobind on a class method that is called as a callback (e.g., in React) without proper binding, or using the decorator incorrectly on a class property.

fix

Ensure @autobind is applied to a method, not a class. For React class components, use 'handleClick = () => {}' or bind in constructor.

error Uncaught TypeError: Cannot assign to read only property 'PI' of object '#<MyClass>' ↓

cause Using @readonly on a property and then trying to assign a new value in strict mode.

fix

Do not attempt to reassign a @readonly decorated property. If you need mutable state, do not use @readonly.

error Decorators are not supported in this environment (e.g., 'Decorators are not valid here' error in Babel) ↓

cause Transpiler is not configured for stage-0 decorators. Babel 6 requires babel-plugin-transform-decorators-legacy; Babel 7 needs @babel/plugin-proposal-decorators with legacy: true.

fix

Add the appropriate Babel plugin. For Babel 7: npm install @babel/plugin-proposal-decorators --save-dev and add to .babelrc: { 'plugins': [['@babel/plugin-proposal-decorators', { 'legacy': true }]] }

error TypeScript: 'experimentalDecorators' must be enabled to use decorators. ↓

cause TypeScript compiler requires the experimentalDecorators option.

fix

Set 'experimentalDecorators': true in tsconfig.json. Note: core-decorators may still have TypeScript incompatibilities.

Warnings

breaking @debounce, @throttle, @memoize, @deprecated and other utility decorators are deprecated in core-decorators and will be removed in future versions. Use lodash-decorators instead. ↓

fix Replace @debounce with lodash-decorators' @debounce, etc.

gotcha core-decorators only supports the stage-0 proposal, not the current stage-2 spec. Mixing with stage-2 decorators will cause incorrect behavior or errors. ↓

fix Ensure your transpiler is configured for stage-0 decorators (babel-plugin-transform-decorators-legacy for Babel 6, or Babel 5). For TypeScript, set experimentalDecorators: true.

gotcha TypeScript compatibility: core-decorators does NOT officially support TypeScript. There are known incompatibilities with the way TypeScript transpiles decorators (e.g., @autobind on methods may not work as expected). ↓

fix Consider using a different library (e.g., mobx-react or custom decorators) if you need TypeScript support. If you must use core-decorators, test thoroughly.

gotcha The @mixin decorator does not work with ES6 classes that extend from other classes; it only works on plain classes. ↓

fix Do not use @mixin on classes that inherit from another class. Use composition or a different pattern.

deprecated @deprecated decorator has been deprecated in core-decorators itself. It still exists but may be removed. ↓

fix Do not rely on @deprecated; implement your own deprecation warning logic.

Install

npm install core-decorators

yarn add core-decorators

pnpm add core-decorators

Imports

default

wrong

const coreDecorators = require('core-decorators')

correct

import coreDecorators from 'core-decorators'

ESM default import works. CJS require also works but prefer ESM.

autobind

wrong

import autobind from 'core-decorators/lib/autobind'

correct

import { autobind } from 'core-decorators'

Named import from the main package is recommended. Avoid deep imports.

readonly

wrong

const readonly = require('core-decorators').readonly

correct

import { readonly } from 'core-decorators'

Named import is supported. CJS require works but ESM is preferred.

override

import { override } from 'core-decorators'

No common mistake for this decorator.

Quickstart

Shows usage of common decorators: autobind, readonly, override, debounce (deprecated), memoize (deprecated). Note deprecation warnings.

import { autobind, readonly, override, debounce, memoize } from 'core-decorators';

class MyClass {
  @autobind
  onClick() {
    console.log('Clicked!');
  }

  @readonly
  PI = 3.14159;

  @override
  toString() {
    return `MyClass with PI=${this.PI}`;
  }

  @debounce(500)
  saveInput() {
    console.log('Saving...');
  }

  @memoize
  expensiveOperation(n) {
    // simulated slow function
    return n * 2;
  }
}

const instance = new MyClass();
instance.onClick();
console.log(instance.PI); // 3.14159
instance.PI = 3; // throws in strict mode
console.log(instance.toString()); // MyClass with PI=3.14159

// Note: @debounce and @memoize are deprecated in favor of lodash-decorators.