diff --git a/types/fm-websync/fm-websync-tests.ts b/types/fm-websync/fm-websync-tests.ts new file mode 100644 index 0000000000..aeb665e5ae --- /dev/null +++ b/types/fm-websync/fm-websync-tests.ts @@ -0,0 +1,19 @@ +const client = fm.websync.client.initialize( { + requestUrl: "", + onSuccess: args => console.log( `Init success: {args.clientId}` ), + onFailure: args => console.log( `Init failure: {args.clientId}` ), + onComplete: args => console.log( `Init complete: {args.clientId}` ) +} ); + +client.subscribe( { + channel: "/my/channel", + onReceive: args => console.log( `Receive data: {args.data}` ), + onFailure: args => console.log( `Subscribe failure: {args.data}` ), + onComplete: args => console.log( `Subscribe complete` ) +} ); + +client.disconnect( { + onSuccess: args => console.log( `Disconnect success: {args.clientId}` ), + onFailure: args => console.log( `Disconnect failure: {args.clientId}` ), + onComplete: args => console.log( `Disconnect complete: {args.clientId}` ) +} ); \ No newline at end of file diff --git a/types/fm-websync/index.d.ts b/types/fm-websync/index.d.ts new file mode 100644 index 0000000000..ae3677b986 --- /dev/null +++ b/types/fm-websync/index.d.ts @@ -0,0 +1,484 @@ +// Type definitions for fm-websync 3 +// Project: https://github.com/baz/foo (Does not have to be to GitHub, but prefer linking to a source code repository rather than to a project website.) +// Definitions by: Markus Mauch +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped + +declare namespace fm +{ + export namespace websync + { + interface initializeConfig + { + /** + * If set to true, an asynchronous disconnect request will be launched when the page unloads. If set to false, no automatic disconnection will be attempted. If set to an object, then a disconnect request will be launched when the page unloads using the object as the disconnect configuration. (See disconnectConfig for details.) Note that automatic disconnects are a best-effort. The only way to guarantee success is to execute the disconnect synchronously and target a request URL on the same domain as the page ({ sync: true, requestUrl: '...relative path.../request.ashx' }). Defaults to false. + */ + autoDisconnect?: boolean; + + /** + * The amount of time in milliseconds to add to the delay between each reconnect attempt in the event of network failure. Defaults to 3000 (3 seconds). + */ + + backoffInterval?: number; + + /** + * The URL of the HTML frame to be used with HTML5 postMessage for cross-domain environments. Must have the same domain as requestUrl. Defaults to a dynamically generated URL based on the host of the client script URL (or the host web.config attribute, if specified) and the path to the WebSync Server ClientHandler registered in web.config with "frame" added to the query. + */ + clientFrameUrl?: string; + + /** + * The domain key to send with each request. If using WebSync On-Demand, this should be set to the public or private API key specified in the Frozen Mountain Portal. If using WebSync Server, this should be used only if grouping connections. Defaults to "11111111-1111-1111-1111-111111111111". + */ + key?: string; + + /** + * The callback to invoke after onSuccess or onFailure. See initializeCompleteArgs for callback argument details. + */ + onComplete?: ( args: initializeCompleteArgs ) => void; + + /** + * The callback to invoke if the initialize fails. Defaults to an alert of the error. See initializeFailureArgs for callback argument details. + */ + onFailure?: ( args: initializeFailureArgs ) => void; + + /** + * The callback to invoke if the initialize succeeds. See initializeSuccessArgs for callback argument details. + */ + onSuccess?: ( args: initializeSuccessArgs ) => void; + + /** + * Whether or not to suppress the alerting of a failure if the client is already initialized. + */ + quiet?: boolean; + + /** + * The URL of the WebSync request handler. This URL typically ends with request.ashx. Must have the same domain as clientFrameUrl. Defaults to a dynamically generated URL based on the host of the client script URL (or the host web.config attribute, if specified) and the path to the WebSync Server RequestHandler registered in web.config. + */ + requestUrl?: string; + + /** + * The number of times to retry a request in the event of network failure before considering it failed and invoking the corresponding OnFailure callback. Defaults to 3. + */ + retries?: number; + + /** + * The URLs to use for streaming connections. Three properties are available: + * + * requestUrl: string + * Same as the root requestUrl parameter, but used for streaming connections. Must have the same domain as stream.clientFrameUrl. Defaults to a dynamically generated URL based on the host of the client script URL (or the streamHost web.config attribute, if specified) and the path to the WebSync Server RequestHandler registered in web.config. + * clientFrameUrl: string + * Same as the root clientFrameUrl parameter, but used for streaming connections. Must have the same domain as stream.requestUrl. Defaults to a dynamically generated URL based on the host of the client script URL (or the streamHost web.config attribute, if specified) and the path to the WebSync Server ClientHandler registered in web.config with "frame" added to the query. + * timeout: number + * Same as the root timeout parameter, but used for streaming connections. Defaults to the root timeout + 25000 (25 seconds). + */ + stream? : any; + + /** + * The number of milliseconds to wait for a standard request to return a response before it is cancelled and a new attempt is made. Defaults to 15000 (15 seconds). + */ + timeout?: number; + + /** + * The token sent with every client request identifying it for query-based load balancing. Defaults to the current timestamp. + */ + + token?: string; + + /** + * An object specifying URLs to be used for specific client methods. Overrides initializeConfig.requestUrl for the specified method type, but can be overridden by the requestUrl specified in individual method configurations. + * + * connect: string + * The URL to use for all client.connect requests. + * + * bind: string + * The URL to use for all client.bind requests. + * + * unbind: string + * The URL to use for all client.unbind requests. + * + * subscribe: string + * The URL to use for all client.subscribe requests. + * + * unsubscribe: string + * The URL to use for all client.unsubscribe requests. + * + * publish: string + * The URL to use for all client.publish requests. + * + * disconnect: string + * The URL to use for all client.disconnect requests. + */ + urls?: any; + } + + interface baseArgs + {} + + interface baseRequestConfig + { + /** + * Extra meta data to associate with the request/response. + */ + meta?: any; + + /** + * The URL of the proxy to use for this request. + */ + requestUrl?: string; + + /** + * Whether to ignore errors when parsing the server response. If true, any errors thrown while parsing the JSON response received from the server will be ignored. Defaults to false. + */ + suppressErrors?: boolean; + + /** + * Whether the request should be executed asynchronously. If true, the request will be executed synchronously if supported by the browser; otherwise, it will be executed asynchronously. All browsers support synchronous requests if the request URL is the same domain as the page. Synchronous requests are not supported in IE6 and IE7 for cross-domain environments. Defaults to false. + */ + sync?: boolean; + } + + interface connectConfig extends baseRequestConfig + { + /** + * The callback to invoke after onSuccess or onFailure. See connectCompleteArgs for callback argument details. + */ + onComplete?: ( args: connectCompleteArgs ) => void; + + /** + * The callback to invoke if the connect fails. Defaults to an alert of the error. See connectFailureArgs for callback argument details. + */ + onFailure?: ( args: connectFailureArgs ) => void; + + /** + * The callback to invoke if the streaming connection fails. See streamFailureArgs for callback argument details. + * This method will be invoked if (a) the connection was lost, automatic retries succeeded, but the client had idled on the server (and so needs to reconnect), or (b) the connection was lost and automatic retries failed. In the former case, willReconnect is true, and in the latter case, willReconnect is false. + * See client for more details on these two scenarios. + * If willReconnect is true, the client will automatically reconnect. If the reconnect succeeds, the callback specified by onSuccess will be invoked with isReconnect set to true. If the reconnect fails, the callback specified by onFailure will be invoked with isReconnect set to false. + * With the exception of UI updates, invocations of this callback with willReconnect set to true can be ignored. + */ + onStreamFailure?: ( args: streamFailureArgs ) => void; + + /** + * The callback to invoke if the connect succeeds. See connectSuccessArgs for callback argument details. + */ + onSuccess?: ( args: connectSuccessArgs ) => void; + + /** + * The callback to invoke when a message is received on a channel that has no local callback specified to handle it. See receiveArgs for callback argument details. + * This can occur if (a) a client is manually subscribed to a channel by the server or (b) a client subscribed to a channel and then manually removed the local callback using client.unsetHandler. + */ + onUnhandledReceive?: Function; + + /** + * Whether to always attempt to stay connected in the event of network failure. If true, the client will continually reconnect, even after exhausting the specified number of retries specified by initializeConfig.retries. If false, the client will stop reconnecting if all retry attempts fail. + */ + stayConnected?: boolean; + } + + interface subscribeConfig extends baseRequestConfig + { + /** + * The channel to which the client should be subscribed. Must start with a forward slash (/). Overrides channels. + */ + channel?: String; + + /** + * The channels to which the client should be subscribed. Each must start with a forward slash (/). Overrides channel. + */ + channels?: String[]; + + /** + * The callback to invoke after onSuccess or onFailure. See subscribeCompleteArgs for callback argument details. + */ + onComplete?: ( args: subscribeCompleteArgs ) => void; + + /** + * (OptionalThe callback to invoke if the subscribe fails. See subscribeFailureArgs for callback argument details. + */ + onFailure?: ( args: subscribeFailureArgs ) => void; + + /** + * The callback to invoke when data is received on the channel(s). See receiveArgs for callback argument details. + */ + onReceive?: ( args: receiveArgs ) => void; + + /** + * Subscribers extension. The callback to invoke when a subscribers change notification is received (i.e. when a client subscribes to or unsubscribes from the channel(s)). + * The current subscribe request will trigger this callback. See subscribersChangeArgs for callback argument details. + */ + onSubscribersChange?: ( args: subscribersChangeArgs ) => void; + + /** + * The callback to invoke if the subscribe succeeds. See subscribeSuccessArgs for callback argument details. + */ + onSuccess?: ( args: subscribeSuccessArgs ) => void; + } + + interface baseCompleteArgs extends baseResponseArgs + { + } + + interface initializeCompleteArgs extends baseArgs + { + } + + interface initializeFailureArgs extends baseArgs + { + } + + interface initializeSuccessArgs extends baseArgs + { + } + + interface subscribeSuccessArgs extends baseSuccessArgs + { + /** + * The channel to which the client was subscribed. Must start with a forward slash (/). + */ + channel: string; + + /** + * The channels to which the client was subscribed. Each must start with a forward slash (/). + */ + channels: string[]; + + /** + * Whether the call to client.subscribe was triggered by a reconnection after network failure. + */ + isResubscribe: boolean; + + /** + * Subscribers extension. The active subscribed clients on the just-subscribed channel(s). + */ + subscribedClients: fm.websync.subscribedClient[]; + } + + interface subscribeCompleteArgs extends baseCompleteArgs + { + /** + * Whether the call to client.subscribe was triggered by a reconnection after network failure. + */ + isResubscribe: boolean; + } + + interface subscribeFailureArgs extends baseFailureArgs + { + /** + * Whether the call to client.subscribe was triggered by a reconnection after network failure. + */ + isResubscribe: boolean; + } + + interface baseFailureArgs extends baseResponseArgs + { + /** + * The error generated while completing the request. + */ + error: string; + } + + interface baseResponseArgs extends baseArgs + { + /** + * The singleton client. + */ + client: fm.websync.client; + + /** + * The ID of the singleton client. + */ + clientId: string; + + /** + * Extra meta data associated with the request/response. + */ + meta: any; + + /** + * The date/time the message was processed on the server. + */ + timestamp: Date; + } + + interface baseSuccessArgs extends baseResponseArgs + { + + } + + interface connectSuccessArgs extends baseResponseArgs + { + /** + * Whether the call to client.connect was triggered by a reconnection after network failure. + */ + isReconnect: boolean; + } + + interface connectFailureArgs extends baseResponseArgs + { + /** + * The error generated while completing the request. + */ + error: string; + + /** + * Whether the call to client.connect was triggered by a reconnection after network failure. + */ + isReconnect: boolean; + + /** + * Whether or not to reconnect automatically after this callback has finished execution. + */ + reconnect: boolean; + } + + interface streamFailureArgs extends baseResponseArgs + { + /** + * The error generated while completing the request. + */ + error: string; + + /** + * Whether the client will automatically reconnect after the callback returns. + */ + willReconnect: boolean; + } + + interface connectCompleteArgs extends baseResponseArgs + { + /** + * Whether the call to client.connect was triggered by a reconnection after network failure. + */ + isReconnect: boolean; + } + + interface receiveArgs extends baseResponseArgs + { + /** + * The channel over which the data was published. + */ + channel: string; + + /** + * The published data. + */ + data: any; + + /** + * Details about the client publishing the data. + */ + publishingClient: fm.websync.publishingClient; + } + + interface subscribersChangeArgs extends baseSuccessArgs + { + /** + * The details of the change that occurred. + */ + change?: fm.websync.subscribersChange + + /** + * The channel on which the change occurred. + */ + channel?: string; + } + + interface publishingClient + { + /** + * The publishing client's bound records. + */ + boundRecords: any; + + /** + * The publishing client's unique identifier. + */ + id: string; + } + + interface subscribersChange + { + /** + * The clients who subscribed to or unsubscribed from the channel. + */ + clients : fm.websync.subscribedClient[]; + + /** + * The type of the change, either "subscribe" or "unsubscribe". + */ + type: string; + } + + interface subscribedClient + { + /** + * The subscribed client's bound records. + */ + boundRecords: any; + + /** + * The subscribed client's unique identifier. + */ + id: string; + } + + interface disconnectConfig extends baseRequestConfig + { + /** + * The callback to invoke after onSuccess or onFailure. See disconnectCompleteArgs for callback argument details. + */ + onComplete: ( args: disconnectCompleteArgs ) => void; + + /** + * The callback to invoke if the disconnect fails. See disconnectFailureArgs for callback argument details. + */ + onFailure: ( args: disconnectFailureArgs ) => void; + + /** + * The callback to invoke if the disconnect succeeds. See disconnectSuccessArgs for callback argument details. + */ + onSuccess: ( args: disconnectSuccessArgs ) => void; + } + + interface disconnectCompleteArgs extends baseCompleteArgs + { + } + + interface disconnectFailureArgs extends baseFailureArgs + { + } + + interface disconnectSuccessArgs extends baseSuccessArgs + { + } + + export class client + { + /** + * Sets up and maintains a streaming connection to the server. + * While this method will typically run asychronously, the WebSync client is designed to be used without (much) consideration for its asynchronous nature. To that end, any calls to methods that require an active connection, like bind, subscribe and publish, will be queued automatically and executed once this method has completed successfully. + * + * @param connectConfig + */ + public connect( config: connectConfig ): client; + + /** + * + * @param config Takes down a streaming connection to the server and unsubscribes the client. + * After the disconnect completes successfully, any further calls to methods that require an active connection, like bind, subscribe and publish, will be queued automatically and executed only if/when the client reconnects. + */ + public disconnect( config: disconnectConfig ): client; + + /** + * Initializes the client according to the specified configuration. + * This method must always be called first. While is always executes synchronously, callbacks are allowed for the purposes of method chaining. + */ + public static initialize( config: initializeConfig ): client; + + /** + * Subscribes the client to receive messages on one or more channels. + * When the subscribe completes successfully, the callback specified by onSuccess will be invoked, passing in the subscribed channel(s), including any modifications made on the server. + */ + public subscribe( config: subscribeConfig ): client; + } + } +} diff --git a/types/fm-websync/package.json b/types/fm-websync/package.json new file mode 100644 index 0000000000..6843239469 --- /dev/null +++ b/types/fm-websync/package.json @@ -0,0 +1,11 @@ +{ + "name": "fm-websync", + "version": "1.0.0", + "description": "Type definitions for Frozen Mountain WebSync 3", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "Markus Mauch", + "license": "ISC" +} diff --git a/types/fm-websync/tsconfig.json b/types/fm-websync/tsconfig.json new file mode 100644 index 0000000000..76193744be --- /dev/null +++ b/types/fm-websync/tsconfig.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "module": "none", + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "baseUrl": "../", + "typeRoots": [ + "../" + ], + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "fm-websync-tests.ts" + ] +} diff --git a/types/fm-websync/tslint.json b/types/fm-websync/tslint.json new file mode 100644 index 0000000000..3db14f85ea --- /dev/null +++ b/types/fm-websync/tslint.json @@ -0,0 +1 @@ +{ "extends": "dtslint/dt.json" }