Update docs

Author: stephencelis

README.md

@@ -31,7 +31,6 @@ struct Reminder {
   var title = ""
   var isCompleted = false
   var priority: Int?
-  @Column(as: Date.ISO8601Representation?.self)
   var dueDate: Date?
 }
 ```

Sources/StructuredQueriesCore/Documentation.docc/Articles/DefiningYourSchema.md

@@ -152,113 +152,6 @@ with your table's columns, instead. For these data types you must either define
 The library comes with several `QueryRepresentable` conformances to aid in representing dates,
 UUIDs, and JSON, and you can define your own conformances for your own custom data types.
 
-#### Dates
-
-While some relational databases, like MySQL and Postgres, have native support for dates, SQLite
-does _not_. Instead, it has 3 different ways to represent dates:
-
-  * Text column interpreted as ISO-8601-formatted string.
-  * Int column interpreted as number of seconds since Unix epoch.
-  * Double column interpreted as a Julian day (number of days since November 24, 4713 BC).
-
-Because of this ambiguity, the `@Table` macro does not know what you intend when you define a data
-type like this:
-
-```swift
-@Table struct Reminder {
-  let id: Int
-  var date: Date  // 🛑 'Date' column requires a query representation
-}
-```
-
-In order to make it explicit how you expect to turn a `Date` into a type that SQLite understands
-(_i.e._ text, integer, or double) you can use the `@Column` macro with the `as:` argument. The
-library comes with 3 strategies out the box to help, ``Foundation/Date/ISO8601Representation`` for
-storing the date as a string, ``Foundation/Date/UnixTimeRepresentation`` for storing the date as an
-integer, and ``Foundation/Date/JulianDayRepresentation`` for storing the date as a floating point
-number.
-
-Any of these representations can be used like so:
-
-```swift
-@Table struct Reminder {
-  let id: Int
-  @Column(as: Date.ISO8601Representation.self)
-  var date: Date
-}
-```
-
-And StructuredQueries will take care of formatting the value for the database:
-
-@Row {
-  @Column {
-    ```swift
-    Reminder.insert(
-      Reminder.Draft(date: Date())
-    )
-    ```
-  }
-  @Column {
-    ```sql
-    INSERT INTO "reminders"
-      ("date")
-    VALUES
-      ('2018-01-29 00:08:00.000')
-    ```
-  }
-}
-
-When querying against a date column with a Swift date, you will need to explicitly bundle up the
-Swift date into the appropriate representation to use various query helpers. This can be done using
-the `#bind` macro:
-
-```swift
-Reminder.where { $0.created > #bind(startDate) }
-```
-
-#### UUID
-
-SQLite also does not have native support for UUIDs. If you try to use a UUID in your tables you
-will get an error:
-
-```swift
-@Table struct Reminder {
-  let id: UUID  // 🛑 'UUID' column requires a query representation
-  var title = ""
-}
-```
-
-To use such identifiers in your table you can store the column as a data blob, and then you can
-use the ``Foundation/UUID/BytesRepresentation`` column representation:
-
-```swift
-@Table struct Reminder {
-  @Column(as: UUID.BytesRepresentation.self)
-  let id: UUID
-  var title = ""
-}
-```
-
-Alternatively you can store the column as text and use either
-``Foundation/UUID/LowercasedRepresentation`` or ``Foundation/UUID/UppercasedRepresentation`` to
-translate the UUID to text:
-
-```swift
-@Table struct Reminder {
-  @Column(as: UUID.LowercasedRepresentation.self)
-  let id: UUID
-  var title = ""
-}
-```
-
-When querying against a UUID column with a Swift UUID, you will need to explicitly bundle up the
-Swift UUID into the appropriate representation to use various query helpers. This can be done using
-the `#bind` macro:
-
-```swift
-Reminder.where { $0.id != #bind(reminder.id) }
-```
-
 #### RawRepresentable
 
 Simple data types, in particular ones conforming to `RawRepresentable` whose `RawValue` is a string
@@ -353,6 +246,83 @@ With that you can insert reminders with notes like so:
   }
 }
 
