import Foundation

// MARK: - TypedRequest

/// A request that knows how to decode database rows.
public protocol TypedRequest<RowDecoder> {
    /// The type that can decode database rows.
    ///
    /// For example, it is `Player` in the request below:
    ///
    /// ```swift
    /// let request = Player.all()
    /// ```
    associatedtype RowDecoder
}

// MARK: - SelectionRequest

/// A request that can define the selected columns.
///
/// ## Topics
///
/// ### The SELECT Clause
///
/// - ``annotated(with:)-4qcem``
/// - ``annotated(with:)-6ehs4``
/// - ``annotatedWhenConnected(with:)``
/// - ``select(_:)-30yzl``
/// - ``select(_:)-7e2y5``
/// - ``select(literal:)``
/// - ``select(sql:arguments:)``
/// - ``selectWhenConnected(_:)``
public protocol SelectionRequest {
    /// Defines the result columns.
    ///
    /// The `selection` parameter is a closure that accepts a database
    /// connection and returns an array of result columns. It is evaluated when
    /// the request has an access to the database, and can perform database
    /// requests in order to build its result.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT id, name FROM player
    /// let request = Player.all().selectWhenConnected { db in
    ///     [Column("id"), Column("name")]
    /// }
    /// ```
    ///
    /// Any previous selection is discarded:
    ///
    /// ```swift
    /// // SELECT name FROM player
    /// let request = Player.all()
    ///     .selectWhenConnected { db in [Column("id")] }
    ///     .selectWhenConnected { db in [Column("name")] }
    /// ```
    ///
    /// - parameter selection: A closure that accepts a database connection and
    ///   returns an array of result columns.
    func selectWhenConnected(_ selection: @escaping (Database) throws -> [any SQLSelectable]) -> Self
    
    /// Appends result columns to the selected columns.
    ///
    /// The `selection` parameter is a closure that accepts a database
    /// connection and returns an array of result columns. It is evaluated when
    /// the request has an access to the database, and can perform database
    /// requests in order to build its result.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT *, score + bonus AS totalScore FROM player
    /// let request = Player.all().annotatedWhenConnected { db in
    ///     [(Column("score") + Column("bonus")).forKey("totalScore")]
    /// }
    /// ```
    ///
    /// - parameter selection: A closure that accepts a database connection and
    ///   returns an array of result columns.
    func annotatedWhenConnected(with selection: @escaping (Database) throws -> [any SQLSelectable]) -> Self
}

extension SelectionRequest {
    /// Defines the result columns.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT id, score FROM player
    /// let request = Player.all().select([Column("id"), Column("score")])
    /// ```
    ///
    /// Any previous selection is replaced:
    ///
    /// ```swift
    /// // SELECT score FROM player
    /// let request = Player.all()
    ///     .select([Column("id")])
    ///     .select([Column("score")])
    /// ```
    public func select(_ selection: [any SQLSelectable]) -> Self {
        selectWhenConnected { _ in selection }
    }
    
    /// Defines the result columns.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT id, score FROM player
    /// let request = Player.all().select(Column("id"), Column("score"))
    /// ```
    ///
    /// Any previous selection is discarded:
    ///
    /// ```swift
    /// // SELECT score FROM player
    /// let request = Player.all()
    ///     .select(Column("id"))
    ///     .select(Column("score"))
    /// ```
    public func select(_ selection: any SQLSelectable...) -> Self {
        select(selection)
    }
    
    /// Defines the result columns with an SQL string.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT id, name FROM player
    /// let request = Player.all()
    ///     .select(sql: "id, name")
    ///
    /// // SELECT id, IFNULL(name, 'Anonymous') FROM player
    /// let defaultName = "Anonymous"
    /// let request = Player.all()
    ///     .select(sql: "id, IFNULL(name, ?)", arguments: [defaultName])
    /// ```
    ///
    /// Any previous selection is discarded:
    ///
    /// ```swift
    /// // SELECT score FROM player
    /// let request = Player.all()
    ///     .select(sql: "id")
    ///     .select(sql: "name")
    /// ```
    public func select(sql: String, arguments: StatementArguments = StatementArguments()) -> Self {
        select(SQL(sql: sql, arguments: arguments))
    }
    
    /// Defines the result columns with an ``SQL`` literal.
    ///
    /// ``SQL`` literals allow you to safely embed raw values in your SQL,
    /// without any risk of syntax errors or SQL injection:
    ///
    /// ```swift
    /// // SELECT id, IFNULL(name, 'Anonymous') FROM player
    /// let defaultName = "Anonymous"
    /// let request = Player.all()
    ///     .select(literal: "id, IFNULL(name, \(defaultName))")
    /// ```
    ///
    /// Any previous selection is discarded:
    ///
    /// ```swift
    /// // SELECT IFNULL(name, 'Anonymous') FROM player
    /// let request = Player.all()
    ///     .select(literal: "id")
    ///     .select(literal: "IFNULL(name, \(defaultName))")
    /// ```
    public func select(literal sqlLiteral: SQL) -> Self {
        // NOT TESTED
        select(sqlLiteral)
    }
    
    /// Appends result columns to the selected columns.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT *, score + bonus AS totalScore FROM player
    /// let totalScore = (Column("score") + Column("bonus")).forKey("totalScore")
    /// let request = Player.all().annotated(with: [totalScore])
    /// ```
    public func annotated(with selection: [any SQLSelectable]) -> Self {
        annotatedWhenConnected(with: { _ in selection })
    }
    
    /// Appends result columns to the selected columns.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT *, score + bonus AS totalScore FROM player
    /// let totalScore = (Column("score") + Column("bonus")).forKey("totalScore")
    /// let request = Player.all().annotated(with: totalScore)
    /// ```
    public func annotated(with selection: any SQLSelectable...) -> Self {
        annotated(with: selection)
    }
}

// MARK: - FilteredRequest

