feat(DataStore): Temporal performance enhancements (#1760)

Co-authored-by: Michael Law <[email protected]>

Author: atierian

Amplify.xcodeproj/project.pbxproj

@@ -7,58 +7,114 @@
 
 import Foundation
 
-public enum DateUnit {
-
-    case days(_ value: Int)
-    case weeks(_ value: Int)
-    case months(_ value: Int)
-    case years(_ value: Int)
+/// `DateUnit` for use in adding and subtracting units from `Temporal.Date`, `Temporal.DateTime`, and `Temporal.Time`.
+///
+/// `DateUnit` uses `Calendar.Component` under the hood to ensure date oddities are accounted for.
+///
+///     let tomorrow = Temporal.Date.now() + .days(1)
+///     let twoWeeksFromNow = Temporal.Date.now() + .weeks(2)
+///     let nextYear = Temporal.Date.now() + .years(1)
+///
+///     let yesterday = Temporal.Date.now() - .days(1)
+///     let sixMonthsAgo = Temporal.Date.now() - .months(6)
+public struct DateUnit {
+    let calendarComponent: Calendar.Component
+    let value: Int
 
+    /// One day. Equivalent to 1 x `Calendar.Component.day`
     public static let oneDay: DateUnit = .days(1)
+
+    /// One week. Equivalent to 7 x `Calendar.Component.day`
     public static let oneWeek: DateUnit = .weeks(1)
+
+    /// One month. Equivalent to 1 x `Calendar.Component.month`
     public static let oneMonth: DateUnit = .months(1)
+
+    /// One year. Equivalent to 1 x `Calendar.Component.year`
     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
-        }
+    /// DateUnit amount of days.
+    /// One day is 1 x `Calendar.Component.day`
+    ///
+    ///     let fiveDays = DateUnit.days(5)
+    ///     // or
+    ///     let fiveDays: DateUnit = .days(5)
+    ///
+    /// - Parameter value: Amount of days in this `DateUnit`
+    /// - Returns: A `DateUnit` with the defined number of days.
+    public static func days(_ value: Int) -> Self {
+        .init(calendarComponent: .day, value: value)
+    }
+
+    /// DateUnit amount of weeks.
+    /// One week is 7 x the `Calendar.Component.day`
+    ///
+    ///     let twoWeeks = DateUnit.weeks(2)
+    ///     // or
+    ///     let twoWeeks: DateUnit = .weeks(2)
+    ///
+    /// - Parameter value: Amount of weeks in this `DateUnit`
+    /// - Returns: A `DateUnit` with the defined number of weeks.
+    public static func weeks(_ value: Int) -> Self {
+        .init(calendarComponent: .day, value: value * 7)
     }
 
-    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
-        }
+    /// DateUnit amount of months.
+    /// One month is 1 x `Calendar.Component.month`
+    ///
+    ///     let sixMonths = DateUnit.months(6)
+    ///     // or
+    ///     let sixMonths: DateUnit = .months(6)
+    ///
+    /// - Parameter value: Amount of months in this `DateUnit`
+    /// - Returns: A `DateUnit` with the defined number of months.
+    public static func months(_ value: Int) -> Self {
+        .init(calendarComponent: .month, value: value)
     }
 
+    /// DateUnit amount of years.
+    /// One year is 1 x `Calendar.Component.year`
+    ///
+    ///     let oneYear = DateUnit.years(1)
+    ///     // or
+    ///     let oneYear: DateUnit = .years(1)
+    ///
+    /// - Parameter value: Amount of years in this `DateUnit`
+    /// - Returns: A `DateUnit` with the defined number of years.
+    public static func years(_ value: Int) -> Self {
+        .init(calendarComponent: .year, value: value)
+    }
 }
 
