feat(datastore): add support for Date, DateTime and Time for DataStore fixes #278

**Notes:**

AWS supports more granular definition for Date types while the Swift
language represents all date values with the built-in `Date` struct.

This change adds `DateTime` and `Time` for an improved and more
permissive (de)serialization support.

**References:**

- #278

Author: drochetti

Amplify.xcodeproj/project.pbxproj

@@ -8,68 +8,28 @@
 import Foundation
 
 public struct ModelDateFormatting {
-    static let iso8601WithFractionalSeconds: ISO8601DateFormatter = {
-        let formatter = ISO8601DateFormatter()
-        formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
-        return formatter
-    }()
-
-    static let iso8601WithoutFractionalSeconds: ISO8601DateFormatter = {
-        let formatter = ISO8601DateFormatter()
-        formatter.formatOptions = [.withInternetDateTime]
-        return formatter
-    }()
 
     public static let decodingStrategy: JSONDecoder.DateDecodingStrategy = {
         let strategy = JSONDecoder.DateDecodingStrategy.custom { decoder -> Date in
             let container = try decoder.singleValueContainer()
             let dateString = try container.decode(String.self)
-
-            if let date = iso8601WithFractionalSeconds.date(from: dateString) {
-                return date
-            }
-
-            if let date = iso8601WithoutFractionalSeconds.date(from: dateString) {
-                return date
-            }
-
-            return try container.decode(Date.self)
+            let dateTime = try Temporal.DateTime(iso8601String: dateString)
+            return dateTime.foundationDate
         }
 
         return strategy
     }()
 
     public static let encodingStrategy: JSONEncoder.DateEncodingStrategy = {
         let strategy = JSONEncoder.DateEncodingStrategy.custom { date, encoder in
-            let dateString = iso8601WithFractionalSeconds.string(from: date)
             var container = encoder.singleValueContainer()
-            try container.encode(dateString)
+            try container.encode(Temporal.DateTime(date).iso8601String)
         }
         return strategy
     }()
 
 }
 