/// A request that can filter database rows.
///
/// The filter applies to the `WHERE` clause, or to the `ON` clause of
/// an SQL join.
///
/// ## Topics
///
/// ### The WHERE and JOIN ON Clauses
///
/// - ``all()``
/// - ``filter(_:)``
/// - ``filter(literal:)``
/// - ``filter(sql:arguments:)``
/// - ``filterWhenConnected(_:)``
/// - ``none()``
public protocol FilteredRequest {
    /// Filters the fetched rows with a boolean SQL expression.
    ///
    /// The `predicate` parameter is a closure that accepts a database
    /// connection and returns a boolean SQL expression. It is evaluated when
    /// the request has an access to the database, and can perform database
    /// requests in order to build its result.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT * FROM player WHERE name = 'O''Brien'
    /// let name = "O'Brien"
    /// let request = Player.all().filterWhenConnected { db in
    ///     Column("name") == name
    /// }
    /// ```
    ///
    /// - parameter predicate: A closure that accepts a database connection and
    ///   returns a boolean SQL expression.
    func filterWhenConnected(_ predicate: @escaping (Database) throws -> any SQLExpressible) -> Self
}

extension FilteredRequest {
    // Accept SQLSpecificExpressible instead of SQLExpressible, so that we
    // prevent the `Player.filter(42)` misuse.
    // See https://github.com/groue/GRDB.swift/pull/864
    /// Filters the fetched rows with a boolean SQL expression.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT * FROM player WHERE name = 'O''Brien'
    /// let name = "O'Brien"
    /// let request = Player.all().filter(Column("name") == name)
    /// ```
    public func filter(_ predicate: some SQLSpecificExpressible) -> Self {
        filterWhenConnected { _ in predicate }
    }
    
    /// Filters the fetched rows with an SQL string.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT * FROM player WHERE name = 'O''Brien'
    /// let name = "O'Brien"
    /// let request = Player.all().filter(sql: "name = ?", arguments: [name])
    /// ```
    public func filter(sql: String, arguments: StatementArguments = StatementArguments()) -> Self {
        filter(SQL(sql: sql, arguments: arguments))
    }
    
    /// Filters the fetched rows with an ``SQL`` literal.
    ///
    /// ``SQL`` literals allow you to safely embed raw values in your SQL,
    /// without any risk of syntax errors or SQL injection:
    ///
    /// ```swift
    /// // SELECT * FROM player WHERE name = 'O''Brien'
    /// let name = "O'Brien"
    /// let request = Player.all().filter(literal: "name = \(name)")
    /// ```
    public func filter(literal sqlLiteral: SQL) -> Self {
        // NOT TESTED
        filter(sqlLiteral)
    }
    
    /// Returns an empty request that fetches no row.
    public func none() -> Self {
        filterWhenConnected { _ in false }
    }
  
  /// Returns `self`: a request that fetches all rows from this request.
  ///
  /// This method, which does nothing, exists in order to match ``none()``.
  public func all() -> Self {
      self
  }
}

// MARK: - TableRequest

/// A request that feeds from a database table
///
/// ## Topics
///
/// ## The Database Table
///
/// - ``databaseTableName``
///
/// ### Instance Methods
///
/// - ``aliased(_:)``
/// - ``TableAlias``
///
/// ### The WHERE Clause
/// 
/// - ``filter(id:)``
/// - ``filter(ids:)``
/// - ``filter(key:)-1p9sq``
/// - ``filter(key:)-2te6v``
/// - ``filter(keys:)-6ggt1``
/// - ``filter(keys:)-8fbn9``
/// - ``matching(_:)-3s3zr``
/// - ``matching(_:)-7c1e8``
///
/// ### The GROUP BY and HAVING Clauses
///
/// - ``groupByPrimaryKey()``
///
/// ### The ORDER BY Clause
///
/// - ``orderByPrimaryKey()``
public protocol TableRequest {
    /// The name of the database table
    var databaseTableName: String { get }
    
    /// Returns a request that can be referred to with the provided alias.
    ///
    /// Use this method when you need to refer to this request from
    /// another request.
    ///
    /// The first example fetches posthumous books:
    ///
    /// ```swift
    /// struct Author: TableRecord, FetchableRecord { }
    /// struct Book: TableRecord, FetchableRecord {
    ///     static let author = belongsTo(Author.self)
    /// }
    ///
    /// // SELECT book.*
    /// // FROM book
    /// // JOIN author ON author.id = book.authorId
    /// // WHERE book.publishDate >= author.deathDate
    /// let authorAlias = TableAlias()
    /// let posthumousBooks = try Book
    ///     .joining(required: Book.author.aliased(authorAlias))
    ///     .filter(Column("publishDate") >= authorAlias[Column("deathDate")])
    ///     .fetchAll(db)
    /// ```
    ///
    /// The second example sorts books by author name first, and then by title:
    ///
    /// ```swift
    /// // SELECT book.*
    /// // FROM book
    /// // JOIN author ON author.id = book.authorId
    /// // ORDER BY author.name, book.title
    /// let authorAlias = TableAlias()
    /// let books = try Book
    ///     .joining(required: Book.author.aliased(authorAlias))
    ///     .order(authorAlias[Column("name")], Column("title"))
    ///     .fetchAll(db)
    /// ```
    ///
    /// The third example uses named ``TableAlias`` so that SQL snippets can
    /// refer to SQL tables with those names:
    ///
    /// ```swift
    /// // SELECT b.*
    /// // FROM book b
    /// // JOIN author a ON a.id = b.authorId
    /// //              AND a.countryCode = 'FR'
    /// // WHERE b.publishDate >= a.deathDate
    /// let bookAlias = TableAlias(name: "b")
    /// let authorAlias = TableAlias(name: "a")
    /// let posthumousFrenchBooks = try Book.aliased(bookAlias)
    ///     .joining(required: Book.author.aliased(authorAlias)
    ///         .filter(sql: "a.countryCode = ?", arguments: ["FR"]))
    ///     .filter(sql: "b.publishDate >= a.deathDate")
    ///     .fetchAll(db)
    /// ```
    func aliased(_ alias: TableAlias) -> Self
}

extension TableRequest where Self: FilteredRequest, Self: TypedRequest {
    
    /// Filters by primary key.
    ///
    /// All single-column primary keys are supported:
    ///
    /// ```swift
    /// // SELECT * FROM player WHERE id = 1
    /// let request = Player.all().filter(key: 1)
    ///
    /// // SELECT * FROM country WHERE code = 'FR'
    /// let request = Country.all().filter(key: "FR")
    /// ```
    ///
    /// - parameter key: A primary key
    public func filter(key: some DatabaseValueConvertible) -> Self {
        if key.databaseValue.isNull {
            return none()
        }
        return filter(keys: [key])
    }
    
