Swift

@kizunajs/swift generates a native Swift client from your Kizuna routes. The generated client uses URLSession and Codable, with no third-party Swift dependencies required.

pnpm add @kizunajs/swift@beta

import { swiftClient } from '@kizunajs/swift';

export default defineConfig({
    adapter: expressAdapter(),
    routes,
    clients: [
        swiftClient({
            output: './ios/MyApp/Generated/APIClient.swift',
            namespace: 'API',
        }),
    ],
});

kizuna generate

let client = APIClient(baseURL: URL(string: "https://api.example.com")!)

// object body
let created = try await client.users.createUser(
    .body(
        name: "Ada",
        email: "ada@example.com"
    )
)

// path param + header
let user = try await client.users.getUser(
    .params(id: "42"),
    .headers(xRequestId: "trace-1")
)

// query
let page = try await client.users.listUsers(
    .query(page: 1, limit: 20)
)
let all = try await client.users.listUsers()

// discriminated-union body
try await client.sendNotification(
    .body(
        .email(to: "ada@example.com", subject: "Hi")
    )
)

import SwiftUI

struct UserRow: View {
    let user: API.User

    var body: some View {
        VStack(alignment: .leading) {
            Text(user.name)
            Text(user.id)
                .font(.caption)
        }
    }
}

struct UserList: View {
    @State private var users: [API.User] = []

    var body: some View {
        List(users, id: \.id) { user in
            UserRow(user: user)
        }
        .task {
            if let response = try? await client.users.listUsers() {
                users = response.body.users
            }
        }
    }
}

Branded IDs

A branded ID becomes a struct, API.UserId, encoded as the bare string. The parameter's type shows it, and passing a String does not compile.

An ID from a response is already an API.UserId, so it passes into the next call as it is:

let created = try await client.users.createUser(
    .body(
        name: "Ada Lovelace",
        email: "ada@example.com"
    )
)

try await client.users.deleteUser(
    .params(id: created.body.id)
)

A String from outside the API, like a deep link, is wrapped once:

let userID = url.lastPathComponent

let user = try await client.users.getUser(
    .params(id: API.UserId(userID))
)

rawValue reads the string back:

Text(user.body.id.rawValue)

Optional and null fields

An .optional() or .nullish() field is a String? that defaults to nil and is left out of the request. A .nullable() field is a String? with no default, sent as null when you pass nil:

try await client.users.updatePreferences(
    .params(id: userID),
    .body(
        timezone: nil,
        mutedChannels: []
    )
)

See Optional and null fields for which to declare.

Property naming

By default, field names are emitted verbatim, so total_count on the wire stays total_count in the generated type.

Pass --camel-case to convert wire fields to camelCase properties (total_count becomes totalCount), preserving the wire name via CodingKeys.

Unknown enum case (open enums)

By default a z.enum is a closed Swift enum that throws on a wire value it doesn't know, failing the whole response. Pass --unknown-enum-case to make enums forward-compatible: each gains an unknown(String) case, so an unrecognised value decodes to .unknown("newValue") instead of throwing:

switch event.kind {
case .login, .logout, .signup:
    render(event)
case .unknown(let raw):
    log("skipping unknown event kind: \(raw)")
}

The raw value is preserved, so re-encoding writes it back unchanged. Discriminated unions still throw on an unknown discriminator.

Generated client

The generated file exports a Sendable client with methods for each route and sub-clients for grouped routes. It is Sendable, so sharing it across tasks needs no actor hop per request. Each request group is a nested struct with a group-named factory:

import Foundation

public final class APIClient: Sendable {
    public let baseURL: URL
    public let session: URLSession

    public var users: APIUsersClient { ... }

    public func listUsers(_ query: APIClient.ListUsers.Query = .query()) async throws(APIClient.ListUsers.Failure) -> APIClient.ListUsers.Result {
        // ...
    }

    public enum ListUsers {
        public struct Query: Sendable {
            public let page: Int?
            public let limit: Int?
            public init(page: Int? = nil, limit: Int? = nil) { ... }
            public static func query(page: Int? = nil, limit: Int? = nil) -> Self { .init(page: page, limit: limit) }
        }
        // Response, Result, Failure ...
    }
}

Cancellation

Failure.cancelled covers a cancelled request, which SwiftUI produces routinely: a view carrying a .task cancels it on disappear, so a screen that loads and then closes arrives in your error path. An error path shared across several routes can check (error as? any KizunaFailure)?.isCancelled instead of matching each route's own enum.

Deprecation

Routes with deprecated and fields with .meta({ deprecated: ... }) emit @available(*, deprecated) in the generated Swift code, with the message when one is set:

@available(*, deprecated)
public func deleteUser(_ params: APIClient.DeleteUser.Params) async throws(APIClient.DeleteUser.Failure) {
    // ...
}

Streams

A route whose response streams returns its body as an AsyncThrowingStream. Named events become an Event enum with one case per event, each carrying its decoded payload:

let result = try await client.assistant.reply(.body(prompt: "hello"))
for try await event in result.body {
    switch event {
    case .delta(let delta):
        text += delta.text
    case .done(let done):
        print(done.outputTokens)
    }
}

A stream of one schema yields that type directly, a text/* stream yields one String per line, and a binary stream yields Data chunks. The status and headers are checked before the method returns, so a 400 throws its Failure as on any route. Cancelling the task that reads the stream closes the connection. A route that mixes a streamed status with another 2xx is left out of the client, with a warning.

Keeping it current

kizuna generate writes every client the config declares, so the Swift one is never generated on its own:

{
    "scripts": {
        "kizuna:generate": "kizuna generate",
        "kizuna:check": "kizuna generate --check"
    }
}

Run kizuna generate --check in CI, and a Swift client nobody regenerated fails the build instead of drifting from the routes it was generated from.

Reference

• generateSwiftClient