MetaCodable

https://github.com/swiftylab/metacodable
Admin
MetaCodable is a Swift framework that uses macros to enhance and simplify `Codable` implementations,...
Tokens:15,302
Snippets:106
Trust Score:9
License:MIT
Update:11 months ago
Show doc for...
Tokens:
Raw
### Setup Development Environment (Bash)

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/README.md

Commands to clone the MetaCodable repository and build the project using Swift Package Manager.

```bash
git clone https://github.com/SwiftyLab/MetaCodable.git
cd MetaCodable
swift build
```

--------------------------------

### Bash Build and Test Commands

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/TESTING.md

Provides essential bash commands for building the Swift project and running its test suite, including options for code coverage analysis.

```bash
swift build
```

```bash
swift test
```

```bash
swift test --enable-code-coverage
```

--------------------------------

### Swift Macro Test Example

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/TESTING.md

Demonstrates a basic unit test for Macro expansion correctness using MetaCodable's testing framework. It asserts the correct expansion of a Codable struct with a single property.

```swift
struct CodingKeysTests {
    @Test
    func testBasicExpansion() {
        assertMacroExpansion(
            """
            @Codable
            struct Model {
                let property: String
            }
            """,
            expandedSource: // Expected expansion
        )
    }
}
```

--------------------------------

### Swift Runtime Debugging: Custom Helper Coder Logging

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/TROUBLESHOOTING.md

Provides an example of a `HelperCoder` implementation that logs the type being decoded during runtime. This aids in tracing decoding processes and identifying potential issues with specific data types.

```swift
struct DebugCoder<T: Codable>: HelperCoder {
    func decode(from decoder: Decoder) throws -> T {
        print("Decoding type: (T.self)")
        return try T(from: decoder)
    }
}
```

--------------------------------

### Bash Build Command: Enabling Verbose Output

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/TROUBLESHOOTING.md

Illustrates how to enable verbose output for the Swift build process using the `-v` flag. This is useful for debugging build plugin issues by providing detailed logs of each build step.

```bash
swift build -v
```

--------------------------------

### Install MetaCodable via Swift Package Manager

Source: https://github.com/swiftylab/metacodable/blob/main/README.md

Add MetaCodable as a dependency to your Swift package by including its URL in the package's dependencies. Then, link the 'MetaCodable' product to your target.

```swift
.package(url: "https://github.com/SwiftyLab/MetaCodable.git", from: "1.0.0"),
```

```swift
.product(name: "MetaCodable", package: "MetaCodable"),
```

--------------------------------

### MetaCodable Build Tool Plugin Configuration (JSON)

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/BUILD_PLUGIN.md

Example JSON configuration for the MetaCodable plugin. This configuration allows customization of various aspects of the code generation process, such as scanning dependencies, output format, generated file prefixes, and the modules to include.

```json
{
    "scanDependencies": true,
    "outputFormat": "swift",
    "generatedFilePrefix": "Generated",
    "modules": ["CoreModule", "UtilityModule"]
}
```

--------------------------------

### Swift Macro Expansion Example: Correcting Conflicting Attributes

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/TROUBLESHOOTING.md

Demonstrates how to resolve 'Conflicting attributes' errors in Swift macros by ensuring only one instance of a specific attribute, like CodingKeys, is applied to a struct.

```swift
// Instead of:
@Codable
@CodingKeys(.snake_case)
@CodingKeys(.PascalCase)  // Error: Multiple CodingKeys attributes
struct Model { }

// Use:
@Codable
@CodingKeys(.snake_case)
struct Model { }
```

--------------------------------

### Install MetaCodable via CocoaPods

Source: https://github.com/swiftylab/metacodable/blob/main/README.md

Integrate MetaCodable into your Xcode project using CocoaPods by specifying 'MetaCodable' in your Podfile.

```ruby
pod 'MetaCodable'
```

--------------------------------

### Swift Protocol Definition for Generation

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/BUILD_PLUGIN.md

Illustrates how to mark Swift protocols for code generation using the `@DynamicCodable` attribute. Protocols marked this way will have their implementations generated by the MetaCodable plugin. Example includes required properties `id` and `data`.

```swift
@DynamicCodable
protocol CustomProtocol {
    var id: String { get }
    var data: Data { get }
}
```

--------------------------------

### Swift Debugging: Conditional Macro Compilation

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/TROUBLESHOOTING.md

Shows how to conditionally print debug information during macro expansion only when the DEBUG build configuration is active. This helps in inspecting generated code without affecting release builds.

```swift
// Add debug prints in development:
#if DEBUG
print("Generated code: (expandedSource)")
#endif
```

--------------------------------

### Swift Macro Debugging Output

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/TESTING.md

A conditional compilation block for debugging Swift macros, allowing the printing of the expanded source code when the DEBUG configuration is active.

```swift
#if DEBUG
print(expandedSource)
#endif
```

--------------------------------

### Custom Generator Implementation in Swift

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/BUILD_PLUGIN.md

Provides an example of how to create a custom code generator by implementing the `CodeGenerator` protocol. This allows for custom generation logic and handling of specific types. The `generate` function takes a `TypeDefinition` and returns a `String` representing the generated code.

```swift
struct CustomGenerator: CodeGenerator {
    func generate(for type: TypeDefinition) throws -> String {
        // Custom generation logic
        return "// Generated code for \(type.name)"
    }
}
```

--------------------------------

### Generate Documentation (Bash)

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/README.md

Command to generate documentation for the MetaCodable project using Swift Package Manager.

```bash
swift package generate-documentation
```

--------------------------------

### Swift Build Tool Plugin Core Implementation

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/BUILD_PLUGIN.md

Defines the main entry point for the MetaProtocolCodable build tool plugin. It conforms to Swift Package Manager's `BuildToolPlugin` protocol and is responsible for creating build commands. Key responsibilities include configuration management, command generation, and file handling.