    /// Filters by primary key.
    ///
    /// All single-column primary keys are supported:
    ///
    /// ```swift
    /// // SELECT * FROM player WHERE id = IN (1, 2, 3)
    /// let request = Player.all().filter(keys: [1, 2, 3])
    ///
    /// // SELECT * FROM country WHERE code = IN ('FR', 'US')
    /// let request = Country.all().filter(keys: ["FR", "US"])
    /// ```
    ///
    /// - parameter keys: A collection of primary keys
    public func filter<Sequence: Swift.Sequence>(keys: Sequence)
    -> Self
    where Sequence.Element: DatabaseValueConvertible
    {
        // In order to encode keys in the database, we perform a runtime check
        // for EncodableRecord, and look for a customized encoding strategy.
        // Such dynamic dispatch is unusual in GRDB, but static dispatch
        // (customizing TableRequest where RowDecoder: EncodableRecord) would
        // make it impractical to define `filter(id:)`, `fetchOne(_:key:)`,
        // `deleteAll(_:ids:)` etc.
        if let recordType = RowDecoder.self as? any EncodableRecord.Type {
            if Sequence.Element.self == Data.self || Sequence.Element.self == Optional<Data>.self {
                let strategy = recordType.databaseDataEncodingStrategy
                let keys = keys.compactMap { ($0 as! Data?).flatMap(strategy.encode)?.databaseValue }
                return filter(rawKeys: keys)
            } else if Sequence.Element.self == Date.self || Sequence.Element.self == Optional<Date>.self {
                let strategy = recordType.databaseDateEncodingStrategy
                let keys = keys.compactMap { ($0 as! Date?).flatMap(strategy.encode)?.databaseValue }
                return filter(rawKeys: keys)
            } else if Sequence.Element.self == UUID.self || Sequence.Element.self == Optional<UUID>.self {
                let strategy = recordType.databaseUUIDEncodingStrategy
                let keys = keys.map { ($0 as! UUID?).map(strategy.encode)?.databaseValue }
                return filter(rawKeys: keys)
            }
        }
        
        return filter(rawKeys: keys)
    }
    
    /// Creates a request filtered by primary key.
    ///
    ///     // SELECT * FROM player WHERE ... id IN (1, 2, 3)
    ///     let request = try Player...filter(rawKeys: [1, 2, 3])
    ///
    /// - parameter keys: A collection of primary keys
    func filter<Keys>(rawKeys: Keys) -> Self
    where Keys: Sequence, Keys.Element: DatabaseValueConvertible
    {
        // Don't bother removing NULLs. We'd lose CPU cycles, and this does not
        // change the SQLite results anyway.
        let expressions = rawKeys.map {
            $0.databaseValue.sqlExpression
        }
        
        if expressions.isEmpty {
            // Don't hit the database
            return none()
        }
        
        let databaseTableName = self.databaseTableName
        return filterWhenConnected { db in
            let primaryKey = try db.primaryKey(databaseTableName)
            GRDBPrecondition(
                primaryKey.columns.count == 1,
                "Requesting by key requires a single-column primary key in the table \(databaseTableName)")
            return SQLCollection.array(expressions).contains(Column(primaryKey.columns[0]).sqlExpression)
        }
    }
    
    /// Filters by primary or unique key.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT * FROM player WHERE id = 1
    /// let request = Player.all().filter(key: ["id": 1])
    ///
    /// // SELECT * FROM player WHERE email = 'arthur@example.com'
    /// let request = Player.all().filter(key: ["email": "arthur@example.com"])
    ///
    /// // SELECT * FROM citizenship WHERE citizenId = 1 AND countryCode = 'FR'
    /// let request = Citizenship.all().filter(key: [
    ///     "citizenId": 1,
    ///     "countryCode": "FR",
    /// ])
    /// ```
    ///
    /// When executed, this request raises a fatal error if no unique index
    /// exists on a subset of the key columns.
    ///
    /// - parameter key: A key dictionary.
    public func filter(key: [String: (any DatabaseValueConvertible)?]?) -> Self {
        guard let key else {
            return none()
        }
        return filter(keys: [key])
    }
    
    /// Filters by primary or unique key.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT * FROM player WHERE id = 1
    /// let request = Player.all().filter(keys: [["id": 1]])
    ///
    /// // SELECT * FROM player WHERE email = 'arthur@example.com'
    /// let request = Player.all().filter(keys: [["email": "arthur@example.com"]])
    ///
    /// // SELECT * FROM citizenship WHERE citizenId = 1 AND countryCode = 'FR'
    /// let request = Citizenship.all().filter(keys: [
    ///     ["citizenId": 1, "countryCode": "FR"],
    /// ])
    /// ```
    ///
    /// When executed, this request raises a fatal error if no unique index
    /// exists on a subset of the key columns.
    ///
    /// - parameter keys: An array of key dictionaries.
    public func filter(keys: [[String: (any DatabaseValueConvertible)?]]) -> Self {
        if keys.isEmpty {
            return none()
        }
        
        let databaseTableName = self.databaseTableName
        return filterWhenConnected { db in
            try keys
                .map { key in
                    // Prevent filter(keys: [["foo": 1, "bar": 2]]) where
                    // ("foo", "bar") do not contain a unique key (primary key
                    // or unique index).
                    guard let columns = try db.columnsForUniqueKey(key.keys, in: databaseTableName) else {
                        fatalError("""
                            table \(databaseTableName) has no unique key on column(s) \
                            \(key.keys.sorted().joined(separator: ", "))
                            """)
                    }
                    
                    let lowercaseColumns = columns.map { $0.lowercased() }
                    return key
                        // Preserve ordering of columns in the unique index
                        .sorted { (kv1, kv2) in
                            guard let index1 = lowercaseColumns.firstIndex(of: kv1.key.lowercased()) else {
                                // We allow extra columns which are not in the unique key
                                // Put them last in the query
                                return false
                            }
                            guard let index2 = lowercaseColumns.firstIndex(of: kv2.key.lowercased()) else {
                                // We allow extra columns which are not in the unique key
                                // Put them last in the query
                                return true
                            }
                            return index1 < index2
                        }
                        .map { (column, value) in Column(column) == value }
                        .joined(operator: .and)
                }
                .joined(operator: .or)
        }
    }
}

