firebase-ios-sdk/Firestore/Source/Model/FSTFieldValue.h

/*
 * 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 "Firestore/third_party/Immutable/FSTImmutableSortedDictionary.h"

@class FSTDatabaseID;
@class FSTDocumentKey;
@class FSTFieldPath;
@class FSTTimestamp;
@class FSTFieldValueOptions;
@class FIRGeoPoint;
@class FIRSnapshotOptions;

NS_ASSUME_NONNULL_BEGIN

/** The order of types in Firestore; this order is defined by the backend. */
typedef NS_ENUM(NSInteger, FSTTypeOrder) {
  FSTTypeOrderNull,
  FSTTypeOrderBoolean,
  FSTTypeOrderNumber,
  FSTTypeOrderTimestamp,
  FSTTypeOrderString,
  FSTTypeOrderBlob,
  FSTTypeOrderReference,
  FSTTypeOrderGeoPoint,
  FSTTypeOrderArray,
  FSTTypeOrderObject,
};

/** Defines the return value for pending server timestamps. */
typedef NS_ENUM(NSInteger, FSTServerTimestampBehavior) {
  FSTServerTimestampBehaviorNone,
  FSTServerTimestampBehaviorEstimate,
  FSTServerTimestampBehaviorPrevious
};

/** Holds properties that define field value deserialization options. */
@interface FSTFieldValueOptions : NSObject

@property(nonatomic, readonly, assign) FSTServerTimestampBehavior serverTimestampBehavior;

- (instancetype)init NS_UNAVAILABLE;

/**
 * Creates an FSTFieldValueOptions instance that specifies deserialization behavior for pending
 * server timestamps.
 */
- (instancetype)initWithServerTimestampBehavior:(FSTServerTimestampBehavior)serverTimestampBehavior
    NS_DESIGNATED_INITIALIZER;

/** Creates an FSTFieldValueOption instance from FIRSnapshotOptions. */
+ (instancetype)optionsForSnapshotOptions:(FIRSnapshotOptions *)value;

@end

/**
 * Abstract base class representing an immutable data value as stored in Firestore. FSTFieldValue
 * represents all the different kinds of values that can be stored in fields in a document.
 *
 * Supported types are:
 *  - Null
 *  - Boolean
 *  - Long
 *  - Double
 *  - Timestamp
 *  - ServerTimestamp (a sentinel used in uncommitted writes)
 *  - String
 *  - Binary
 *  - (Document) References
 *  - GeoPoint
 *  - Array
 *  - Object
 */
@interface FSTFieldValue <__covariant T> : NSObject

/** Returns the FSTTypeOrder for this value. */
- (FSTTypeOrder)typeOrder;

/**
 * Converts an FSTFieldValue into the value that users will see in document snapshots.
 *
 * TODO(mikelehen): This conversion should probably happen at the API level and right now `value` is
 * used inappropriately in the serializer implementation, etc.  We need to do some reworking.
 */
- (T)value;

/**
 * Converts an FSTFieldValue into the value that users will see in document snapshots.
 *
 * Options can be provided to configure the deserialization of some field values (such as server
 * timestamps).
 */
- (T)valueWithOptions:(FSTFieldValueOptions *)options;

/** Compares against another FSTFieldValue. */
- (NSComparisonResult)compare:(FSTFieldValue *)other;

@end

/**
 * A null value stored in Firestore. The |value| of a FSTNullValue is [NSNull null].
 */
@interface FSTNullValue : FSTFieldValue <NSNull *>
+ (instancetype)nullValue;
@end

/**
 * A boolean value stored in Firestore.
 */
@interface FSTBooleanValue : FSTFieldValue <NSNumber *>
+ (instancetype)trueValue;
+ (instancetype)falseValue;
+ (instancetype)booleanValue:(BOOL)value;
@end

/**
 * Base class inherited from by FSTIntegerValue and FSTDoubleValue. It implements proper number
 * comparisons between the two types.
 */
@interface FSTNumberValue : FSTFieldValue <NSNumber *>
@end

/**
 * An integer value stored in Firestore.
 */
@interface FSTIntegerValue : FSTNumberValue
+ (instancetype)integerValue:(int64_t)value;
- (int64_t)internalValue;
@end

/**
 * A double-precision floating point number stored in Firestore.
 */
@interface FSTDoubleValue : FSTNumberValue
+ (instancetype)doubleValue:(double)value;
+ (instancetype)nanValue;
- (double)internalValue;
@end

/**
 * A string stored in Firestore.
 */
@interface FSTStringValue : FSTFieldValue <NSString *>
+ (instancetype)stringValue:(NSString *)value;
@end

/**
 * A timestamp value stored in Firestore.
 */
