@decorize/deprecate v1.0.0

Decorator to deprecate the class, method, accessor and property.

Install

npm install @decorize/deprecate --save

Usage

Decorate with the message:

import { deprecate } from '@decorize/deprecate';

class Example {
  @deprecate('Here can be string or string[]')
  public property;
}

new Example().property = 'anyText'; // Output deprecation message.

Decorate the property:

import { deprecate } from '@decorize/deprecate';

class Example {
  @deprecate
  public property;
}

new Example().property = 'anyText'; // Output deprecation message.

Decorate the method:

import { deprecate } from '@decorize/deprecate';

class Example {
  @deprecate
  public method(): boolean {
    return this instanceof Example;
  }
}

new Example().method.call(null); // Output deprecation message.

Decorate the accessor:

import { deprecate } from '@decorize/deprecate';

class Example {
  @deprecate
  public get property(): void {
    return;
  }
}

new Example().property; // Output deprecation message.

Decorate the class:

import { deprecate } from '@decorize/deprecate';

@deprecate
class Example {}

new Example(); // Output deprecation message.

Decorate the class with members:

import { deprecate } from '@decorize/deprecate';

@deprecate
class Example {
  public method(): boolean {
    return this instanceof Example;
  }
}

new Example().method.call(null); // Output deprecation message.

Typing

export interface DeprecateConfig {
  setter?: boolean;
  getter?: boolean;
  message?: string | string[];
}

export declare function deprecate<T extends Function>(target: T): T;
export declare function deprecate(message: string | string[]): any;
export declare function deprecate(configuration: DeprecateConfig): any;
export declare function deprecate(target: object, property: PropertyKey): void;
export declare function deprecate(target: object, property: PropertyKey, descriptor: PropertyDescriptor): any;
export declare function deprecate(...args: any[]): any;

Feature

• Support different naming conventions.\ Available in lowercase @deprecate or capital letter @Deprecate.

• Support different coding conventions.\ Applicable directly to the declaration @deprecate or as the decorator's factory @deprecate().

• Allow to configure the deprecation output.\ Configure output message as plain string or array of strings. The decorator cannot be applied to both the getter and setter of the same property, so its possible to specify explicitly the getter or setter.

• Allow to change the Global configuration and helpers.\ The package exports Global, which can be used to change the logic of creating and outputting a message.

• Polyfill free, TypeScript and ES5 compatibility.\ There is no need for any polyfill and can be fully used with TypeScript (d.ts) and ES5.

• Intelligent and backward compatible (ES5 vs ES2015+).\ Ensures correct use of the decorator and verifies whether the property can be decorated by checking the attributes of the descriptor.

• Advanced decoration and synergy with other decorators.\ Logic respects the original method and other decorators, so all the attributes of the descriptor not related to this decorator will be kept or adapted.

• Extensive source documentation and testing coverage.\ Source code is fully documented and tested for each line.

Future

The package includes an implementation of the decorator using the TypeScript syntax and will be extended in future with the new proposal from TC39.

We are actively supporting the package, so please contact us at GitHub or Gitter if you have any suggestions or questions.