+/// Supports addition and subtraction of `Temporal.Date` and `Temporal.DateTime` with `DateUnit`
 public protocol DateUnitOperable {
-
     static func + (left: Self, right: DateUnit) -> Self
-
     static func - (left: Self, right: DateUnit) -> Self
-
 }
 
 extension TemporalSpec where Self: DateUnitOperable {
 
+    /// Add a `DateUnit` to a `Temporal.Date` or `Temporal.DateTime`
+    ///
+    ///     let tomorrow = Temporal.Date.now() + .days(1)
+    ///
+    /// - Parameters:
+    ///   - left: `Temporal.Date` or `Temporal.DateTime`
+    ///   - right: `DateUnit` to add to `left`
+    /// - Returns: A new `Temporal.Date` or `Temporal.DateTime` the `DateUnit` was added to.
     public static func + (left: Self, right: DateUnit) -> Self {
         return left.add(value: right.value, to: right.calendarComponent)
     }
 
+    /// Subtract a `DateUnit` from a `Temporal.Date` or `Temporal.DateTime`
+    ///
+    ///     let yesterday = Temporal.Date.now() - .day(1)
+    ///
+    /// - Parameters:
+    ///   - left: `Temporal.Date` or `Temporal.DateTime`
+    ///   - right: `DateUnit` to subtract from `left`
+    /// - Returns: A new `Temporal.Date` or `Temporal.DateTime` the `DateUnit` was subtracted from.
     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

@@ -9,30 +9,31 @@ 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`.
+    /// `Temporal.Date` represents a `Date` with specific allowable formats.
     ///
-    /// 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())
-        }
-
+    ///  * `.short` => `yyyy-MM-dd`
+    ///  * `.medium` => `yyyy-MM-ddZZZZZ`
+    ///  * `.long` => `yyyy-MM-ddZZZZZ`
+    ///  * `.full` => `yyyy-MM-ddZZZZZ`
+    ///
+    ///  - Note: `.medium`, `.long`, and `.full` are the same date format.
+    public struct Date: TemporalSpec {
+        // Inherits documentation from `TemporalSpec`
         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)
+        // Inherits documentation from `TemporalSpec`
+        public static func now() -> Self {
+            Temporal.Date(Foundation.Date())
         }
 
+        // Inherits documentation from `TemporalSpec`
         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)
+            self.foundationDate = Temporal
+                .iso8601Calendar
+                .startOfDay(for: date)
         }
     }
 }
+
+// Allow date unit operations on `Temporal.Date`
+extension Temporal.Date: DateUnitOperable {}

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

@@ -8,41 +8,52 @@
 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`.
+    /// `Temporal.DateTime` represents a `DateTime` with specific allowable formats.
     ///
-    /// `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]
-        }
+    ///  * `.short` => `yyyy-MM-dd'T'HH:mm`
+    ///  * `.medium` => `yyyy-MM-dd'T'HH:mm:ss`
+    ///  * `.long` => `yyyy-MM-dd'T'HH:mm:ssZZZZZ`
+    ///  * `.full` => `yyyy-MM-dd'T'HH:mm:ss.SSSZZZZZ`
+    public struct DateTime: TemporalSpec {
+        // Inherits documentation from `TemporalSpec`
+        public let foundationDate: Foundation.Date
 
-        public static func now() -> DateTime {
-            return DateTime(Foundation.Date())
+        // Inherits documentation from `TemporalSpec`
+        public static func now() -> Self {
+            Temporal.DateTime(Foundation.Date())
         }
 
-        public let foundationDate: Foundation.Date
-
+        /// `Temporal.Time` of this `Temporal.DateTime`.
         public var time: Time {
             Time(foundationDate)
         }
 
+        // Inherits documentation from `TemporalSpec`
         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
+            let calendar = Temporal.iso8601Calendar
+            let components = calendar.dateComponents(
+                DateTime.iso8601DateComponents,
+                from: date
+            )
+
+            foundationDate = calendar
+                .date(from: components) ?? date
         }
 
+        /// `Calendar.Component`s used in `init(_ date:)`
+        static let iso8601DateComponents: Set<Calendar.Component> =
+        [
+            .year,
+            .month,
+            .day,
+            .hour,
+            .minute,
+            .second,
+            .nanosecond,
+            .timeZone
+        ]
     }
-
 }
+
+// Allow date unit and time unit operations on `Temporal.DateTime`
+extension Temporal.DateTime: DateUnitOperable, TimeUnitOperable {}

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

@@ -0,0 +1,46 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+
+/// Internal generic method to reduce code reuse in the `init`s of `TemporalSpec`
+/// conforming types
+@usableFromInline
+internal struct SpecBasedDateConverting<Spec: TemporalSpec> {
+    @usableFromInline
+    internal typealias DateConverter = (_ string: String, _ format: TemporalFormat?) throws -> Date
+
+    @usableFromInline
+    internal let convert: DateConverter
+
+    @inlinable
+    @inline(never)
+    init(converter: @escaping DateConverter = Self.default) {
+        self.convert = converter
+    }
+
+    @inlinable
+    @inline(never)
+    internal static func `default`(
+        iso8601String: String,
+        format: TemporalFormat? = nil
+    ) throws -> Date {
+        let date: Foundation.Date
+        if let format = format {
+            date = try Temporal.date(
+                from: iso8601String,
+                with: [format(for: Spec.self)]
+            )
+        } else {
+            date = try Temporal.date(
+                from: iso8601String,
+                with: TemporalFormat.sortedFormats(for: Spec.self)
+            )
+        }
+        return date
+    }
+}