|
| 1 | +# Getting started |
| 2 | + |
| 3 | +Generate your schema, port the queries and mutators your app uses, and |
| 4 | +create a client. |
| 5 | + |
| 6 | +## Add the package |
| 7 | + |
| 8 | +The package is published from this repository's `swift/` directory to |
| 9 | +`github.com/wevm/zero-swift`: |
| 10 | + |
| 11 | +```swift |
| 12 | +.package(url: "https://github.com/wevm/zero-swift", from: "0.1.0"), |
| 13 | +``` |
| 14 | + |
| 15 | +Depend on `Zero`, and on `ZeroUI` for SwiftUI, UIKit, and AppKit. It needs |
| 16 | +Swift 6.2 and iOS 26 or macOS 26; the core also builds on Linux. |
| 17 | + |
| 18 | +## Generate the schema |
| 19 | + |
| 20 | +Your TypeScript schema stays the source of truth. The `zero-swift` CLI |
| 21 | +generates Swift from it: a ``ZeroSchema``, a row struct for each table, and |
| 22 | +a `zql` builder with a ``Query`` for each table. |
| 23 | + |
| 24 | +```json |
| 25 | +{ |
| 26 | + "schema": "../web/shared/schema.ts", |
| 27 | + "output": "Sources/App/Schema.swift", |
| 28 | + "schemaName": "app", |
| 29 | + "tables": { |
| 30 | + "issue": {"columns": {"shortID": {"type": "int"}}} |
| 31 | + } |
| 32 | +} |
| 33 | +``` |
| 34 | + |
| 35 | +```sh |
| 36 | +npx zero-swift codegen # reads zero-swift.json |
| 37 | +npx zero-swift codegen --check # in CI: fails when Schema.swift is stale |
| 38 | +``` |
| 39 | + |
| 40 | +`number()` columns are `Double`; give a column the type `int` to make it an |
| 41 | +`Int`, which must then hold integers. `json<T>()` columns get a generated `Codable` type when `T` is a |
| 42 | +plain object or literal union. |
| 43 | + |
| 44 | +## Port your queries and mutators |
| 45 | + |
| 46 | +Write the queries and mutators your app runs in Swift, named as in your |
| 47 | +TypeScript registries. The server runs the TypeScript ones; the client runs |
| 48 | +the Swift ones to show results before the server answers. |
| 49 | + |
| 50 | +```swift |
| 51 | +enum IssueQueries { |
| 52 | + static let open = defineQuery("issues.open") { (_: NoArgs, auth: AuthData?) in |
| 53 | + zql.issue.where(\.open, true).orderBy(\.modified, .desc).limit(50) |
| 54 | + } |
| 55 | + static let byID = defineQuery("issues.byID") { (id: String, auth: AuthData?) in |
| 56 | + zql.issue.where(\.id, id).related(\.comments).one() |
| 57 | + } |
| 58 | +} |
| 59 | + |
| 60 | +enum IssueMutators { |
| 61 | + struct Create: Codable, Sendable { |
| 62 | + var id: String |
| 63 | + var title: String |
| 64 | + var created: Double |
| 65 | + } |
| 66 | + |
| 67 | + static let create = defineMutator("issue.create") { (tx, args: Create, auth: AuthData?) in |
| 68 | + guard let auth else { throw ApplicationError("Not logged in") } |
| 69 | + try tx.mutate.issue.insert( |
| 70 | + Issue(id: args.id, title: args.title, creatorID: auth.sub, created: args.created)) |
| 71 | + } |
| 72 | +} |
| 73 | +``` |
| 74 | + |
| 75 | +Mutators are plain `throws` functions: they read and write through the |
| 76 | +``Transaction`` synchronously. Pass IDs and timestamps in as arguments |
| 77 | +rather than making them up inside, so the client and the server write the |
| 78 | +same rows. |
| 79 | + |
| 80 | +The drift harness checks the ports: `zero-swift drift record` runs your |
| 81 | +TypeScript queries and mutators on sample arguments and writes what they |
| 82 | +did, and `Drift.expectNoDrift` in `ZeroTesting` fails a test where the Swift |
| 83 | +ones do something else, or where a query or mutator exists on one side only. |
| 84 | + |
| 85 | +## Create a client |
| 86 | + |
| 87 | +```swift |
| 88 | +var options = ZeroOptions(cacheURL: "https://zero.example.com", userID: auth?.sub, auth: token) |
| 89 | +options.mutateURL = "https://api.example.com/mutate" // or zero-cache's configured URL |
| 90 | +options.queryURL = "https://api.example.com/query" |
| 91 | + |
| 92 | +let zero = try Zero( |
| 93 | + schema: .app, context: auth, mutators: [IssueMutators.create], options: options) |
| 94 | +``` |
| 95 | + |
| 96 | +Register every mutator the app may run: pending mutations are stored by |
| 97 | +name and run again when the server's state arrives, including after a |
| 98 | +relaunch. The client keeps its replica in SQLite (``ZeroStorage``) and |
| 99 | +connects with `URLSession`. |
| 100 | + |
| 101 | +## Read rows |
| 102 | + |
| 103 | +``LiveQuery`` is an observable object whose `data` stays current: |
| 104 | + |
| 105 | +```swift |
| 106 | +let open = try zero.liveQuery(IssueQueries.open()) |
| 107 | +open.data // [Issue] |
| 108 | +open.resultType // .unknown until the server has confirmed the rows, then .complete |
| 109 | +``` |
| 110 | + |
| 111 | +In SwiftUI, `@ZeroQuery` from `ZeroUI` does the same for a view. For UIKit |
| 112 | +and AppKit, `DiffableAdapter` feeds a diffable data source. |
| 113 | + |
| 114 | +`zero.materialize(_:ttl:)` returns the untyped ``MaterializedView``, whose |
| 115 | +``ViewSnapshot``s say which rows were inserted, removed, or changed. |
| 116 | +`zero.run(_:type:ttl:)` reads rows once, and `zero.preload(_:ttl:)` syncs |
| 117 | +rows without a view. |
| 118 | + |
| 119 | +## Change rows |
| 120 | + |
| 121 | +```swift |
| 122 | +let result = zero.mutate(IssueMutators.create(.init(id: newID(), title: "Crash", created: now))) |
| 123 | +try await result.client.value // the optimistic run |
| 124 | +try await result.server.value // the server's verdict |
| 125 | +``` |
| 126 | + |
| 127 | +The client applies the mutator at once; views update before `mutate` |
| 128 | +returns. The server runs its own mutator; when its result arrives, the |
| 129 | +client replaces its optimistic changes with the server's. |
| 130 | + |
| 131 | +## Follow the connection |
| 132 | + |
| 133 | +``Connection`` is observable. Its ``ConnectionState`` is `.needsAuth` when |
| 134 | +the server rejects the token: get a new one and call |
| 135 | +``Connection/connect(auth:)``. |
0 commit comments