breeze-client/src/event.d.ts

Breeze data management for JavaScript clients

/** @hidden @internal */
export interface Subscription {
    unsubKey: number;
    callback: (data: any) => any;
}
/**
Class to support basic event publication and subscription semantics.
@dynamic
**/
export declare class BreezeEvent<T> {
    /** @hidden @internal */
    static __eventNameMap: {};
    /** @hidden @internal */
    static __nextUnsubKey: number;
    /** The name of this Event */
    name: string;
    /** The object doing the publication. i.e. the object to which this event is attached. */
    publisher: Object;
    /** @hidden @internal */
    _subscribers: Subscription[];
    /** @hidden @internal */
    _defaultErrorCallback: (e: Error) => any;
    /**
    Constructor for an Event
    >     salaryEvent = new BreezeEvent("salaryEvent", person);
    @param name - The name of the event.
    @param publisher - The object that will be doing the publication. i.e. the object to which this event is attached.
    @param defaultErrorCallback - Function to call when an error occurs during subscription execution.
    If omitted then subscriber notification failures will be ignored.
    **/
    constructor(name: string, publisher: Object, defaultErrorCallback?: (e: Error) => any);
    /**
    Publish data for this event.
    >      // Assume 'salaryEvent' is previously constructed Event
    >      salaryEvent.publish( { eventType: "payRaise", amount: 100 });
  
    This event can also be published asychronously
    >      salaryEvent.publish( { eventType: "payRaise", amount: 100 }, true);
  
    And we can add a handler in case the subscriber 'mishandles' the event.
    >      salaryEvent.publish( { eventType: "payRaise", amount: 100 }, true, function(error) {
    >          // do something with the 'error' object
    >      });
    @param data - Data to publish
    @param publishAsync - (default=false) Whether to publish asynchonously or not.
    @param errorCallback - Function to be called for any errors that occur during publication. If omitted,
    errors will be eaten.
    @return false if event is disabled; true otherwise.
    **/
    publish(data: T, publishAsync?: boolean, errorCallback?: (e: Error) => any): boolean;
    /**
    Publish data for this event asynchronously.
    >      // Assume 'salaryEvent' is previously constructed Event
    >      salaryEvent.publishAsync( { eventType: "payRaise", amount: 100 });
  
    And we can add a handler in case the subscriber 'mishandles' the event.
    >      salaryEvent.publishAsync( { eventType: "payRaise", amount: 100 }, function(error) {
    >          // do something with the 'error' object
    >      });
    @param data - Data to publish
    @param errorCallback - Function to be called for any errors that occur during publication. If omitted,
    errors will be eaten.
    **/
    publishAsync(data: T, errorCallback: (e: Error) => any): void;
    /**
    Subscribe to this event.
    >      // Assume 'salaryEvent' is previously constructed Event
    >      salaryEvent.subscribe(function (eventArgs) {
    >          if (eventArgs.eventType === "payRaise") {
    >              // do something
    >          }
    >      });
  
    There are several built in Breeze events, such as [[EntityAspect.propertyChanged]], [[EntityAspect.validationErrorsChanged]] as well.
    >      // Assume order is a preexisting 'order' entity
    >      order.entityAspect.propertyChanged.subscribe(function (pcEvent) {
    >          if ( pcEvent.propertyName === "OrderDate") {
    >              // do something
    >          }
    >      });
    @param callback- Function to be called whenever 'data' is published for this event.
    @param callback.data - {Object} Whatever 'data' was published.  This should be documented on the specific event.
    @return This is a key for 'unsubscription'.  It can be passed to the 'unsubscribe' method.
    **/
    subscribe(callback: (data: T) => any): number;
    /**
    Unsubscribe from this event.
    >      // Assume order is a preexisting 'order' entity
    >      let token = order.entityAspect.propertyChanged.subscribe(function (pcEvent) {
    >              // do something
    >      });
    >      // sometime later
    >      order.entityAspect.propertyChanged.unsubscribe(token);
    @param unsubKey - The value returned from the 'subscribe' method may be used to unsubscribe here.
    @return Whether unsubscription occured. This will return false if already unsubscribed or if the key simply
    cannot be found.
    **/
    unsubscribe: (unsubKey: number) => boolean;
    /** remove all subscribers */
    clear(): void;
    /** event bubbling - document later. */
    static bubbleEvent(target: any, getParentFn?: (() => any)): void;
    /**
    Enables or disables the named event for an object and all of its children.
    >      BreezeEvent.enable(“propertyChanged”, myEntityManager, false)
  
    will disable all EntityAspect.propertyChanged events within a EntityManager.
    >      BreezeEvent.enable(“propertyChanged”, myEntityManager, true)
  
    will enable all EntityAspect.propertyChanged events within a EntityManager.
    >      BreezeEvent.enable(“propertyChanged”, myEntity.entityAspect, false)
  
    will disable EntityAspect.propertyChanged events for a specific entity.
    >      BreezeEvent.enable(“propertyChanged”, myEntity.entityAspect, null)
  
    will removes any enabling / disabling at the entity aspect level so now any 'Event.enable' calls at the EntityManager level,
    made either previously or in the future, will control notification.
    >      BreezeEvent.enable(“validationErrorsChanged”, myEntityManager, function(em) {
    >          return em.customTag === “blue”;
    >      })
  
  
    will either enable or disable myEntityManager based on the current value of a ‘customTag’ property on myEntityManager.
    Note that this is dynamic, changing the customTag value will cause events to be enabled or disabled immediately.
    @param eventName - The name of the event.
    @param target - The object at which enabling or disabling will occur.  All event notifications that occur to this object or
    children of this object will be enabled or disabled.
    @param isEnabled - A boolean, a null or a function that returns either a boolean or a null.
    **/
    static enable(eventName: string, obj: Object, isEnabled: boolean | ((x: any) => boolean)): void;
    /**
    Returns whether for a specific event and a specific object and its children, notification is enabled or disabled or not set.
    >      BreezeEvent.isEnabled(“propertyChanged”, myEntityManager)
    >
    @param eventName - The name of the event.
    @param target - The object for which we want to know if notifications are enabled.
    @return A null is returned if this value has not been set.
    **/
    static isEnabled(eventName: string, obj: Object): boolean;
    /** @hidden @internal */
    static _isEnabled: (eventName: string, obj: Object) => boolean;
}