Release 4.3.0 (#327)

Initial release of Firestore at 0.8.0
Bump FirebaseCommunity to 0.1.3

1 files changed, 414 insertions, 0 deletions

diff --git a/Firestore/Source/Public/FIRQuery.h b/Firestore/Source/Public/FIRQuery.h
new file mode 100644
index 0000000..5c5546d
--- /dev/null
+++ b/Firestore/Source/Public/FIRQuery.h
@@ -0,0 +1,414 @@
+/*
+ * Copyright 2017 Google
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#import <Foundation/Foundation.h>
+
+#import "FIRFirestoreSwiftNameSupport.h"
+#import "FIRListenerRegistration.h"
+
+@class FIRFieldPath;
+@class FIRFirestore;
+@class FIRQuerySnapshot;
+@class FIRDocumentSnapshot;
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Options for use with `[FIRQuery addSnapshotListener]` to control the behavior of the snapshot
+ * listener.
+ */
+FIR_SWIFT_NAME(QueryListenOptions)
+@interface FIRQueryListenOptions : NSObject
+
++ (instancetype)options NS_SWIFT_UNAVAILABLE("Use initializer");
+
+- (instancetype)init;
+
+@property(nonatomic, assign, readonly) BOOL includeQueryMetadataChanges;
+
+/**
+ * Sets the includeQueryMetadataChanges option which controls whether metadata-only changes on the
+ * query (i.e. only `FIRQuerySnapshot.metadata` changed) should trigger snapshot events. Default is
+ * NO.
+ *
+ * @param includeQueryMetadataChanges Whether to raise events for metadata-only changes on the
+ *     query.
+ * @return The receiver is returned for optional method chaining.
+ */
+- (instancetype)includeQueryMetadataChanges:(BOOL)includeQueryMetadataChanges
+    FIR_SWIFT_NAME(includeQueryMetadataChanges(_:));
+
+@property(nonatomic, assign, readonly) BOOL includeDocumentMetadataChanges;
+
+/**
+ * Sets the includeDocumentMetadataChanges option which controls whether document metadata-only
+ * changes (i.e. only `FIRDocumentSnapshot.metadata` on a document contained in the query
+ * changed) should trigger snapshot events. Default is NO.
+ *
+ * @param includeDocumentMetadataChanges Whether to raise events for document metadata-only changes.
+ * @return The receiver is returned for optional method chaining.
+ */
+- (instancetype)includeDocumentMetadataChanges:(BOOL)includeDocumentMetadataChanges
+    FIR_SWIFT_NAME(includeDocumentMetadataChanges(_:));
+
+@end
+
+typedef void (^FIRQuerySnapshotBlock)(FIRQuerySnapshot *_Nullable snapshot,
+                                      NSError *_Nullable error);
+
+/**
+ * A `FIRQuery` refers to a Query which you can read or listen to. You can also construct
+ * refined `FIRQuery` objects by adding filters and ordering.
+ */
+FIR_SWIFT_NAME(Query)
+@interface FIRQuery : NSObject
+/**   */
+- (id)init __attribute__((unavailable("FIRQuery cannot be created directly.")));
+
+/** The `FIRFirestore` for the Firestore database (useful for performing transactions, etc.). */
+@property(nonatomic, strong, readonly) FIRFirestore *firestore;
+
+#pragma mark - Retrieving Data
+/**
+ * Reads the documents matching this query.
+ *
+ * @param completion a block to execute once the documents have been successfully read.
+ *     documentSet will be `nil` only if error is `non-nil`.
+ */
+- (void)getDocumentsWithCompletion:(FIRQuerySnapshotBlock)completion
+    FIR_SWIFT_NAME(getDocuments(completion:));
+
+/**
+ * Attaches a listener for QuerySnapshot events.
+ *
+ * @param listener The listener to attach.
+ *
+ * @return A FIRListenerRegistration that can be used to remove this listener.
+ */
+- (id<FIRListenerRegistration>)addSnapshotListener:(FIRQuerySnapshotBlock)listener
+    FIR_SWIFT_NAME(addSnapshotListener(_:));
+
+/**
+ * Attaches a listener for QuerySnapshot events.
+ *
+ * @param options Options controlling the listener behavior.
+ * @param listener The listener to attach.
+ *
+ * @return A FIRListenerRegistration that can be used to remove this listener.
+ */
+// clang-format off
+- (id<FIRListenerRegistration>)addSnapshotListenerWithOptions:
+                                   (nullable FIRQueryListenOptions *)options
+                                                     listener:(FIRQuerySnapshotBlock)listener
+    FIR_SWIFT_NAME(addSnapshotListener(options:listener:));
+// clang-format on
+
+#pragma mark - Filtering Data
+/**
+ * Creates and returns a new `FIRQuery` with the additional filter that documents must
+ * contain the specified field and the value must be equal to the specified value.
+ *
+ * @param field The name of the field to compare.
+ * @param value The value the field must be equal to.
+ *
+ * @return The created `FIRQuery`.
+ */
+// clang-format off
+- (FIRQuery *)queryWhereField:(NSString *)field
+                    isEqualTo:(id)value FIR_SWIFT_NAME(whereField(_:isEqualTo:));
+// clang-format on
+
+/**
+ * Creates and returns a new `FIRQuery` with the additional filter that documents must
+ * contain the specified field and the value must be equal to the specified value.
+ *
+ * @param path The path of the field to compare.
+ * @param value The value the field must be equal to.
+ *
+ * @return The created `FIRQuery`.
+ */
+// clang-format off
+- (FIRQuery *)queryWhereFieldPath:(FIRFieldPath *)path
+                        isEqualTo:(id)value FIR_SWIFT_NAME(whereField(_:isEqualTo:));
+// clang-format on
+
+/**
+ * Creates and returns a new `FIRQuery` with the additional filter that documents must
+ * contain the specified field and the value must be less than the specified value.
+ *
+ * @param field The name of the field to compare.
+ * @param value The value the field must be less than.
+ *
+ * @return The created `FIRQuery`.
+ */
+// clang-format off
+- (FIRQuery *)queryWhereField:(NSString *)field
+                   isLessThan:(id)value FIR_SWIFT_NAME(whereField(_:isLessThan:));
+// clang-format on
+
+/**
+ * Creates and returns a new `FIRQuery` with the additional filter that documents must
+ * contain the specified field and the value must be less than the specified value.
+ *
+ * @param path The path of the field to compare.
+ * @param value The value the field must be less than.
+ *
+ * @return The created `FIRQuery`.
+ */
+// clang-format off
+- (FIRQuery *)queryWhereFieldPath:(FIRFieldPath *)path
+                       isLessThan:(id)value FIR_SWIFT_NAME(whereField(_:isLessThan:));
+// clang-format on
+
+/**
+ * Creates and returns a new `FIRQuery` with the additional filter that documents must
+ * contain the specified field and the value must be less than or equal to the specified value.
+ *
+ * @param field The name of the field to compare
+ * @param value The value the field must be less than or equal to.
+ *
+ * @return The created `FIRQuery`.
+ */
+// clang-format off
+- (FIRQuery *)queryWhereField:(NSString *)field
+          isLessThanOrEqualTo:(id)value FIR_SWIFT_NAME(whereField(_:isLessThanOrEqualTo:));
+// clang-format on
+
+/**
+ * Creates and returns a new `FIRQuery` with the additional filter that documents must
+ * contain the specified field and the value must be less than or equal to the specified value.
+ *
+ * @param path The path of the field to compare
+ * @param value The value the field must be less than or equal to.
+ *
+ * @return The created `FIRQuery`.
+ */
+// clang-format off
+- (FIRQuery *)queryWhereFieldPath:(FIRFieldPath *)path
+              isLessThanOrEqualTo:(id)value FIR_SWIFT_NAME(whereField(_:isLessThanOrEqualTo:));
+// clang-format on
+
+/**
+ * Creates and returns a new `FIRQuery` with the additional filter that documents must
+ * contain the specified field and the value must greater than the specified value.
+ *
+ * @param field The name of the field to compare
+ * @param value The value the field must be greater than.
+ *
+ * @return The created `FIRQuery`.
+ */
+// clang-format off
+- (FIRQuery *)queryWhereField:(NSString *)field
+                isGreaterThan:(id)value FIR_SWIFT_NAME(whereField(_:isGreaterThan:));
+// clang-format on
+
+/**
+ * Creates and returns a new `FIRQuery` with the additional filter that documents must
+ * contain the specified field and the value must greater than the specified value.
+ *
+ * @param path The path of the field to compare
+ * @param value The value the field must be greater than.
+ *
+ * @return The created `FIRQuery`.
+ */
+// clang-format off
+- (FIRQuery *)queryWhereFieldPath:(FIRFieldPath *)path
+                    isGreaterThan:(id)value FIR_SWIFT_NAME(whereField(_:isGreaterThan:));
+// clang-format on
+
+/**
+ * Creates and returns a new `FIRQuery` with the additional filter that documents must
+ * contain the specified field and the value must be greater than or equal to the specified value.
+ *
+ * @param field The name of the field to compare
+ * @param value The value the field must be greater than.
+ *
+ * @return The created `FIRQuery`.
+ */
+// clang-format off
+- (FIRQuery *)queryWhereField:(NSString *)field
+       isGreaterThanOrEqualTo:(id)value FIR_SWIFT_NAME(whereField(_:isGreaterThanOrEqualTo:));
+// clang-format on
+
+/**
+ * Creates and returns a new `FIRQuery` with the additional filter that documents must
+ * contain the specified field and the value must be greater than or equal to the specified value.
+ *
+ * @param path The path of the field to compare
+ * @param value The value the field must be greater than.
+ *
+ * @return The created `FIRQuery`.
+ */
+// clang-format off
+- (FIRQuery *)queryWhereFieldPath:(FIRFieldPath *)path
+           isGreaterThanOrEqualTo:(id)value FIR_SWIFT_NAME(whereField(_:isGreaterThanOrEqualTo:));
+// clang-format on
+
+#pragma mark - Sorting Data
+/**
+ * Creates and returns a new `FIRQuery` that's additionally sorted by the specified field.
+ *
+ * @param field The field to sort by.
+ *
+ * @return The created `FIRQuery`.
+ */
+- (FIRQuery *)queryOrderedByField:(NSString *)field FIR_SWIFT_NAME(order(by:));
+
+/**
+ * Creates and returns a new `FIRQuery` that's additionally sorted by the specified field.
+ *
+ * @param path The field to sort by.
+ *
+ * @return The created `FIRQuery`.
+ */
+- (FIRQuery *)queryOrderedByFieldPath:(FIRFieldPath *)path FIR_SWIFT_NAME(order(by:));
+
+/**
+ * Creates and returns a new `FIRQuery` that's additionally sorted by the specified field,
+ * optionally in descending order instead of ascending.
+ *
+ * @param field The field to sort by.
+ * @param descending Whether to sort descending.
+ *
+ * @return The created `FIRQuery`.
+ */
+// clang-format off
+- (FIRQuery *)queryOrderedByField:(NSString *)field
+                       descending:(BOOL)descending FIR_SWIFT_NAME(order(by:descending:));
+// clang-format on
+
+/**
+ * Creates and returns a new `FIRQuery` that's additionally sorted by the specified field,
+ * optionally in descending order instead of ascending.
+ *
+ * @param path The field to sort by.
+ * @param descending Whether to sort descending.
+ *
+ * @return The created `FIRQuery`.
+ */
+// clang-format off
+- (FIRQuery *)queryOrderedByFieldPath:(FIRFieldPath *)path
+                           descending:(BOOL)descending FIR_SWIFT_NAME(order(by:descending:));
+// clang-format on
+
+#pragma mark - Limiting Data
+/**
+ * Creates and returns a new `FIRQuery` that's additionally limited to only return up to
+ * the specified number of documents.
+ *
+ * @param limit The maximum number of items to return.
+ *
+ * @return The created `FIRQuery`.
+ */
+- (FIRQuery *)queryLimitedTo:(NSInteger)limit FIR_SWIFT_NAME(limit(to:));
+
+#pragma mark - Choosing Endpoints
+/**
+ * Creates and returns a new `FIRQuery` that starts at the provided document (inclusive). The
+ * starting position is relative to the order of the query. The document must contain all of the
+ * fields provided in the orderBy of this query.
+ *
+ * @param document The snapshot of the document to start at.
+ *
+ * @return The created `FIRQuery`.
+ */
+- (FIRQuery *)queryStartingAtDocument:(FIRDocumentSnapshot *)document
+    FIR_SWIFT_NAME(start(atDocument:));
+
+/**
+ * Creates and returns a new `FIRQuery` that starts at the provided fields relative to the order of
+ * the query. The order of the field values must match the order of the order by clauses of the
+ * query.
+ *
+ * @param fieldValues The field values to start this query at, in order of the query's order by.
+ *
+ * @return The created `FIRQuery`.
+ */
+- (FIRQuery *)queryStartingAtValues:(NSArray *)fieldValues FIR_SWIFT_NAME(start(at:));
+
+/**
+ * Creates and returns a new `FIRQuery` that starts after the provided document (exclusive). The
+ * starting position is relative to the order of the query. The document must contain all of the
+ * fields provided in the orderBy of this query.
+ *
+ * @param document The snapshot of the document to start after.
+ *
+ * @return The created `FIRQuery`.
+ */
+- (FIRQuery *)queryStartingAfterDocument:(FIRDocumentSnapshot *)document
+    FIR_SWIFT_NAME(start(afterDocument:));
+
+/**
+ * Creates and returns a new `FIRQuery` that starts after the provided fields relative to the order
+ * of the query. The order of the field values must match the order of the order by clauses of the
+ * query.
+ *
+ * @param fieldValues The field values to start this query after, in order of the query's order
+ *     by.
+ *
+ * @return The created `FIRQuery`.
+ */
+- (FIRQuery *)queryStartingAfterValues:(NSArray *)fieldValues FIR_SWIFT_NAME(start(after:));
+
+/**
+ * Creates and returns a new `FIRQuery` that ends before the provided document (exclusive). The end
+ * position is relative to the order of the query. The document must contain all of the fields
+ * provided in the orderBy of this query.
+ *
+ * @param document The snapshot of the document to end before.
+ *
+ * @return The created `FIRQuery`.
+ */
+- (FIRQuery *)queryEndingBeforeDocument:(FIRDocumentSnapshot *)document
+    FIR_SWIFT_NAME(end(beforeDocument:));
+
+/**
+ * Creates and returns a new `FIRQuery` that ends before the provided fields relative to the order
+ * of the query. The order of the field values must match the order of the order by clauses of the
+ * query.
+ *
+ * @param fieldValues The field values to end this query before, in order of the query's order by.
+ *
+ * @return The created `FIRQuery`.
+ */
+- (FIRQuery *)queryEndingBeforeValues:(NSArray *)fieldValues FIR_SWIFT_NAME(end(before:));
+
+/**
+ * Creates and returns a new `FIRQuery` that ends at the provided document (exclusive). The end
+ * position is relative to the order of the query. The document must contain all of the fields
+ * provided in the orderBy of this query.
+ *
+ * @param document The snapshot of the document to end at.
+ *
+ * @return The created `FIRQuery`.
+ */
+- (FIRQuery *)queryEndingAtDocument:(FIRDocumentSnapshot *)document
+    FIR_SWIFT_NAME(end(atDocument:));
+
+/**
+ * Creates and returns a new `FIRQuery` that ends at the provided fields relative to the order of
+ * the query. The order of the field values must match the order of the order by clauses of the
+ * query.
+ *
+ * @param fieldValues The field values to end this query at, in order of the query's order by.
+ *
+ * @return The created `FIRQuery`.
+ */
+- (FIRQuery *)queryEndingAtValues:(NSArray *)fieldValues FIR_SWIFT_NAME(end(at:));
+
+@end
+
+NS_ASSUME_NONNULL_END