From c65af0ffed5ac43ad37f7cc5dd2a210ac6b869e6 Mon Sep 17 00:00:00 2001 From: Greg Holmes Date: Mon, 29 Jan 2024 14:16:57 +0000 Subject: [PATCH 01/17] Change channels index JS examples from callback to promise calls --- content/channels/index.textile | 178 ++++++++++++++++----------------- 1 file changed, 86 insertions(+), 92 deletions(-) diff --git a/content/channels/index.textile b/content/channels/index.textile index 5b6aae7ad4..9ff41dba9d 100644 --- a/content/channels/index.textile +++ b/content/channels/index.textile @@ -74,11 +74,11 @@ Channels are the unit of security and scalability. If you are sending data that The following is an example of creating a channel: ```[realtime_javascript] -var channel = realtime.channels.get('channelName'); +const channel = realtime.channels.get('channelName'); ``` ```[realtime_nodejs] -var channel = realtime.channels.get('channelName'); +const channel = realtime.channels.get('channelName'); ``` ```[realtime_java] @@ -110,11 +110,11 @@ final channel = realtime.channels.get('channelName'); ``` ```[rest_javascript] -var channel = rest.channels.get('channelName'); +const channel = rest.channels.get('channelName'); ``` ```[rest_nodejs] -var channel = rest.channels.get('channelName'); +const channel = rest.channels.get('channelName'); ``` ```[rest_java] @@ -164,15 +164,13 @@ Note that "@attach()@":/api/realtime-sdk/channels#attach can be called explicitl The following example explicitly attaches to a channel, which results in the channel being provisioned in Ably's global realtime cluster. This channel will remain available globally until there are no more clients attached to the channel: ```[realtime_javascript] -realtime.channels.get('chatroom').attach(function(err) { - console.log('"chatroom" exists and is now available globally in every datacenter'); -}); +const channel = realtime.channels.get('chatroom'); +await channel.attach(); ``` ```[realtime_nodejs] -realtime.channels.get('chatroom').attach(function(err) { - console.log('"chatroom" exists and is now available globally in every datacenter'); -}); +const channel = realtime.channels.get('chatroom'); +await channel.attach(); ``` ```[realtime_ruby] @@ -247,17 +245,13 @@ A channel will automatically close when all of the following criteria are met: The following is an example of detaching from a channel: ```[realtime_javascript] -channel.detach(); -channel.on('detached', function(stateChange) { - console.log('detached from the channel ' + channel.name); -}; +const channel = realtime.channels.get('chatroom'); +await channel.detach(); ``` ```[realtime_nodejs] -channel.detach(); -channel.on('detached', function(stateChange) { - console.log('detached from the channel ' + channel.name); -}; +const channel = realtime.channels.get('chatroom'); +await channel.detach(); ``` ```[realtime_ruby] @@ -322,16 +316,15 @@ Use the "@publish()@":/api/realtime-sdk/channels#publish method to send messages The following is an example of publishing a message to a channel: ```[realtime_javascript] - var realtime = new Ably.Realtime('{{API_KEY}}'); - var channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}'); - channel.publish('example', 'message data'); +const realtime = new Ably.Realtime.Promise('{{API_KEY}}'); +const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}'); +await channel.publish('example', 'message data'); ``` ```[realtime_nodejs] - var Ably = require('ably'); - var realtime = new Ably.Realtime('{{API_KEY}}'); - var channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}'); - channel.publish("example", "message data"); +const realtime = new Ably.Realtime.Promise('{{API_KEY}}'); +const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}'); +await channel.publish('example', 'message data'); ``` ```[realtime_ruby] @@ -378,15 +371,15 @@ channel.publish("example", data: "message data") ``` ```[rest_javascript] - var rest = new Ably.Rest('{{API_KEY}}'); - var channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}'); - channel.publish('example', 'message data'); +const rest = new Ably.Rest.Promise('{{API_KEY}}'); +const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}'); +await channel.publish('example', 'message data'); ``` ```[rest_nodejs] - var rest = new Ably.Rest('{{API_KEY}}'); - var channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}'); - channel.publish('example', 'message data'); +const rest = new Ably.Rest.Promise('{{API_KEY}}'); +const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}'); +await channel.publish('example', 'message data'); ``` ```[rest_ruby] @@ -458,19 +451,14 @@ h3(#batch-publish). Batch publish It is possible to publish messages to multiple channels with a single request. A batch request queries an API multiple times with single HTTP request. A batch request has a single set of request details containing the request body, parameters and headers. These are converted into an array of requests to the underlying API. Each individual request to the underlying API is performed in parallel and may succeed or fail independently. -The following is an example of a batch publish request using the "@request()@":/api/rest-sdk#request method to query the "batch REST API":/api/rest-api#batch-publish: +The following is an example of a batch publish request using the "@request()@":/api/rest-sdk#request method to query the "batch REST API":/api/rest-api#batch-publish ```[rest_javascript] -var ablyRest = new Ably.Rest({ key: '{{API_KEY}}' }) -var content = { "channels": [ "test1", "test2" ], "messages": { "data": 'myData' } } -ablyRest.request('post', '/messages', null, content, null, -function(err, response) { - if(err) { - alert('An error occurred; err = ' + err.toString()); - } else { - alert('Success! status code was ' + response.statusCode); - } -}); +const ablyRest = new Ably.Rest.Promise({ key: '{{API_KEY}}' }) +const content = { "channels": [ "test1", "test2" ], "messages": { "data": 'myData' } } +const batchPublish = await ablyRest.request('post', '/messages', null, content, null); + +console.log('Success! status code was ' + batchPublish.statusCode) ``` h4(#batch-requests). Batch requests @@ -612,15 +600,15 @@ Transient publishing is when a client publishes messages without attaching to a The following is an example of publishing without attaching to a channel: ```[realtime_javascript] -var channel = realtime.channels.get('chatroom'); +const channel = realtime.channels.get('chatroom'); // The publish below will not attach you to the channel -channel.publish('action', 'boom!'); +await channel.publish('action', 'boom!'); ``` ```[realtime_nodejs] -var channel = realtime.channels.get('chatroom'); +const channel = realtime.channels.get('chatroom'); // The publish below will not attach you to the channel -channel.publish('action', 'boom!'); +await channel.publish('action', 'boom!'); ``` ```[realtime_ruby] @@ -652,9 +640,9 @@ If idempotent publishing is enabled using the @idempotentRestPublishing@ "@Clien It is also possible to manually specify message IDs. The following is an example of how you might do this: ```[rest_javascript] -const rest = new Ably.Rest('{{API_KEY}}'); +const rest = new Ably.Rest.Promise('{{API_KEY}}'); const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}'); -channel.publish([{data: 'payload', id: 'unique123'}]); +await channel.publish([{data: 'payload', id: 'unique123'}]); ``` If manually specifying message IDs, it is important to be aware of how messages are published when calling the "publish()":/api/rest-sdk/channels#publish method with an array of messages. See this "FAQ":https://faqs.ably.com/client-specified-message-id-restrictions-for-multiple-messages-published-atomically for further information. @@ -693,20 +681,19 @@ A client can subscribe to all messages published to a channel by passing a lambd The following is an example of registering a listener for all messages: ```[realtime_javascript] - var realtime = new Ably.Realtime('{{API_KEY}}'); - var channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}'); - channel.subscribe(function(message) { - alert('Received: ' + message.data); - }); +const realtime = new Ably.Realtime.Promise('{{API_KEY}}'); +const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}'); +await channel.subscribe((message) => { + alert('Received: ' + message.data); +}); ``` ```[realtime_nodejs] - var Ably = require('ably'); - var realtime = new Ably.Realtime('{{API_KEY}}'); - var channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}'); - channel.subscribe(function(message) { - console.log("Received: " + message.data); - }); +const realtime = new Ably.Realtime.Promise('{{API_KEY}}'); +const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}'); +await channel.subscribe((message) => { + console.log("Received: " + message.data); +}); ``` ```[realtime_ruby] @@ -774,14 +761,14 @@ channel.subscribe { message in The following is an example of registering a listener for a specific message name: ```[realtime_javascript] -channel.subscribe('myEvent', function(message) { +await channel.subscribe('myEvent', (message) => { console.log('message received for event ' + message.name); console.log('message data:' + message.data); }); ``` ```[realtime_nodejs] -channel.subscribe('myEvent', function(message) { +await channel.subscribe('myEvent', (message) => { console.log('message received for event ' + message.name); console.log('message data:' + message.data); }); @@ -850,19 +837,19 @@ Normally, errors in attaching to a channel are communicated through the "attach( The following is an example of implicitly attaching to a channel and publishing a message: ```[realtime_javascript] -var channel = realtime.channels.get('chatroom'); -channel.subscribe('action', function(message) { // implicit attach - console.log('Message received '' + message.data); +const channel = realtime.channels.get('chatroom'); +await channel.subscribe('action', (message) => { // implicit attach + console.log('Message received ' + message.data); }); -channel.publish('action', 'boom!'); +await channel.publish('action', 'boom!'); ``` ```[realtime_nodejs] -var channel = realtime.channels.get('chatroom'); -channel.subscribe('action', function(message) { // implicit attach - console.log('Message received '' + message.data); +const channel = realtime.channels.get('chatroom'); +await channel.subscribe('action', (message) => { // implicit attach + console.log('Message received ' + message.data); }); -channel.publish('action', 'boom!'); +await channel.publish('action', 'boom!'); ``` ```[realtime_ruby] @@ -1033,7 +1020,8 @@ Filter expressions should be written using "JMESPath.":https://jmespath.org/ The The following is an example of publishing a message with additional metadata: ```[realtime_javascript] -realtime.channels.get('scoops-kiosk').publish({ +const channel = realtime.channels.get('scoops-kiosk'); +await channel.publish({ name: 'ice-cream', data: '...', extras: { @@ -1047,7 +1035,8 @@ realtime.channels.get('scoops-kiosk').publish({ ``` ```[rest_javascript] -rest.channels.get('scoops-kiosk').publish({ +const channel = rest.channels.get('scoops-kiosk');` +await channel.publish({ name: 'ice-cream', data: '...', extras: { @@ -1081,9 +1070,10 @@ In order to subscribe to a channel with a filter expression, you obtain a channe The following is an example of subscribing to a channel using one of the previous example filters: ```[realtime_javascript] -realtime.channels.getDerived('scoops-kiosk', { - filter: 'name == `"ice-cream"` && headers.flavor == `"strawberry"` && headers.cost < `50`' -}).subscribe(...); +const channel = realtime.channels.getDerived('scoops-kiosk', { + filter: 'name == `"ice-cream"` && headers.flavor == `"strawberry"` && headers.cost < `50`' +}) +await channel.subscribe(...); ```