Lots of README re org rewrite and cleanup

Author: kylehughes

README.md

@@ -33,28 +33,7 @@ PersistentKeyValueKit is backed by a robust test suite.
 
 ## Usage
 
-### Types
-
-#### Primitive Types
-
-Primitive types are natively supported by `UserDefaults` and/or `NSUbiquitousKeyValueStore`. These types are all
-`KeyValuePersistible` and are stored directly with no transformation (where possible). All other `KeyValuePersistible` 
-types must be transformed into a primitive type through a `PersistentKeyValueRepresentation`.
-
-The primitive types are:
-
-- `Bool`
-- `Data`
-- `Double`
-- `Float`
-- `Int`
-- `Optional`
-- `String`
-- `URL`
-- `[KeyValuePersisiblt]`
-- `[String: any KeyValuePersisitble]`
-
-#### Make a Type Persistible
+### Make a Type Persistible
 
 Make a type persistible by conforming to `KeyValuePersistible`.
 
@@ -64,37 +43,52 @@ Make a type persistible by conforming to `KeyValuePersistible`.
 static var persistentKeyValueRepresentation: some PersistentKeyValueRepresentation<Self> { get }
 ```
 
-A representation is a type that describes how a value is persisted – how is is stored inside of `UserDefaults` or 
-`NSUbiquitousKeyValueStore`, and how it is retrieved. Severeal common representations are provided and it is easy to
+A representation is a type that describes how a value is persisted – how it is stored inside of `UserDefaults` or 
+`NSUbiquitousKeyValueStore`, and how it is retrieved. Several common representations are provided and it is easy to
 build custom ones inside of the `KeyValuePersistible` implementation.
 
 e.g.
 
 ```swift
 extension UIContentSizeCategory: KeyValuePersistible {
-    public static var persistentKeyValueRepresentation: some PersistentKeyValueRepresentation<Self> {
+    static var persistentKeyValueRepresentation: some PersistentKeyValueRepresentation<Self> {
         RawRepresentablePersistentKeyValueRepresentation()
     }
 }
 ```
 
-##### Built-in Persistence Representations
+#### Primitive Types
+
+Primitive types are natively supported by `UserDefaults` and/or `NSUbiquitousKeyValueStore`. These types are all
+`KeyValuePersistible` and are stored directly with little-to-no transformation. All other `KeyValuePersistible` 
+types must be transformed into a primitive type through a `PersistentKeyValueRepresentation`.
+
+The primitive types are:
+
+- `Bool`
+- `Data`
+- `Double`
+- `Float`
+- `Int`
+- `String`
+- `URL`
+- `Optional<T> where T: KeyValuePersistible`
+- `[T] where T: KeyValuePersistible`
+- `[String: T] where T: KeyValuePersistible`
+
+### Persistence Representations
 
 There are several built-in representations that cover the most common use cases for applications. They should be
 generic enough for almost any need. They are all described here. Their building blocks are available if necessary, but 
 not described here.
 
-###### `ProxyPersistentKeyValueRepresentation`
+#### `ProxyPersistentKeyValueRepresentation`
 
 `ProxyPersistentKeyValueRepresentation` is a representation that persists a value as the `Proxy` type. The `Proxy` type
 must be a `KeyValuePersistible` type.
 
 This is the base representation for types to build on top of. A common pattern is to use a primitive type as the proxy 
-type. Any `KeyValuePersistible` type can be used as the proxy type; there is no limit to the layers of indirection.
-
-> [!WARNING]
-> It is possible to define an infinite loop where `KeyValuePersistible` types proxy through each other recursively. This 
-> is a programming error and will result in undefined behavior at runtime.
+type, but any `KeyValuePersistible` type can be used as the proxy type. There is no limit to the layers of indirection.
 
 e.g.
 
@@ -104,17 +98,17 @@ e.g.
 extension Date: KeyValuePersistible {
     public static var persistentKeyValueRepresentation: some PersistentKeyValueRepresentation<Self> {
         ProxyPersistentKeyValueRepresentation(
-            to: \.timeIntervalSince1970,
-            from: Date.init(timeIntervalSince1970:)
+            to: \.timeIntervalSinceReferenceDate,
+            from: Date.init(timeIntervalSinceReferenceDate:)
         )
     }
 }
 ```
 
-###### `RawRepresentablePersistentKeyValueRepresentation`
+#### `RawRepresentablePersistentKeyValueRepresentation`
 
-`RawRepresentablePersistentKeyValueRepresentation` is a representation that persists a `RawRepresentable` value as its
-`RawValue`, if `RawValue` is `KeyValuePersistible`.
+`RawRepresentablePersistentKeyValueRepresentation` is a proxy representation that persists a `RawRepresentable` value as 
+its `RawValue`, if `RawValue` is `KeyValuePersistible`.
 
 e.g.
 
@@ -134,69 +128,11 @@ extension RuntimeColorScheme: KeyValuePersistible {
 }
 ```
 
-###### `StringlyKeyedDictionaryPersistentKeyValueRepresentation`
-
-`StringlyKeyedDictionaryPersistentKeyValueRepresentation` is a representation that persists a value as a 
-`[String: Any]`. This is just a typealias for `ProxyPersistentKeyValueRepresentation<[String: Any]>`.
-
-This representation is notable because `[String: Any]` is a primitive type and can be persisted directly with no 
-transformation. This is the most performant way to persist keyed types; much faster than JSON coding, for example. The 
-trade-off is that it requires manual (de)serialization.
-
-> [!WARNING]
-> `Any` is a lie: only property list types can be stored as values. Storing an unsupported type is a programming error
-> and will result in a crash at runtime.
-
-e.g.
-
-`Address` is persisted as `[String: Any]`.
-
-```swift
-struct Address {
-    let street: String
-    let city: String
-    let state: String
-    let zipCode: String
-}
-
-extension Address: KeyValuePersistible {
-    static var persistentKeyValueRepresentation: some PersistentKeyValueRepresentation<Self> {
-        StringlyKeyedDictionaryKeyValueRepresentation {
-            [
-                "street": $0.street,
-                "city": $0.city,
-                "state": $0.state,
-                "zipCode": $0.zipCode,
-            ]
-        } from: {
-            guard 
-                let street = $0["street"] as? String,
-                let city = $0["city"] as? String,
-                let state = $0["state"] as? String,
-                let zipCode = $0["zipCode"] as? String
-            else {
-                return nil
-            }
-            return Address(street: street, city: city, state: state, zipCode: zipCode)
-        }
-    }
-}
-```
-
-###### `CodablePersistentKeyValueRepresentation`
+#### `CodablePersistentKeyValueRepresentation`
 
 `CodablePersistentKeyValueRepresentation` is a proxy representation that persists a value as the `Input`/`Output` type
 of the given encoder and decoder.
 
-> [!TIP]
-> Although easy to use, `CodablePersistentKeyValueRepresentation` (with JSON) is the slowest built-in representation. 
-> One should prefer to use any other representation when possible. If one needs to persist a small keyed type, consider 
-> using `ProxyPersistentKeyValueRepresentation` with `[String: Any]` as the proxy type. `[String: Any]` is a primitive 
-> type and manual (de)serialization into a dictionary will be much faster.
->
-> If one is storing a type that is so large as to be impractical to do manual (de)serialization, reconsider using 
-> `UserDefaults` or `NSUbiquitousKeyValueStore` altogether. They are not meant for large values.
-
 e.g.
 
 `Address` is persisted as `Data`.
@@ -268,9 +204,8 @@ the amount of conditional code you need to write.
 All key-based interfaces accept `PersistentKeyProtocol`, which both `PersistentKey` and `PersistentDebugKey` conform to.
 
 > [!WARNING]
-> Debug keys will only work if one is compiling this framework from source (e.g. as a SwiftPM dependency). If one is
-> using a pre-built binary then the `DEBUG` code paths will likely not be included and default values will always be
-> used.
+> Debug keys will only work if compiling this framework from source (e.g. as a SwiftPM dependency). If using a pre-built 
+> binary then the `DEBUG` code paths will likely not be included and default values will always be used.
 
 e.g.
 
@@ -293,12 +228,13 @@ userDefaults.get(.isAppStoreRatingEnabled) // false in Debug, true in Release
 #### Use a Custom Representation for a Single Key
 
 Every `KeyValuePersistible` type has an associated `PersistentKeyValueRepresentation` type and 
-`peristentKeyValueRepresentation` property. This is the default representation used to persist the value into
-the backing store.
+`peristentKeyValueRepresentation` property. This is the default representation used to persist the value with a store.
+
+However, a representation for a single key can be provided at definition time—even if the value isn't 
+`KeyValuePersistible`. This is useful for:
 
-However, you can supply a different representation for a single key at definition time. This is useful if you have
-a type that you want to persist in a non-standard way, or if you have existing values that are stored differently
-from the default representation.
+- One-off keys for nonconforming types.
+- Handling older values stored differently from the default representation.
 
 e.g.
 
@@ -309,8 +245,8 @@ extension PersistentKeyProtocol where Self == PersistentKey<Date?> {
             "LastAppStoreReviewRequestDate", 
             defaultValue: nil,
             representation: ProxyPersistentKeyValueRepresentation(
-                to: \.timeIntervalSinceReferenceDate,
-                from: Date.init(timeIntervalSinceReferenceDate:)
+                to: \.timeIntervalSince1970,
+                from: Date.init(timeIntervalSince1970:)
             )
         )
     }