Lo primero que tienes que saber es que siempre es bueno leer la documentación. Si nos damos una leída podemos encontrar la información que a continuación se abarca de una forma muy resumida (tomando lo más básico).
Decorators
Un Decorator es un tipo especial de declaración que se puede adjuntar a una declaración de clase, método, descriptor de acceso -los famosos getters-, propiedad o parámetro. Los decoradores utilizan la forma @expression
, donde la expresión debe evaluar una función que se llamará en tiempo de ejecución con información sobre la declaración decorada.
En otras palabras y poniéndolo de una forma sencilla, es una función que nos permite encapsular algo para agregar funcionalidades extra y/o cambiar su comportamiento; lo anterior dependiendo de dónde se utilce.
Decorator Factory
[...] Un Decorator Factory es una función que devuelve la expresión que será llamada por el decorador en tiempo de ejecución.
Básicamente podemos utilizarlo cuando queremos obtener un comportamiento diferente según los argumentos que le pasemos a la función. Lucen de la siguiente manera:
function decorador(value: any) {
// este es decorator factory, dependiendo de tu lógica
// estableces el tipo de decorador a retornar
return function (target: any) {
// este es el decorador
// aquí trabajas con 'target' y 'value'...
};
}
Ejemplo
Ya que tenemos un conocimiento básico sobre lo que son los decoradores y su aplicación, podemos continuar con el ejemplo, me tomé la libertad de renombrar la clase Math
por Calculator
.
class Calculator {
@log({showTime: true})
public static add(a: number, b: number) {
return a + b;
}
@log()
@validate
public static divide(a: number, @required b?: number){
return a / b!;
}
}
En el ejemplo anterior se observa el uso de los decoradores de método y parámetro.
En el caso de @log()
tenemos un decorator factory, que apoyado de la interfaz logOptions
nos permite indicar si el logueo mostrará la hora o no.
interface logOptions {
showTime?: boolean;
}
function log(options?: logOptions) {
return function log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
let method = descriptor.value;
let time = options && options!.showTime ? new Date().toTimeString().split(' ')[0] : '';
descriptor.value = function(...args: unknown[]) {
console.log(`${time ? `${time}: ` : ''}Calling ${propertyKey}(${args.join(', ')})`);
return method.apply(this, args);
}
return descriptor;
};
}
Para el caso del decorador @validate
, tenemos un decorador de método y para el decorador @required
uno de parámetro. Ambos ejemplos son tomados de la documentación original.
function required(target: Object, propertyKey: string | symbol, parameterIndex: number) {
let existingRequiredParameters: number[] = Reflect.getOwnMetadata(requiredMetadataKey, target, propertyKey) || [];
existingRequiredParameters.push(parameterIndex);
Reflect.defineMetadata( requiredMetadataKey, existingRequiredParameters, target, propertyKey);
}
function validate(target: any, propertyName: string, descriptor: PropertyDescriptor) {
let method = descriptor.value!;
descriptor.value = function () {
let requiredParameters: number[] = Reflect.getOwnMetadata(requiredMetadataKey, target, propertyName);
if (requiredParameters) {
for (let parameterIndex of requiredParameters) {
if (parameterIndex >= arguments.length || arguments[parameterIndex] === undefined) {
throw new Error('Missing required argument');
}
}
}
return method.apply(this, arguments);
};
return descriptor;
}
El decorador @validate
validará que el número de argumentos sea el mismo que los marcados como requeridos. He dejado la firma de la función divide(a: number, b?: number)
con el parámetro b
marcado como opcional pero decorado con @requiered
a propósito, para mostrar de forma simbólica lo que sucedería cuando los decoradores entren en acción. En la práctica, esto no suele ser muy común.
Resultados
Ahora veamos lo que sucede cuando hacemos uso del método .add()
.
let x = Calculator.add(2, 4);
/* Obtenemos esta salida en consola debido a que la función
del decorador @log() es justamente esa, loguear la llamada.
Console output:
03:11:01: Calling add(2, 4)
~~~~~~~~~> La hora es mostrada debido a showTime:true */
console.log(x);
/* Esta salida muestra el resultado de la operación anterior,
solo el valor y nada más.
Console output:
6 */
Ahora observemos el comportamiento del método .divide()
.
console.log(Calculator.divide(1, 2));
/* Debido a que estamos imprimiendo directamente
el resultado sin asignarlo a una varibale obtenemos la siguiente salida
Console output:
Calling divide(1, 2)
~~~~~~~~~~~~~~~~~~~~> Salida proporcionada por @log(),
se puede observar la ausencia de
la hora debido a que no pasamos ningún
objeto de opciones
0.5
~~~> Salida proporcionada por el console.log() en donde
la función Calculator.divide() es llamada. Si se
hubiera hecho una asignación, esta salida no sería
mostrada.
*/
console.log(Calculator.divide(1));
/* Por último esta llamada nos mostrará un error debido
al decorador @required en el parámetro b y al decorador
@validate que se encarga de validar los parametros marcados
con @required. Algo como lo siguiente:
Console output:
Error: Missing required argument
at Function.descriptor.value
...
*/
Conclusión
El uso de decoradores, aunque es experimental en TypeScript tiene ya muchas implementaciones en librerías y aplicaciones, debido a las utilidades que representan. Especialmente se volvieron populares con Angular 2+ y se encuentran en la fase 2 de propuestas de JavaScript, por lo que posiblemente se pueda hacer uso del beneficio que ofrecen fuera de TS muy pronto.
Hablando ya de usos en aplicaciones reales, puedes pasarte por el repositorio de class-validator
, la cual es una librería que permite hacer uso de validaciones a través de decoradores. Muy útil por ejemplo cuando trabajas con modelos, en los que para realizar ciertas operaciones (digamos en un CRUD de una API) necesitas que los datos se encuentren de una forma antes de poder hacer cualquier tipo de operación.
Otra librería con la que he trabajado y puedo mencionar que hace uso de decoradores es routing-controllers
. Básicamente nos permite crear controladores (ya sea con Express o Koa) de una forma muy sencilla y estructurada y con una sintaxis similar a Asp.NET o Java.
Y pues como mencioné en párrafos anteriores, los decoradores en Angular son de mucha utilidad pues permiten inyección de dependencias entre muchas otras cosas, aprovechando también metadata
.
Probablemente parezca difícil, pero creéme que cuando tienes la necesidad de utilizarlos, deja de ser un tema de miedo y pasa a ser uno bastante interesante. Muchas librería que hacen uso de los decoradores, tienen sus propias guías y métodos para "registrar" nuevos decoradores y que estén disponibles, agregando metadatos que son de mucha utilidad, pero en el transfondo, siguen utilizando la misma implemntación mostrada en la documentación.
Por último, te dejo el playground en donde podrás ver el ejemplo en funcionamiento. Espero que la información te sea de utilidad y te pido una disculpa de antemano si no me di a entender. Saludos!