@available(iOS 13, macOS 10.15, tvOS 13, watchOS 6, *)
extension TableRequest
where Self: FilteredRequest,
      Self: TypedRequest,
      RowDecoder: Identifiable,
      RowDecoder.ID: DatabaseValueConvertible
{
    /// Filters by primary key.
    ///
    /// All single-column primary keys are supported:
    ///
    /// ```swift
    /// // SELECT * FROM player WHERE id = 1
    /// let request = Player.all().filter(id: 1)
    ///
    /// // SELECT * FROM country WHERE code = 'FR'
    /// let request = Country.all().filter(id: "FR")
    /// ```
    ///
    /// - parameter id: A primary key
    public func filter(id: RowDecoder.ID) -> Self {
        filter(key: id)
    }
    
    /// Filters by primary key.
    ///
    /// All single-column primary keys are supported:
    ///
    /// ```swift
    /// // SELECT * FROM player WHERE id = IN (1, 2, 3)
    /// let request = Player.all().filter(ids: [1, 2, 3])
    ///
    /// // SELECT * FROM country WHERE code = IN ('FR', 'US')
    /// let request = Country.all().filter(ids: ["FR", "US"])
    /// ```
    ///
    /// - parameter ids: A collection of primary keys
    public func filter<IDS>(ids: IDS) -> Self
    where IDS: Collection, IDS.Element == RowDecoder.ID
    {
        filter(keys: ids)
    }
}

extension TableRequest where Self: OrderedRequest {
    /// Sorts the fetched rows according to the primary key.
    ///
    /// All primary keys are supported:
    ///
    /// ```swift
    /// // SELECT * FROM player ORDER BY id
    /// let request = Player.all().orderByPrimaryKey()
    ///
    /// // SELECT * FROM country ORDER BY code
    /// let request = Country.all().orderByPrimaryKey()
    ///
    /// // SELECT * FROM citizenship ORDER BY citizenId, countryCode
    /// let request = Citizenship.all().orderByPrimaryKey()
    /// ```
    ///
    /// Any previous ordering is discarded.
    public func orderByPrimaryKey() -> Self {
        let tableName = self.databaseTableName
        return orderWhenConnected { db in
            try db.primaryKey(tableName).columns.map(SQLExpression.column)
        }
    }
}

extension TableRequest where Self: AggregatingRequest {
    /// Returns an aggregate request grouped on the primary key.
    ///
    /// Any previous grouping is discarded.
    public func groupByPrimaryKey() -> Self {
        let tableName = self.databaseTableName
        return groupWhenConnected { db in
            let primaryKey = try db.primaryKey(tableName)
            if let rowIDColumn = primaryKey.rowIDColumn {
                // Prefer the user-provided name of the rowid:
                //
                //  // CREATE TABLE player (id INTEGER PRIMARY KEY, ...)
                //  // SELECT * FROM player GROUP BY id
                //  Player.all().groupByPrimaryKey()
                return [Column(rowIDColumn)]
            } else if primaryKey.tableHasRowID {
                // Prefer the rowid
                //
                //  // CREATE TABLE player (uuid TEXT NOT NULL PRIMARY KEY, ...)
                //  // SELECT * FROM player GROUP BY rowid
                //  Player.all().groupByPrimaryKey()
                return [.rowID]
            } else {
                // WITHOUT ROWID table: group by primary key columns
                //
                //  // CREATE TABLE player (uuid TEXT NOT NULL PRIMARY KEY, ...) WITHOUT ROWID
                //  // SELECT * FROM player GROUP BY uuid
                //  Player.all().groupByPrimaryKey()
                return primaryKey.columns.map { Column($0) }
            }
        }
    }
}

// MARK: - AggregatingRequest

/// A request that can aggregate database rows.
///
/// ## Topics
///
/// ### The GROUP BY Clause
///
/// - ``group(_:)-edak``
/// - ``group(_:)-4216o``
/// - ``group(literal:)``
/// - ``group(sql:arguments:)``
/// - ``groupWhenConnected(_:)``
///
/// ### The HAVING Clause
///
/// - ``having(_:)``
/// - ``having(literal:)``
/// - ``having(sql:arguments:)``
/// - ``havingWhenConnected(_:)``
public protocol AggregatingRequest {
    /// Returns an aggregate request grouped on the given SQL expressions.
    ///
    /// The `expressions` parameter is a closure that accepts a database
    /// connection and returns an array of grouping SQL expressions. It is
    /// evaluated when the request has an access to the database, and can
    /// perform database requests in order to build its result.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT teamId, MAX(score)
    /// // FROM player
    /// // GROUP BY teamId
    /// let request = Player
    ///     .select(Column("teamId"), max(Column("score")))
    ///     .groupWhenConnected { db in [Column("teamId")] }
    /// ```
    ///
    /// Any previous grouping is discarded.
    ///
    /// - parameter expressions: A closure that accepts a database connection
    ///   and returns an array of SQL expressions.
    func groupWhenConnected(_ expressions: @escaping (Database) throws -> [any SQLExpressible]) -> Self
    
    /// Filters the aggregated groups with a boolean SQL expression.
    ///
    /// The `predicate` parameter is a closure that accepts a database
    /// connection and returns a boolean SQL expression. It is evaluated when
    /// the request has an access to the database, and can perform database
    /// requests in order to build its result.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT teamId, MAX(score)
    /// // FROM player
    /// // GROUP BY teamId
    /// // HAVING MAX(score) > 1000
    /// let request = Player
    ///     .select(Column("teamId"), max(Column("score")))
    ///     .group(Column("teamId"))
    ///     .havingWhenConnected { db in max(Column("score")) > 1000 }
    /// ```
    ///
    /// - parameter predicate: A closure that accepts a database connection and
    ///   returns a boolean SQL expression.
    func havingWhenConnected(_ predicate: @escaping (Database) throws -> any SQLExpressible) -> Self
}

extension AggregatingRequest {
    /// Returns an aggregate request grouped on the given SQL expressions.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT teamId, MAX(score)
    /// // FROM player
    /// // GROUP BY teamId
    /// let request = Player
    ///     .select(Column("teamId"), max(Column("score")))
    ///     .group([Column("teamId")])
    /// ```
    ///
    /// Any previous grouping is discarded.
    ///
    /// - parameter expressions: An array of SQL expressions.
    public func group(_ expressions: [any SQLExpressible]) -> Self {
        groupWhenConnected { _ in expressions }
    }
    
