Improve query-representable UX

Currently, the various query representable wrappers must be used a very
specific way when dealing with optionals, where the optional must be on
the representation type, not the type being represented:

```swift
@column(as: Date.ISO8601Representation?.self)  // ✅
var date: Date?

@column(as: Date?.ISO8601Representation.self)  // ❌
var date: Date?
```

This PR adds a few helper type aliases to address this issue, so both
now compile and do the right thing:

```swift
@column(as: Date.ISO8601Representation?.self)  // ✅
var date: Date?

@column(as: Date?.ISO8601Representation.self)  // ✅
var date: Date?
```

It also renames `JSONRepresentation` to `Codable.JSONRepresentation`,
deprecating the former spelling. This also allows the optionality to be
placed either place:

```swift
@column(as: Notes.JSONRepresentation?.self)  // ✅
var notes: Notes?

@column(as: Notes?.JSONRepresentation.self)  // ✅
var notes: Notes?
```

Author: stephencelis

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

@@ -295,14 +295,15 @@ example, suppose the `Reminder` table had an array of notes:
 
 This does not work because the `@Table` macro does not know how to encode and decode an array
 of strings into a value that SQLite understands. If you annotate this field with
-``JSONRepresentation``, then the library can encode the array of strings to a JSON string when
-storing data in the table, and decode the JSON array into a Swift array when decoding a row:
+``Swift/Decodable/JSONRepresentation``, then the library can encode the array of strings to a JSON
+string when storing data in the table, and decode the JSON array into a Swift array when decoding a
+row:
 
 ```swift
 @Table struct Reminder {
   let id: Int
   var title = ""
-  @Column(as: JSONRepresentation<[String]>.self)
+  @Column(as: [String].JSONRepresentation.self)
   var notes: [String]
 }
 ```

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

@@ -396,19 +396,20 @@ suspiciously like a join constraint, which should give us a hint that what we ar
 quite right.
 
 Another way to do this is to use the `@Selection` macro described above