```swift
@main
struct MetaProtocolCodable: BuildToolPlugin {
    func createBuildCommands(
        context: PluginContext,
        target: Target
    ) throws -> [Command]
}
```

--------------------------------

### Run Test Suite with Node.js (Shell)

Source: https://github.com/swiftylab/metacodable/blob/main/CONTRIBUTING.md

This command executes the project's test suite using Node.js. It's a convenient way to run tests locally, potentially reducing reliance on CI runners. This command is typically found in the 'package.json' scripts.

```shell
npm run test
```

--------------------------------

### Run CocoaPods Integration Tests (Shell)

Source: https://github.com/swiftylab/metacodable/blob/main/CONTRIBUTING.md

This command lints the CocoaPods integration for the project. It uses the 'pod lib lint' command with specific flags to ensure proper integration and allow warnings. This is part of the manual testing process for CocoaPods.

```shell
pod lib lint --no-clean --allow-warnings
```

--------------------------------

### Run Swift Package Manager Integration Tests (Shell)

Source: https://github.com/swiftylab/metacodable/blob/main/CONTRIBUTING.md

This command executes the Swift Package Manager (SPM) integration tests locally. It requires the 'METACODABLE_CI' environment variable to be set to 'true'. This helps in testing the project's integration with SPM before submitting changes.

```shell
METACODABLE_CI=true swift test
```

--------------------------------

### Run Tests (Bash)

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/README.md

Command to execute all tests within the MetaCodable project using Swift Package Manager.

```bash
swift test
```

--------------------------------

### Launch Xcode with Environment Variable (Shell)

Source: https://github.com/swiftylab/metacodable/blob/main/CONTRIBUTING.md

This command launches Xcode with the 'METACODABLE_CI' environment variable set to '1'. This is required for development within Xcode. Ensure Xcode is not running before executing this command for it to take effect.

```shell
open $PATH_TO_XCODE_INSTALLATION --env METACODABLE_CI=1
# i.e. open /Applications/Xcode.app --env METACODABLE_CI=1
```

--------------------------------

### CodingKeysMap: Swift Key Management for Codable

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Manages key name generation and uniqueness for Codable types. It handles type names, fallback type names, and ensures that generated keys are unique. It supports key registration, case generation, and key transformation. Dependencies include `TokenSyntax` and `OrderedDictionary`.

```swift
final class CodingKeysMap {
    let typeName: TokenSyntax
    let fallbackTypeName: TokenSyntax?
    private var data: OrderedDictionary<String, Case> = [:]
    private var usedKeys: Set<String> = []

    var type: ExprSyntax {
        guard data.isEmpty, usedKeys.isEmpty, let fallbackTypeName
        else { return "(typeName).self" }
        return "(fallbackTypeName).self"
    }
}
```

--------------------------------

### Run CocoaPods Linting with Node.js (Shell)

Source: https://github.com/swiftylab/metacodable/blob/main/CONTRIBUTING.md

This command triggers the 'pod-lint' script via npm, which is used to check the CocoaPods integration of the project. It's an automated way to perform linting for CocoaPods dependencies.

```shell
npm run pod-lint
```

--------------------------------

### Decoding Generation (init(from:))

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

This function generates the `init(from:)` implementation for Codable conformance. It involves creating container declarations, decoding properties, and adding initialization and error handling logic.

```swift
func decoding(in context: MacroExpansionContext, from location: TypeCodingLocation) -> TypeGenerated? {
    let container = location.context.forVariable

    // 1. Generate container access
    let containerDecl = generateContainerDeclaration(container)

    // 2. Generate property decoding
    for variable in variables where variable.decode ?? true {
        let decodingSyntax = variable.decoding(in: context, from: container)
    }

    // 3. Add initialization code
    let initCode = generateInitialization()

    // 4. Add error handling
    return TypeGenerated(
        code: containerDecl + decodingSyntax + initCode,
        modifiers: modifiers,
        whereClause: whereClause
    )
}
```

--------------------------------

### Swift Macro Plugin Entry Point

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Defines the main entry point for the MetaCodable Swift macro plugin, specifying the macros it provides to the compiler. This includes macros like CodedAt, CodedIn, CodedBy, and Default.

```swift
@main
struct MetaCodablePlugin: CompilerPlugin {
    let providingMacros: [Macro.Type] = [
        CodedAt.self,
        CodedIn.self,
        CodedBy.self,
        Default.self,
        // ... other macros
    ]
}
```

--------------------------------

### Swift Package Manager Plugin Integration

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/BUILD_PLUGIN.md

Shows how to integrate the MetaProtocolCodable plugin into a project's `Package.swift` file. This involves defining the plugin's name, its capability as a build tool, and any necessary dependencies, such as 'ProtocolGen'.

```swift
.plugin(
    name: "MetaProtocolCodable",
    capability: .buildTool(),
    dependencies: ["ProtocolGen"] // Example dependency
)
```

--------------------------------

### MemberInit: Memberwise Initializer Generation with Defaults in Swift

Source: https://context7.com/swiftylab/metacodable/llms.txt

Automatically generates memberwise initializers for structs. Supports default values for properties using the @Default macro, simplifying object creation.

```swift
@Codable
@MemberInit
struct CreateUserRequest {
    let username: String
    let email: String

    @Default(false)
    let isAdmin: Bool

    @Default(true)
    let isActive: Bool

    @Default("user")
    let role: String
}

// Generated initializer:
// init(username: String, email: String, isAdmin: Bool = false,
//      isActive: Bool = true, role: String = "user")

// Usage with defaults
let request1 = CreateUserRequest(username: "alice", email: "alice@example.com")
// request1.isAdmin == false, isActive == true, role == "user"

// Usage with custom values
let request2 = CreateUserRequest(
    username: "bob",
    email: "bob@example.com",
    isAdmin: true,
    role: "admin"
)

```