    /// Returns an aggregate request grouped on the given SQL expressions.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT teamId, MAX(score)
    /// // FROM player
    /// // GROUP BY teamId
    /// let request = Player
    ///     .select(Column("teamId"), max(Column("score")))
    ///     .group(Column("teamId"))
    /// ```
    ///
    /// Any previous grouping is discarded.
    ///
    /// - parameter expressions: An array of SQL expressions.
    public func group(_ expressions: any SQLExpressible...) -> Self {
        group(expressions)
    }
    
    /// Returns an aggregate request grouped on an SQL string.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT teamId, MAX(score)
    /// // FROM player
    /// // GROUP BY teamId
    /// let request = Player
    ///     .select(Column("teamId"), max(Column("score")))
    ///     .group(sql: "teamId")
    /// ```
    ///
    /// Any previous grouping is discarded.
    public func group(sql: String, arguments: StatementArguments = StatementArguments()) -> Self {
        group(SQL(sql: sql, arguments: arguments))
    }
    
    /// Returns an aggregate request grouped on an ``SQL`` literal.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT teamId, MAX(score)
    /// // FROM player
    /// // GROUP BY teamId
    /// let request = Player
    ///     .select(Column("teamId"), max(Column("score")))
    ///     .group(literal: "teamId")
    /// ```
    ///
    /// Any previous grouping is discarded.
    public func group(literal sqlLiteral: SQL) -> Self {
        // NOT TESTED
        group(sqlLiteral)
    }
    
    /// Filters the aggregated groups with a boolean SQL expression.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT teamId, MAX(score)
    /// // FROM player
    /// // GROUP BY teamId
    /// // HAVING MAX(score) > 1000
    /// let request = Player
    ///     .select(Column("teamId"), max(Column("score")))
    ///     .group(Column("teamId"))
    ///     .having(max(Column("score")) > 1000)
    /// ```
    public func having(_ predicate: some SQLExpressible) -> Self {
        havingWhenConnected { _ in predicate }
    }
    
    /// Filters the aggregated groups with an SQL string.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT teamId, MAX(score)
    /// // FROM player
    /// // GROUP BY teamId
    /// // HAVING MAX(score) > 1000
    /// let request = Player
    ///     .select(Column("teamId"), max(Column("score")))
    ///     .group(Column("teamId"))
    ///     .having(sql: "MAX(score) > 1000")
    /// ```
    public func having(sql: String, arguments: StatementArguments = StatementArguments()) -> Self {
        having(SQL(sql: sql, arguments: arguments))
    }
    
    /// Filters the aggregated groups with an ``SQL`` literal.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT teamId, MAX(score)
    /// // FROM player
    /// // GROUP BY teamId
    /// // HAVING MAX(score) > 1000
    /// let request = Player
    ///     .select(Column("teamId"), max(Column("score")))
    ///     .group(Column("teamId"))
    ///     .having(literal: "MAX(score) > 1000")
    /// ```
    public func having(literal sqlLiteral: SQL) -> Self {
        // NOT TESTED
        having(sqlLiteral)
    }
}

// MARK: - OrderedRequest

/// A request that can sort database rows.
///
/// ## Topics
///
/// ### The ORDER BY Clause
///
/// - ``order(_:)-63rzl``
/// - ``order(_:)-6co0m``
/// - ``order(literal:)``
/// - ``order(sql:arguments:)``
/// - ``orderWhenConnected(_:)``
/// - ``reversed()``
/// - ``unordered()``
/// - ``withStableOrder()``
public protocol OrderedRequest {
    /// Sorts the fetched rows according to the given SQL ordering terms.
    ///
    /// The `orderings` parameter is a closure that accepts a database
    /// connection and returns an array of SQL ordering terms. It is evaluated
    /// when the request has an access to the database, and can perform database
    /// requests in order to build its result.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT * FROM player ORDER BY score DESC, name
    /// let request = Player.all().orderWhenConnected { db in
    ///     [Column("score").desc, Column("name")]
    /// }
    /// ```
    ///
    /// Any previous ordering is discarded:
    ///
    /// ```swift
    /// // SELECT * FROM player ORDER BY name
    /// let request = Player.all()
    ///     .orderWhenConnected { db in [Column("score").desc] }
    ///     .orderWhenConnected { db in [Column("name")] }
    /// ```
    ///
    /// - parameter orderings: A closure that accepts a database connection and
    ///   returns an array of SQL ordering terms.
    func orderWhenConnected(_ orderings: @escaping (Database) throws -> [any SQLOrderingTerm]) -> Self
    
    /// Returns a request with reversed ordering.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT * FROM player ORDER BY name DESC
    /// let request = Player.all()
    ///     .order(Column("name"))
    ///     .reversed()
    /// ```
    ///
    /// If no ordering was already specified, this method has no effect:
    ///
    /// ```swift
    /// // SELECT * FROM player
    /// let request = Player.all().reversed()
    /// ```
    func reversed() -> Self
    
    /// Returns a request without any ordering.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT * FROM player
    /// let request = Player.all()
    ///     .order(Column("name"))
    ///     .unordered()
    /// ```
    func unordered() -> Self
    
    /// Returns a request with a stable order.
    ///
    /// The returned request lifts ordering ambiguities and always return
    /// its results in the same order.
    ///
    /// The purpose of this method is to make requests testable.
    func withStableOrder() -> Self
}

extension OrderedRequest {
    /// Sorts the fetched rows according to the given SQL ordering terms.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT * FROM player ORDER BY score DESC, name
    /// let request = Player.all()
    ///     .order(Column("score").desc, Column("name"))
    /// ```
    ///
    /// Any previous ordering is discarded:
    ///
    /// ```swift
    /// // SELECT * FROM player ORDER BY name
    /// let request = Player.all()
    ///     .order(Column("score").desc)
    ///     .order(Column("name"))
    /// ```
    public func order(_ orderings: any SQLOrderingTerm...) -> Self {
        orderWhenConnected { _ in orderings }
    }
    
    /// Sorts the fetched rows according to the given SQL ordering terms.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT * FROM player ORDER BY score DESC, name
    /// let request = Player.all()
    ///     .order([Column("score").desc, Column("name")])
    /// ```
    ///
    /// Any previous ordering is discarded:
    ///
    /// ```swift
    /// // SELECT * FROM player ORDER BY name
    /// let request = Player.all()
    ///     .order([Column("score").desc])
    ///     .order([Column("name")])
    /// ```
    public func order(_ orderings: [any SQLOrderingTerm]) -> Self {
        orderWhenConnected { _ in orderings }
    }
    