-public extension Date {
-
-    /// Retrieve the ISO 8601 formatted String, like "2019-11-25T00:35:01.746Z", from the Date instance
-    var iso8601String: String {
-        return ModelDateFormatting.iso8601WithFractionalSeconds.string(from: self)
-    }
-}
-
-public extension String {
-
-    /// Retrieve the ISO 8601 Date for valid String values like "2019-11-25T00:35:01.746Z". Supports values with and
-    /// without fractional seconds.
-    var iso8601Date: Date? {
-        if let date = ModelDateFormatting.iso8601WithFractionalSeconds.date(from: self) {
-            return date
-        }
-        return ModelDateFormatting.iso8601WithoutFractionalSeconds.date(from: self)
-    }
-}
-
 public extension JSONDecoder {
     convenience init(dateDecodingStrategy: JSONDecoder.DateDecodingStrategy) {
         self.init()

Amplify/Categories/DataStore/Model/Model+DateFormatting.swift

@@ -12,17 +12,21 @@ import Foundation
 ///
 /// Core Types that conform to this protocol:
 /// - `Bool`
-/// - `Date`
 /// - `Double`
 /// - `Int`
 /// - `String`
+/// - `Temporal.Date`
+/// - `Temporal.DateTime`
+/// - `Temporal.Time`
 public protocol Persistable {}
 
 extension Bool: Persistable {}
-extension Date: Persistable {}
 extension Double: Persistable {}
 extension Int: Persistable {}
 extension String: Persistable {}
+extension Temporal.Date: Persistable {}
+extension Temporal.DateTime: Persistable {}
+extension Temporal.Time: Persistable {}
 
 struct PersistableHelper {
 
@@ -43,7 +47,11 @@ struct PersistableHelper {
         switch (lhs, rhs) {
         case let (lhs, rhs) as (Bool, Bool):
             return lhs == rhs
-        case let (lhs, rhs) as (Date, Date):
+        case let (lhs, rhs) as (Temporal.Date, Temporal.Date):
+            return lhs == rhs
+        case let (lhs, rhs) as (Temporal.DateTime, Temporal.DateTime):
+            return lhs == rhs
+        case let (lhs, rhs) as (Temporal.Time, Temporal.Time):
             return lhs == rhs
         case let (lhs, rhs) as (Double, Double):
             return lhs == rhs

Amplify/Categories/DataStore/Model/Persistable.swift

@@ -45,10 +45,18 @@ public enum ModelFieldType {
         if type is Bool.Type {
             return .bool
         }
-        // TODO handle other DataScalar once the DateTime PR is merged
         if type is Date.Type {
             return .dateTime
         }
+        if type is Temporal.Date.Type {
+            return .date
+        }
+        if type is Temporal.DateTime.Type {
+            return .dateTime
+        }
+        if type is Temporal.Time.Type {
+            return .time
+        }
         if let enumType = type as? EnumPersistable.Type {
             return .enum(type: enumType)
         }

Amplify/Categories/DataStore/Model/Schema/ModelSchema+Definition.swift

@@ -0,0 +1,23 @@
+//
+// Copyright 2018-2020 Amazon.com,
+// Inc. or its affiliates. All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+
+extension DataStoreError {
+
+    public static func invalidDateFormat(_ value: String) -> DataStoreError {
+        return DataStoreError.decodingError(
+            """
+            Could not parse \(value) as a Date using the ISO8601 format.
+            """,
+            """
+            Check if the format used to parse the date is the correct one. Check
+            `TemporalFormat` for all the options.
+            """)
+    }
+
+}

Amplify/Categories/DataStore/Model/Temporal/DataStoreError+Temporal.swift

@@ -0,0 +1,64 @@
+//
+// Copyright 2018-2020 Amazon.com,
+// Inc. or its affiliates. All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+
+public enum DateUnit {
+
+    case days(_ value: Int)
+    case weeks(_ value: Int)
+    case months(_ value: Int)
+    case years(_ value: Int)
+
+    public static let oneDay: DateUnit = .days(1)
+    public static let oneWeek: DateUnit = .weeks(1)
+    public static let oneMonth: DateUnit = .months(1)
+    public static let oneYear: DateUnit = .years(1)
+
+    public var calendarComponent: Calendar.Component {
+        switch self {
+        case .days, .weeks:
+            return .day
+        case .months:
+            return .month
+        case .years:
+            return .year
+        }
+    }
+
+    public var value: Int {
+        switch self {
+        case .days(let value),
+             .months(let value),
+             .years(let value):
+            return value
+        case .weeks(let value):
+            return value * 7
+        }
+    }
+
+}
+
+public protocol DateUnitOperable {
+
+    static func + (left: Self, right: DateUnit) -> Self
+
+    static func - (left: Self, right: DateUnit) -> Self
+
+}
+
+extension TemporalSpec where Self: DateUnitOperable {
+
+    public static func + (left: Self, right: DateUnit) -> Self {
+        return left.add(value: right.value, to: right.calendarComponent)
+    }
+
+    public static func - (left: Self, right: DateUnit) -> Self {
+        return left.add(value: -right.value, to: right.calendarComponent)
+    }
+
+}

Amplify/Categories/DataStore/Model/Temporal/Date+Operation.swift

@@ -0,0 +1,38 @@
+//
+// Copyright 2018-2020 Amazon.com,
+// Inc. or its affiliates. All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+
+extension Temporal {
+
+    /// An extension that makes the `Date` struct conform with the `TemporalSpec` protocol.
+    /// When used in persistence operations, the granularity of the different date representations
+    /// is set by using different scalar types: `Date`, `DateTime` and `Time`.
+    ///
+    /// In those scenarios, the standard `Date` is formatted to ISO-8601 without the time.
+    /// When the full date information is required, use `DateTime` instead.
+    public struct Date: TemporalSpec, DateUnitOperable {
+
+        public static func now() -> Self {
+            return Temporal.Date(Foundation.Date())
+        }
+
+        public let foundationDate: Foundation.Date
+
+        public init(iso8601String: String) throws {
+            guard let date = Temporal.Date.iso8601Date(from: iso8601String) else {
+                throw DataStoreError.invalidDateFormat(iso8601String)
+            }
+            self.init(date)
+        }
+
+        public init(_ date: Foundation.Date) {
+            // sets the date to a fixed instant so date-only operations are safe
+            self.foundationDate = Date.iso8601Calendar.startOfDay(for: date)
+        }
+    }
+}

Amplify/Categories/DataStore/Model/Temporal/Date.swift

@@ -0,0 +1,48 @@
+//
+// Copyright 2018-2020 Amazon.com,
+// Inc. or its affiliates. All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+
+extension Temporal {
+
+    /// `DateTime` is an immutable `TemporalSpec` object that represents a date with a time,
+    /// often viewed as `yyyy-MM-dd'T'HH:mm:ss.SSSZZZZZ`.
+    ///
+    /// `DateTime` can be represented to nanosecond precision and it also holds a reference
+    /// to a TimeZone. As all Date scalars, `DateTime` relies on the ISO-8601 calendar.
+    public struct DateTime: TemporalSpec, DateUnitOperable, TimeUnitOperable {
+
+        public static var iso8601DateComponents: Set<Calendar.Component> {
+            [.year, .month, .day, .hour, .minute, .second, .nanosecond, .timeZone]
+        }
+
+        public static func now() -> DateTime {
+            return DateTime(Foundation.Date())
+        }
+
+        public let foundationDate: Foundation.Date
+
+        public var time: Time {
+            Time(foundationDate)
+        }
+
+        public init(_ date: Foundation.Date) {
+            let calendar = DateTime.iso8601Calendar
+            let components = calendar.dateComponents(DateTime.iso8601DateComponents, from: date)
+            self.foundationDate = components.date ?? date
+        }
+
+        public init(iso8601String: String) throws {
+            guard let date = DateTime.iso8601Date(from: iso8601String) else {
+                throw DataStoreError.invalidDateFormat(iso8601String)
+            }
+            self.foundationDate = date
+        }
+
+    }
+
+}

Amplify/Categories/DataStore/Model/Temporal/DateTime.swift

@@ -0,0 +1,61 @@
+## Custom Data Types
+
+`DataStore > Model > Temporal`
+
+Model-based programming aims to simplify data management on apps by abstracting away the complexities of data persistence from the core logic of the app. Therefore, data types are a critical piece of it.
+
+This module provides types that complements the Swift provided [`Date`](https://developer.apple.com/documentation/foundation/date) with more control over the date granularity when persisting values to a database (i.e. time-only, date-only, date+time).
+
+**Table of Contents**
+
+- [Custom Data Types](#custom-data-types)
+  - [1. Temporal](#1-temporal)
+    - [1.1. `Temporal.Date`, `Temporal.DateTime`, `Temporal.Time`](#11-temporaldate-temporaldatetime-temporaltime)
+    - [1.2. ISO-8601](#12-iso-8601)
+    - [1.3. The underlying `Date`](#13-the-underlying-date)
+    - [1.4. Operations](#14-operations)
+    - [1.5. References](#15-references)
+
+### 1. Temporal
+
+The Swift foundation module provides the [`Date`](https://developer.apple.com/documentation/foundation/date) struct that represents a single point in time and can fit any precision, calendrical system or time zone. While that approach is concise and powerful, when it comes to representing persistent data its flexibility can result in ambiguity (i.e. should only the date portion be used or both date and time).
+
+
+#### 1.1. `Temporal.Date`, `Temporal.DateTime`, `Temporal.Time`
+
+The `TemporalSpec` protocol was introduced to establish a more strict way to represent dates that make sense in a data persistence context.
+
+#### 1.2. ISO-8601
+
+The temporal implementations rely on a fixed [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) Calendar implementation ([`.iso8601`](https://developer.apple.com/documentation/foundation/calendar/identifier/iso8601)). If a representation of the date is needed in different calendars, use the underlying date object described in the next section.
+
+#### 1.3. The underlying `Date`
+
+Both `DateTime` and `Time` are backed by a [`Date`](https://developer.apple.com/documentation/foundation/date) instance. Therefore, they are compatible with all existing Date APIs from Foundation, including third-party libraries.
+
+#### 1.4. Operations
+
+Swift offers great support for complex date operations using [`Calendar`](https://developer.apple.com/documentation/foundation/calendar), but unfortunately simple use-cases often require several lines of code.
+
+The `TemporalSpec` implementation offers utilities that enable simple date operations to be defined in a readable and idiomatic way.
+
+Time:
+
+```swift
+// current time plus 2 hours
+let time = Time.now + .hours(2)
+```
+
+Date/Time:
+
+```swift
+// current date/time 2 weeks ago
+let datetime = DateTime.now - .weeks(2)
+```
+
+#### 1.5. References
+
+Some resources that inspired types defined here:
+
+- Joda Time: https://www.joda.org/joda-time/
+- Ruby on Rails Date API: https://api.rubyonrails.org/classes/Date.html

Amplify/Categories/DataStore/Model/Temporal/README.md

@@ -0,0 +1,25 @@
+//
+// Copyright 2018-2020 Amazon.com,
+// Inc. or its affiliates. All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+extension TemporalSpec where Self: Codable {
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.singleValueContainer()
+        let value = try container.decode(String.self)
+        try self.init(iso8601String: value)
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.singleValueContainer()
+        try container.encode(iso8601String)
+    }
+
+}
+
+extension Temporal.Date: Codable {}
+extension Temporal.DateTime: Codable {}
+extension Temporal.Time: Codable {}