--------------------------------

### Swift AttributeExpander Initialization

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Demonstrates the initialization of the AttributeExpander in Swift, which is responsible for processing declarations within the macro system. It handles parsing declarations and creating TypeVariable instances.

```swift
init?(
    for declaration: some DeclGroupSyntax,
    in context: some MacroExpansionContext
) {
    guard
        let decl = declaration as? any VariableSyntax,
        case let variable = decl.codableVariable(
            in: context
        ) as any DeclaredVariable,
        let typeVar = variable as? any TypeVariable
    else { return nil }
    self.variable = typeVar
    self.options = .init(for: declaration)
}
```

--------------------------------

### Custom CodingKey Declaration with MetaCodable

Source: https://github.com/swiftylab/metacodable/blob/main/README.md

Demonstrates how MetaCodable's @CodedAt decorator simplifies custom CodingKey declarations compared to the traditional Swift Codable approach. This reduces boilerplate code by mapping property names to different JSON keys directly.

```swift
struct Landmark {
    @CodedAt("title")
    var name: String
    @CodedAt("founding_date")
    var foundingYear: Int

    var location: Coordinate
    var vantagePoints: [Coordinate]
}

@Codable
struct LandmarkStandard {
    var name: String
    var foundingYear: Int
    var location: Coordinate
    var vantagePoints: [Coordinate]

    enum CodingKeys: String, CodingKey {
        case name = "title"
        case foundingYear = "founding_date"
        case location
        case vantagePoints
    }
}
```

--------------------------------

### Encoding Generation (encode(to:))

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

This function generates the `encode(to:)` implementation for Codable conformance. It handles creating an encoding container, encoding properties, and managing inheritance for classes.

```swift
func encoding(in context: MacroExpansionContext, to location: TypeCodingLocation) -> TypeGenerated? {
    // 1. Create container
    let container = createEncodingContainer(location)

    // 2. Generate property encoding
    for variable in variables where variable.encode ?? true {
        let encodingSyntax = variable.encoding(in: context, to: container)
    }

    // 3. Add inheritance handling for classes
    if let superClass = inheritedType {
        let superEncoding = generateSuperEncoding(superClass)
    }

    // 4. Add error handling
    return TypeGenerated(
        code: containerCode + encodingSyntax + superEncoding,
        modifiers: modifiers,
        whereClause: whereClause
    )
}
```

--------------------------------

### Implement Custom HelperCoder Protocol in Swift

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/CODING_STRATEGIES.md

Shows the implementation of a custom date coder by conforming to the `HelperCoder` protocol in Swift. This involves defining `decode` and `encode` methods for custom data type handling during coding.

```swift
protocol HelperCoder {
    associatedtype Coded
    func decode(from decoder: Decoder) throws -> Coded
    func encode(_ value: Coded, to encoder: Encoder) throws
}

struct CustomDateCoder: HelperCoder {
    let formatter: DateFormatter

    func decode(from decoder: Decoder) throws -> Date {
        let string = try String(from: decoder)
        guard let date = formatter.date(from: string) else {
            throw DecodingError.dataCorruptedError(
                in: decoder as! any SingleValueDecodingContainer,
                debugDescription: "Invalid date format"
            )
        }
        return date
    }

    func encode(_ value: Date, to encoder: Encoder) throws {
        try formatter.string(from: value).encode(to: encoder)
    }
}
```

--------------------------------

### PropertyVariableTreeNode: Swift Trie Implementation for Coding Paths

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Implements a Trie-based tree structure for managing nested coding paths. It supports registering variables, generating decoding logic, and generating encoding logic. Dependencies include `Variable` and `VariableTreeNode` protocols, and `OrderedDictionary`.

```swift
final class PropertyVariableTreeNode: Variable, VariableTreeNode {
    var variables: [any PropertyVariable] = []
    var children: OrderedDictionary<CodingKeysMap.Key, PropertyVariableTreeNode> = [: ]
    private var decodingContainer: TokenSyntax?
    var immutableEncodeContainer: Bool = false
}
```

```swift
mutating func register<Variable: PropertyVariable>(
        variable: Variable,
        keyPath: [CodingKeysMap.Key],
        immutableEncodeContainer: Bool = false
    )
```

--------------------------------

### Default Values on Decoding Failures with MetaCodable

Source: https://github.com/swiftylab/metacodable/blob/main/README.md

Shows how MetaCodable's @Default decorator provides default values for properties when decoding fails due to missing keys or type mismatches. It also demonstrates how @MemberInit can generate an initializer that uses these default values.

```swift
@Codable
struct CodableData {
    @Default("some")
    let field: String
}

@Codable
@MemberInit
struct CodableDataWithInitializer {
    @Default("some")
    let field: String
}

// Example of the generated initializer:
// init(field: String = "some") {
//     self.field = field
// }
```

--------------------------------

### Swift Basic Property Variable for Decoding and Encoding

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Handles standard property decoding and encoding logic. It supports decoding from both a 'coder' and a 'container' context, with similar patterns for encoding. Dependencies include Swift's MacroExpansionContext and PropertyCodingLocation.

```swift
struct BasicPropertyVariable: PropertyVariable {
    let name: TokenSyntax
    let type: TypeSyntax
    let value: ExprSyntax?
    let decodePrefix: TokenSyntax
    let encodePrefix: TokenSyntax

    func decoding(
        in context: some MacroExpansionContext,
        from location: PropertyCodingLocation
    ) -> CodeBlockItemListSyntax {
        switch location {
        case .coder(let decoder, let passedMethod):
            // Direct decoder implementation
        case .container(let container, let key, let passedMethod):
            // Container-based decoding
        }
    }

    func encoding(
        in context: some MacroExpansionContext,
        to location: PropertyCodingLocation
    ) -> CodeBlockItemListSyntax {
        // Similar pattern for encoding
    }
}
```