    /// Sorts the fetched rows according to the given SQL string.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT * FROM player ORDER BY score DESC, name
    /// let request = Player.all()
    ///     .order(sql: "score DESC, name")
    /// ```
    ///
    /// Any previous ordering is discarded.
    public func order(sql: String, arguments: StatementArguments = StatementArguments()) -> Self {
        order(SQL(sql: sql, arguments: arguments))
    }
    
    /// Sorts the fetched rows according to the given ``SQL`` literal.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT * FROM player ORDER BY score DESC, name
    /// let request = Player.all()
    ///     .order(literal: "score DESC, name")
    /// ```
    ///
    /// Any previous ordering is discarded.
    public func order(literal sqlLiteral: SQL) -> Self {
        // NOT TESTED
        order(sqlLiteral)
    }
}

// MARK: - JoinableRequest

/// A request that can join and prefetch associations.
///
/// `JoinableRequest` is adopted by ``QueryInterfaceRequest`` and all
/// types conforming to ``Association``.
///
/// It provides the methods that build requests involving several tables linked
/// through associations.
///
/// ## Topics
///
/// ### Extending the Selection with Columns of Associated Records
///
/// - ``annotated(withOptional:)``
/// - ``annotated(withRequired:)``
///
/// ### Prefetching Associated Records
///
/// - ``including(all:)``
/// - ``including(optional:)``
/// - ``including(required:)``
///
/// ### Joining Associated Records
///
/// - ``joining(optional:)``
/// - ``joining(required:)``
public protocol JoinableRequest<RowDecoder>: TypedRequest {
    /// Creates a request that prefetches an association.
    func _including(all association: _SQLAssociation) -> Self
    
    /// Creates a request that includes an association. The columns of the
    /// associated record are selected. The returned request does not
    /// require that the associated database table contains a matching row.
    func _including(optional association: _SQLAssociation) -> Self
    
    /// Creates a request that includes an association. The columns of the
    /// associated record are selected. The returned request requires
    /// that the associated database table contains a matching row.
    func _including(required association: _SQLAssociation) -> Self
    
    /// Creates a request that joins an association. The columns of the
    /// associated record are not selected. The returned request does not
    /// require that the associated database table contains a matching row.
    func _joining(optional association: _SQLAssociation) -> Self
    
    /// Creates a request that joins an association. The columns of the
    /// associated record are not selected. The returned request requires
    /// that the associated database table contains a matching row.
    func _joining(required association: _SQLAssociation) -> Self
}

extension JoinableRequest {
    /// Returns a request that fetches all records associated with each record
    /// in this request.
    ///
    /// For example, we can fetch authors along with their books:
    ///
    /// ```swift
    /// struct Author: TableRecord, FetchableRecord, Decodable {
    ///     static let books = hasMany(Book.self)
    /// }
    /// struct Book: TableRecord, FetchableRecord, Decodable { }
    ///
    /// struct AuthorInfo: FetchableRecord, Decodable {
    ///     var author: Author
    ///     var books: [Book]
    /// }
    ///
    /// let authorInfos = try Author.all()
    ///     .including(all: Author.books)
    ///     .asRequest(of: AuthorInfo.self)
    ///     .fetchAll(db)
    /// ```
    public func including<A: AssociationToMany>(all association: A) -> Self where A.OriginRowDecoder == RowDecoder {
        _including(all: association._sqlAssociation)
    }
    
    /// Returns a request that fetches the eventual record associated with each
    /// record of this request.
    ///
    /// For example, we can fetch books along with their eventual author:
    ///
    /// ```swift
    /// struct Author: TableRecord, FetchableRecord, Decodable { }
    /// struct Book: TableRecord, FetchableRecord, Decodable {
    ///     static let author = belongsTo(Author.self)
    /// }
    ///
    /// struct BookInfo: FetchableRecord, Decodable {
    ///     var book: Book
    ///     var author: Author?
    /// }
    ///
    /// let bookInfos = try Book.all()
    ///     .including(optional: Book.author)
    ///     .asRequest(of: BookInfo.self)
    ///     .fetchAll(db)
    /// ```
    public func including<A: Association>(optional association: A) -> Self where A.OriginRowDecoder == RowDecoder {
        _including(optional: association._sqlAssociation)
    }
    
    /// Returns a request that fetches the record associated with each record in
    /// this request. Records that do not have an associated record
    /// are discarded.
    ///
    /// For example, we can fetch books along with their eventual author:
    ///
    /// ```swift
    /// struct Author: TableRecord, FetchableRecord, Decodable { }
    /// struct Book: TableRecord, FetchableRecord, Decodable {
    ///     static let author = belongsTo(Author.self)
    /// }
    ///
    /// struct BookInfo: FetchableRecord, Decodable {
    ///     var book: Book
    ///     var author: Author
    /// }
    ///
    /// let bookInfos = try Book.all()
    ///     .including(required: Book.author)
    ///     .asRequest(of: BookInfo.self)
    ///     .fetchAll(db)
    /// ```
    public func including<A: Association>(required association: A) -> Self where A.OriginRowDecoder == RowDecoder {
        _including(required: association._sqlAssociation)
    }
    
    /// Returns a request that joins each record of this request to its
    /// eventual associated record.
    public func joining<A: Association>(optional association: A) -> Self where A.OriginRowDecoder == RowDecoder {
        _joining(optional: association._sqlAssociation)
    }
    
    /// Returns a request that joins each record of this request to its
    /// associated record. Records that do not have an associated record
    /// are discarded.
    ///
    /// For example, we can fetch only books whose author is French:
    ///
    /// ```swift
    /// struct Author: TableRecord, FetchableRecord, Decodable { }
    /// struct Book: TableRecord, FetchableRecord, Decodable {
    ///     static let author = belongsTo(Author.self)
    /// }
    ///
    /// let frenchAuthors = Book.author.filter(Column("countryCode") == "FR")
    /// let bookInfos = try Book.all()
    ///     .joining(required: frenchAuthors)
    ///     .fetchAll(db)
    /// ```
    public func joining<A: Association>(required association: A) -> Self where A.OriginRowDecoder == RowDecoder {
        _joining(required: association._sqlAssociation)
    }
}