+#### SQLite dates and UUIDs
+
+While some relational databases, like MySQL and Postgres, have native types for dates and UUIDs,
+SQLite does _not_, and instead can represent them in a variety of ways. Dates, for example, have 3
+different representations:
+
+  * Text column interpreted as ISO-8601-formatted string.
+  * Int column interpreted as number of seconds since Unix epoch.
+  * Double column interpreted as a Julian day (number of days since November 24, 4713 BC).
+
+By default, StructuredQueries will bind and decode dates as ISO-8601 text. If you want to the
+library to use a different representation (_i.e._ integer or double), you can provide an explicit
+query representation to the `@Column` macro's `as:` argument.
+``Foundation/Date/UnixTimeRepresentation`` will store the date as an integer, and
+``Foundation/Date/JulianDayRepresentation`` will store the date as a floating point number.
+
+For example:
+
+```swift
+@Table struct Reminder {
+  let id: Int
+  @Column(as: Date.UnixTimeRepresentation.self)
+  var date: Date
+}
+```
+
+And StructuredQueries will take care of formatting the value for the database:
+
+@Row {
+  @Column {
+    ```swift
+    Reminder.insert(
+      Reminder.Draft(date: Date())
+    )
+    ```
+  }
+  @Column {
+    ```sql
+    INSERT INTO "reminders"
+      ("date")
+    VALUES
+      (1517184480)
+    ```
+  }
+}
+
+When querying against a date column with a Swift date, you will need to explicitly bundle up the
+Swift date into the appropriate representation to use various query helpers. This can be done using
+the `#bind` macro:
+
+```swift
+Reminder.where { $0.created > #bind(startDate) }
+```
+
+SQLite also does not have type-level support for UUIDs. By default, the library will bind and decode
+UUIDs as lowercased, hexadecimal text, but it also provides custom representations. This includes
+``Foundation/UUID/UppercasedRepresentation`` for uppercased text, as well as
+``Foundation/UUID/BytesRepresentation`` for raw bytes.
+
+To use such custom representations, you can provide it to the `@Column` macro's `as:` parameter:
+
+```swift
+@Table struct Reminder {
+  @Column(as: UUID.BytesRepresentation.self)
+  let id: UUID
+  var title = ""
+}
+```
+
+When querying against a UUID column with a Swift UUID, you will need to explicitly bundle up the
+Swift UUID into the appropriate representation to use various query helpers. This can be done using
+the `#bind` macro:
+
+```swift
+Reminder.where { $0.id != #bind(reminder.id) }
+```
+
 ### Primary keyed tables
 
 It is possible to tell let the `@Table` macro know which property of your data type is the primary

Sources/StructuredQueriesCore/Documentation.docc/Articles/QueryCookbook.md

@@ -26,17 +26,14 @@ could be restored for a certain amount of time. These tables can be represented
 struct RemindersList: Identifiable {
   let id: Int
   var title = ""
-  @Column(as: Date.ISO8601Representation?.self)
   var deletedAt: Date?
 }
 @Table
 struct Reminder: Identifiable {
   let id: Int
   var title = ""
   var isCompleted = false
-  @Column(as: Date.ISO8601Representation?.self)
   var dueAt: Date?
-  @Column(as: Date.ISO8601Representation?.self)
   var deletedAt: Date?
   var remindersListID: RemindersList.ID
 }