--------------------------------

### Implementing Custom URLCoder with HelperCoder Protocol in Swift

Source: https://context7.com/swiftylab/metacodable/llms.txt

Defines a custom HelperCoder for URL type, validating string representations during decoding and encoding URLs as strings. This enables robust URL handling within Codable structures.

```swift
import MetaCodable

// Custom coder for URL with validation
struct URLCoder: HelperCoder {
    func decode(from decoder: Decoder) throws -> URL {
        let container = try decoder.singleValueContainer()
        let urlString = try container.decode(String.self)
        guard let url = URL(string: urlString) else {
            throw DecodingError.dataCorrupted(
                DecodingError.Context(
                    codingPath: decoder.codingPath,
                    debugDescription: "Invalid URL: \(urlString)"
                )
            )
        }
        return url
    }

    func encode(_ value: URL, to encoder: Encoder) throws {
        var container = encoder.singleValueContainer()
        try container.encode(value.absoluteString)
    }
}

@Codable
struct Website {
    @CodedBy(URLCoder())
    let homepage: URL

    @CodedBy(URLCoder())
    let documentation: URL
}

let json = """
{
    "homepage": "https://example.com",
    "documentation": "https://docs.example.com"
}
"""

let site = try JSONDecoder().decode(Website.self, from: json.data(using: .utf8)!)
// site.homepage and site.documentation are valid URL objects
```

--------------------------------

### Swift Helper Coded Variable for Custom Decoding Logic

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Manages custom coding helpers for properties. It allows defining custom decoding logic using either a direct expression or an action with parameters. This enhances flexibility in how properties are decoded.

```swift
struct HelperCodedVariable<Wrapped>: ComposedVariable, PropertyVariable
where Wrapped: DefaultPropertyVariable {
    enum Options {
        case helper(_ expr: ExprSyntax)
        case helperAction(_ action: ExprSyntax, _ params: [Parameter])
    }

    func decoding(
        in context: some MacroExpansionContext,
        from location: PropertyCodingLocation
    ) -> CodeBlockItemListSyntax {
        // Generate helper-based decoding implementation
    }
}
```

--------------------------------

### ConstraintGenerator: Swift Generic Constraint Handling

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Manages generic constraints for Codable conformance. It helps in generating `where` clauses for generic types, ensuring correct protocol conformance and handling of generic parameters. Dependencies include `TokenSyntax`, `TypeSyntax`, and `GenericWhereClauseSyntax`.

```swift
struct ConstraintGenerator {
    var typeArguments: [TokenSyntax] = []

    func codingClause(
        forRequirementPath path: KeyPath<any PropertyVariable, Bool?>, 
        withVariables variables: [any PropertyVariable],
        conformingTo protocol: TypeSyntax
    ) -> GenericWhereClauseSyntax?
}
```

--------------------------------

### CodingKeys Generation

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

This function generates the `CodingKeys` enum required for custom key mappings in Codable conformance. It checks protocol conformance and adds custom key declarations.

```swift
func codingKeys(confirmingTo protocols: [TypeSyntax], in context: MacroExpansionContext) -> MemberBlockItemListSyntax {
    // 1. Check protocol conformance
    let decodable = variable.protocol(named: "Decodable", in: protocols)
    let encodable = variable.protocol(named: "Encodable", in: protocols)

    // 2. Generate coding keys enum
    let enumDecl = generateCodingKeysEnum()

    // 3. Add custom key mappings
    for (property, customKey) in keyMappings {
        let caseDecl = generateKeyCase(property, customKey)
    }

    return MemberBlockItemListSyntax([enumDecl, casesDecl])
}
```

--------------------------------

### Swift Enum for Command Variations with MetaCodable

Source: https://github.com/swiftylab/metacodable/blob/main/README.md

Demonstrates how a Swift enum can represent different data commands (load, store) using external, internal, and adjacent tagging. MetaCodable extends Swift's default capabilities to handle these variations.

```swift
enum Command {
    case load(key: String)
    case store(key: String, value: Int)
}
```

--------------------------------

### AttributeExpander for Codable Conformance

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

The `AttributeExpander` struct is responsible for coordinating the code generation process to make types conform to Codable. It takes type information and context to produce Swift extension declarations.

```swift
struct AttributeExpander {
    let variable: any TypeVariable
    private let options: Options

    func codableExpansion(
        for type: some TypeSyntaxProtocol,
        to protocols: [TypeSyntax],
        in context: some MacroExpansionContext
    ) -> [ExtensionDeclSyntax] {
        // Generate extensions for Codable conformance
    }
}
```

--------------------------------

### CodedBy: Property-Based HelperCoders for Contextual Encoding/Decoding in Swift

Source: https://context7.com/swiftylab/metacodable/llms.txt

Creates custom `HelperCoder` instances using values from other properties as context. This allows for dynamic encoding and decoding logic based on the state of the surrounding struct.

```swift
@Codable
struct VersionedData {
    @Default(1)
    let version: Int

    // Transform data based on version number
    @CodedBy(DataTransformer.init, properties: \VersionedData.version)
    let content: Content

    struct DataTransformer: HelperCoder {
        let version: Int

        func decode(from decoder: Decoder) throws -> Content {
            var data = try Content(from: decoder)
            // Apply version-specific transformations
            if version >= 2 {
                data.legacyField = nil
            }
            return data
        }

        func encode(_ value: Content, to encoder: Encoder) throws {
            var data = value
            // Apply version-specific transformations
            if version < 2 {
                data.newField = nil
            }
            try data.encode(to: encoder)
        }
    }
}

@Codable
struct Content {
    var newField: String?
    var legacyField: String?
}

// Multi-property example
@Codable
struct AuthenticatedRequest {
    let userId: String
    let timestamp: Date

    @CodedBy(
        SignedData.init,
        properties: \AuthenticatedRequest.userId, \AuthenticatedRequest.timestamp
    )
    let signature: String

    struct SignedData: HelperCoder {
        let userId: String
        let timestamp: Date

        func decode(from decoder: Decoder) throws -> String {
            let container = try decoder.singleValueContainer()
            let sig = try container.decode(String.self)
            // Verify signature with userId and timestamp
            return sig
        }

        func encode(_ value: String, to encoder: Encoder) throws {
            var container = encoder.singleValueContainer()
            // Sign data with userId and timestamp
            try container.encode(value)
        }
    }
}

```