extension JoinableRequest where Self: SelectionRequest {
    /// Appends the columns of the eventual associated record to the
    /// selected columns.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT player.*, team.color
    /// // FROM player LEFT JOIN team ...
    /// let teamColor = Player.team.select(Column("color"))
    /// let request = Player.all().annotated(withOptional: teamColor)
    /// ```
    ///
    /// This method performs the exact same SQL request as
    /// ``including(optional:)``. The difference is in the record type that can
    /// decode such a request: the columns of the associated record must be
    /// decoded at the same level as the main record. For example:
    ///
    /// ```swift
    /// struct PlayerWithTeamColor: FetchableRecord, Decodable {
    ///     var player: Player
    ///     var color: String?
    /// }
    /// try dbQueue.read { db in
    ///     let players = try request
    ///         .asRequest(of: PlayerWithTeamColor.self)
    ///         .fetchAll(db)
    /// }
    /// ```
    ///
    /// This method is a convenience. You can build the same request with
    /// ``TableAlias``, ``SelectionRequest/annotated(with:)-6ehs4``, and
    /// ``JoinableRequest/joining(optional:)``:
    ///
    /// ```swift
    /// let teamAlias = TableAlias()
    /// let request = Player.all()
    ///     .annotated(with: teamAlias[Column("color")])
    ///     .joining(optional: Player.team.aliased(teamAlias))
    /// ```
    public func annotated<A: Association>(withOptional association: A) -> Self where A.OriginRowDecoder == RowDecoder {
        // TODO: find a way to prefix the selection with the association key
        let alias = TableAlias()
        let selection = association._sqlAssociation.destination.relation.selectionPromise
        return self
            .joining(optional: association.aliased(alias))
            .annotatedWhenConnected(with: { db in
                try selection.resolve(db).map { selection in
                    selection.qualified(with: alias)
                }
            })
    }
    
    /// Appends the columns of the associated record to the selected columns.
    /// Records that do not have an associated record are discarded.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT player.*, team.color
    /// // FROM player JOIN team ...
    /// let teamColor = Player.team.select(Column("color"))
    /// let request = Player.all().annotated(withRequired: teamColor)
    /// ```
    ///
    /// This method performs the exact same SQL request as
    /// ``including(required:)``. The difference is in the record type that can
    /// decode such a request: the columns of the associated record must be
    /// decoded at the same level as the main record. For example:
    ///
    /// ```swift
    /// struct PlayerWithTeamColor: FetchableRecord, Decodable {
    ///     var player: Player
    ///     var color: String
    /// }
    /// try dbQueue.read { db in
    ///     let players = try request
    ///         .asRequest(of: PlayerWithTeamColor.self)
    ///         .fetchAll(db)
    /// }
    /// ```
    ///
    /// This method is a convenience. You can build the same request with
    /// ``TableAlias``, ``SelectionRequest/annotated(with:)-6ehs4``, and
    /// ``JoinableRequest/joining(required:)``:
    ///
    /// ```swift
    /// let teamAlias = TableAlias()
    /// let request = Player.all()
    ///     .annotated(with: teamAlias[Column("color")])
    ///     .joining(required: Player.team.aliased(teamAlias))
    /// ```
    public func annotated<A: Association>(withRequired association: A) -> Self where A.OriginRowDecoder == RowDecoder {
        // TODO: find a way to prefix the selection with the association key
        let selection = association._sqlAssociation.destination.relation.selectionPromise
        let alias = TableAlias()
        return self
            .joining(required: association.aliased(alias))
            .annotatedWhenConnected(with: { db in
                try selection.resolve(db).map { selection in
                    selection.qualified(with: alias)
                }
            })
    }
}

// MARK: - DerivableRequest

/// `DerivableRequest` is the base protocol for ``QueryInterfaceRequest``
/// and ``Association``.
///
/// Most features of `DerivableRequest` come from the protocols it
/// inherits from.
///
/// ## Topics
///
/// ### Instance Methods
///
/// - ``TableRequest/aliased(_:)``
/// - ``TableAlias``
///
/// ### The WITH Clause
///
/// - ``with(_:)``
///
/// ### The SELECT Clause
///
/// - ``SelectionRequest/annotated(with:)-4qcem``
/// - ``SelectionRequest/annotated(with:)-6ehs4``
/// - ``SelectionRequest/annotatedWhenConnected(with:)``
/// - ``distinct()``
/// - ``SelectionRequest/select(_:)-30yzl``
/// - ``SelectionRequest/select(_:)-7e2y5``
/// - ``SelectionRequest/select(literal:)``
/// - ``SelectionRequest/select(sql:arguments:)``
/// - ``SelectionRequest/selectWhenConnected(_:)``
///
/// ### The WHERE Clause
///
/// - ``FilteredRequest/all()``
/// - ``FilteredRequest/filter(_:)``
/// - ``TableRequest/filter(id:)``
/// - ``TableRequest/filter(ids:)``
/// - ``TableRequest/filter(key:)-1p9sq``
/// - ``TableRequest/filter(key:)-2te6v``
/// - ``TableRequest/filter(keys:)-6ggt1``
/// - ``TableRequest/filter(keys:)-8fbn9``
/// - ``FilteredRequest/filter(literal:)``
/// - ``FilteredRequest/filter(sql:arguments:)``
/// - ``FilteredRequest/filterWhenConnected(_:)``
/// - ``TableRequest/matching(_:)-3s3zr``
/// - ``TableRequest/matching(_:)-7c1e8``
/// - ``FilteredRequest/none()``
///
/// ### The GROUP BY and HAVING Clauses
///
/// - ``AggregatingRequest/group(_:)-edak``
/// - ``AggregatingRequest/group(_:)-4216o``
/// - ``AggregatingRequest/group(literal:)``
/// - ``AggregatingRequest/group(sql:arguments:)``
/// - ``TableRequest/groupByPrimaryKey()``
/// - ``AggregatingRequest/groupWhenConnected(_:)``
/// - ``AggregatingRequest/having(_:)``
/// - ``AggregatingRequest/having(literal:)``
/// - ``AggregatingRequest/having(sql:arguments:)``
/// - ``AggregatingRequest/havingWhenConnected(_:)``
///
/// ### The ORDER BY Clause
///
/// - ``OrderedRequest/order(_:)-63rzl``
/// - ``OrderedRequest/order(_:)-6co0m``
/// - ``OrderedRequest/order(literal:)``
/// - ``OrderedRequest/order(sql:arguments:)``
/// - ``OrderedRequest/orderWhenConnected(_:)``
/// - ``TableRequest/orderByPrimaryKey()``
/// - ``OrderedRequest/reversed()``
/// - ``OrderedRequest/unordered()``
/// - ``OrderedRequest/withStableOrder()``
///
/// ### Associations
///
/// - ``JoinableRequest/annotated(withOptional:)``
/// - ``JoinableRequest/annotated(withRequired:)``
/// - ``annotated(with:)-74xfs``
/// - ``annotated(with:)-8snn4``
/// - ``having(_:)``
/// - ``JoinableRequest/including(all:)``
/// - ``JoinableRequest/including(optional:)``
/// - ``JoinableRequest/including(required:)``
/// - ``JoinableRequest/joining(optional:)``
/// - ``JoinableRequest/joining(required:)``
///
/// ### Supporting Types
///
/// - ``AggregatingRequest``
/// - ``FilteredRequest``
/// - ``JoinableRequest``
/// - ``OrderedRequest``
/// - ``SelectionRequest``
/// - ``TableRequest``
/// - ``TypedRequest``
public protocol DerivableRequest<RowDecoder>: AggregatingRequest, FilteredRequest,
                                              JoinableRequest, OrderedRequest,
                                              SelectionRequest, TableRequest
{
    /// Returns a request which returns distinct rows.
    ///
    /// For example:
    ///
    /// ```swift
    /// // SELECT DISTINCT * FROM player
    /// let request = Player.all().distinct()
    ///
    /// // SELECT DISTINCT name FROM player
    /// let request = Player.select(Column("name")).distinct()
    /// ```
    func distinct() -> Self
    
    /// Embeds a common table expression.
    ///
    /// If a common table expression with the same table name had already been
    /// embedded, it is replaced by the new one.
    ///
    /// For example, you can build a request that fetches all chats with their
    /// latest message:
    ///
    /// ```swift
    /// let latestMessageRequest = Message
    ///     .annotated(with: max(Column("date")))
    ///     .group(Column("chatID"))
    ///
    /// let latestMessageCTE = CommonTableExpression(
    ///     named: "latestMessage",
    ///     request: latestMessageRequest)
    ///
    /// let latestMessageAssociation = Chat.association(
    ///     to: latestMessageCTE,
    ///     on: { chat, latestMessage in
    ///         chat[Column("id")] == latestMessage[Column("chatID")]
    ///     })
    ///
    /// // WITH latestMessage AS
    /// //   (SELECT *, MAX(date) FROM message GROUP BY chatID)
    /// // SELECT chat.*, latestMessage.*
    /// // FROM chat
    /// // LEFT JOIN latestMessage ON chat.id = latestMessage.chatID
    /// let request = Chat.all()
    ///     .with(latestMessageCTE)
    ///     .including(optional: latestMessageAssociation)
    /// ```
    func with<RowDecoder>(_ cte: CommonTableExpression<RowDecoder>) -> Self
}

