Added the ability to customize encoding and decoding dates. (#54)

* Added the ability to customize encoding and decoding dates when parking or retrieving Codable objects.

* Split out SwiftCodableTests into separate files to significantly reduce file size.

* Fixed comment formatting.

* Updated comments and documentation to match the recent changes.

Author: mrlegowatch

Sources/GarageStorage/Garage.swift

@@ -33,9 +33,23 @@ public class Garage: NSObject {
 
     /// Autosave is set to true by default, for every operation that causes a change to the underlying Core Data Managed Object Context.
     ///
-    /// When set to true, the garage will be saved after any operation that causes a change to the underlying Core Data Managed Object Context, including `park()`, `setSyncStatus()`, and `delete()`. When set to false, `save()` must be called instead, in order to persist those changes. You might want to use `withAutosaveDisabled(:)` to set this to false, in order to perform batch changes to many objects before saving them all, optimizing performance.
+    /// When set to true, the garage will be saved after any operation that causes a change to the underlying Core Data Managed Object Context, such as `park()`. When set to false, `save()` must be called instead, in order to persist those changes.
+    ///
+    /// Use ``withAutosaveDisabled(_:)`` to set this to false, in order to perform batch changes to many objects before saving them all, optimizing performance.
     @objc(autosaveEnabled)
-    public var isAutosaveEnabled = true
+    public private(set) var isAutosaveEnabled = true
+    
+    /// The date decoding strategy used by JSONDecoder when decoding objects.
+    ///
+    /// By default, this is set to a custom strategy that uses `Date.isoFormatter`f or Codable objects and a wrapper conversion check for backward compatibility with Objective-C `MappableObject`.
+    /// You can modify this to apply a different date decoding strategy for a `retrieve()` call using ``withDateDecodingStrategy(_:_:)``.
+    public private(set) var dateDecodingStrategy: JSONDecoder.DateDecodingStrategy = .custom(decodeTransformableDate)
+    
+    /// The date encoding strategy used by JSONEncoder when encoding objects.
+    ///
+    /// By default, this is set to use ISO 8601 formatted dates via `Date.isoFormatter`.
+    /// You can modify this to apply a different date encoding strategy for a `park()` call using ``withDateEncodingStrategy(_:_:)``.
+    public private(set) var dateEncodingStrategy: JSONEncoder.DateEncodingStrategy = .formatted(Date.isoFormatter)
 
     /// The date decoding strategy used by JSONDecoder when decoding objects.
     ///
@@ -149,6 +163,8 @@ public class Garage: NSObject {
     ///
     /// This is useful for performing batch operations where you want to defer saving until all changes are complete. The autosave state is automatically restored even if the closure throws an error.
     ///
+    /// - note: You must call ``save()`` directly at some point after executing one or more closures in this manner.
+    ///
     /// - parameter closure: A closure to execute with autosave disabled. If the closure throws, the error is propagated after restoring the autosave state.
     /// - throws: Rethrows any error thrown by the closure.
     ///

Sources/GarageStorage/GarageStorage.docc/GarageStorage.md

@@ -16,7 +16,7 @@ GarageStorage is designed to do two things:
 
 The ``Garage`` is the main object that coordinates activity in GarageStorage. It's called a *garage* because you can park pretty much anything in it, like, you know, a garage. The `Garage` handles the backing Core Data stack, as well as the saving and retrieving of data. You *park* objects in the `Garage`, and *retrieve* them later. 
 
-Any object going into or coming out of the `Garage` must conform to the `Codable` protocol. If it's a top-level object, it must also conform to either the `Hashable` protocol, or GarageStorage's ``Mappable`` protocol. You can add whatever type of conforming object you like to the `Garage`, whenever you like. You don't have to migrate data models or anything, just park whatever you want!
+Any object going into or coming out of the `Garage` must conform to the `Codable` protocol. If it's a top-level object, it must also conform to either the `Hashable` protocol, or the `Identifiable` protocol. You can add whatever type of conforming object you like to the `Garage`, whenever you like. You don't have to migrate data models or anything, just park whatever you want!
 
 ## Topics
 

Sources/GarageStorage/GarageStorage.docc/GettingStarted.md

@@ -8,7 +8,7 @@ To start working with GarageStorage, you create a `Garage`, then start parking a
 
 ### How does a Garage work?
 
-Anything going into or coming out of the Garage must conform to the `Codable` protocol. Top-level objects—that is, anything stored or retrieved directly— must also conform to either the `Hashable` protocol, or GarageStorage's ``Mappable`` protocol (which is `Codable` and `Identifiable where ID == String`) for uniquely identified top-level objects. A top-level object can be stored or retrieved using its unique `id`, or as part of an array of the same type.
+Anything going into or coming out of the Garage must conform to the `Codable` protocol. Top-level objects—that is, anything stored or retrieved directly— must also conform to either the `Hashable` protocol, or `Identifiable` protocol for uniquely identified top-level objects. A top-level object can be stored or retrieved using its unique `id`, or as part of an array of the same type.
 
 It's important to draw a distinction between how Garage Storage operates and how Core Data operates: Garage Storage stores a JSON representation of your objects in Core Data, as opposed to storing the objects themselves, as Core Data does. There are some implications to this (explained below), but the best part is that you can add whatever type of object you like to the Garage, whenever you like. You don't have to migrate data models or anything, just park whatever you want!
 
@@ -46,7 +46,7 @@ In order to store this in GarageStorage, conform it to Codable:
 ```swift
 extension Address: Codable { }
 ```
-If this type is only embedded in another object, then no additional work is required. However, in order to *park* this object as a top-level object (that is, directly using `park(_:)` or `parkAll(_:)`), it must additionally conform to the either the `Hashable` protocol or the GarageStorage `Mappable` protocol, which combines `Codable` conformance with a `String` `id` property (see next section). 
+If this type is only embedded in another object, then no additional work is required. However, in order to *park* this object as a top-level object (that is, directly using `park(_:)` or `parkAll(_:)`), it must additionally conform to the either the `Hashable` protocol or the `Identifiable` protocol (see next section). 
 
 ### What making an object Hashable does
 
@@ -61,10 +61,10 @@ If many references of this type with the same value are being embedded (e.g., mu
 
 As indicated in the previous section, a top-level object or elements of a top-level array need only conform to `Hashable`. They may be either value or reference types.
 
-Standalone top-level objects—that is, root objects that are parked directly using `park()`—often require being uniquely identified in the Garage, and are often reference types, such as classes. This is supported through the `Mappable` protocol, which combines `Codable` conformance with an `String` ID property. For example:
+Standalone top-level objects—that is, root objects that are parked directly using `park()`—often require being uniquely identified in the Garage, and are often reference types, such as classes. This is supported through the `Identifiable` protocol. The only requirement for `Identifiable` is that its ID conform to `LosslessStringConvertible`. For example:
 
 ```swift
-class Person: Mappable {
+class Person: Codable, Identifiable {
     // Map the identifier to a preferred property, if desired.
     var id: String { name }
 
@@ -78,14 +78,28 @@ class Person: Mappable {
 }
 ```
 
-Note that in the above example, another property, `name`, is mapped to the `id` property, and the `id` property itself is synthesized (i.e., not stored directly with the object). In general, this is how you would map an existing unique identifier of any type (such as from a server or remote storage), to the one required for the Garage.
+Note that in the above example, another property, `name`, is mapped to the `id` property, and the `id` property itself is synthesized (i.e., not stored directly with the object). In general, this is how you might map an existing unique identifier of any type (such as from a server or remote storage), to the one required for the Garage.
+
+Note: Many Swift types support the `LosslessStringConvertible` protocol requirement for `Identifiable`'s `ID`, including `String` (of course), `Int`, `Double`, etc. However, `UUID` does not support this directly. To add conformance for `UUID`, implement the following in your project:
+
+```swift
+import Foundation
+
+extension UUID: LosslessStringConvertible {
+    public init?(_ description: String) {
+        self.init(uuidString: description)
+    }
+
+    public var description: String { self.uuidString }
+}
+```
 
 ### Parking Objects
-Parking an object puts a snapshot of that object into the Garage. As mentioned earlier, this is different from pure Core Data, where changes to your `NSManagedObjects` are directly reflected in the managed object context. With GarageStorage, since you're parking a snapshot, *you will need to park that object any time you want changes you've made to it to be reflected/persisted.* You can park the same object multiple times, which will update the existing object of that same type and identifier. To park a `Mappable` object in the garage, call:
+Parking an object puts a snapshot of that object into the Garage. As mentioned earlier, this is different from pure Core Data, where changes to your `NSManagedObjects` are directly reflected in the managed object context. With GarageStorage, since you're parking a snapshot, *you will need to park that object any time you want changes you've made to it to be reflected/persisted.* You can park the same object multiple times, which will update the existing object of that same type and identifier. To park an `Identifiable` object in the garage, call:
 ```swift
     try garage.park(myPerson)
 ```
-You may also park an array of objects in the garage (assuming all are `Codable` and `Hashable` or `Mappable` and of the same type):
+You may also park an array of objects in the garage (assuming all are `Codable` and `Hashable` or `Identifiable` and of the same type):
 ```swift
     try garage.parkAll([myBrother, mySister, myMom, myDad])
 ```
@@ -101,7 +115,7 @@ You can also retrieve all objects for a given type:
 ```
 
 ### Deleting Objects
-To delete an object from the Garage, you must specify the mappable object that was originally parked:
+To delete an object from the Garage, you must specify the Identifiable object that was originally parked:
 ```swift
     try garage.delete(myPerson)
 ```
@@ -153,15 +167,15 @@ Parking, deleting, or modifying the sync status of objects will automatically pe
 ```
 
 ### A Note about Identifying Objects
-It's worth going into a bit of detail about how *identified*, *unidentified*, and *anonymous* types work with respect to *top-level* vs. *embedded* objects, so you can best leverage (read: account for the quirks of) Garage Storage. 
+It's worth going into a bit of detail about how *identified*, *unidentified*, and *anonymous* types work with respect to *top-level* vs. *embedded* objects, so you can best leverage (read: *"account for the quirks of"*) Garage Storage. 
 
-Any Mappable object with an *id* or identifying attribute will be stored as its own separate object in the Garage, and each *reference* will point back to that object. This is great if you have a bunch of objects that reference each other, as the graph is properly maintained in the garage, so a change to one object will be "seen" by the other objects pointing to it. This also enables you to *retrieve* any top-level object by its identifier.
+Any `Identifiable` object with an *id* attribute will be stored as its own separate object in the Garage, and each *reference* will point back to that object. This is great if you have a bunch of objects that reference each other, as the graph is properly maintained in the garage, so a change to one object will be "seen" by the other objects pointing to it. This also enables you to *retrieve* any top-level object by its identifier.
 
-If you instead conform the type to `Hashable` then there is still only one instance or value of its type in storage; however, it is now an *unidentified* object. If you park an unidentified *Object A*, then change one of its properties, and park *Object A* again, you'll now have *two different versions* of *Object A* in the Garage, as its hash value has changed. If *Object A* had had an identifier, then *Object A* would have just been updated when it was parked the second time. Therefore, it's considered a best practice for top-level reference types to conform to `Mappable` so that they always have an identifying attribute, and are treated as the same instance in storage.
+If you instead conform the type to `Hashable` then there is still only one instance or value of its type in storage; however, it is now an *unidentified* object. If you park an unidentified *Object A*, then change one of its properties, and park *Object A* again, you'll now have *two different versions* of *Object A* in the Garage, as its hash value has changed. If *Object A* had had an identifier, then *Object A* would have just been updated when it was parked the second time. Therefore, it's considered a best practice for top-level reference types to conform to `Identifiable` so that they always have an *id* attribute, and are treated as the same instance in storage.
 
-However, if the object is an embedded *property* of a top-level object, you may want to leave it *unidentified*, especially if it doesn't have an attribute that's logically its identifier, or if it is a value type. If the object object does not conform to `Hashable`, then it is completely *anonymous*: it is serialized as in-line JSON, instead of having a separate underlying core data object, as a `Mappable` or `Hashable` object would. This means you won't be able to retrieve anonymous sub-objects by type directly. To make an object completely anonymous, it only needs to conform to `Codable`. 
+However, if the object is an embedded *property* of a top-level object, you may want to leave it *unidentified*, especially if it doesn't have an attribute that's logically its identifier, or if it is a value type. If the object does not conform to `Hashable`, then it is completely *anonymous*: it is serialized as in-line JSON, instead of having a separate underlying core data object, as an `Identifiable` or `Hashable` object would. This means you won't be able to retrieve anonymous sub-objects by type directly. To make an object completely anonymous, it only needs to conform to `Codable`. 
 
-The primary advantages of *anonymous* objects are twofold: First, you don't have to arbitrarily pick an identifier if your object doesn't naturally have one. Second, there's an underlying difference in how deletion is handled. When you delete an object from the Garage, only the top level `Mappable` is deleted. If it references other `Mappable` or `Hashable` objects, those are not deleted. Garage Storage doesn't monitor retain counts on objects, so for safety, only the object specified is removed. However, since *anonymous* objects are part of the top level object's JSON, and are not separate underlying objects, they will be removed. It's considered best practice for embedded objects to be *anonymous*, unless there is a compelling reason otherwise, such as to reduce overall storage footprint.
+The primary advantages of *anonymous* objects are twofold: First, you don't have to arbitrarily pick an *identifier* if your object doesn't naturally have one, and you don't have to bother conforming it to `Hashable` either. Second, there's an underlying difference in how deletion is handled. When you delete an object from the Garage, only the top level `Identifiable` is deleted. If it references other `Identifiable` or `Hashable` objects, those sub-objects are not deleted. Garage Storage doesn't monitor retain counts on objects, so for safety, only the object specified is removed. However, since *anonymous* objects are part of its parent object's JSON, and are not separate underlying objects, they will be removed along with that top level object. It's considered best practice for embedded objects to be *anonymous*, unless there is a compelling reason otherwise, such as to reduce overall storage footprint.
 
 ### Handling errors
 

Sources/GarageStorage/Interface/Mappable.swift

@@ -9,7 +9,8 @@
 import Foundation
 
 /// An optional, convenience protocol that conforms to `Codable` and `Identifiable` where `ID` conforms to `LosslessStringConvertible`.
-/// These two protocol conformances are required for uniquely identified objects in a Garage.
-/// Most clients can simply conform to `Codable` and `Identifiable` directly, to meet these requirements.
-/// This protocol is only required for backward compatibility with existing code already using Mappable.
+/// These two protocol conformances are required for parking and retrieving uniquely identified objects in a Garage.
+///
+/// - note: Most clients can simply conform to `Codable` and `Identifiable` directly, to meet these requirements.
+/// This protocol is only required for backward compatibility with existing code already using `Mappable`.
 public protocol Mappable: Codable, Identifiable where ID: LosslessStringConvertible { }

Sources/GarageStorage/Interface/MappableObject.swift

@@ -9,14 +9,15 @@
 import Foundation
 
 
-/// A protocol for providing Objective-C Key-Value Coding mappings of properties for garage storage. Optional support is provided through ``ObjectMapping`` to uniquely identify top-level objects.
+/// A protocol for providing Objective-C Key-Value Coding mappings of properties for garage storage, with optional support is provided to uniquely identify top-level objects.
 ///
 /// Properties must include the `@objc` keyword if declared in Swift. If the object must be uniquely identified in storage, the ``ObjectMapping/identifyingAttribute`` can be assigned.
 ///
 /// Supported property types include:
 ///  - Core types: `Int`, `Double`, `Bool`, `String`, `Date`
 ///  - Container types: `Array`, `Dictionary`
 ///  - Other ``MappableObject`` classes
+///  - note: This protocol is only required for Objective-C compatibility. For Swift projects, use `Codable`, and for top-level objects use `Hashable` or `Identifiable`.
 @objc(GSMappableObject)
 public protocol MappableObject : NSObjectProtocol {
 

Sources/GarageStorage/Interface/ObjectMapping.swift

@@ -17,6 +17,7 @@ import Foundation
 ///  - Core types: `Int`, `Double`, `Bool`, `String`, `Date`
 ///  - Container types: `Array`, `Dictionary`
 ///  - Other ``MappableObject`` classes
+///  - note: This protocol is only required for Objective-C compatibility. For Swift projects, use `Codable`, and for top-level objects use `Hashable` or `Identifiable`.
 @objc(GSObjectMapping)
 public class ObjectMapping: NSObject {
 

Sources/GarageStorage/Interface/SyncableObject.swift

@@ -12,6 +12,7 @@ import Foundation
 /// An optional protocol for managing the web server sync status of an Objective-C ``MappableObject``.
 ///
 /// This can be used to retrieve all objects of a specific class and sync status, eliminating the need to fetch all instances of a specific class then filtering on sync status.
+///  - note: This protocol is only required for Objective-C compatibility. For Swift projects, use `Syncable`.
 @objc(GSSyncableObject)
 public protocol SyncableObject: NSObjectProtocol {