diff --git a/README.md b/README.md index ca7c25375..fbe0caaa8 100644 --- a/README.md +++ b/README.md @@ -237,7 +237,7 @@ void getHistory([ably.RestHistoryParams params]) async { getHistory(); // sorted and filtered history -getHistory(ably.RestHistoryParams(direction: 'forwards', limit: 10)); +getHistory(ably.RestHistoryParams(direction: HistoryDirection.forwards, limit: 10)); ``` Get REST Channel Presence: @@ -294,7 +294,7 @@ void getPresenceHistory([ably.RestHistoryParams params]) async { getPresenceHistory(); // filtered presence members -getPresenceHistory(ably.RestHistoryParams(direction: 'forwards', limit: 10)); +getPresenceHistory(ably.RestHistoryParams(direction: HistoryDirection.forwards, limit: 10)); ``` ### Using the Realtime API @@ -414,7 +414,7 @@ void getHistory([ably.RealtimeHistoryParams params]) async { getHistory(); // sorted and filtered history -getHistory(ably.RealtimeHistoryParams(direction: 'forwards', limit: 10)); +getHistory(ably.RealtimeHistoryParams(direction: HistoryDirection.forwards, limit: 10)); ``` Enter Realtime Presence: @@ -516,7 +516,7 @@ void getPresenceHistory([ably.RealtimeHistoryParams params]) async { getPresenceHistory(); // sorted and filtered history -getPresenceHistory(ably.RealtimeHistoryParams(direction: 'forwards', limit: 10)); +getPresenceHistory(ably.RealtimeHistoryParams(direction: HistoryDirection.forwards, limit: 10)); ``` Subscribe to Realtime Presence messages diff --git a/UPDATING.md b/UPDATING.md index 07abe2238..f7faad4b1 100644 --- a/UPDATING.md +++ b/UPDATING.md @@ -2,6 +2,10 @@ This guide lists the changes needed to upgrade from one version of Ably to a newer one when there are breaking changes. +## [Upgrading from v1.2.13] + +- `RestHistoryParams` and `RealtimeHistoryParams` now use `HistoryDirection` enum instead of `String` value for `direction` + ## [Upgrading from v1.2.12] - `TokenDetails`, `TokenParams` and `TokenRequest` classes are now immutable, parameters have to be passed through constructor diff --git a/example/lib/ui/rest_sliver.dart b/example/lib/ui/rest_sliver.dart index 2d0e78eb5..55d235ac7 100644 --- a/example/lib/ui/rest_sliver.dart +++ b/example/lib/ui/rest_sliver.dart @@ -93,7 +93,7 @@ class RestSliver extends HookWidget { PaginatedResultViewer( title: 'History', query: () => channel.history(ably.RestHistoryParams( - direction: 'forwards', + direction: ably.HistoryDirection.forwards, limit: 10, )), builder: (context, message, _) => Column( diff --git a/lib/src/common/common.dart b/lib/src/common/common.dart index 6e5cd4f4f..b4fa7aeb6 100644 --- a/lib/src/common/common.dart +++ b/lib/src/common/common.dart @@ -2,3 +2,4 @@ export 'src/channels.dart'; export 'src/event_emitter.dart'; export 'src/event_listener.dart'; export 'src/http_paginated_response.dart'; +export 'src/history_direction.dart'; diff --git a/lib/src/common/src/history_direction.dart b/lib/src/common/src/history_direction.dart new file mode 100644 index 000000000..6ce512ec4 --- /dev/null +++ b/lib/src/common/src/history_direction.dart @@ -0,0 +1,20 @@ +import 'dart:core'; + +/// Used to indicate direction of entries in Realtime and REST history +// ignore_for_file: public_member_api_docs +enum HistoryDirection { + forwards, + backwards, +} + +extension Value on HistoryDirection { + /// Returns enum value as String + String value() { + switch (this) { + case HistoryDirection.forwards: + return 'forwards'; + case HistoryDirection.backwards: + return 'backwards'; + } + } +} diff --git a/lib/src/platform/src/codec.dart b/lib/src/platform/src/codec.dart index eb8e6fc95..d7f881cc5 100644 --- a/lib/src/platform/src/codec.dart +++ b/lib/src/platform/src/codec.dart @@ -400,7 +400,7 @@ class Codec extends StandardMessageCodec { jsonMap, TxRestHistoryParams.start, v.start.millisecondsSinceEpoch); _writeToJson( jsonMap, TxRestHistoryParams.end, v.end.millisecondsSinceEpoch); - _writeToJson(jsonMap, TxRestHistoryParams.direction, v.direction); + _writeToJson(jsonMap, TxRestHistoryParams.direction, v.direction.value()); _writeToJson(jsonMap, TxRestHistoryParams.limit, v.limit); return jsonMap; } @@ -441,7 +441,8 @@ class Codec extends StandardMessageCodec { TxRealtimeHistoryParams.end, v.end.millisecondsSinceEpoch, ); - _writeToJson(jsonMap, TxRealtimeHistoryParams.direction, v.direction); + _writeToJson( + jsonMap, TxRealtimeHistoryParams.direction, v.direction.value()); _writeToJson(jsonMap, TxRealtimeHistoryParams.limit, v.limit); _writeToJson(jsonMap, TxRealtimeHistoryParams.untilAttach, v.untilAttach); return jsonMap; diff --git a/lib/src/realtime/src/realtime_history_params.dart b/lib/src/realtime/src/realtime_history_params.dart index c60e9f6d9..1655755af 100644 --- a/lib/src/realtime/src/realtime_history_params.dart +++ b/lib/src/realtime/src/realtime_history_params.dart @@ -1,3 +1,4 @@ +import 'package:ably_flutter/src/common/src/history_direction.dart'; import 'package:meta/meta.dart'; /// Params for realtime history @@ -26,7 +27,7 @@ class RealtimeHistoryParams { /// if omitted the direction defaults to the REST API default (backwards) /// /// https://docs.ably.com/client-lib-development-guide/features/#RTL10a - final String direction; + final HistoryDirection direction; /// Number of items returned in one page /// [limit] supports up to 1,000 items. @@ -44,18 +45,15 @@ class RealtimeHistoryParams { /// https://docs.ably.com/client-lib-development-guide/features/#RTL10b final bool? untilAttach; - /// instantiates with [direction] set to "backwards", [limit] to 100 - /// [start] to epoch and end to current time - /// - /// Raises [AssertionError] if [direction] is not "backwards" or "forwards" + /// instantiates with [direction] set to [HistoryDirection.backwards], + /// [limit] to 100, [start] to epoch and [end] to current time RealtimeHistoryParams({ - this.direction = 'backwards', + this.direction = HistoryDirection.backwards, DateTime? end, this.limit = 100, DateTime? start, this.untilAttach, - }) : assert(direction == 'backwards' || direction == 'forwards'), - end = end ?? DateTime.now(), + }) : end = end ?? DateTime.now(), start = start ?? DateTime.fromMillisecondsSinceEpoch(0); @override diff --git a/lib/src/rest/src/rest_history_params.dart b/lib/src/rest/src/rest_history_params.dart index 07d3bf171..1c6808989 100644 --- a/lib/src/rest/src/rest_history_params.dart +++ b/lib/src/rest/src/rest_history_params.dart @@ -1,3 +1,5 @@ +import 'package:ably_flutter/src/common/src/history_direction.dart'; + /// Params for rest history /// /// https://docs.ably.com/client-lib-development-guide/features/#RSL2b @@ -23,7 +25,7 @@ class RestHistoryParams { /// if omitted the direction defaults to the REST API default (backwards) /// /// https://docs.ably.com/client-lib-development-guide/features/#RSL2b2 - final String direction; + final HistoryDirection direction; /// Number of items returned in one page /// [limit] supports up to 1,000 items. @@ -33,17 +35,14 @@ class RestHistoryParams { /// https://docs.ably.com/client-lib-development-guide/features/#RSL2b3 final int limit; - /// instantiates with [direction] set to "backwards", [limit] to 100 - /// [start] to epoch and end to current time - /// - /// Raises [AssertionError] if [direction] is not "backwards" or "forwards" + /// instantiates with [direction] set to [HistoryDirection.backwards], + /// [limit] to 100, [start] to epoch and [end] to current time RestHistoryParams({ - this.direction = 'backwards', + this.direction = HistoryDirection.backwards, DateTime? end, this.limit = 100, DateTime? start, - }) : assert(direction == 'backwards' || direction == 'forwards'), - end = end ?? DateTime.now(), + }) : end = end ?? DateTime.now(), start = start ?? DateTime.fromMillisecondsSinceEpoch(0); @override diff --git a/test_integration/lib/test/realtime/realtime_encrypted_publish_test.dart b/test_integration/lib/test/realtime/realtime_encrypted_publish_test.dart index 17e9bebc9..c896cb18a 100644 --- a/test_integration/lib/test/realtime/realtime_encrypted_publish_test.dart +++ b/test_integration/lib/test/realtime/realtime_encrypted_publish_test.dart @@ -96,7 +96,7 @@ Future> testRealtimeEncryptedPublishSpec({ // Retrieve history of channel where client id was specified final historyOfEncryptedChannel = await getHistory( encryptedChannel, - RealtimeHistoryParams(direction: 'forwards'), + RealtimeHistoryParams(direction: HistoryDirection.forwards), ); // Create encrypted channel with push capability @@ -121,7 +121,7 @@ Future> testRealtimeEncryptedPublishSpec({ await encryptedChannel.setOptions(RealtimeChannelOptions()); final historyOfPlaintextChannel = await getHistory( encryptedChannel, - RealtimeHistoryParams(direction: 'forwards'), + RealtimeHistoryParams(direction: HistoryDirection.forwards), ); await encryptedPushEnabledChannel.setOptions(RealtimeChannelOptions()); final historyOfPlaintextPushEnabledChannel = diff --git a/test_integration/lib/test/realtime/realtime_history_test.dart b/test_integration/lib/test/realtime/realtime_history_test.dart index 258e22efd..e673e2810 100644 --- a/test_integration/lib/test/realtime/realtime_history_test.dart +++ b/test_integration/lib/test/realtime/realtime_history_test.dart @@ -41,7 +41,7 @@ Future> testRealtimeHistory({ final historyForwardLimit4 = await getHistory( channel, - RealtimeHistoryParams(direction: 'forwards', limit: 4), + RealtimeHistoryParams(direction: HistoryDirection.forwards, limit: 4), ); await Future.delayed(TestConstants.publishToHistoryDelay); diff --git a/test_integration/lib/test/realtime/realtime_presence_history_test.dart b/test_integration/lib/test/realtime/realtime_presence_history_test.dart index 519cfc914..9464dc051 100644 --- a/test_integration/lib/test/realtime/realtime_presence_history_test.dart +++ b/test_integration/lib/test/realtime/realtime_presence_history_test.dart @@ -53,7 +53,7 @@ Future> testRealtimePresenceHistory({ final historyForwards = await getPresenceHistory( channel, - RealtimeHistoryParams(direction: 'forwards'), + RealtimeHistoryParams(direction: HistoryDirection.forwards), ); await Future.delayed(TestConstants.publishToHistoryDelay); diff --git a/test_integration/lib/test/realtime/realtime_publish_test.dart b/test_integration/lib/test/realtime/realtime_publish_test.dart index 999e23734..005154cee 100644 --- a/test_integration/lib/test/realtime/realtime_publish_test.dart +++ b/test_integration/lib/test/realtime/realtime_publish_test.dart @@ -77,7 +77,7 @@ Future> testRealtimePublishSpec({ } final history = await getHistory( channel, - RealtimeHistoryParams(direction: 'forwards'), + RealtimeHistoryParams(direction: HistoryDirection.forwards), ); // client options - no client id, message has client id @@ -95,7 +95,7 @@ Future> testRealtimePublishSpec({ await Future.delayed(TestConstants.publishToHistoryDelay); final history2 = await getHistory( channel2, - RealtimeHistoryParams(direction: 'forwards'), + RealtimeHistoryParams(direction: HistoryDirection.forwards), ); final channel3 = realtime2.channels.get('©Äblý'); diff --git a/test_integration/lib/test/rest/rest_encrypted_publish_test.dart b/test_integration/lib/test/rest/rest_encrypted_publish_test.dart index 12802bc18..7acee3cda 100644 --- a/test_integration/lib/test/rest/rest_encrypted_publish_test.dart +++ b/test_integration/lib/test/rest/rest_encrypted_publish_test.dart @@ -97,7 +97,7 @@ Future> testRestEncryptedPublishSpec({ // Retrieve history of channel where client id was specified final historyOfEncryptedChannel = await getHistory( encryptedChannel, - RestHistoryParams(direction: 'forwards'), + RestHistoryParams(direction: HistoryDirection.forwards), ); // Create encrypted channel with push capability @@ -122,7 +122,7 @@ Future> testRestEncryptedPublishSpec({ await encryptedChannel.setOptions(RestChannelOptions()); final historyOfPlaintextChannel = await getHistory( encryptedChannel, - RestHistoryParams(direction: 'forwards'), + RestHistoryParams(direction: HistoryDirection.forwards), ); await encryptedPushEnabledChannel.setOptions(RestChannelOptions()); final historyOfPlaintextPushEnabledChannel = diff --git a/test_integration/lib/test/rest/rest_history_test.dart b/test_integration/lib/test/rest/rest_history_test.dart index 9c8454934..2fc796172 100644 --- a/test_integration/lib/test/rest/rest_history_test.dart +++ b/test_integration/lib/test/rest/rest_history_test.dart @@ -34,7 +34,11 @@ Future> testRestHistory({ await Future.delayed(TestConstants.publishToHistoryDelay); final historyForwardLimit4 = await getHistory( - channel, RestHistoryParams(direction: 'forwards', limit: 4)); + channel, + RestHistoryParams( + direction: HistoryDirection.forwards, + limit: 4, + )); await Future.delayed(TestConstants.publishToHistoryDelay); final time1 = DateTime.now(); diff --git a/test_integration/lib/test/rest/rest_presence_history_test.dart b/test_integration/lib/test/rest/rest_presence_history_test.dart index bff5d4c79..e5c08bc56 100644 --- a/test_integration/lib/test/rest/rest_presence_history_test.dart +++ b/test_integration/lib/test/rest/rest_presence_history_test.dart @@ -54,7 +54,7 @@ Future> testRestPresenceHistory({ final historyForwards = await getPresenceHistory( channel, - RestHistoryParams(direction: 'forwards'), + RestHistoryParams(direction: HistoryDirection.forwards), ); await Future.delayed(TestConstants.publishToHistoryDelay); diff --git a/test_integration/lib/test/rest/rest_publish_test.dart b/test_integration/lib/test/rest/rest_publish_test.dart index 9ac580b7f..2b5fc61f5 100644 --- a/test_integration/lib/test/rest/rest_publish_test.dart +++ b/test_integration/lib/test/rest/rest_publish_test.dart @@ -77,7 +77,7 @@ Future> testRestPublishSpec({ } final history = await getHistory( channel, - RestHistoryParams(direction: 'forwards'), + RestHistoryParams(direction: HistoryDirection.forwards), ); // client options - no client id, message has client id @@ -95,7 +95,7 @@ Future> testRestPublishSpec({ await Future.delayed(TestConstants.publishToHistoryDelay); final history2 = await getHistory( channel2, - RestHistoryParams(direction: 'forwards'), + RestHistoryParams(direction: HistoryDirection.forwards), ); // publish max allowed length - sandbox apps message limit is 16384