MetaCodable

HelperCoders provides a collection of helpers designed to level up MetaCodable's generated implementations by reducing boilerplate for common encoding/decoding tasks.

Key capabilities include:

• Basic Data: Decoding types like Bool, Int, or String from other basic types.
• Date Handling: Custom approaches such as UNIX timestamps or text-formatted dates.
• Data Handling: Converting between Data and formats like Base64 text.
• Non-conforming Floats: Handling text-based representations of infinity and NaN.
• Composition: Using property wrappers or conditional decoding/encoding.
• Sequences: Specialized coding for sequences.

Standard Swift Codable enums typically expect an 'external tagged' format. MetaCodable extends this to support other common JSON patterns for enums, such as:

1. Internal Tagging: A type field alongside the data.

   { "type": "load", "key": "MyKey" }

2. Adjacent Tagging: A type field and a content object containing the data.

   { "type": "load", "content": { "key": "MyKey" } }

This allows a single Swift enum to represent various data variations without complex manual decoding logic.

The library provides several built-in HelperCoder implementations to handle common non-standard data formats:

• LossySequenceCoder: Decodes only valid elements in a sequence, skipping invalid ones instead of failing the entire array.
• ValueCoder: Coerces basic types (e.g., decoding an Int from a String like "1" or a Bool from "yes").
• Since1970DateCoder: Handles UNIX timestamps.
• DateCoder / ISO8601DateCoder: Handles specific date formats.
• Base64Coder: Handles Base64 encoded strings.

You can also implement your own custom logic by conforming to the HelperCoder protocol.

For actor types, Codable(commonStrategies:) automatically generates Decodable conformance, but it does not generate Encodable conformance.

This is because generating Encodable requires a synchronous encode(to:) method. Making this method nonisolated to allow conformance would prevent the actor from safely accessing its mutable properties.

Requirement: You must implement Encodable conformance manually for actor types.

To use HelperCoders in your Swift project, add MetaCodable as a dependency in your Package.swift file, and then specifically include the HelperCoders product in your target's dependencies.

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

// In your target definition
.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "HelperCoders", package: "MetaCodable")
    ]
)

To integrate MetaCodable into an Xcode project using CocoaPods, add the following line to your Podfile and run pod install.

pod 'MetaCodable'

Because the Swift compiler does not provide type inference data to macros, Codable(commonStrategies:) cannot determine the type of variables that rely on implicit typing. To avoid macro expansion errors, you must explicitly declare the type of all properties in a @Codable struct or class.

Incorrect:

@Codable
struct Model {
    let value = 1
}

Correct:

@Codable
struct Model {
    let value: Int = 1
}

To use MetaCodable in your Swift project, add it as a dependency in your Package.swift file. First, add the package to your dependencies array, then add the MetaCodable product to your specific target's dependencies.

// Add to dependencies
.package(url: "https://github.com/SwiftyLab/MetaCodable.git", from: "1.0.0"),

// Add to target dependencies
.product(name: "MetaCodable", package: "MetaCodable"),

You can provide additional customization options for the MetaProtocolCodable build tool plugin using a configuration file.

Supported Formats

The file can be in either plist or json format.

Naming Requirements

The filename must match metacodableconfig after removing non-alphanumeric characters and converting to lowercase. Supported examples include:

• MetaCodableConfig.plist
• meta_codable_config.json
• meta-codable-config.json

Placement Rules

• Swift Packages: The file must be added at the target root directory.
• Xcode Targets: The file must be explicitly added as part of the target.

Key Sensitivity

Option names and keys within the file are case-insensitive (e.g., Scan, scan, and SCAN are treated identically).

Swift does not currently allow macro attributes to be attached to individual enum-case arguments. Therefore, you cannot apply customization attributes (like @CodedAt) directly to arguments within an enum case.

Workaround: Extract the enum-case arguments into a separate @Codable struct and use that struct as the associated value for the enum case. This allows you to apply customization options within the struct itself.

Example Workaround:

@Codable
enum SomeEnum {
    case string(StringData)

    @Codable
    struct StringData {
        @CodedAt("data")
        let data: String
    }
}

In certain SwiftUI customization scenarios, the Swift compiler may fail to send protocol data to Codable(commonStrategies:). This causes the macro to incorrectly assume a class inherits Codable conformance from a superclass, leading to errors (especially with SwiftData classes).

Workaround: Use the Inherits(decodable:encodable:) macro to explicitly indicate that the class does not inherit Codable conformance from its superclass.

// Use this to explicitly state the class does not inherit Codable conformance
@Inherits(decodable: false, encodable: false)
class MySwiftDataModel: ... {
    // ...
}