Implement startAfter and endBefore for RTDB queries (#7209)

jmwski · web-flow · commit b1766c2fd605 · 2021-01-13T18:34:05.000-08:00
diff --git a/FirebaseDatabase/CHANGELOG.md b/FirebaseDatabase/CHANGELOG.md
@@ -1,4 +1,5 @@
 # v7.5.0
+- [added] Implmement `queryStartingAfterValue` and `queryEndingBeforeValue` for FirebaseDatabase query pagination.
 - [added] Added `DatabaseQuery#getData` which returns data from the server when cache is stale (#7110).
 
 # v7.2.0
diff --git a/FirebaseDatabase/Sources/Api/FIRDatabaseQuery.m b/FirebaseDatabase/Sources/Api/FIRDatabaseQuery.m
@@ -28,6 +28,7 @@
 #import "FirebaseDatabase/Sources/FValueIndex.h"
 #import "FirebaseDatabase/Sources/Snapshot/FLeafNode.h"
 #import "FirebaseDatabase/Sources/Snapshot/FSnapshotUtilities.h"
+#import "FirebaseDatabase/Sources/Utilities/FNextPushId.h"
 #import "FirebaseDatabase/Sources/Utilities/FValidation.h"
 
 @implementation FIRDatabaseQuery
@@ -91,7 +92,8 @@ - (FQuerySpec *)querySpec {
 - (void)validateQueryEndpointsForParams:(FQueryParams *)params {
     if ([params.index isEqual:[FKeyIndex keyIndex]]) {
         if ([params hasStart]) {
-            if (params.indexStartKey != [FUtilities minName]) {
+            if (params.indexStartKey != [FUtilities minName] &&
+                params.indexStartKey != [FUtilities maxName]) {
                 [NSException raise:INVALID_QUERY_PARAM_ERROR
                             format:@"Can't use queryStartingAtValue:childKey: "
                                    @"or queryEqualTo:andChildKey: in "
@@ -106,7 +108,8 @@ - (void)validateQueryEndpointsForParams:(FQueryParams *)params {
             }
         }
         if ([params hasEnd]) {
-            if (params.indexEndKey != [FUtilities maxName]) {
+            if (params.indexEndKey != [FUtilities maxName] &&
+                params.indexEndKey != [FUtilities minName]) {
                 [NSException raise:INVALID_QUERY_PARAM_ERROR
                             format:@"Can't use queryEndingAtValue:childKey: or "
                                    @"queryEqualToValue:childKey: in "
@@ -183,9 +186,44 @@ - (FIRDatabaseQuery *)queryStartingAtValue:(id)startValue
                          @"queryOrderedByKey:"
                 userInfo:nil];
     }
+    NSString *methodName = @"queryStartingAtValue:childKey:";
+    if (childKey != nil) {
+        [FValidation validateFrom:methodName validKey:childKey];
+    }
     return [self queryStartingAtInternal:startValue
                                 childKey:childKey
-                                    from:@"queryStartingAtValue:childKey:"
+                                    from:methodName
+                          priorityMethod:NO];
+}
+
+- (FIRDatabaseQuery *)queryStartingAfterValue:(id)startAfterValue {
+    return [self queryStartingAfterValue:startAfterValue childKey:nil];
+}
+
+- (FIRDatabaseQuery *)queryStartingAfterValue:(id)startAfterValue
+                                     childKey:(NSString *)childKey {
+    if ([self.queryParams.index isEqual:[FKeyIndex keyIndex]] &&
+        childKey != nil) {
+        @throw [[NSException alloc]
+            initWithName:INVALID_QUERY_PARAM_ERROR
+                  reason:@"You must use queryStartingAfterValue: instead of "
+                         @"queryStartingAfterValue:childKey: when using "
+                         @"queryOrderedByKey:"
+                userInfo:nil];
+    }
+    if (childKey == nil) {
+        childKey = [FUtilities maxName];
+    } else {
+        childKey = [FNextPushId successor:childKey];
+        NSLog(@"successor of child key %@", childKey);
+    }
+    NSString *methodName = @"queryStartingAfterValue:childKey:";
+    if (childKey != nil && ![childKey isEqual:[FUtilities maxName]]) {
+        [FValidation validateFrom:methodName validKey:childKey];
+    }
+    return [self queryStartingAtInternal:startAfterValue
+                                childKey:childKey
+                                    from:methodName
                           priorityMethod:NO];
 }
 
@@ -194,9 +232,6 @@ - (FIRDatabaseQuery *)queryStartingAtInternal:(id<FNode>)startValue
                                          from:(NSString *)methodName
                                priorityMethod:(BOOL)priorityMethod {
     [self validateIndexValueType:startValue fromMethod:methodName];
-    if (childKey != nil) {
-        [FValidation validateFrom:methodName validKey:childKey];
-    }
     if ([self.queryParams hasStart]) {
         [NSException raise:INVALID_QUERY_PARAM_ERROR
                     format:@"Can't call %@ after queryStartingAtValue or "
@@ -232,10 +267,44 @@ - (FIRDatabaseQuery *)queryEndingAtValue:(id)endValue
                          @"queryOrderedByKey:"
                 userInfo:nil];
     }
+    NSString *methodName = @"queryEndingAtValue:childKey:";
+    if (childKey != nil) {
+        [FValidation validateFrom:methodName validKey:childKey];
+    }
+    return [self queryEndingAtInternal:endValue
+                              childKey:childKey
+                                  from:methodName
+                        priorityMethod:NO];
+}
 
+- (FIRDatabaseQuery *)queryEndingBeforeValue:(id)endValue {
+    return [self queryEndingBeforeValue:endValue childKey:nil];
+}
+
+- (FIRDatabaseQuery *)queryEndingBeforeValue:(id)endValue
+                                    childKey:(NSString *)childKey {
+    if ([self.queryParams.index isEqual:[FKeyIndex keyIndex]] &&
+        childKey != nil) {
+        @throw [[NSException alloc]
+            initWithName:INVALID_QUERY_PARAM_ERROR
+                  reason:@"You must use queryEndingBeforeValue: instead of "
+                         @"queryEndingBeforeValue:childKey: when using "
+                         @"queryOrderedByKey:"
+                userInfo:nil];
+    }
+
+    if (childKey == nil) {
+        childKey = [FUtilities minName];
+    } else {
+        childKey = [FNextPushId predecessor:childKey];
+    }
+    NSString *methodName = @"queryEndingBeforeValue:childKey:";
+    if (childKey != nil && ![childKey isEqual:[FUtilities minName]]) {
+        [FValidation validateFrom:methodName validKey:childKey];
+    }
     return [self queryEndingAtInternal:endValue
                               childKey:childKey
-                                  from:@"queryEndingAtValue:childKey:"
+                                  from:methodName
                         priorityMethod:NO];
 }
 
@@ -244,9 +313,6 @@ - (FIRDatabaseQuery *)queryEndingAtInternal:(id)endValue
                                        from:(NSString *)methodName
                              priorityMethod:(BOOL)priorityMethod {
     [self validateIndexValueType:endValue fromMethod:methodName];
-    if (childKey != nil) {
-        [FValidation validateFrom:methodName validKey:childKey];
-    }
     if ([self.queryParams hasEnd]) {
         [NSException raise:INVALID_QUERY_PARAM_ERROR
                     format:@"Can't call %@ after queryEndingAtValue or "
diff --git a/FirebaseDatabase/Sources/FIRDatabaseReference.m b/FirebaseDatabase/Sources/FIRDatabaseReference.m
@@ -472,6 +472,15 @@ - (FIRDatabaseQuery *)queryStartingAtValue:(id)startValue
     return [super queryStartingAtValue:startValue childKey:childKey];
 }
 
+- (FIRDatabaseQuery *)queryStartingAfterValue:(id)startAfterValue {
+    return [super queryStartingAfterValue:startAfterValue];
+}
+
+- (FIRDatabaseQuery *)queryStartingAfterValue:(id)startAfterValue
+                                     childKey:(NSString *)childKey {
+    return [super queryStartingAfterValue:startAfterValue childKey:childKey];
+}
+
 - (FIRDatabaseQuery *)queryEndingAtValue:(id)endValue {
     return [super queryEndingAtValue:endValue];
 }
diff --git a/FirebaseDatabase/Sources/Public/FirebaseDatabase/FIRDatabaseQuery.h b/FirebaseDatabase/Sources/Public/FirebaseDatabase/FIRDatabaseQuery.h
@@ -327,6 +327,36 @@ NS_SWIFT_NAME(DatabaseQuery)
 - (FIRDatabaseQuery *)queryStartingAtValue:(nullable id)startValue
                                   childKey:(nullable NSString *)childKey;
 
+/**
+ * queryStartingAfterValue: is used to generate a reference to a
+ * limited view of the data at this location. The FIRDatabaseQuery instance
+ * returned by queryStartingAfterValue: will respond to events at nodes
+ * with a value greater than startAfterValue.
+ *
+ * @param startAfterValue The lower bound, exclusive, for the value of data
+ * visible to the returned FIRDatabaseQuery
+ * @return A FIRDatabaseQuery instance, limited to data with value greater
+ * startAfterValue
+ */
+- (FIRDatabaseQuery *)queryStartingAfterValue:(nullable id)startAfterValue;
+
+/**
+ * queryStartingAfterValue:childKey: is used to generate a reference to a
+ * limited view of the data at this location. The FIRDatabaseQuery instance
+ * returned by queryStartingAfterValue:childKey will respond to events at nodes
+ * with a value greater than startAfterValue, or equal to startAfterValue and
+ * with a key greater than childKey. This is most useful when implementing
+ * pagination in a case where multiple nodes can match the startAfterValue.
+ *
+ * @param startAfterValue The lower bound, inclusive, for the value of data
+ * visible to the returned FIRDatabaseQuery
+ * @param childKey The lower bound, exclusive, for the key of nodes with value
+ * equal to startAfterValue
+ * @return A FIRDatabaseQuery instance, limited to data with value greater than
+ * startAfterValue, or equal to startAfterValue with a key greater than childKey
+ */
+- (FIRDatabaseQuery *)queryStartingAfterValue:(nullable id)startAfterValue
+                                     childKey:(nullable NSString *)childKey;
 /**
  * queryEndingAtValue: is used to generate a reference to a limited view of the
  * data at this location. The FIRDatabaseQuery instance returned by
@@ -358,6 +388,35 @@ NS_SWIFT_NAME(DatabaseQuery)
 - (FIRDatabaseQuery *)queryEndingAtValue:(nullable id)endValue
                                 childKey:(nullable NSString *)childKey;
 
+/**
+ * queryEndingBeforeValue: is used to generate a reference to a limited view of
+ * the data at this location. The FIRDatabaseQuery instance returned by
+ * queryEndingBeforeValue: will respond to events at nodes with a value less
+ * than endValue.
+ *
+ * @param endValue The upper bound, exclusive, for the value of data visible to
+ * the returned FIRDatabaseQuery
+ * @return A FIRDatabaseQuery instance, limited to data with value less than
+ * endValue
+ */
+- (FIRDatabaseQuery *)queryEndingBeforeValue:(nullable id)endValue;
+
+/**
+ * queryEndingBeforeValue:childKey: is used to generate a reference to a limited
+ * view of the data at this location. The FIRDatabaseQuery instance returned by
+ * queryEndingBeforeValue:childKey will respond to events at nodes with a value
+ * less than endValue, or equal to endValue and with a key less than childKey.
+ *
+ * @param endValue The upper bound, inclusive, for the value of data visible to
+ * the returned FIRDatabaseQuery
+ * @param childKey The upper bound, exclusive, for the key of nodes with value
+ * equal to endValue
+ * @return A FIRDatabaseQuery instance, limited to data with value less than or
+ * equal to endValue
+ */
+- (FIRDatabaseQuery *)queryEndingBeforeValue:(nullable id)endValue
+                                    childKey:(nullable NSString *)childKey;
+
 /**
  * queryEqualToValue: is used to generate a reference to a limited view of the
  * data at this location. The FIRDatabaseQuery instance returned by
diff --git a/FirebaseDatabase/Sources/Public/FirebaseDatabase/FIRDatabaseReference.h b/FirebaseDatabase/Sources/Public/FirebaseDatabase/FIRDatabaseReference.h
@@ -483,6 +483,38 @@ priority is meant to be preserved, you should use setValue:andPriority: instead.
 - (FIRDatabaseQuery *)queryStartingAtValue:(nullable id)startValue
                                   childKey:(nullable NSString *)childKey;
 
+/**
+ * queryStartingAfterValue: is used to generate a reference to a limited view of
+ * the data at this location. The FIRDatabaseQuery instance returned by
+ * queryStartingAfterValue: will respond to events at nodes with a value greater
+ * than startAfterValue.
+ *
+ * @param startAfterValue The lower bound, exclusive, for the value of data
+ * visible to the returned FIRDatabaseQuery
+ * @return A FIRDatabaseQuery instance, limited to data with value greater than
+ * startAfterValue
+ */
+- (FIRDatabaseQuery *)queryStartingAfterValue:(nullable id)startAfterValue;
+
+/**
+ * queryStartingAfterValue:childKey: is used to generate a reference to a
+ * limited view of the data at this location. The FIRDatabaseQuery instance
+ * returned by queryStartingAfterValue:childKey will respond to events at nodes
+ * with a value greater than startAfterValue, or equal to startAfterValue and
+ * with a key greater than childKey. This is most useful when implementing
+ * pagination in a case where multiple nodes can match the startAfterValue.
+ *
+ * @param startAfterValue The lower bound, inclusive, for the value of data
+ * visible to the returned FIRDatabaseQuery
+ * @param childKey The lower bound, exclusive, for the key of nodes with value
+ * equal to startAfterValue
+ * @return A FIRDatabaseQuery instance, limited to data with value greater than
+ * or equal to startAfterValue, or equal to startAfterValue and with a key
+ * greater than childKey.
+ */
+- (FIRDatabaseQuery *)queryStartingAfterValue:(nullable id)startAfterValue
+                                     childKey:(nullable NSString *)childKey;
+
 /**
  * queryEndingAtValue: is used to generate a reference to a limited view of the
  * data at this location. The FIRDatabaseQuery instance returned by
diff --git a/FirebaseDatabase/Sources/Utilities/FNextPushId.h b/FirebaseDatabase/Sources/Utilities/FNextPushId.h
@@ -20,4 +20,8 @@
 
 + (NSString *)get:(NSTimeInterval)now;
 
++ (NSString *)successor:(NSString *)key;
+
++ (NSString *)predecessor:(NSString *)key;
+
 @end
diff --git a/FirebaseDatabase/Sources/Utilities/FNextPushId.m b/FirebaseDatabase/Sources/Utilities/FNextPushId.m
@@ -20,6 +20,12 @@
 static NSString *const PUSH_CHARS =
     @"-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz";
 
+static NSString *const MIN_PUSH_CHAR = @"-";
+
+static NSString *const MAX_PUSH_CHAR = @"z";
+
+static NSInteger const MAX_KEY_LEN = 786;
+
 @implementation FNextPushId
 
 + (NSString *)get:(NSTimeInterval)currentTime {
@@ -59,4 +65,80 @@ + (NSString *)get:(NSTimeInterval)currentTime {
     return [NSString stringWithString:id];
 }
 
++ (NSString *)successor:(NSString *_Nonnull)key {
+    NSInteger keyAsInt;
+    if ([FUtilities tryParseString:key asInt:&keyAsInt]) {
+        if (keyAsInt == [FUtilities int32max]) {
+            return MIN_PUSH_CHAR;
+        }
+        return [NSString stringWithFormat:@"%ld", (long)keyAsInt + 1];
+    }
+    NSMutableString *next = [NSMutableString stringWithString:key];
+    if ([next length] < MAX_KEY_LEN) {
+        [next insertString:MIN_PUSH_CHAR atIndex:[key length]];
+        return next;
+    }
+
+    long i = [next length] - 1;
+    while (i >= 0) {
+        if ([next characterAtIndex:i] != [MAX_PUSH_CHAR characterAtIndex:0]) {
+            break;
+        }
+        --i;
+    }
+
+    // `nextAfter` was called on the largest possible key, so return the
+    // maxName, which sorts larger than all keys.
+    if (i == -1) {
+        return [FUtilities maxName];
+    }
+
+    NSString *source =
+        [NSString stringWithFormat:@"%C", [next characterAtIndex:i]];
+    NSInteger sourceIndex = [PUSH_CHARS rangeOfString:source].location;
+    NSString *sourcePlusOne = [NSString
+        stringWithFormat:@"%C", [PUSH_CHARS characterAtIndex:sourceIndex + 1]];
+
+    [next replaceCharactersInRange:NSMakeRange(i, i + 1)
+                        withString:sourcePlusOne];
+    return [next substringWithRange:NSMakeRange(0, i + 1)];
+}
+
+// `key` is assumed to be non-empty.
++ (NSString *)predecessor:(NSString *_Nonnull)key {
+    NSInteger keyAsInt;
+    if ([FUtilities tryParseString:key asInt:&keyAsInt]) {
+        if (keyAsInt == [FUtilities int32min]) {
+            return [FUtilities minName];
+        }
+        return [NSString stringWithFormat:@"%ld", (long)keyAsInt - 1];
+    }
+    NSMutableString *next = [NSMutableString stringWithString:key];
+    if ([next characterAtIndex:(next.length - 1)] ==
+        [MIN_PUSH_CHAR characterAtIndex:0]) {
+        if ([next length] == 1) {
+            return
+                [NSString stringWithFormat:@"%ld", (long)[FUtilities int32max]];
+        }
+        // If the last character is the smallest possible character, then the
+        // next smallest string is the prefix of `key` without it.
+        [next replaceCharactersInRange:NSMakeRange([next length] - 1, 1)
+                            withString:@""];
+        return next;
+    }
+    // Replace the last character with its immedate predecessor, and fill the
+    // suffix of the key with MAX_PUSH_CHAR. This is the lexicographically
+    // largest possible key smaller than `key`.
+    unichar curr = [next characterAtIndex:next.length - 1];
+    NSRange dstRange = NSMakeRange([next length] - 1, 1);
+    NSRange srcRange =
+        [PUSH_CHARS rangeOfString:[NSString stringWithFormat:@"%C", curr]];
+    srcRange.location -= 1;
+    [next replaceCharactersInRange:dstRange
+                        withString:[PUSH_CHARS substringWithRange:srcRange]];
+    return [next stringByPaddingToLength:MAX_KEY_LEN
+                              withString:MAX_PUSH_CHAR
+                         startingAtIndex:0];
+};
+
 @end
diff --git a/FirebaseDatabase/Sources/Utilities/FUtilities.h b/FirebaseDatabase/Sources/Utilities/FUtilities.h
@@ -27,7 +27,10 @@
 + (NSString *)getJavascriptType:(id)obj;
 + (NSError *)errorForStatus:(NSString *)status andReason:(NSString *)reason;
 + (NSNumber *)intForString:(NSString *)string;
++ (NSInteger)int32min;
++ (NSInteger)int32max;
 + (NSString *)ieee754StringForNumber:(NSNumber *)val;
++ (BOOL)tryParseString:(NSString *)string asInt:(NSInteger *)integer;
 + (void)setLoggingEnabled:(BOOL)enabled;
 + (BOOL)getLoggingEnabled;
 
@@ -76,6 +79,9 @@ FOUNDATION_EXPORT NSString *const kFPersistenceLogTag;
         }                                                                      \
     } while (0)
 
+#define INTEGER_32_MIN (-2147483648)
+#define INTEGER_32_MAX 2147483647
+
 extern FIRLoggerService kFIRLoggerDatabase;
 BOOL FFIsLoggingEnabled(FLogLevel logLevel);
 void firebaseUncaughtExceptionHandler(NSException *exception);
diff --git a/FirebaseDatabase/Sources/Utilities/FUtilities.m b/FirebaseDatabase/Sources/Utilities/FUtilities.m
diff --git a/FirebaseDatabase/Tests/Helpers/FTestExpectations.m b/FirebaseDatabase/Tests/Helpers/FTestExpectations.m
diff --git a/FirebaseDatabase/Tests/Integration/FIRDatabaseQueryTests.m b/FirebaseDatabase/Tests/Integration/FIRDatabaseQueryTests.m
diff --git a/FirebaseDatabase/Tests/Unit/FNextPushIdTest.m b/FirebaseDatabase/Tests/Unit/FNextPushIdTest.m

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`# v7.5.0`
	`2`	+- [added] Implmement `queryStartingAfterValue` and `queryEndingBeforeValue` for FirebaseDatabase query pagination.
`2`	`3`	- [added] Added `DatabaseQuery#getData` which returns data from the server when cache is stale (#7110).
`3`	`4`
`4`	`5`	`# v7.2.0`