krzysztofzablocki/Swift-Macros

Swift Macros :rocket:

Swift Macros have brought in a new wave of possibilities. The aim of this project is to curate a list of community-created Macros and associated learning resources.

A lot of use-cases my Sourcery covered before can now be implemented by Swift Macros.

If you'd like to support my work and improve your engineering workflows, check out my SwiftyStack course

Learning Resources :books:

Tools

• Swift AST Explorer
  • This is extremely helpful when working with SwiftSyntax, I used this when writing Sourcery parser and you can leverage it to build your own Macros.

Frameworks

• Swift Macro Testing: Magical testing tools for Swift macros.
  • Provides assertMacro, an alternative to Apple's assertMacroExpansion that automatically snapshots macro expansions.
  • Also provides string-based matching for diagnostics and fix-its instead of manually specifying line and column numbers.
• Macro ToolKit
  • A powerful toolkit for creating concise and expressive Swift macros.

Apple:

Dive into Swift Macros with these WWDC sessions:

• Write Swift Macros: An introductory session on Macros, their roles, and workings with a basic example.
• Expand Swift Macros: A deeper exploration into crafting your Macros and testing their functionality.

Other Apple Resources:

• Macros: The Official Step-by-Step Guide to Using Macros for Compile-Time Code Generation in Swift.
• Example Swift Macros: Check out real-world examples from Apple, like @AddCompletionHandler and @AddAsync.

Community Blogs

• Swift Macros by SwiftLee
  • Antoine goes over the introduction of what Macros are and how you can build your own one with an example.
• How to Create Swift Macros in Xcode 15
  • Francesco goes over creating your first macro with testing and some interesting tidbits.
• Exploring Swift Macros
  • Sergey goes over creating a macro for a memberwise initaliser step by step with tests and convenience methods for SwiftSyntax
• Automating RawRepresentable Conformance with Swift Macros
  • Nikita goes over creating a macro for automating the String RawRepresentable conformance.
• Setup to develop Swift Macros
  • A step-by-step tutorial to develop Swift Macros.
• Support Swift macros with CocoaPods
  • Guide to distribute your macros using CocoaPods.
• Deep Dive Into Macros by Coding With Vera
  • Vera goes into how Macros work with a real-life comparison. Also explains the different types of macros and how they can help your codebase.
• How to Create Swift Macros: The Easiest and Least Boring Way
  • A step-by-step guide to building your first Swift macro from scratch, simple and straightforward. Learn the syntax, how to register a macro, how to test it, and more, all with practical examples.

Macros :computer:

SwiftUI

• EnvironmentValues & EnvironmentValue: Bypass boilerplate code and swiftly support new SwiftUI Environment Keys and Values.
• SFSymbols Macro: A Swift Macro for "type-safe" SF Symbols.
• SF Symbols Generator: A Swift macro generating type-safe SF Symbols.
• Prototype (WIP): Prototype generates SwiftUI Forms and Views for data structures and classes, designed to complement SwiftData Models seamlessly.
• HexColors: Swift Macros for validating hex colors from string and hexadecimal integer literals.
• Equatable: A Swift Macros for generating Equatable conformances for structs for high performance SwiftUI view diffing.
• ColorMacros: Compile-time-checked SwiftUI Colors.

Models

• Coding Keys: Effortlessly generate CodingKeys for converting snake_case to lowerCamelCase.
• Coding Keys: A Swift Macro for automating CodingKeys creation in Codable structs. Supports custom string mappings for properties.
• Coding Keys: Swift macros generating customizable CodingKeys.
• Builder pattern: Apply the Builder Pattern with ease by generating a Builder helper class, mimicking stored properties of the associated struct.
• Buildable Macro: An attached macro for structs, classes and enums, which produces a peer struct implementing the builder pattern. Initialise your object with minimal effort using default values:

  @Buildable struct Person { ... }
  let person = PersonBuilder(age: 42).build()
  

• EnhancedMirror: An experimental Mirror alternative that utilizes Swift Macros for static reflection.
• MetaCodable: Generates Codable implementation with following features:
  • Allows custom CodingKey value declaration per variable, instead of requiring you to write for all fields.
  • Allows to create flattened model for nested CodingKey values.
  • Allows to create composition of multiple Codable types.
  • Allows to provide default value in case of decoding failures.
  • Generates member-wise initializer considering the default values.
  • Allows to create custom decoding/encoding strategies.
  • Allows specifying fallback CodingKey values for fields and cases.
  • Allows to ignore specific properties/cases from decoding/encoding.
  • Allows setting CodingKey case style per type.
  • Allows decoding/encoding any type that conform to a particular protocol.
  • Allows decoding/encoding enums and protocols with external/internal/adjacent identifier.
  • Allows decoding/encoding enums and protocols with non-String identifier or customize the identifier detection.
• Sealed: Parsing easily Sealed Class JSON Model on Server. (ex. kotlin server)
• MacroCodableKit: Fully self-sufficient Codable kit:
  • Implements OpenAPI allOf and oneOf specs
  • Adjusts coding keys with a simple @CodingKey annotation
  • Decodes arrays and dictionaries in a safe manner with @CustomCoding(SafeDecoding)
  • Has built-in per-property Codable strategies and is extendible for new ones.