--------------------------------

### Swift Protocol Definition for PropertyVariable

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Defines the core `PropertyVariable` protocol, outlining the essential properties and methods for handling variable decoding and encoding within the metaprogramming context. It specifies requirements for type, name, value, and decoding/encoding functions.

```swift
protocol PropertyVariable: NamedVariable {
    var type: TypeSyntax { get }
    var name: TokenSyntax { get }
    var value: ExprSyntax? { get }
    var requireDecodable: Bool? { get }
    var requireEncodable: Bool? { get }

    func decoding(in: MacroExpansionContext, from: PropertyCodingLocation) -> CodeBlockItemListSyntax
    func encoding(in: MacroExpansionContext, to: PropertyCodingLocation) -> CodeBlockItemListSyntax
}
```

--------------------------------

### Enum Tagging Strategies for Codable Enums in Swift

Source: https://context7.com/swiftylab/metacodable/llms.txt

Demonstrates various strategies for serializing enums using Metacodable's @Codable. Supports external, internal, and adjacent tagging, along with custom case identifiers and untagged enums. This requires the Metacodable library.

```swift
// External tagging (Swift default)
@Codable
enum Message {
    case text(content: String)
    case image(url: String, width: Int)
}
// JSON: {"text": {"content": "Hello"}}

// Internal tagging
@Codable
@CodedAt("type")
enum Command {
    case load(key: String)
    case store(key: String, value: Int)
}
// JSON: {"type": "load", "key": "myKey"}
// JSON: {"type": "store", "key": "myKey", "value": 42}

let json1 = """
{"type": "load", "key": "config"}
"""
let cmd1 = try JSONDecoder().decode(Command.self, from: json1.data(using: .utf8)!)
// cmd1 == .load(key: "config")

// Adjacent tagging
@Codable
@CodedAt("type")
@ContentAt("data")
enum Event {
    case click(x: Int, y: Int)
    case scroll(delta: Int)
}
// JSON: {"type": "click", "data": {"x": 10, "y": 20}}

let json2 = """
{"type": "scroll", "data": {"delta": -50}}
"""
let evt = try JSONDecoder().decode(Event.self, from: json2.data(using: .utf8)!)
// evt == .scroll(delta: -50)

// Custom case identifiers
@Codable
@CodedAt("action")
enum Action {
    @CodedAs("fetch")
    case load(id: String)

    @CodedAs("persist")
    case save(id: String, data: String)
}
// JSON: {"action": "fetch", "id": "123"}

// Untagged enum - tries each case in order
@Codable
@UnTagged
enum Response {
    case success(data: [String: String])
    case error(message: String)
}
// JSON: {"data": {"key": "value"}} -> .success
// JSON: {"message": "Failed"} -> .error

```

--------------------------------

### Swift: Map JSON Keys with @CodedAt Macro

Source: https://context7.com/swiftylab/metacodable/llms.txt

Demonstrates using the @CodedAt macro in Swift to map struct properties to specific JSON keys, including nested paths. This eliminates the need for manual CodingKeys enums and simplifies handling complex JSON structures. Requires the MetaCodable framework.

```swift
@Codable
struct Location {
    let city: String
    let country: String

    // Nested path with multiple keys
    @CodedAt("coordinates", "latitude")
    let lat: Double

    @CodedAt("coordinates", "longitude")
    let lon: Double

    // Deep nesting
    @CodedAt("metadata", "info", "elevation")
    let elevation: Double
}

// Handles JSON:
let json = """
{
    "city": "Paris",
    "country": "France",
    "coordinates": {
        "latitude": 48.8566,
        "longitude": 2.3522
    },
    "metadata": {
        "info": {
            "elevation": 35.0
        }
    }
}
"""

let location = try JSONDecoder().decode(Location.self, from: json.data(using: .utf8)!)
// location.lat == 48.8566, location.elevation == 35.0
```

--------------------------------

### Ignoring Initialized Properties with @IgnoreCodingInitialized in Swift

Source: https://context7.com/swiftylab/metacodable/llms.txt

Demonstrates the use of Metacodable's @IgnoreCodingInitialized attribute, which skips encoding and decoding for properties that have initial values unless they are explicitly marked with coding attributes like @CodedAt or @Default. Requires the Metacodable library.

```swift
@Codable
@IgnoreCodingInitialized
struct Settings {
    // Decoded/encoded - has @CodedAt
    @CodedAt("api_key")
    let apiKey: String

    // Decoded/encoded - no initial value
    let userId: String

    // IGNORED - initialized and no coding attribute
    let version: String = "2.0"

    // IGNORED - initialized and no coding attribute
    var debugMode: Bool = false

    // Decoded/encoded - has @Default
    @Default(300)
    let timeout: Int
}

let json = """
{
    "api_key": "abc123",
    "userId": "user-456",
    "version": "should-be-ignored",
    "debugMode": true
}
"""

let settings = try JSONDecoder().decode(Settings.self, from: json.data(using: .utf8)!)
// settings.version == "2.0" (not "should-be-ignored")
// settings.debugMode == false (not true)
// settings.timeout == 300 (default applied)

```

--------------------------------