@@ -207,7 +204,6 @@ struct Reminder {
   let id: Int
   var title = ""
   var isCompleted = false
-  @Column(as: Date.ISO8601Representation?.self)
   var deletedAt: Date?
 
   static let all = Self.where { $0.isDeleted.isNot(nil) }

Sources/StructuredQueriesCore/Documentation.docc/Extensions/QueryRepresentable.md

@@ -10,10 +10,13 @@
 
 ### Conformances
 
-- ``Foundation/Date/ISO8601Representation``
+- ``Swift/Decodable/JSONRepresentation``
 - ``Foundation/Date/JulianDayRepresentation``
 - ``Foundation/Date/UnixTimeRepresentation``
 - ``Foundation/UUID/BytesRepresentation``
-- ``Foundation/UUID/LowercasedRepresentation``
 - ``Foundation/UUID/UppercasedRepresentation``
-- ``Swift/Decodable/JSONRepresentation``
+
+### Deprecations
+
+- ``Foundation/Date/ISO8601Representation``
+- ``Foundation/UUID/LowercasedRepresentation``

Sources/StructuredQueriesCore/Documentation.docc/StructuredQueriesCore.md

@@ -15,7 +15,6 @@ struct Reminder {
   var title = ""
   var isCompleted = false
   var priority: Int?
-  @Column(as: Date.ISO8601Representation?.self)
   var dueDate: Date?
 }
 ```

Sources/StructuredQueriesCore/Internal/Deprecations.swift

@@ -1,3 +1,134 @@
+import Foundation
+
+// NB: Deprecated after 0.3.0:
+
+extension Date {
+  @available(
+    *,
+    deprecated,
+    message: "ISO-8601 text is the default representation and is no longer explicitly needed."
+  )
+  public struct ISO8601Representation: QueryRepresentable {
+    public var queryOutput: Date
+
+    public var iso8601String: String {
+      queryOutput.iso8601String
+    }
+
+    public init(queryOutput: Date) {
+      self.queryOutput = queryOutput
+    }
+
+    public init(iso8601String: String) throws {
+      try self.init(queryOutput: Date(iso8601String: iso8601String))
+    }
+  }
+}
+
+@available(
+  *,
+  deprecated,
+  message: "ISO-8601 text is the default representation and is no longer explicitly needed."
+)
+extension Date? {
+  public typealias ISO8601Representation = Date.ISO8601Representation?
+}
+
+@available(
+  *,
+  deprecated,
+  message: "ISO-8601 text is the default representation and is no longer explicitly needed."
+)
+extension Date.ISO8601Representation: QueryBindable {
+  public var queryBinding: QueryBinding {
+    .text(queryOutput.iso8601String)
+  }
+}
+
+@available(
+  *,
+  deprecated,
+  message: "ISO-8601 text is the default representation and is no longer explicitly needed."
+)
+extension Date.ISO8601Representation: QueryDecodable {
+  public init(decoder: inout some QueryDecoder) throws {
+    try self.init(queryOutput: Date(iso8601String: String(decoder: &decoder)))
+  }
+}
+
+@available(
+  *,
+  deprecated,
+  message: "ISO-8601 text is the default representation and is no longer explicitly needed."
+)
+extension Date.ISO8601Representation: SQLiteType {
+  public static var typeAffinity: SQLiteTypeAffinity {
+    String.typeAffinity
+  }
+}
+
+@available(
+  *,
+  deprecated,
+  message: "Lowercased text is the default representation and is no longer explicitly needed."
+)
+extension UUID {
+  public struct LowercasedRepresentation: QueryRepresentable {
+    public var queryOutput: UUID
+
+    public init(queryOutput: UUID) {
+      self.queryOutput = queryOutput
+    }
+  }
+}
+
+@available(
+  *,
+  deprecated,
+  message: "Lowercased text is the default representation and is no longer explicitly needed."
+)
+extension UUID? {
+  public typealias LowercasedRepresentation = UUID.LowercasedRepresentation?
+}
+
+@available(
+  *,
+  deprecated,
+  message: "Lowercased text is the default representation and is no longer explicitly needed."
+)
+extension UUID.LowercasedRepresentation: QueryBindable {
+  public var queryBinding: QueryBinding {
+    .text(queryOutput.uuidString.lowercased())
+  }
+}
+
+@available(
+  *,
+  deprecated,
+  message: "Lowercased text is the default representation and is no longer explicitly needed."
+)
+extension UUID.LowercasedRepresentation: QueryDecodable {
+  public init(decoder: inout some QueryDecoder) throws {
+    guard let uuid = try UUID(uuidString: String(decoder: &decoder)) else {
+      throw InvalidString()
+    }
+    self.init(queryOutput: uuid)
+  }
+
+  private struct InvalidString: Error {}
+}
+
+@available(
+  *,
+  deprecated,
+  message: "Lowercased text is the default representation and is no longer explicitly needed."
+)
+extension UUID.LowercasedRepresentation: SQLiteType {
+  public static var typeAffinity: SQLiteTypeAffinity {
+    String.typeAffinity
+  }
+}
+
 // NB: Deprecated after 0.1.1:
 
 @available(*, deprecated, message: "Use 'MyCodableType.JSONRepresentation', instead.")