-(<doc:QueryCookbook#Custom-selections>), along with a ``JSONRepresentation`` of the collection
-of reminders you want to load for each list:
+(<doc:QueryCookbook#Custom-selections>), along with a ``Swift/Decodable/JSONRepresentation`` of the
+collection of reminders you want to load for each list:
 
 ```struct
 @Selection
 struct Row {
   let remindersList: RemindersList
-  @Column(as: JSONRepresentation<[Reminder]>.self)
+  @Column(as: [Reminder].JSONRepresentation.self)
   let reminders: [Reminder]
 }
 ```
 
-> Note: `Reminder` must conform to `Codable` to be able to use ``JSONRepresentation``.
+> Note: `Reminder` must conform to `Codable` to be able to use
+> ``Swift/Decodable/JSONRepresentation``.
 
 This allows the query to serialize the associated rows into JSON, which are then deserialized into
 a `Row` type. To construct such a query you can use the

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

@@ -16,4 +16,4 @@
 - ``Foundation/UUID/BytesRepresentation``
 - ``Foundation/UUID/LowercasedRepresentation``
 - ``Foundation/UUID/UppercasedRepresentation``
-- ``JSONRepresentation``
+- ``Swift/Decodable/JSONRepresentation``

Sources/StructuredQueriesCore/Internal/Deprecations.swift

@@ -0,0 +1,4 @@
+// NB: Deprecated after 0.1.1:
+
+@available(*, deprecated, message: "Use 'MyCodableType.JSONRepresentation', instead.")
+public typealias JSONRepresentation<Value: Codable> = _CodableJSONRepresentation<Value>

Sources/StructuredQueriesCore/QueryRepresentable/Codable+JSON.swift

@@ -1,18 +1,6 @@
 import Foundation
 
-/// A query expression representing codable JSON.
-///
-/// ```swift
-/// @Table
-/// struct Item {
-///   @Column(as: JSONRepresentation<[String]>.self)
-///   var notes: [String] = []
-/// }
-///
-/// Item.insert { $0.notes } values: { ["First post", "An update"] }
-/// // INSERT INTO "items" ("notes") VALUES ('["First post","An update"]')
-/// ```
-public struct JSONRepresentation<QueryOutput: Codable & Sendable>: QueryRepresentable {
+public struct _CodableJSONRepresentation<QueryOutput: Codable & Sendable>: QueryRepresentable {
   public var queryOutput: QueryOutput
 
   public init(queryOutput: QueryOutput) {
@@ -29,7 +17,28 @@ public struct JSONRepresentation<QueryOutput: Codable & Sendable>: QueryRepresen
   }
 }
 
-extension JSONRepresentation: QueryBindable {
+extension Decodable where Self: Encodable {
+  /// A query expression representing codable JSON.
+  ///
+  /// ```swift
+  /// @Table
+  /// struct Item {
+  ///   @Column(as: [String].JSONRepresentation.self)
+  ///   var notes: [String] = []
+  /// }
+  ///
+  /// Item.insert { $0.notes } values: { ["First post", "An update"] }
+  /// // INSERT INTO "items" ("notes") VALUES ('["First post","An update"]')
+  /// ```
+  public typealias JSONRepresentation = _CodableJSONRepresentation<Self>
+}
+
+extension Optional where Wrapped: Codable {
+  @_documentation(visibility: private)
+  public typealias JSONRepresentation = _CodableJSONRepresentation<Wrapped>?
+}
+
+extension _CodableJSONRepresentation: QueryBindable {
   public var queryBinding: QueryBinding {
     do {
       return try .text(String(decoding: jsonEncoder.encode(queryOutput), as: UTF8.self))
@@ -39,7 +48,7 @@ extension JSONRepresentation: QueryBindable {
   }
 }
 
-extension JSONRepresentation: SQLiteType {
+extension _CodableJSONRepresentation: SQLiteType {
   public static var typeAffinity: SQLiteTypeAffinity {
     String.typeAffinity
   }

Sources/StructuredQueriesCore/QueryRepresentable/Date+ISO8601.swift

@@ -22,6 +22,10 @@ extension Date {
   }
 }
 
+extension Date? {
+  public typealias ISO8601Representation = Date.ISO8601Representation?
+}
+
 extension Date.ISO8601Representation: QueryBindable {
   public var queryBinding: QueryBinding {
     .text(queryOutput.iso8601String)

Sources/StructuredQueriesCore/QueryRepresentable/Date+JulianDay.swift

@@ -22,6 +22,10 @@ extension Date {
   }
 }
 
+extension Date? {
+  public typealias JulianDayRepresentation = Date.JulianDayRepresentation?
+}
+
 extension Date.JulianDayRepresentation: QueryBindable {
   public var queryBinding: QueryBinding {
     .double(2440587.5 + queryOutput.timeIntervalSince1970 / 86400)

Sources/StructuredQueriesCore/QueryRepresentable/Date+UnixTime.swift

@@ -22,6 +22,10 @@ extension Date {
   }
 }
 
+extension Date? {
+  public typealias UnixTimeRepresentation = Date.UnixTimeRepresentation?
+}
+
 extension Date.UnixTimeRepresentation: QueryBindable {
   public var queryBinding: QueryBinding {
     .int(Int64(queryOutput.timeIntervalSince1970))

Sources/StructuredQueriesCore/QueryRepresentable/UUID+Bytes.swift

@@ -22,6 +22,10 @@ extension UUID {
   }
 }
 
+extension UUID? {
+  public typealias BytesRepresentation = UUID.BytesRepresentation?
+}
+
 extension UUID.BytesRepresentation: QueryBindable {
   public var queryBinding: QueryBinding {
     .blob(withUnsafeBytes(of: queryOutput.uuid, [UInt8].init))

Sources/StructuredQueriesCore/QueryRepresentable/UUID+Lowercased.swift

@@ -22,6 +22,10 @@ extension UUID {
   }
 }
 
+extension UUID? {
+  public typealias LowercasedRepresentation = UUID.LowercasedRepresentation?
+}
+
 extension UUID.LowercasedRepresentation: QueryBindable {
   public var queryBinding: QueryBinding {
     .text(queryOutput.uuidString.lowercased())