feat(postgrest): add type-safe PostgREST query layer via Swift Macros

[grdsdev]

Summary

Adds a type-safe PostgREST query layer to supabase-swift, allowing users to interact with their database using Swift types instead of raw strings — column names, table names, and query filters are all type-checked at compile time.

What's new

Swift Macros (@Table, @SelectionOf, @Relationship) — Applied to a Swift struct, @Table synthesizes full TableRepresentable conformance including:

• Insert and Update nested types (with optional fields for @Default/nullable columns; @PrimaryKey fields excluded from inserts)
• CodingKeys with automatic camelCase → snake_case conversion (overridable via @Column)
• columnName(for:) using KeyPath identity for type-safe column lookup
• Read-only tables/views via @Table(readOnly: true)

@SelectionOf(Table.self) declares a partial column projection or join query. Fields annotated with @Relationship(\Table.fkColumn) generate PostgREST disambiguation syntax (alias:tableName!fk_column(subselect)) — the FK column is identified via a Swift KeyPath (type-checked at compile time) and the referenced type is inferred from the field's type annotation.

@Table enforces that @Relationship fields are never declared on it — joins belong exclusively on @SelectionOf structs.

Typed query builders — Four generic wrappers delegate to the existing string-based builders:

• TypedPostgrestQueryBuilder<Table: TableRepresentable> — insert, upsert, update, delete, select
• TypedReadOnlyQueryBuilder<Table: ReadOnlyTableRepresentable> — select-only (insert/update/delete are compile errors)
• TypedPostgrestFilterBuilder<Table, Selection> — KeyPath-based filters (eq, neq, in, like, order, limit, …)
• TypedPostgrestTransformBuilder / TypedSingleResultBuilder — transform and single-row execution

Entry point — PostgrestClient.from(_ table: T.Type) returns the appropriate typed builder based on whether T conforms to TableRepresentable or ReadOnlyTableRepresentable.

Usage

// Define your table
@Table("messages")
struct Message {
  @PrimaryKey var id: UUID
  var senderId: UUID
  var body: String
}

// Declare a projection with a join
@SelectionOf(Message.self)
struct MessageWithSender {
  var id: UUID
  var body: String
  @Relationship(\Message.senderId) var sender: User
}
// MessageWithSender.selectString == "id,body,sender:users!sender_id(*)"

// Query with full type safety
let rows = try await supabase
  .from(Message.self)
  .select(MessageWithSender.self)
  .execute()
  .value  // [MessageWithSender]

// Filters use KeyPaths
let unread = try await supabase
  .from(Message.self)
  .select()
  .eq(\.senderId, value: userId)
  .execute()
  .value  // [Message]

Architecture

The typed API lives entirely in SupabaseSwiftMacros, a separate opt-in library. PostgREST and Supabase have no dependency on it, so swift-syntax is only compiled for users who explicitly import SupabaseSwiftMacros.

SupabaseMacros (compiler plugin, internal)
    ↑
SupabaseSwiftMacros (opt-in library)
    ├── Protocols.swift         — SelectionRepresentable, ReadOnlyTableRepresentable, TableRepresentable
    ├── Macros.swift            — @Table, @SelectionOf, @PrimaryKey, @Default, @Column, @Relationship
    ├── TypedBuilders/          — TypedPostgrestQueryBuilder, TypedPostgrestFilterBuilder, …
    └── PostgrestClient+Typed.swift — from(_ table: T.Type) entry point

PostgREST  ←──── no swift-syntax dependency
Supabase   ←──── no swift-syntax dependency

Diagnostics

Non-primitive @SelectionOf fields without @Relationship, @Relationship on a @Table field, and let bindings on @Table are all compile-time errors with descriptive messages.

Testing

• 17 macro expansion tests (exact synthesized source assertions via swift-macro-testing)
• 8 Swift Testing tests verifying KeyPath → snake_case column name translation via inline-snapshot of actual HTTP request URLs

Test plan

• swift test --filter SupabaseMacrosTests — all 17 expansion/diagnostic tests pass
• swift test --filter PostgRESTTests — all typed builder tests pass
• import PostgREST alone (without import SupabaseSwiftMacros) does not pull in swift-syntax
• @Table struct with a @Relationship field is a compile error
• Non-primitive @SelectionOf field without @Relationship is a compile error
• client.from(ReadOnlyView.self).insert(...) is a compile error

[coveralls]

Coverage Report for CI Build 28173234122

Coverage increased (+0.2%) to 81.177%

Details

• Coverage increased (+0.2%) from the base build.
• Patch coverage: No coverable lines changed in this PR.
• 6 coverage regressions across 2 files.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

6 previously-covered lines in 2 files lost coverage.

File	Lines Losing Coverage	Coverage
Sources/Auth/Internal/Keychain.swift	5	37.5%
Sources/Auth/Storage/KeychainLocalStorage.swift	1	41.67%

---

Coverage Stats

Relevant Lines:	9244
Covered Lines:	7504
Line Coverage:	81.18%
Coverage Strength:	37.2 hits per line

---

💛 - Coveralls