// Association aggregates don't require all DerivableRequest abilities. The
// minimum set of requirements is:
//
// - AggregatingRequest, for the GROUP BY and HAVING clauses
// - TableRequest, for grouping by primary key
// - JoinableRequest, for joining associations
// - SelectionRequest, for annotating the selection
//
// It is just that extending DerivableRequest is simpler. We want the user to
// use aggregates on QueryInterfaceRequest and associations: both conform to
// DerivableRequest already.
extension DerivableRequest {
    private func annotated(with aggregate: AssociationAggregate<RowDecoder>) -> Self {
        var request = self
        let expression = aggregate.prepare(&request)
        if let key = aggregate.key {
            return request.annotated(with: expression.forKey(key))
        } else {
            return request.annotated(with: expression)
        }
    }
    
    /// Appends association aggregates to the selected columns.
    ///
    /// For example:
    ///
    /// ```swift
    /// struct Author: TableRecord, FetchableRecord, Decodable {
    ///     static let books = hasMany(Book.self)
    /// }
    /// struct Book: TableRecord, FetchableRecord, Decodable { }
    ///
    /// struct AuthorInfo: FetchableRecord, Decodable {
    ///     var author: Author
    ///     var bookCount: Int
    /// }
    ///
    /// // SELECT author.*, COUNT(DISTINCT book.id) AS bookCount
    /// // FROM author
    /// // LEFT JOIN book ON book.authorId = author.id
    /// // GROUP BY author.id
    /// let authorInfos = try Author.all()
    ///     .annotated(with: Author.books.count)
    ///     .asRequest(of: AuthorInfo.self)
    ///     .fetchAll(db)
    /// ```
    public func annotated(with aggregates: AssociationAggregate<RowDecoder>...) -> Self {
        annotated(with: aggregates)
    }
    
    /// Appends association aggregates to the selected columns.
    ///
    /// For example:
    ///
    /// ```swift
    /// struct Author: TableRecord, FetchableRecord, Decodable {
    ///     static let books = hasMany(Book.self)
    /// }
    /// struct Book: TableRecord, FetchableRecord, Decodable { }
    ///
    /// struct AuthorInfo: FetchableRecord, Decodable {
    ///     var author: Author
    ///     var bookCount: Int
    /// }
    ///
    /// // SELECT author.*, COUNT(DISTINCT book.id) AS bookCount
    /// // FROM author
    /// // LEFT JOIN book ON book.authorId = author.id
    /// // GROUP BY author.id
    /// let authorInfos = try Author.all()
    ///     .annotated(with: [Author.books.count])
    ///     .asRequest(of: AuthorInfo.self)
    ///     .fetchAll(db)
    /// ```
    public func annotated(with aggregates: [AssociationAggregate<RowDecoder>]) -> Self {
        aggregates.reduce(self) { request, aggregate in
            request.annotated(with: aggregate)
        }
    }
    
    /// Filters the fetched records with an association aggregate.
    ///
    /// For example:
    ///
    /// ```swift
    /// struct Author: TableRecord, FetchableRecord {
    ///     static let books = hasMany(Book.self)
    /// }
    /// struct Book: TableRecord, FetchableRecord { }
    ///
    /// // SELECT author.*
    /// // FROM author
    /// // LEFT JOIN book ON book.authorId = author.id
    /// // GROUP BY author.id
    /// // HAVING COUNT(DISTINCT book.id) > 5
    /// let authors = try Author.all()
    ///     .having(Author.books.count > 5)
    ///     .fetchAll(db)
    /// ```
    public func having(_ predicate: AssociationAggregate<RowDecoder>) -> Self {
        var request = self
        let expression = predicate.prepare(&request)
        return request.having(expression)
    }
}