@interface FSTTimestampValue : FSTFieldValue <NSDate *>
+ (instancetype)timestampValue:(FSTTimestamp *)value;
- (FSTTimestamp *)internalValue;
@end

/**
 * Represents a locally-applied Server Timestamp.
 *
 * Notes:
 * - FSTServerTimestampValue instances are created as the result of applying an FSTTransformMutation
 *   (see [FSTTransformMutation applyTo]). They can only exist in the local view of a document.
 *   Therefore they do not need to be parsed or serialized.
 * - When evaluated locally (e.g. via FSTDocumentSnapshot data), they by default evaluate to NSNull.
 *   This behavior can be configured by passing custom FSTFieldValueOptions to `valueWithOptions:`.
 * - They sort after all FSTTimestampValues. With respect to other FSTServerTimestampValues, they
 *   sort by their localWriteTime.
 */
@interface FSTServerTimestampValue : FSTFieldValue <id>
+ (instancetype)serverTimestampValueWithLocalWriteTime:(FSTTimestamp *)localWriteTime
                                         previousValue:(nullable FSTFieldValue *)previousValue;

@property(nonatomic, strong, readonly) FSTTimestamp *localWriteTime;
@property(nonatomic, strong, readonly, nullable) FSTFieldValue *previousValue;

@end

/**
 * A geo point value stored in Firestore.
 */
@interface FSTGeoPointValue : FSTFieldValue <FIRGeoPoint *>
+ (instancetype)geoPointValue:(FIRGeoPoint *)value;
- (FIRGeoPoint *)valueWithOptions:(FSTFieldValueOptions *)options;
@end

/**
 * A blob value stored in Firestore.
 */
@interface FSTBlobValue : FSTFieldValue <NSData *>
+ (instancetype)blobValue:(NSData *)value;
- (NSData *)valueWithOptions:(FSTFieldValueOptions *)options;
@end

/**
 * A reference value stored in Firestore.
 */
@interface FSTReferenceValue : FSTFieldValue <FSTDocumentKey *>
+ (instancetype)referenceValue:(FSTDocumentKey *)value databaseID:(FSTDatabaseID *)databaseID;
- (FSTDocumentKey *)valueWithOptions:(FSTFieldValueOptions *)options;
@property(nonatomic, strong, readonly) FSTDatabaseID *databaseID;
@end

/**
 * A structured object value stored in Firestore.
 */
// clang-format off
@interface FSTObjectValue : FSTFieldValue < NSDictionary<NSString *, id> * >

- (instancetype)init NS_UNAVAILABLE;
// clang-format on

/** Returns an empty FSTObjectValue. */
+ (instancetype)objectValue;

/**
 * Initializes this FSTObjectValue with the given dictionary.
 */
- (instancetype)initWithDictionary:(NSDictionary<NSString *, FSTFieldValue *> *)value;

/**
 * Initializes this FSTObjectValue with the given immutable dictionary.
 */
- (instancetype)initWithImmutableDictionary:
    (FSTImmutableSortedDictionary<NSString *, FSTFieldValue *> *)value NS_DESIGNATED_INITIALIZER;

- (NSDictionary<NSString *, id> *)valueWithOptions:(FSTFieldValueOptions *)options;
- (FSTImmutableSortedDictionary<NSString *, FSTFieldValue *> *)internalValue;

/** Returns the value at the given path if it exists. Returns nil otherwise. */
- (nullable FSTFieldValue *)valueForPath:(FSTFieldPath *)fieldPath;

/**
 * Returns a new object where the field at the named path has its value set to the given value.
 * This object remains unmodified.
 */
- (FSTObjectValue *)objectBySettingValue:(FSTFieldValue *)value forPath:(FSTFieldPath *)fieldPath;

/**
 * Returns a new object where the field at the named path has been removed. If any segment of the
 * path does not exist within this object's structure, no change is performed.
 */
- (FSTObjectValue *)objectByDeletingPath:(FSTFieldPath *)fieldPath;
@end

/**
 * An array value stored in Firestore.
 */
// clang-format off
@interface FSTArrayValue : FSTFieldValue < NSArray <id> * >

- (instancetype)init NS_UNAVAILABLE;
// clang-format on

/**
 * Initializes this instance with the given array of wrapped values.
 *
 * @param value An immutable array of FSTFieldValue objects. Caller is responsible for copying the
 *      value or releasing all references.
 */
- (instancetype)initWithValueNoCopy:(NSArray<FSTFieldValue *> *)value NS_DESIGNATED_INITIALIZER;

- (NSArray<FSTFieldValue *> *)internalValue;

@end

NS_ASSUME_NONNULL_END