@openfin/core 33.76.27 → 33.76.36

package/src/api/interappbus/channel/channels-docs.js

@@ -6,7 +6,8 @@
  */
 const InterApplicationBus = {};
 /**
- * @namespace
+ * @PORTED
+ *
  * @desc The Channel namespace allows an OpenFin application to create a channel as a {@link Channel#ChannelProvider ChannelProvider},
  * or connect to a channel as a {@link Channel#ChannelClient ChannelClient}. The "handshake" between the communication partners is
  * simplified when using a channel.  A request to connect to a channel as a client will return a promise that resolves if/when the channel has been created. Both the
@@ -24,9 +25,9 @@ InterApplicationBus.Channel = function () { };
  *
  * Create a new channel.  Returns a promise that resolves with a {@link Channel#ChannelProvider ChannelProvider} instance for your channel.
  * You must provide a unique channelName.  If a channelName is not provided, or it is not unique, the creation will fail. EXPERIMENTAL: pass { protocols: ['rtc'] } as options to opt-in to High Throughput Channels.
- * @param {string} channelName - Name of the channel to be created.
- * @param {InterApplicationBus.Channel~ChannelCreateOptions} options - Creation options.
- * @returns {Promise<Channel#ChannelProvider>} Returns promise that resolves with an instance of {@link Channel#ChannelProvider ChannelProvider}.
+ * @param channelName - Name of the channel to be created.
+ * @param options - Creation options.
+ *
  * @tutorial Channel.create
  */
 InterApplicationBus.Channel.create = function () { };