• SampleBuilder: The aim of @SampleBuilder is straightforward: Generate an array of sample data from your models for use in SwiftUI previews, unit tests, or any scenario that needs mock data—without the hassle of crafting it from scratch.It works with structs and enums!
  • SampleBuilderItem: If you want to customize your sample data even further for .random generator, you can use @SampleBuilderItem to specify the type of data you want to generate for each property in your model (images, prices, names, etc.).
• CodableOptionSet: CodableOptionSet allows for easy extensions to OptionSets implementing Codable protocol.
• ListableProperties: ListableProperties macro adds getProperties static func which returns an array of all property names in your model.
• BuildableMacro: A set of macros simplifying setter function generation for nominal types, inspired by SwiftUI modifiers and Observation framework macros:
  • @Buildable Automates the marking of settable properties as @BuildableTracked, excluding those marked as @BuildableIgnored.
  • @BuildableTracked Generates setter functions for each marked property, allowing fluent chaining of modifications.
  • @BuildableIgnored Excludes properties from automatic setter function generation.
• StaticArray: An allocation-less C-like fixed size arrays.
• UserDefaultsObservation: Combines UserDefaults and the Observation Framework. Users can easily create an Observable class where properties are backed by UserDefaults and NSUbiquitousKeyValueStore.
• LoremSwiftify: LoremSwiftify is a Macro that creates lorem ipsum data for your models.
• SwiftCopyable: Auto-generates a copy function for structs, making it easy to duplicate a struct instance while updating its properties with new values, similar to what Kotlin data class offers.

Dependency Injection

• swift-blade: A macro powered dependency injection framework.
• MDI: High performance dependency injection framework.
• SwiftEnvironment: SwiftUI based Environment global dependency locator framework with macro.
• SafeDI: Compile-time safe dependency injection via code generation.
• Stitch: A lightweight, SwiftUI inspired, compile time safe dependency injection library fully integrated into the SwiftUI lifecycle and compatible with view composition updates.
• Crocodil: Elegant dependency injection with Swift Macro
• Scaffold: A Swift macro-based dependency injection framework that provides elegant, type-safe dependency management through compile-time code generation.

Testing

• Testable: A macro that produces tests hooks on DEBUG builds to allow testing private methods and properties.
• Mockable: Provides automatic mock implementations for your protocols and an intuitive syntax that simplifies the process of mocking services and verifying invocations in your unit tests.
• swift-mockable: A Swift Macro that generates mock classes from protocols for testing with call tracking, configurable handlers, and thread-safe support for Sendable and Actor protocols.
• Power Assert: Adds assertions that can automatically produce information about the values being evaluated, and present it in an easily digestible form.
• Spyable: A Swift macro that simplifies and automates the process of creating spies for testing. Using the @Spyable annotation on a protocol, the macro generates a spy class that implements the same interface as the protocol and keeps track of interactions with its methods and properties.
• SwiftMock: A Swift framework that simplifies and automates the process of creating mock objects for testing. Using the @Mock macro on a protocol generates Mock class. You can stub methods and properties, verifying mock calls.
• XCTestParametrizedMacro: A Swift macro that greatly simplifies testing for many parameters. It will allow you to write one test method and parametrize it with many cases. Use @Parametrize(input: ["any", "values"]) to automatically generate new test methods for all parameters.
• swift-mocking A compact macro powered by parameter packs that provides mock objects for your protocols and a Mockito-style API.

Networking

• SwiftRequest: SwiftRequest is a lightweight, type-safe HTTP client for Swift, streamlining the construction and execution of HTTP request build on top of Macros.
• Papyrus: A type-safe, protocol based HTTP client - turn your APIs into Swift protocols. Includes first-class testing support with out of the box mocking.
• SwiftNet: SwiftNet allows to create complex network request with built-in SSL/Certificate pinning, safe access token storage, automatic callback mechanism and the ability to build those requests as Combine's Publishers as well as Async/Await tasks. Framework also provides methods to test your requests easily with or without response model checks.
• Snowdrop: Super lightweight, type-safe, protocol based framework that includes simple and fast out of the box mocking, SSL/Certificate pinning, interception mechanism and the path variable default value support to bypass Swift protocol's limitations.

Enums

• CasePaths: @CasePathable produces key paths for enum cases, allowing enums to be used in dynamic member lookup and other generic algorithms.
• ExtractCaseValue: A Swift macro that extracts associated values from enum cases.
• EnumeratorMacro: Generate custom code for your enums using Mustache templates.
• EnumRawValues: Enables full-fledged raw values for enums, supporting any equatable raw value types, assigning raw values with constants, expressions and more.
• EnumOptionSet: Enables more concise and safer declaration of option sets through enumeration notation.
• CaseEquatable: Automatically generates a “raw” case-only enumeration and makes your enum conform to CaseEquatable. This allows you to compare only the case names—ignoring any associated values.
• QuickEnum: Quickly generate a simple enum based on a property's type and a list of cases that you provide