### Swift Enum Case Protocol

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Defines the protocol for individual enum cases, handling their associated variables, name, and generating decoding and encoding logic for each case.

```swift
protocol EnumCaseVariable: Variable {
    var variables: [AssociatedVariable] { get }
    var name: TokenSyntax { get }

    func decoding(in: MacroExpansionContext, from: EnumCaseCodingLocation) -> CodeBlockItemListSyntax
    func encoding(in: MacroExpansionContext, to: EnumCaseCodingLocation) -> CodeBlockItemListSyntax
}
```

--------------------------------

### Define Nested Models with Flattened Structures in Swift

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/CODING_STRATEGIES.md

Demonstrates how to use the `@Codable` and `@CodedIn` attributes to flatten nested data structures in Swift. This allows for a cleaner Swift model representation while mapping to a nested JSON structure.

```swift
@Codable
struct Coordinate {
    var latitude: Double
    var longitude: Double
    @CodedIn("additionalInfo")
    var elevation: Double
}
```

--------------------------------

### Date Coding Strategies in Swift

Source: https://context7.com/swiftylab/metacodable/llms.txt

Handles various date formats including Unix timestamps (seconds and milliseconds), custom string formats, and ISO8601. Requires the HelperCoders import. Decodes dates from different JSON representations into Swift Date objects.

```swift
import HelperCoders

@Codable
struct Event {
    // Unix timestamp (seconds since 1970)
    @CodedBy(Since1970DateCoder())
    let createdAt: Date

    // Unix timestamp in milliseconds
    @CodedBy(Since1970DateCoder(withMilliseconds: true))
    let updatedAt: Date

    // Custom date format
    @CodedBy(DateCoder(format: "yyyy-MM-dd"))
    let eventDate: Date

    // ISO8601 format
    @CodedBy(ISO8601DateCoder())
    let scheduledAt: Date
}

let json = """
{
    "createdAt": 1609459200,
    "updatedAt": 1609459200000,
    "eventDate": "2024-12-25",
    "scheduledAt": "2024-12-25T12:00:00Z"
}
"""

let event = try JSONDecoder().decode(Event.self, from: json.data(using: .utf8)!)
// All date fields properly decoded from their respective formats

// Custom DateFormatter
let customFormatter = DateFormatter()
customFormatter.dateFormat = "MM/dd/yyyy HH:mm"
customFormatter.timeZone = TimeZone(identifier: "UTC")

@Codable
struct Meeting {
    @CodedBy(DateCoder(formatter: customFormatter))
    let startTime: Date
}

```

--------------------------------

### Swift: Nested Decoding with @CodedIn Macro

Source: https://context7.com/swiftylab/metacodable/llms.txt

Illustrates how to use the @CodedIn macro in Swift for simplifying nested JSON decoding when the final JSON key matches the property name. It allows specifying the container path for properties. Requires the MetaCodable framework.

```swift
@Codable
struct Product {
    let id: String
    let name: String

    // Property name "price" used as final key in "pricing" container
    @CodedIn("pricing")
    let price: Double

    // Multiple levels
    @CodedIn("pricing", "discount")
    let percentage: Int
}

// Handles JSON:
let json = """
{
    "id": "prod-001",
    "name": "Widget",
    "pricing": {
        "price": 29.99,
        "discount": {
            "percentage": 15
        }
    }
}
"""

let product = try JSONDecoder().decode(Product.self, from: json.data(using: .utf8)!)
// product.price == 29.99, product.percentage == 15
```

--------------------------------

### Swift Enum Switcher Protocol

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Defines the protocol for enum switchers, responsible for managing case detection and switching logic within an enum. It includes methods for processing enum case declarations and coding keys.

```swift
protocol EnumSwitcherVariable: Variable {
    func node(for: EnumCaseVariableDeclSyntax, in: MacroExpansionContext)
    func codingKeys(in: MacroExpansionContext)
}
```

--------------------------------

### Swift: Generate Codable with @Codable Macro

Source: https://context7.com/swiftylab/metacodable/llms.txt

Generates complete Codable conformance for a Swift struct using the @Codable macro. It demonstrates basic usage with custom CodingKeys for JSON decoding and encoding. Requires the MetaCodable framework.

```swift
import MetaCodable

// Basic usage with custom CodingKeys
@Codable
struct User {
    @CodedAt("user_id")
    let id: String
    @CodedAt("full_name")
    let name: String
    let email: String
}

// Decoding from JSON
let json = """
{
    "user_id": "12345",
    "full_name": "John Doe",
    "email": "john@example.com"
}
"""
let decoder = JSONDecoder()
let user = try decoder.decode(User.self, from: json.data(using: .utf8)!)
// user.id == "12345", user.name == "John Doe"

// Encoding to JSON
let encoder = JSONEncoder()
encoder.outputFormatting = .prettyPrinted
let data = try encoder.encode(user)
// Output: {"user_id":"12345","full_name":"John Doe","email":"john@example.com"}
```

--------------------------------

### Swift: Default Values with @Default Macro

Source: https://context7.com/swiftylab/metacodable/llms.txt

Shows how to use the @Default macro in Swift to provide fallback values for properties during JSON decoding when keys are missing or types are mismatched. Supports different defaults for missing keys versus type errors. Requires the MetaCodable framework.

