swift-typescript-bridge: The Swift Macro That Makes TypeScript Unions Feel Native
A close look at the macro tricks, discriminator fast path, and literal-union decoding that let Swift mirror TypeScript schemas with far less boilerplate.
- swift-typescript-bridge turns TypeScript unions into Swift enums without forcing teams to handwrite the usual Codable scaffolding.
- Its most interesting move is mixed-union decoding, where literal and structural variants can live in one generated model.
- The discriminator fast path is the difference between a clever macro and a serious interoperability tool.
- The project is narrowly scoped, which is why it feels polished rather than overbuilt.
The best way to understand swift-typescript-bridge is to start with the part Swift usually makes painful: unions. TypeScript is happy to say a field can be "auto" | 100 or one of several object shapes. Swift usually answers with a long enum, custom decoding logic, and a lot of repetition.
This repo does not pretend that mismatch disappears. It does something better. It moves the mismatch into a macro, then generates the enum, the decoding paths, and the discriminator-aware shortcuts for you.
The union problem Swift never solved
TypeScript unions are expressive because they are cheap to write and easy to compose. Swift can model the same ideas, but the ceremony piles up fast. If you want a value that might be one of several literals, or one of several payload types, you usually end up building the shape yourself and teaching Codable how to walk it.
That is tolerable once. It is exhausting across an API surface. The appeal of this project is that it turns a schema translation problem into a declaration problem.
@Union("auto", "manual")
enum Mode {}
@Union(User.self, Org.self)
enum Actor {}
How @Union compresses boilerplate into one declaration
The public surface is small on purpose. The library defines a literal-boundary protocol, then lets the macro generate the cases and decoding behavior for supported literal types like String, Int, Double, and Bool. That keeps the API opinionated instead of magical.
The mixed-union path is the clever bit. When the macro sees something like @Union("auto", 100), it can generate a single enum that stores a raw value through an existential literal type, then tries the right concrete representation at decode time.
public protocol _LiteralType {}
extension String: _LiteralType {}
extension Int: _LiteralType {}
extension Double: _LiteralType {}
extension Bool: _LiteralType {}
That small boundary matters. It prevents the macro from drifting into a generic grab bag and forces the generated code to stay inside the types Swift can actually reason about.
The real trick: discriminator-aware decoding
The most interesting behavior in the repo is not the enum generation itself. It is the decoder path for structural unions. The library can recognize when a candidate type conforms to TypeDiscriminated, read a discriminator key, and jump directly to the right branch instead of trying every schema in sequence.
That is the difference between a neat macro and a practical one. Sequential decoding is fine when you have two cases. It gets expensive, and brittle, when you have many. A discriminator gives the library a short-circuit, which is both faster and less error-prone.
Introducing swift-typescript-bridge, an open-source tool that automatically generates Swift code from TypeScript definitions. Bridging Swift and TypeScript has never been easier!
Why this is faster than naive trial-and-error decoding
The fallback path still matters. Not every union will carry a clean discriminator, and not every type should be forced into one. When the tag is missing, the library can still fall back to sequential decode attempts using a single-value container.
| Approach | Input source | Union support | Decoder strategy | Swift ergonomics | Best fit |
|---|---|---|---|---|---|
| Manual Codable boilerplate | Handwritten Swift | Yes, but custom | Usually trial-and-error or custom branching | Verbose | Small one-off models |
| swift-typescript-bridge | TypeScript definitions | Yes, including mixed literals | Discriminator fast path plus fallback | Macro-generated | Shared TS to Swift schemas |
| QuickType | JSON or schema | Partial, depends on schema shape | Generated parsing code | Good, but broader and less TS-specific | General codegen |
| Language-level interop | Future toolchain support | Potentially native | Toolchain-defined | Best long term, not here yet | Platform evolution |
That tradeoff is the heart of the project. It does not force every schema into the fastest path. It makes the fast path available when the source type supports it, then preserves a sane fallback when it does not.
What it is competing with
This repo sits in a narrow but useful lane. Manual Codable code gives you full control, but costs time. Generators like QuickType help, but they are broader tools. Larger interop efforts may eventually reduce the need for a bridge like this, but they are not the same thing as a working macro today.
That is why the project feels specific in a good way. It is optimized for one boring, expensive job: keeping Swift aligned with TypeScript schemas without making developers pay the boilerplate tax over and over.
Why the project feels unusually polished for its size
The codebase shows that the author cared about the edge cases that usually get ignored. Access modifiers propagate correctly, tests cover numeric and literal behavior, and the macro layer is separated cleanly from the public API.
The dependency surface is also small. That matters for a macro package, because every extra dependency increases the chance that the toolchain becomes the real product. Here, the product stays simple: SwiftSyntax, Swift 6.2, and a focused set of transformations.
Origin and intent
Sunghyun Kim introduced the project as a way to automatically generate Swift code from TypeScript definitions. That framing is useful because it keeps the story honest. This is not a new type system. It is a bridge for teams that already made TypeScript the source of truth.
The project exists because the cost of retyping schemas is higher than it looks. Once a team has both a TypeScript backend or contract layer and a Swift consumer, the real bug risk is drift. This repo attacks that drift directly.





