ably · ikurek · Apr 8, 2022 · Apr 8, 2022 · Apr 8, 2022 · Apr 8, 2022
diff --git 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
@@ -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
@@ -93,7 +93,7 @@ class RestSliver extends HookWidget {
         PaginatedResultViewer<ably.Message>(
             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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -96,7 +96,7 @@ Future<Map<String, dynamic>> 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<Map<String, dynamic>> 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
@@ -41,7 +41,7 @@ Future<Map<String, dynamic>> 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
@@ -53,7 +53,7 @@ Future<Map<String, dynamic>> 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
@@ -77,7 +77,7 @@ Future<Map<String, dynamic>> 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<Map<String, dynamic>> 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
@@ -97,7 +97,7 @@ Future<Map<String, dynamic>> 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<Map<String, dynamic>> 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
@@ -34,7 +34,11 @@ Future<Map<String, dynamic>> 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
@@ -54,7 +54,7 @@ Future<Map<String, dynamic>> 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
@@ -77,7 +77,7 @@ Future<Map<String, dynamic>> 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<Map<String, dynamic>> 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