```swift
@Codable
struct Configuration {
    // Default for all errors (missing or wrong type)
    @Default(false)
    let enabled: Bool

    // Default only when key is missing
    @Default(ifMissing: 100)
    let timeout: Int

    // Different defaults for missing vs. type errors
    @Default(ifMissing: "production", forErrors: "unknown")
    let environment: String

    let apiKey: String
}

// Missing fields use defaults
let json1 = """{"apiKey": "abc123"}"""
let config1 = try JSONDecoder().decode(Configuration.self, from: json1.data(using: .utf8)!)
// config1.enabled == false, config1.timeout == 100, config1.environment == "production"

// Type mismatch uses error default
let json2 = """{"apiKey": "abc123", "enabled": "not-a-bool", "environment": 42}"""
let config2 = try JSONDecoder().decode(Configuration.self, from: json2.data(using: .utf8)!)
// config2.enabled == false, config2.environment == "unknown"

// Works with @MemberInit for constructor defaults
@Codable
@MemberInit
struct Settings {
    @Default(10)
    let retries: Int
}
// Generated: init(retries: Int = 10) { self.retries = retries }
```

--------------------------------

### Swift Aliased Property Variable for Multiple Coding Keys

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Handles properties that can be decoded using multiple coding keys. It maintains a list of additional keys and checks them during the decoding process to find the available one. This is useful for API versioning or flexible data structures.

```swift
struct AliasedPropertyVariable<Wrapped>: PropertyVariable, ComposedVariable {
    let additionalKeys: OrderedSet<CodingKeysMap.Key>

    func decoding(
        in context: some MacroExpansionContext,
        from location: PropertyCodingLocation
    ) -> CodeBlockItemListSyntax {
        // Check multiple keys and decode from available one
    }
}
```

--------------------------------

### JSON Data Formats for Command Enum with MetaCodable

Source: https://github.com/swiftylab/metacodable/blob/main/README.md

Illustrates various JSON data structures that can be successfully decoded into the 'Command' Swift enum using MetaCodable. This includes externally tagged, internally tagged ('type' field), and internally tagged with content object ('content' field) formats.

```json
[
  {
    "load": {
      "key": "MyKey"
    }
  },
  {
    "store": {
      "key": "MyKey",
      "value": 42
    }
  }
]
```

```json
[
  {
    "type": "load",
    "key": "MyKey"
  },
  {
    "type": "store",
    "key": "MyKey",
    "value": 42
  }
]
```

```json
[
  {
    "type": "load",
    "content": {
      "key": "MyKey"
    }
  },
  {
    "type": "store",
    "content": {
      "key": "MyKey",
      "value": 42
    }
  }
]
```

--------------------------------

### PathRegistration Type Alias

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Defines a type alias `PathRegistration` for registering properties that use coding key paths. This is a generic type within the variable registration system.

```swift
/// A type representing property variable registration for code generation.
typealias PathRegistration<Decl, Var> = Registration<Decl, [String], Var>
where Var: Variable
```

--------------------------------

### Applying Case Style Transformations with @CodingKeys in Swift

Source: https://context7.com/swiftylab/metacodable/llms.txt

Illustrates how to use Metacodable's @CodingKeys attribute to automatically apply consistent case transformations (e.g., snake_case, camelCase) to all property keys within a Codable struct during JSON serialization. Requires the Metacodable library.

```swift
@Codable
@CodingKeys(.snake_case)
struct ApiRequest {
    let userId: String          // Encoded as: "user_id"
    let requestType: String     // Encoded as: "request_type"
    let createdAt: Date         // Encoded as: "created_at"
}

// JSON format:
let json = """
{
    "user_id": "12345",
    "request_type": "GET",
    "created_at": "2024-01-01T00:00:00Z"
}
"""

// Supported case styles:
// .camelCase      -> userProfileName
// .snake_case     -> user_profile_name
// .kebab_case     -> user-profile-name
// .PascalCase     -> UserProfileName
// .SCREAMING_CASE -> USER_PROFILE_NAME

```

--------------------------------

### Flexible Type Conversion with ValueCoder in Swift

Source: https://context7.com/swiftylab/metacodable/llms.txt

Utilizes ValueCoder for flexible type conversions between basic types during decoding and encoding. It supports converting various string and numeric formats to Booleans, Integers, Doubles, and Strings, and can be applied globally using `commonStrategies`.

```swift
import HelperCoders

@Codable
struct DataTypes {
    // Decode Bool from various formats
    @CodedBy(ValueCoder<Bool>())
    let flag1: Bool  // Accepts: true, "true", "yes", "1", 1

    // Decode Int from strings
    @CodedBy(ValueCoder<Int>())
    let count: Int  // Accepts: 42, "42"

    // Decode Double from strings
    @CodedBy(ValueCoder<Double>())
    let price: Double  // Accepts: 19.99, "19.99"

    // Decode String from numbers
    @CodedBy(ValueCoder<String>())
    let code: String  // Accepts: "ABC", 123
}

let json = """
{
    "flag1": "yes",
    "count": "100",
    "price": "29.99",
    "code": 456
}
"""

let data = try JSONDecoder().decode(DataTypes.self, from: json.data(using: .utf8)!)
// data.flag1 == true, data.count == 100, data.price == 29.99, data.code == "456"

// Common strategies applied to entire type
@Codable(commonStrategies: [.valueCoders])
struct FlexibleData {
    let isActive: Bool  // Automatically applies ValueCoder<Bool>
    let itemCount: Int   // Automatically applies ValueCoder<Int>
}
```

--------------------------------

### Swift: Explicitly Indicate Non-Inherited Codable Conformance

Source: https://github.com/swiftylab/metacodable/blob/main/Sources/MetaCodable/MetaCodable.docc/Limitations.md

Shows how to use the Inherits macro to explicitly signal that a class does not inherit Codable conformance, which can resolve issues when working with SwiftData classes and the @Codable macro during certain SwiftUI customizations.

```swift
import MetaCodable

// Use Inherits macro to indicate non-inherited conformance:
@Codable
@Inherits(decodable: false, encodable: false)
class MyClass {
    // ... class properties and methods
}
```

--------------------------------

### Custom Encoding/Decoding with HelperCoders in Swift

Source: https://context7.com/swiftylab/metacodable/llms.txt