Misc

• Protocol: A macro that produces a protocol based on a class/struct public interface.
• MacroKit: A collection of macros including:
  • @PublicInit: Generate public memberwise init
  • @GenerateMock: Create a mock object for testing from a protocol
  • @KeyPathIterable: Like CaseIterable but for available keypaths on a type
  • @StaticMemberIterable: Like CaseIterable but for available static members on a type
  • More to come...
• InitMacro: A Swift Macro implementation that generates initializers for classes and structs with support for default values, wildcards and access control.
• AssociatedObject: A Swift Macro for adding stored properties in Extension to classes defined in external modules, etc.
  (This is implemented by wrapping objc_getAssociatedObject/objc_setAssociatedObject.)
• AssociatedObjectMacro: A Swift Macro for convenient declaration of variables in class extensions.
• AliasMacro: A Swift Macro for defining aliases for types, functions, or variables.
• UtilityType: UtilityType is an innovative library designed to realize TypeScript's UtilityTypes in Swift. See more details: https://www.typescriptlang.org/docs/handbook/utility-types.html
  • @Partial,@Required: Constructs a type with all properties set to optional(@Partial) or require(@Required). This utility will return a type that represents all subsets of a given type.
  • @Pick,@Omit: Constructs a type by picking(@Pick) or removing(@Omit) the set of specific properties keys (only string literal) from attached Type.
  • @Exclude,@Extract: Constructs a type by excluding(@Exclude) or extracting(@Extract) from enum all cases.
  • @Parameters: Constructs a tuple type from the types used in the parameters of a function type.
  • @ReturnType: Constructs a type consisting of the return type of function.
• Reuse Identifier: A Reuse Identifier Macro that is useful in generation of a reuse id for your UICollectionViewCells and UITableViewCells
• SwiftMacros collection: A practical collection of Swift Macros that help code correctly and smartly.
• ModifiedCopyMacro: A Swift macro for making inline copies of a struct by modifying a property.
• DictionaryLiteralShorthandMacro: A Swfit macro for creating dictionary literals with keys as "string representations of corresponding variable names".
• TemporaryVariable: TemporaryVariable provide a macro #info {...}. It capture most function calls and assign them to temporary variables.
• Localizable: Localizable A macro that produces variables and methods, for your localization files. From the enumeration keys.
• Localize: #Localize An inline (freestanding) macro that expands to LocalizedStringResource and works within Swift packages.
• TranslateKit SDK: A Swift localization framework that simplifies app translation with macros and pre-localized strings.
  • #tk("Save Changes") automatically generates a semantic localization key instead of hardcoding strings.
  • 2000+ pre-localized strings in ~40 languages, covering common UI text without adding them to a String Catalog.
  • Autocompletion support in Xcode makes discovering the right translation easy.
  • Category-specific extensions for App Store app types (Finance, Health, Productivity, etc.).
  • Supports Swift Packages with #tkm, ensuring correct key resolution inside SPM modules.
• SafeDecoding: SafeDecoding A macro that implements failable decoding via custom initializer; allows auto-conformance to `Decodable`` and per-property opt-out.
• ObfuscateMacro: A macro for obfuscating strings and make them harder to find by binary analysis.
• MemoizeMacro: A macro for effortless function memoization in Swift
• MemberwiseInit: Informed by explicit developer cues, @MemberwiseInit can more often automatically provide your intended memberwise init, while following the same safe-by-default semantics underlying Swift’s memberwise initializers.
• PropertyTracer: Library for tracing access to properties.@PropertyTraced macro makes possible to trace from which method a property has been accessed.
• URLMacro: A lightweight Swift macro for compile-time URL validation. Validates URLs at build time with clear error messages and zero runtime overhead. Supports SwiftSyntax 509-601 for maximum compatibility.
• Swift Macros: Contains a collection of useful macros:
  • #symbol: Verify if SFSymbol is valid
  • #URL: Validate and return URL Object
  • #unwrap: Unwrap value.
  • @AssociatedValues: Add variables to retrieve the associated values.
  • @Singleton: Generate singleton code for struct and class.
  • More to come...
• Migrator: Migrator is a versatile Swift package designed to streamline the execution of asynchronous tasks with dependency management on all Apple platforms. The package also includes a handy macro for semantic versioning (SemVer 2.0.0).
  • #SemanticVersion("1.2.3")
• Equatable: A macro for synthesizing Equatable conformance for classes and actors.
• CloakedString: A macro designed to improve the security of open text strings in Swift applications
• SmartLogMacro: Powerful Swift macros for structured logging, privacy, and seamless 3rd-party log forwarding
• Loggable: Set of macros that support type-wide and per-function logging with ability to customize how logs are handled
• IterableMacros: @CaseIterable and @StaticMemberIterable power macros.
• SettingsKit: Swift macros for saving values in UserDefaults. Type and Typo safe.

Take part in this exciting evolution in Swift. Your contributions are most welcome!