@openfin/core 33.76.27 → 33.76.36

package/src/api/interappbus/channel/channel.js

@@ -6,6 +6,9 @@ const resultOrPayload = (func) => async (topic, payload, senderIdentity) => {
     return res === undefined ? payload : res;
 };
 class ProtectedItems {
+    /**
+     * @internal
+     */
     constructor(providerIdentity, wire) {
         this.providerIdentity = providerIdentity;
         this.wire = wire;
@@ -35,27 +38,234 @@ class ChannelBase {
             throw e;
         }
     }
+    /**
+     * Register middleware that fires before the action.
+     *
+     * @param func
+     *
+     * @example
+     *
+     * Channel Provider:
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     provider.register('provider-action', (payload, identity) => {
+     *         console.log(payload, identity);
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     provider.beforeAction((action, payload, identity) => {
+     *         //The payload can be altered here before handling the action.
+     *         payload.received = Date.now();
+     *         return payload;
+     *     });
+     *
+     * })();
+     * ```
+     *
+     * Channel Client:
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     client.register('client-action', (payload, identity) => {
+     *         console.log(payload, identity);
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     client.beforeAction((action, payload, identity) => {
+     *         //The payload can be altered here before handling the action.
+     *         payload.received = Date.now();
+     *         return payload;
+     *     });
+     *
+     *     const providerResponse = await client.dispatch('provider-action', { message: 'Hello From the client' });
+     *     console.log(providerResponse);
+     * })();
+     * ```
+     */
     beforeAction(func) {
         if (this.preAction) {
             throw new Error('Already registered beforeAction middleware');
         }
         this.preAction = resultOrPayload(func);
     }
+    /**
+     * Register an error handler. This is called before responding on any error.
+     *
+     * @param func
+     *
+     * Channel Provider:
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     provider.register('provider-action', (payload, identity) => {
+     *         console.log(payload);
+     *         throw new Error('Action error');
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     provider.onError((action, error, identity) => {
+     *         console.log('uncaught Exception in action:', action);
+     *         console.error(error);
+     *     });
+     *
+     * })();
+     * ```
+     *
+     * Channel Client:
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     client.register('client-action', (payload, identity) => {
+     *         console.log(payload);
+     *         throw new Error('Action error');
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     client.onError((action, error, identity) => {
+     *         console.log('uncaught Exception in action:', action);
+     *         console.error(error);
+     *     });
+     * })();
+     * ```
+     */
     onError(func) {
         if (this.errorMiddleware) {
             throw new Error('Already registered error middleware');
         }
         this.errorMiddleware = func;
     }
+    /**
+     * Register middleware that fires after the action.
+     *
+     * @param func
+     *
+     * @remarks If the action does not return the payload, then the afterAction will not have access to the payload object.
+     *
+     * @example
+     *
+     * Channel Provider:
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     await provider.register('provider-action', (payload, identity) => {
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     await provider.afterAction((action, payload, identity) => {
+     *         //the payload can be altered here after handling the action but before sending an acknowledgement.
+     *         payload.sent = date.now();
+     *         return payload;
+     *     });
+     *
+     * })();
+     * ```
+     *
+     * Channel Client:
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     await client.register('client-action', (payload, identity) => {
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     await client.afterAction((action, payload, identity) => {
+     *         //the payload can be altered here after handling the action but before sending an acknowledgement.
+     *         payload.sent = date.now();
+     *         return payload;
+     *     });
+     *
+     * })();
+     * ```
+     */
     afterAction(func) {
         if (this.postAction) {
             throw new Error('Already registered afterAction middleware');
         }
         this.postAction = resultOrPayload(func);
     }
+    /**
+     * Remove an action by action name.
+     *
+     * @param action
+     *
+     * @example
+     *
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     await provider.register('provider-action', (payload, identity) => {
+     *         console.log(payload);
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     await provider.remove('provider-action');
+     *
+     * })();
+     * ```
+     */
     remove(action) {
         this.subscriptions.delete(action);
     }
+    /**
+     * Registers a default action. This is used any time an action that has not been registered is invoked.
+     *
+     * @example
+     *
+     * Channel Provider:
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     await provider.setDefaultAction((action, payload, identity) => {
+     *         console.log(`Client with identity ${JSON.stringify(identity)} has attempted to dispatch unregistered action: ${action}.`);
+     *
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     * })();
+     * ```
+     *
+     * Channel Client:
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     await client.setDefaultAction((action, payload, identity) => {
+     *         console.log(`Provider with identity ${JSON.stringify(identity)} has attempted to dispatch unregistered action: ${action}.`);
+     *
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     * })();
+     * ```
+     * @param func
+     */
     setDefaultAction(func) {
         if (this.defaultAction) {
             throw new Error('default action can only be set once');
@@ -64,6 +274,53 @@ class ChannelBase {
             this.defaultAction = func;
         }
     }
+    /**
+     * Register an action to be called by dispatching from any channelClient or channelProvider.
+     *
+     * @param topic
+     * @param listener
+     *
+     * @remarks The return value will be sent back as an acknowledgement to the original caller. You can throw an
+     * error to send a negative-acknowledgement and the error will reject the promise returned to the sender by the
+     * dispatch call.  Once a listener is registered for a particular action, it stays in place receiving and responding
+     * to incoming messages until it is removed.  This messaging mechanism works exactly the same when messages are
+     * dispatched from the provider to a client.  However, the provider has an additional publish method that sends messages
+     * to all connected clients.
+     *
+     * Because multiple clients can share the same `name` and `uuid`, in order to distinguish between individual clients,
+     * the `identity` argument in a provider's registered action callback contains an `endpointId` property. When dispatching
+     * from a provider to a client, the `endpointId` property must be provided in order to send an action to a specific client.
+     *
+     * @example
+     *
+     * Channel Provider:
+     * ```js
+     * (async ()=> {
+     *     const provider = await fin.InterApplicationBus.Channel.create('channelName');
+     *
+     *     await provider.register('provider-action', (payload, identity) => {
+     *        console.log('Action dispatched by client: ', identity);
+     *        console.log('Payload sent in dispatch: ', payload);
+     *
+     *        return { echo: payload };
+     *    });
+     * })();
+     * ```
+     *
+     * Channel Client:
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     await client.register('client-action', (payload, identity) => {
+     *        console.log('Action dispatched by client: ', identity);
+     *        console.log('Payload sent in dispatch: ', payload);
+     *
+     *        return { echo: payload };
+     *    });
+     * })();
+     * ```
+     */
     register(topic, listener) {
         if (this.subscriptions.has(topic)) {
             throw new Error(`Subscription already registered for action: ${topic}. Unsubscribe before adding new subscription`);

package/src/api/interappbus/channel/channels-docs.d.ts

@@ -1,5 +1,6 @@
 declare const InterApplicationBus: any;
 /**
+ * @PORTED
  * Instance created to enable use of a channel as a provider.  Allows for communication with the {@link Channel#ChannelClient ChannelClients} by invoking an action on
  * a single client via {@link Channel#ChannelProvider#dispatch dispatch} or all clients via {@link Channel#ChannelProvider#publish publish}
  * and to listen for communication from clients by registering an action via {@link Channel#ChannelProvider#register register}.
@@ -38,26 +39,26 @@ declare class ChannelProvider {
     /**
      *
      * Destroy the channel.
-     * @returns {Promise<void>}
+     *
      * @tutorial ChannelProvider.destroy
      */
     destroy(): void;
     /**
      *
      * Dispatch an action to a specified client. Returns a promise for the result of executing that action on the client side.
-     * @param {InterApplicationBus.Channel~ClientIdentity} to - Identity of the target client.
-     * @param {string} action - Name of the action to be invoked by the client.
-     * @param {*} payload - Payload to be sent along with the action.
-     * @returns {Promise<any>}
+     * @param to - Identity of the target client.
+     * @param action - Name of the action to be invoked by the client.
+     * @param payload - Payload to be sent along with the action.
+     *
      * @tutorial Channel.dispatch
      */
     dispatch(): void;
     /**
      *
      * Register an action to be called
-     * @param {string} action - Name of the action to be registered for channel clients to later invoke.
-     * @param {Channel#ChannelProvider~Action} listener - Function representing the action to be taken on a client dispatch.
-     * @returns {boolean} - Boolean representing the successful registration of the action.
+     * @param action - Name of the action to be registered for channel clients to later invoke.
+     * @param listener - Function representing the action to be taken on a client dispatch.
+     * @returns - Boolean representing the successful registration of the action.
      * @tutorial Channel.register
      */
     register(): void;
@@ -65,9 +66,9 @@ declare class ChannelProvider {
      *
      * Publish an action and payload to every connected client.
      * Synchronously returns an array of promises for each action (see dispatch).
-     * @param {string} action
-     * @param {*} payload
-     * @returns {Array<Promise<any>>}
+     * @param action
+     * @param payload
+     *
      * @tutorial ChannelProvider.publish
      */
     publish(): void;
@@ -77,8 +78,8 @@ declare class ChannelProvider {
      * It is passed the identity of the connecting client and a payload if it was provided to {@link Channel.connect}.
      * If you wish to reject the connection, throw an error.  Be sure to synchronously provide an onConnection upon receipt of the channelProvider
      * to ensure all potential client connections are caught by the listener.
-     * @param {Channel#ChannelProvider~ConnectionListener} listener
-     * @returns {void}
+     * @param listener
+     *
      * @tutorial ChannelProvider.onConnection
      */
     onConnection(): void;
@@ -86,40 +87,40 @@ declare class ChannelProvider {
      *
      * Register a listener that is called on every new client disconnection.
      * It is passed the disconnection event of the disconnecting client.
-     * @param {InterApplicationBus.Channel~ConnectionEvent} listener
-     * @returns {void}
+     * @param listener
+     *
      * @tutorial Channel.onDisconnection
      */
     onDisconnection(): void;
     /**
      *
      * Register middleware that fires before the action.
-     * @param {Channel#ChannelProvider~Middleware} middleware - Function to be executed before invoking the action.
-     * @returns {void}
+     * @param middleware - Function to be executed before invoking the action.
+     *
      * @tutorial ChannelMiddleware.beforeAction
      */
     beforeAction(): void;
     /**
      *
      * Register an error handler. This is called before responding on any error.
-     * @param {Channel#ChannelProvider~Middleware} middleware - Function to be executed in case of an error.
-     * @returns {void}
+     * @param middleware - Function to be executed in case of an error.
+     *
      * @tutorial ChannelMiddleware.onError
      */
     onError(): void;
     /**
      *
      * Register middleware that fires after the action.  This is passed the return value of the action.
-     * @param {Channel#ChannelProvider~Middleware} middleware - Function to be executed after invoking the action.
-     * @returns {void}
+     * @param middleware - Function to be executed after invoking the action.
+     *
      * @tutorial ChannelMiddleware.afterAction
      */
     afterAction(): void;
     /**
      *
      * Remove an action by action name.
-     * @param {string} action - Name of the action to be removed.
-     * @returns {void}
+     * @param action - Name of the action to be removed.
+     *
      * @tutorial Channel.remove
      */
     remove(): void;
@@ -127,18 +128,19 @@ declare class ChannelProvider {
      *
      * Sets a default action. This is used any time an action that has not been registered is invoked.
      * Default behavior if not set is to throw an error.
-     * @param {Channel#ChannelProvider~Middleware} middleware - Function to be executed when a client invokes an action name that has not been registered.
-     * @returns {void}
+     * @param middleware - Function to be executed when a client invokes an action name that has not been registered.
+     *
      * @tutorial ChannelMiddleware.setDefaultAction
      */
     setDefaultAction(): void;
     /** Returns an array with info on every Client connected to the Provider
-     * @returns { Promise<Array<ClientInfo>> }
+     *
      * @tutorial Channel.getAllClientInfo
      */
     getAllClientInfo(): void;
 }
 /**
+ * @PORTED
  * Instance created to enable use of a channel as a client.  Allows for communication with the
  * {@link Channel#ChannelProvider ChannelProvider} by invoking an action on the
  * provider via {@link Channel#ChannelClient#dispatch dispatch} and to listen for communication
@@ -174,32 +176,32 @@ declare class ChannelClient {
      *
      * Disconnect from the channel.
      * @tutorial Channel.disconnect
-     * @returns {Promise<void>}
+     *
      */
     disconnect(): void;
     /**
      *
      * Dispatch the given action to the channel provider.  Returns a promise that resolves with the response from the provider for that action.
-     * @param {string} action - Name of the action to be invoked by the channel provider.
-     * @param {*} payload - Payload to be sent along with the action.
+     * @param action - Name of the action to be invoked by the channel provider.
+     * @param payload - Payload to be sent along with the action.
      * @tutorial Channel.dispatch
-     * @returns {Promise<any>}
+     *
      */
     dispatch(): void;
     /**
      *
      * Register an action to be called by the provider of the channel.
-     * @param {string} action - Name of the action to be registered for the channel provider to later invoke.
-     * @param {Channel#ChannelClient~Action} listener - Function representing the action to be taken on a provider dispatch.
-     * @returns {boolean}
+     * @param action - Name of the action to be registered for the channel provider to later invoke.
+     * @param listener - Function representing the action to be taken on a provider dispatch.
+     *
      * @tutorial Channel.register
      */
     register(): void;
     /**
      *
      * Register middleware that fires before the action.
-     * @param {Channel#ChannelClient~Middleware} middleware - Function to be executed before invoking the action.
-     * @returns {void}
+     * @param middleware - Function to be executed before invoking the action.
+     *
      * @tutorial ChannelMiddleware.beforeAction
      */
     beforeAction(): void;
@@ -207,31 +209,31 @@ declare class ChannelClient {
      *
      * Register a listener that is called on channel disconnection.
      * It is passed the disconnection event of the disconnecting channel.
-     * @param {InterApplicationBus.Channel~ConnectionEvent} listener
-     * @returns {void}
+     * @param listener
+     *
      * @tutorial Channel.onDisconnection
      */
     onDisconnection(): void;
     /**
      * Register an error handler. This is called before responding on any error.
-     * @param {Channel#ChannelClient~Middleware} middleware - Function to be executed in case of an error.
-     * @returns {void}
+     * @param middleware - Function to be executed in case of an error.
+     *
      * @tutorial ChannelMiddleware.onError
      */
     onError(): void;
     /**
      *
      * Register middleware that fires after the action.  This is passed the return value of the action.
-     * @param {Channel#ChannelClient~Middleware} middleware - Function to be executed after invoking the action.
-     * @returns {void}
+     * @param middleware - Function to be executed after invoking the action.
+     *
      * @tutorial ChannelMiddleware.afterAction
      */
     afterAction(): void;
     /**
      *
      * Remove an action by action name.
-     * @param {string} action - Name of the action to be removed.
-     * @returns {void}
+     * @param action - Name of the action to be removed.
+     *
      * @tutorial Channel.remove
      */
     remove(): void;
@@ -239,8 +241,8 @@ declare class ChannelClient {
      *
      * Sets a default action. This is used any time an action that has not been registered is invoked.
      * Default behavior if not set is to throw an error.
-     * @param {Channel#ChannelClient~Middleware} middleware - Function to be executed when a client invokes an action name that has not been registered.
-     * @returns {void}
+     * @param middleware - Function to be executed when a client invokes an action name that has not been registered.
+     *
      * @tutorial ChannelMiddleware.setDefaultAction
      */
     setDefaultAction(): void;
@@ -248,34 +250,34 @@ declare class ChannelClient {
 /**
  * Channel action callback signature
  * @callback Channel#ChannelProvider~Action
- * @param {any} payload - Payload sent along with the message.
- * @param {InterApplicationBus.Channel~ClientIdentity} identity - Identity of the sender.
+ * @param payload - Payload sent along with the message.
+ * @param identity - Identity of the sender.
  */
 /**
  * Channel action callback signature
  * @callback Channel#ChannelClient~Action
- * @param {any} payload - Payload sent along with the message.
- * @param {Identity} identity - Identity of the sender.
+ * @param payload - Payload sent along with the message.
+ * @param identity - Identity of the sender.
  */
 /**
  * Middleware function signature
  * @callback Channel#ChannelProvider~Middleware
- * @param {string} action - Action to be invoked.
- * @param {any} payload - Payload sent along with the message (or error for error middleware).
- * @param {Identity} identity - Identity of the sender.
+ * @param action - Action to be invoked.
+ * @param payload - Payload sent along with the message (or error for error middleware).
+ * @param identity - Identity of the sender.
  */
 /**
  * Middleware function signature
  * @callback Channel#ChannelClient~Middleware
- * @param {string} action - Action to be invoked.
- * @param {any} payload - Payload sent along with the message (or error for error middleware).
- * @param {Identity} identity - Identity of the sender.
+ * @param action - Action to be invoked.
+ * @param payload - Payload sent along with the message (or error for error middleware).
+ * @param identity - Identity of the sender.
  */
 /**
  * Callback for the channel onConnection or onDisconnection. If it errors connection will be rejected.
  * @callback Channel#ChannelProvider~ConnectionListener
- * @param {InterApplicationBus.Channel~ClientIdentity} identity - Identity of the client attempting to connect to the channel.
- * @param {any} payload - Payload sent with connection request.
+ * @param identity - Identity of the client attempting to connect to the channel.
+ * @param payload - Payload sent with connection request.
  */
 /**
  * @REMOVED