@@ -34,9 +35,9 @@ InterApplicationBus.Channel.create = function () { };
  *
  * Connect to a channel.  Returns a promise for a {@link Channel#ChannelClient ChannelClient} instance for that channel.
  * If you wish to send a payload to the provider, add a payload property to the options argument. EXPERIMENTAL: pass { protocols: ['rtc'] } as options to opt-in to High Throughput Channels.
- * @param {string} channelName - Name of the target channel.
- * @param {InterApplicationBus.Channel~ChannelConnectOptions} options - Connection options.
- * @returns {Promise<Channel#ChannelClient>} Returns promise that resolves with an instance of {@link Channel#ChannelClient ChannelClient}.
+ * @param channelName - Name of the target channel.
+ * @param options - Connection options.
+ *
  * @tutorial Channel.connect
  *
  */
@@ -44,20 +45,21 @@ InterApplicationBus.Channel.connect = function (options) { };
 /**
  *
  * Listens for channel connections.
- * @param {InterApplicationBus.Channel~ConnectionEvent} listener - callback to execute.
- * @returns {Promise<void>}
+ * @param listener - callback to execute.
+ *
  * @tutorial Channel.onChannelConnect
  */
 InterApplicationBus.Channel.onChannelConnect = function () { };
 /**
  *
  * Listen for channel disconnections.
- * @param {InterApplicationBus.Channel~ConnectionEvent} listener - callback to execute.
- * @returns {Promise<void>}
+ * @param listener - callback to execute.
+ *
  * @tutorial Channel.onChannelDisconnect
  */
 InterApplicationBus.Channel.onChannelDisconnect = function () { };
 /**
+ * @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}.
@@ -96,26 +98,26 @@ class ChannelProvider {
     /**
      *
      * Destroy the channel.
-     * @returns {Promise<void>}
+     *
      * @tutorial ChannelProvider.destroy
      */
     destroy() { }
     /**
      *
      * 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() { }
     /**
      *
      * 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() { }
@@ -123,9 +125,9 @@ 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() { }
@@ -135,8 +137,8 @@ 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() { }
@@ -144,40 +146,40 @@ 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() { }
     /**
      *
      * 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() { }
     /**
      *
      * 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() { }
     /**
      *
      * 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() { }
     /**
      *
      * 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() { }
@@ -185,18 +187,19 @@ 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() { }
     /** Returns an array with info on every Client connected to the Provider
-     * @returns { Promise<Array<ClientInfo>> }
+     *
      * @tutorial Channel.getAllClientInfo
      */
     getAllClientInfo() { }
 }
 /**
+ * @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
@@ -232,32 +235,32 @@ class ChannelClient {
      *
      * Disconnect from the channel.
      * @tutorial Channel.disconnect
-     * @returns {Promise<void>}
+     *
      */
     disconnect() { }
     /**
      *
      * 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() { }
     /**
      *
      * 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() { }
     /**
      *
      * 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() { }
@@ -265,31 +268,31 @@ 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() { }
     /**
      * 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() { }
     /**
      *
      * 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() { }
     /**
      *
      * 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() { }
@@ -297,8 +300,8 @@ 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() { }
@@ -306,34 +309,34 @@ 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

package/src/api/interappbus/channel/client.d.ts

@@ -7,17 +7,110 @@ type DisconnectionListener = (providerIdentity: ProviderIdentity) => any;
 export type RoutingInfo = ProviderIdentity & {
     endpointId: string;
 };
+/**
+ * Instance created to enable use of a channel as a client.  Allows for communication with the
+ * {@link ChannelProvider ChannelProvider} by invoking an action on the
+ * provider via {@link ChannelClient#dispatch dispatch} and to listen for communication
+ * from the provider by registering an action via {@link ChannelClient#register register}.
+ *
+ * Synchronous Methods:
+ *  * {@link ChannelClient#onDisconnection onDisconnection(listener)}
+ *  * {@link ChannelClient#register register(action, listener)}
+ *  * {@link ChannelClient#remove remove(action)}
+ *
+ * Asynchronous Methods:
+ *  * {@link ChannelClient#disconnect disconnect()}
+ *  * {@link ChannelClient#dispatch dispatch(action, payload)}
+ *
+ * Middleware:
+ * <br>Middleware functions receive the following arguments: (action, payload, senderId).
+ * The return value of the middleware function will be passed on as the payload from beforeAction, to the action listener, to afterAction
+ * unless it is undefined, in which case the original payload is used.  Middleware can be used for side effects.
+ *  * {@link ChannelClient#setDefaultAction setDefaultAction(middleware)}
+ *  * {@link ChannelClient#onError onError(middleware)}
+ *  * {@link ChannelClient#beforeAction beforeAction(middleware)}
+ *  * {@link ChannelClient#afterAction afterAction(middleware)}
+ */
 export default class ChannelClient extends ChannelBase {
     #private;
     private disconnectListener;
     private endpointId;
+    /**
+     * @internal
+     */
     static closeChannelByEndpointId(id: string): void;
+    /**
+     * @internal
+     * closes the corresponding channel and invokes the disconnect listener if an event payload is passed.
+     */
     static handleProviderDisconnect(eventPayload: ProviderIdentity): void;
+    /**
+     * @internal
+     */
     constructor(routingInfo: RoutingInfo, wire: Transport, strategy: AnyStrategy);
     protected processAction: (action: string, payload: any, senderIdentity: ProviderIdentity | OpenFin.ClientIdentity) => Promise<any>;
+    /**
+     * a read-only provider identity
+     */
     get providerIdentity(): ProviderIdentity;
+    /**
+     * Dispatch the given action to the channel provider. Returns a promise that resolves with the response from
+     * the provider for that action.
+     *
+     * @param action
+     * @param payload
+     *
+     * @example
+     *
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     await client.register('client-action', (payload, identity) => {
+     *         console.log(payload, identity);
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     const providerResponse = await client.dispatch('provider-action', { message: 'Hello From the client'});
+     *     console.log(providerResponse);
+     * })();
+     * ```
+     */
     dispatch(action: string, payload?: any): Promise<any>;
+    /**
+     * Register a listener that is called on provider disconnection. It is passed the disconnection event of the
+     * disconnecting provider.
+     *
+     * @param listener
+     *
+     * @example
+     *
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     await client.onDisconnection(evt => {
+     *         console.log('Provider disconnected', `uuid: ${evt.uuid}, name: ${evt.name}`);
+     *     });
+     * })();
+     * ```
+     */
     onDisconnection(listener: DisconnectionListener): void;
+    /**
+     * Disconnects the client from the channel.
+     *
+     * @example
+     *
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     await client.disconnect();
+     * })();
+     * ```
+     */
     disconnect(): Promise<void>;
     sendDisconnectAction(): Promise<void>;
 }

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

@@ -14,14 +14,44 @@ var _ChannelClient_protectedObj, _ChannelClient_strategy, _ChannelClient_close;
 Object.defineProperty(exports, "__esModule", { value: true });
 const channel_1 = require("./channel");
 const channelClientsByEndpointId = new Map();
+/**
+ * Instance created to enable use of a channel as a client.  Allows for communication with the
+ * {@link ChannelProvider ChannelProvider} by invoking an action on the
+ * provider via {@link ChannelClient#dispatch dispatch} and to listen for communication
+ * from the provider by registering an action via {@link ChannelClient#register register}.
+ *
+ * Synchronous Methods:
+ *  * {@link ChannelClient#onDisconnection onDisconnection(listener)}
+ *  * {@link ChannelClient#register register(action, listener)}
+ *  * {@link ChannelClient#remove remove(action)}
+ *
+ * Asynchronous Methods:
+ *  * {@link ChannelClient#disconnect disconnect()}
+ *  * {@link ChannelClient#dispatch dispatch(action, payload)}
+ *
+ * Middleware:
+ * <br>Middleware functions receive the following arguments: (action, payload, senderId).
+ * The return value of the middleware function will be passed on as the payload from beforeAction, to the action listener, to afterAction
+ * unless it is undefined, in which case the original payload is used.  Middleware can be used for side effects.
+ *  * {@link ChannelClient#setDefaultAction setDefaultAction(middleware)}
+ *  * {@link ChannelClient#onError onError(middleware)}
+ *  * {@link ChannelClient#beforeAction beforeAction(middleware)}
+ *  * {@link ChannelClient#afterAction afterAction(middleware)}
+ */
 class ChannelClient extends channel_1.ChannelBase {
+    /**
+     * @internal
+     */
     static closeChannelByEndpointId(id) {
         const channel = channelClientsByEndpointId.get(id);
         if (channel) {
             __classPrivateFieldGet(channel, _ChannelClient_close, "f").call(channel);
         }
     }
-    // closes the corresponding channel and invokes the disconnect listener if an event payload is passed.
+    /**
+     * @internal
+     * closes the corresponding channel and invokes the disconnect listener if an event payload is passed.
+     */
     static handleProviderDisconnect(eventPayload) {
         for (const channelClient of channelClientsByEndpointId.values()) {
             if (channelClient.providerIdentity.channelId === eventPayload.channelId) {
@@ -30,6 +60,9 @@ class ChannelClient extends channel_1.ChannelBase {
             }
         }
     }
+    /**
+     * @internal
+     */
     constructor(routingInfo, wire, strategy) {
         super();
         _ChannelClient_protectedObj.set(this, void 0);
@@ -47,16 +80,62 @@ class ChannelClient extends channel_1.ChannelBase {
         channelClientsByEndpointId.set(this.endpointId, this);
         strategy.receive(this.processAction);
     }
+    /**
+     * a read-only provider identity
+     */
     get providerIdentity() {
         const protectedObj = __classPrivateFieldGet(this, _ChannelClient_protectedObj, "f");
         return protectedObj.providerIdentity;
     }
+    /**
+     * Dispatch the given action to the channel provider. Returns a promise that resolves with the response from
+     * the provider for that action.
+     *
+     * @param action
+     * @param payload
+     *
+     * @example
+     *
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     await client.register('client-action', (payload, identity) => {
+     *         console.log(payload, identity);
+     *         return {
+     *             echo: payload
+     *         };
+     *     });
+     *
+     *     const providerResponse = await client.dispatch('provider-action', { message: 'Hello From the client'});
+     *     console.log(providerResponse);
+     * })();
+     * ```
+     */
     async dispatch(action, payload) {
         if (__classPrivateFieldGet(this, _ChannelClient_strategy, "f").isEndpointConnected(this.providerIdentity.channelId)) {
             return __classPrivateFieldGet(this, _ChannelClient_strategy, "f").send(this.providerIdentity.channelId, action, payload);
         }
         throw new Error('The client you are trying to dispatch from is disconnected from the target provider.');
     }
+    /**
+     * Register a listener that is called on provider disconnection. It is passed the disconnection event of the
+     * disconnecting provider.
+     *
+     * @param listener
+     *
+     * @example
+     *
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     await client.onDisconnection(evt => {
+     *         console.log('Provider disconnected', `uuid: ${evt.uuid}, name: ${evt.name}`);
+     *     });
+     * })();
+     * ```
+     */
     onDisconnection(listener) {
         this.disconnectListener = (payload) => {
             try {
@@ -70,6 +149,19 @@ class ChannelClient extends channel_1.ChannelBase {
             }
         };
     }
+    /**
+     * Disconnects the client from the channel.
+     *
+     * @example
+     *
+     * ```js
+     * (async ()=> {
+     *     const client = await fin.InterApplicationBus.Channel.connect('channelName');
+     *
+     *     await client.disconnect();
+     * })();
+     * ```
+     */
     async disconnect() {
         await this.sendDisconnectAction();
         __classPrivateFieldGet(this, _ChannelClient_close, "f").call(this);