From eb669fbb54adcdb952779af48ff23404ac208c6f Mon Sep 17 00:00:00 2001 From: Gwynne Raskind Date: Tue, 14 Jul 2026 11:25:59 -0500 Subject: [PATCH] Add missing declarations to docs, fix mis-specified declarations. update README. --- README.md | 19 +++++++++--------- .../Builders/Prototypes/SQLQueryFetcher.swift | 6 +++++- Sources/SQLKit/Docs.docc/BasicUsage.md | 20 +++++++++---------- Sources/SQLKit/Docs.docc/SQLKit.md | 6 ++++++ .../SQLQueryFetcher+ExtensionDocs.md | 4 ++-- 5 files changed, 33 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 9d994894..f9ac80cf 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,15 @@ -

+

SQLKit
-
-Documentation -Team Chat -MIT License -Continuous Integration -Code Coverage -Swift 6.0+ -

+ +[![Documentation](https://design.vapor.codes/images/readthedocs.svg)](https://docs.vapor.codes/4.0/) +[![Team Chat](https://design.vapor.codes/images/discordchat.svg)](https://discord.gg/vapor) +[![MIT License](https://design.vapor.codes/images/mitlicense.svg)](LICENSE) +[![Continuous Integration](https://img.shields.io/github/actions/workflow/status/vapor/sql-kit/test.yml?event=push&style=plastic&logo=github&label=tests&logoColor=ccc)](https://github.com/vapor/sql-kit/actions/workflows/test.yml) +[![Code Coverage](https://img.shields.io/codecov/c/github/vapor/sql-kit?style=plastic&logo=codecov&label=codecov)](https://codecov.io/github/vapor/sql-kit) +[![Swift 6.1+](https://design.vapor.codes/images/swift61up.svg)](https://swift.org) + +

diff --git a/Sources/SQLKit/Builders/Prototypes/SQLQueryFetcher.swift b/Sources/SQLKit/Builders/Prototypes/SQLQueryFetcher.swift index 8250a13a..f6c9489c 100644 --- a/Sources/SQLKit/Builders/Prototypes/SQLQueryFetcher.swift +++ b/Sources/SQLKit/Builders/Prototypes/SQLQueryFetcher.swift @@ -128,9 +128,13 @@ extension SQLQueryFetcher { /// If `self` conforms to ``SQLPartialResultBuilder``, ``SQLPartialResultBuilder/limit(_:)`` is used to avoid /// loading more rows than necessary from the database. /// + /// > Note: This method returns `Optional` rather than the semantically identical `(any SQLRow)?` + /// > due to a bug in Swift DocC causing it to become confused by the latter. The syntactic sugar will be + /// > restored once the bug is fixed. + /// /// - Returns: The first output row, if any. @inlinable - public func first() async throws -> (any SQLRow)? { + public func first() async throws -> Optional { (self as? any SQLPartialResultBuilder)?.limit(1) nonisolated(unsafe) var rows = [any SQLRow]() try await self.run { if rows.isEmpty { rows.append($0) } } diff --git a/Sources/SQLKit/Docs.docc/BasicUsage.md b/Sources/SQLKit/Docs.docc/BasicUsage.md index e7dace3d..31f42b19 100644 --- a/Sources/SQLKit/Docs.docc/BasicUsage.md +++ b/Sources/SQLKit/Docs.docc/BasicUsage.md @@ -166,16 +166,16 @@ Notice that `Encodable` values are automatically bound as parameters instead of The select builder includes the following methods (most of which have numerous variations): -- `columns()` (specify a list of columns and/or expressions to return) -- `from()` (specify a table to select from) -- `join()` (specify additional tables and how to relate them to others) -- `where()` and `orWhere()` (specify conditions that narrow down the possible results) -- `limit()` and `offset()` (specify a limited and/or offsetted range of results to return) -- `orderBy()` (specify how to sort results before returning them) -- `groupBy()` (specify columns and/or expressions for aggregating results) -- `having()` and `orHaving()` (specify secondary conditions to apply to the results after aggregation) -- `distinct()` (specify coalescing of duplicate results) -- `for()` and `lockingClause()` (specify locking behavior for rows that appear in results) +- ``SQLSelectBuilder/columns(_:)-([SQLExpression])`` (specify a list of columns and/or expressions to return) +- ``SQLSelectBuilder/from(_:)-(String)`` (specify a table to select from) +- ``SQLSelectBuilder/join(_:method:on:_:_:)-(SQLExpression,_,_,_,_)`` (specify additional tables and how to relate them to others) +- ``SQLSelectBuilder/where(_:_:_:)-(SQLExpression,SQLBinaryOperator,_)`` and ``SQLSelectBuilder/orWhere(_:_:_:)-(SQLExpression,SQLBinaryOperator,_)`` (specify conditions that narrow down the possible results) +- ``SQLSelectBuilder/limit(_:)`` and ``SQLSelectBuilder/offset(_:)`` (specify a limited and/or offsetted range of results to return) +- ``SQLSelectBuilder/orderBy(_:_:)-(String,_)`` (specify how to sort results before returning them) +- ``SQLSelectBuilder/groupBy(_:)-(SQLExpression)`` (specify columns and/or expressions for aggregating results) +- ``SQLSelectBuilder/having(_:_:_:)-(SQLExpression,SQLBinaryOperator,_)`` and ``SQLSelectBuilder/orHaving(_:_:_:)-(SQLExpression,SQLBinaryOperator,_)`` (specify secondary conditions to apply to the results after aggregation) +- ``SQLSelectBuilder/distinct()`` (specify coalescing of duplicate results) +- ``SQLSelectBuilder/for(_:)`` and ``SQLSelectBuilder/lockingClause(_:)`` (specify locking behavior for rows that appear in results) Conditional expressions provided to `where()` or `having()` are joined with `AND`. Corresponding `orWhere()` and `orHaving()` methods join conditions with `OR` instead. diff --git a/Sources/SQLKit/Docs.docc/SQLKit.md b/Sources/SQLKit/Docs.docc/SQLKit.md index 2503ad55..09239987 100644 --- a/Sources/SQLKit/Docs.docc/SQLKit.md +++ b/Sources/SQLKit/Docs.docc/SQLKit.md @@ -43,6 +43,8 @@ SQLKit does _not_ provide facilities for creating or managing database connectio - ``SQLAliasedColumnListBuilder`` - ``SQLColumnUpdateBuilder`` +- ``SQLCommonTableExpressionBuilder`` +- ``SQLCommonUnionBuilder`` - ``SQLJoinBuilder`` - ``SQLPartialResultBuilder`` - ``SQLPredicateBuilder`` @@ -75,6 +77,7 @@ SQLKit does _not_ provide facilities for creating or managing database connectio - ``SQLSelectBuilder`` - ``SQLSubqueryBuilder`` - ``SQLUnionBuilder`` +- ``SQLUnionSubqueryBuilder`` - ``SQLUpdateBuilder`` ### Syntactic Expressions @@ -109,6 +112,8 @@ SQLKit does _not_ provide facilities for creating or managing database connectio - ``SQLColumnAssignment`` - ``SQLColumnConstraintAlgorithm`` - ``SQLColumnDefinition`` +- ``SQLCommonTableExpression`` +- ``SQLCommonTableExpressionGroup`` - ``SQLConflictAction`` - ``SQLConflictResolutionStrategy`` - ``SQLDropBehavior`` @@ -124,6 +129,7 @@ SQLKit does _not_ provide facilities for creating or managing database connectio - ``SQLSubquery`` - ``SQLTableConstraintAlgorithm`` - ``SQLUnionJoiner`` +- ``SQLUnionSubquery`` ### Query Expressions diff --git a/Sources/SQLKit/Docs.docc/SQLQueryFetcher+ExtensionDocs.md b/Sources/SQLKit/Docs.docc/SQLQueryFetcher+ExtensionDocs.md index 94696311..c1af142c 100644 --- a/Sources/SQLKit/Docs.docc/SQLQueryFetcher+ExtensionDocs.md +++ b/Sources/SQLKit/Docs.docc/SQLQueryFetcher+ExtensionDocs.md @@ -11,7 +11,7 @@ ### Getting All Rows -- ``SQLQueryFetcher/all(decoding:with:)->[D]`` +- ``SQLQueryFetcher/all()->[SQLRow]`` - ``SQLQueryFetcher/all(decoding:)->[D]`` - ``SQLQueryFetcher/all(decoding:prefix:keyDecodingStrategy:userInfo:)->[D]`` - ``SQLQueryFetcher/all(decoding:with:)->[D]`` @@ -19,7 +19,7 @@ ### Getting One Row -- ``SQLQueryFetcher/first()->EventLoopFuture<(SQLRow)?>`` +- ``SQLQueryFetcher/first()->SQLRow?`` - ``SQLQueryFetcher/first(decoding:)->D?`` - ``SQLQueryFetcher/first(decoding:prefix:keyDecodingStrategy:userInfo:)->D?`` - ``SQLQueryFetcher/first(decoding:with:)->D?``