Merge 273ce78 into 36303b3

types/observer-mixin.d.ts

@@ -4,8 +4,22 @@
 // License text available at https://opensource.org/licenses/MIT
 
 import {Callback, PromiseOrVoid} from './common';
+import {PersistedModel, PersistedModelClass} from './persisted-model';
 
-export type Listener = (ctx: object, next: (err?: any) => void) => void;
+export interface OperationHookContext<T extends typeof PersistedModel> {
+  /**
+   * The constructor of the model that triggered the operation.
+   */
+  Model: T;
+
+  /**
+   * Additional context properties, not typed yet.
+   * See https://loopback.io/doc/en/lb3/Operation-hooks.html#hooks
+   */
+  [property: string]: any;
+}
+
+export type Listener<Ctx> = (ctx: Ctx, next: (err?: any) => void) => void;
 
 export interface ObserverMixin {
   /**
@@ -36,7 +50,7 @@ export interface ObserverMixin {
    * `this` set to the model constructor, e.g. `User`.
    * @end
    */
-  observe(operation: string, listener: Listener): void;
+  observe(operation: string, listener: Listener<OperationHookContext<PersistedModelClass>>): void;
 
   /**
    * Unregister an asynchronous observer for the given operation (event).
@@ -54,7 +68,7 @@ export interface ObserverMixin {
    * @callback {function} listener The listener function.
    * @end
    */
-  removeObserver(operation: string, listener: Listener): Listener | undefined;
+  removeObserver(operation: string, listener: Listener<OperationHookContext<PersistedModelClass>>): Listener<OperationHookContext<PersistedModelClass>> | undefined;
 
   /**
    * Unregister all asynchronous observers for the given operation (event).

types/persisted-model.d.ts

@@ -5,6 +5,7 @@
 
 import {Callback, Options, PromiseOrVoid} from './common';
 import {ModelBase, ModelData} from './model';
+import {Listener, OperationHookContext} from './observer-mixin';
 import {Filter, Where} from './query';
 
 /**
@@ -519,6 +520,67 @@ export declare class PersistedModel extends ModelBase {
    * @returns {String} The `id` property name
    */
   static getIdName(): string;
+
+  /**
+  * Register an asynchronous observer for the given operation (event).
+  *
+  * Example:
+  *
+  * Registers a `before save` observer for a given model.
+  *
+  * ```js
+  * MyModel.observe('before save', function filterProperties(ctx, next) {
+  if (ctx.options && ctx.options.skipPropertyFilter) return next();
+  if (ctx.instance) {
+    FILTERED_PROPERTIES.forEach(function(p) {
+      ctx.instance.unsetAttribute(p);
+    });
+  } else {
+    FILTERED_PROPERTIES.forEach(function(p) {
+      delete ctx.data[p];
+    });
+  }
+  next();
+  });
+  * ```
+  *
+  * @param {String} operation The operation name.
+  * @callback {function} listener The listener function. It will be invoked with
+  * `this` set to the model constructor, e.g. `User`.
+  */
+  static observe(operation: string, handler: Listener<OperationHookContext<PersistedModelClass>>): void;
+
+  /**
+  * Unregister an asynchronous observer for the given operation (event).
+  *
+  * Example:
+  *
+  * ```js
+  * MyModel.removeObserver('before save', function removedObserver(ctx, next) {
+    // some logic user want to apply to the removed observer...
+    next();
+  });
+  * ```
+  *
+  * @param {String} operation The operation name.
+  * @callback {function} listener The listener function.
+  */
+  static removeObserver(operation: string, handler: Listener<OperationHookContext<PersistedModelClass>>): void;
+
+  /**
+  * Unregister all asynchronous observers for the given operation (event).
+  *
+  * Example:
+  *
+  * Remove all observers connected to the `before save` operation.
+  *
+  * ```js
+  * MyModel.clearObservers('before save');
+  * ```
+  *
+  * @param {String} operation The operation name.
+  */
+  static clearObservers(operation: string): void;
 }
 
 export type PersistedModelClass = typeof PersistedModel;