Feature Proposal: Macros for API Code Generation

[o-nnerb]

Overview

@Endpoint — an attached macro that turns a lightweight, attribute-annotated struct into a full Property, generating the PropertyModifier boilerplate that would otherwise be hand-written for every endpoint.

@Endpoint
struct FetchUser {

    let payload: UserModel

    @URL("https://api.example.com/user")
    @Headers(HTTPHeaders)
    @Method(.get)
    @Queries([String: String])
    func callAsFunction<Content: Property>(_ content: Content) -> some Property {
        content
        Payload(payload)
    }
}

Usage — FetchUser is a plain Property, usable standalone with nothing before it:

DataTask {
    FetchUser(payload: model)
}

How the expansion works

@URL/@Headers/@Method/@Queries are attribute syntax @Endpoint's own macro expansion reads off the callAsFunction declaration via SwiftSyntax — they don't need to be independently functioning macros themselves, only valid attribute syntax the compiler accepts.

The macro generates two things, both built entirely from existing public API — no changes to Property, PropertyModifier, or the graph engine are needed:

1. A nested Modifier: PropertyModifier, mirroring the modifier boilerplate already written by hand for every existing PropertyModifier conformance in the codebase:

   struct Modifier: PropertyModifier {
       let endpoint: FetchUser
       let url: String
       let headers: HTTPHeaders
       let method: HTTPMethod
       let queries: [String: String]
   
       func body(content: Content) -> some Property {
           FlexibleURL(url)
           HeaderGroup(headers)
           RequestMethod(method)
           QueryGroup(queries)
           endpoint(content)
       }
   }

2. Property conformance on FetchUser itself, feeding Modifier an empty base via the existing EmptyProperty leaf (Properties/Sources/Extra Properties/Empty/EmptyProperty.swift) — this is the part that makes FetchUser(payload: model) usable standalone, with nothing composed before it:

   extension FetchUser: Property {
       var body: some Property {
           EmptyProperty().modifier(
               Modifier(endpoint: self, url: "...", headers: ..., method: ..., queries: ...)
           )
       }
   }

callAsFunction's content parameter is the macro-assembled scaffolding (FlexibleURL + HeaderGroup + RequestMethod + QueryGroup), and the author's own callAsFunction body is the escape hatch for layering extra properties (like Payload(payload)) on top of it.

Constraint that shaped this design

callAsFunction must be synchronous and non-throwing — Property.body: Body { get } and PropertyModifier.body(content:) -> Self.Body are both plain, non-async, non-throws requirements. The async/throwing part of this package's pipeline is PropertyNode.make(_ make: inout Make) async throws, which runs later, during resolution of already-built leaf nodes — not during graph composition. An endpoint needing genuine async/throwing work (e.g. an async token fetch) isn't expressible through callAsFunction; it would need its own PropertyNode leaf with a real make(), not this macro.

Infra cost

No macro target exists in Package.swift today. This needs a new SwiftPM target depending on swift-syntax + SwiftCompilerPlugin, exposed from the main RequestDL target via @attached(...) public macro Endpoint() = #externalMacro(...). Macro plugins are host-tool executables — needs verifying they build cleanly on the Linux CI runners this project already runs (swift-ci.yaml), not just assumed to work.

Milestone: 4.5.0

[o-nnerb]

Repurposed from a generic "macros" idea into a concrete design: @Endpoint, an attached macro that expands an attribute-annotated struct into a full Property, generating a PropertyModifier + an EmptyProperty()-based Property conformance so the result is usable standalone in a @PropertyBuilder block. Built entirely on existing public API (PropertyModifier, EmptyProperty, .modifier(_:)) — no core engine changes needed, only the macro itself (new SwiftPM macro target + swift-syntax dependency). Ready to be picked up as an implementation task.