Applies custom encoding and decoding logic using HelperCoder implementations for type conversions or non-Codable types. Supports boolean conversion from strings, lossy array decoding, Base64 data encoding/decoding, and Unix timestamp to Date conversion.

```swift
import HelperCoders

@Codable
struct ApiResponse {
    // Convert string "true"/"false" to Bool
    @CodedBy(ValueCoder<Bool>())
    let success: Bool

    // Lossy array decoding - skip invalid elements
    @CodedBy(SequenceCoder(output: [Int].self, configuration: .lossy))
    let validIds: [Int]

    // Base64 encoded data
    @CodedBy(Base64Coder())
    let payload: Data

    // Unix timestamp to Date
    @CodedBy(Since1970DateCoder())
    let timestamp: Date
}

let json = """
{
    "success": "true",
    "validIds": [1, 2, "invalid", 3, null, 4],
    "payload": "SGVsbG8gV29ybGQ=",
    "timestamp": 1609459200
}
"""

let response = try JSONDecoder().decode(ApiResponse.self, from: json.data(using: .utf8)!)
// response.success == true
// response.validIds == [1, 2, 3, 4] (invalid entries skipped)
// response.payload contains "Hello World" decoded from base64
// response.timestamp == Date from Unix timestamp
```

--------------------------------

### DynamicCodable: Polymorphic Encoding/Decoding with Protocols in Swift

Source: https://context7.com/swiftylab/metacodable/llms.txt

Enables polymorphic encoding and decoding of protocol types, even across different modules. It uses a type identifier to determine the concrete type during decoding. Requires the MetaProtocolCodable build plugin.

```swift
@Codable
@CodedAt("type")
protocol Vehicle {
    var id: String { get }
    var name: String { get }
}

@Codable
struct Car: Vehicle, DynamicCodable {
    static var identifier: DynamicCodableIdentifier<String> { "car" }
    let id: String
    let name: String
    let doors: Int
}

@Codable
struct Motorcycle: Vehicle, DynamicCodable {
    static var identifier: DynamicCodableIdentifier<String> { "motorcycle" }
    let id: String
    let name: String
    let hasSidecar: Bool
}

// Use MetaProtocolCodable build plugin to generate protocol codec
// In Package.swift: .plugin(name: "MetaProtocolCodable", package: "MetaCodable")

let json = """
[
    {"type": "car", "id": "v1", "name": "Sedan", "doors": 4},
    {"type": "motorcycle", "id": "v2", "name": "Cruiser", "hasSidecar": true}
]
"""

let vehicles = try JSONDecoder().decode([Vehicle].self, from: json.data(using: .utf8)!)
// vehicles[0] is Car instance
// vehicles[1] is Motorcycle instance

// Integer identifiers
@Codable
@CodedAt("kind")
@CodedAs<Int>
protocol Shape {
    var area: Double { get }
}

@Codable
struct Circle: Shape, DynamicCodable {
    static var identifier: DynamicCodableIdentifier<Int> { 1 }
    let radius: Double
    var area: Double { .pi * radius * radius }
}
// JSON: {"kind": 1, "radius": 5.0}

```

--------------------------------

### Flattened Composition with @CodedAt in Swift

Source: https://context7.com/swiftylab/metacodable/llms.txt

Enables decoding/encoding nested Codable types directly at the root level of the JSON, flattening the structure. Useful for integrating with APIs that don't mirror the desired Swift object hierarchy. No specific imports are required beyond standard Codable.

```swift
@Codable
struct BaseEntity {
    let id: String
    let createdAt: Date
}

@Codable
struct Car {
    // Decode BaseEntity fields directly from root JSON
    @CodedAt
    let base: BaseEntity

    let make: String
    let model: String
    let year: Int
}

let json = """
{
    "id": "car-123",
    "createdAt": 1704067200,
    "make": "Toyota",
    "model": "Camry",
    "year": 2024
}
"""

// Without @CodedAt, would expect:
// {"base": {"id": "...", "createdAt": ...}, "make": "...", ...}

// With @CodedAt (no args), flattens structure
let car = try JSONDecoder().decode(Car.self, from: json.data(using: .utf8)!)
// car.base.id == "car-123"
// car.make == "Toyota"

```

--------------------------------

### Swift Associated Variable Protocol

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Defines the protocol for associated variables within enum cases, extending `PropertyVariable` and including an optional label for the associated value.

```swift
protocol AssociatedVariable: PropertyVariable {
    var label: TokenSyntax? { get }
}
```

--------------------------------

### Swift TypeVariable for Classes (ClassVariable)

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Defines the ClassVariable struct in Swift, implementing the TypeVariable protocol for class declarations. It contains a MemberGroup, the class declaration syntax, and an optional 'inherits' property.

```swift
struct ClassVariable: TypeVariable {
    let group: MemberGroup<ClassDeclSyntax>
    let decl: ClassDeclSyntax
    var inherits: Inherits?
}
```

--------------------------------

### Swift TypeVariable for Structs (MemberGroup)

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Defines the MemberGroup struct in Swift, which serves as the base implementation for TypeVariable for structs and is also used for classes and actors. It includes a constraint generator, property tree node, and coding keys map.

```swift
struct MemberGroup<Decl>: TypeVariable {
    let constraintGenerator: ConstraintGenerator
    let node: PropertyVariableTreeNode
    let codingKeys: CodingKeysMap
}
```

--------------------------------

### Swift TypeVariable for Actors (ActorVariable)

Source: https://github.com/swiftylab/metacodable/blob/main/Contributing/MACRO_PROCESSING.md

Defines the ActorVariable struct in Swift, implementing the TypeVariable protocol for actor declarations. It wraps a MemberGroup specific to ActorDeclSyntax.

```swift
struct ActorVariable: TypeVariable {
    let base: MemberGroup<ActorDeclSyntax>
}
```
Tokens:
Raw