SmartCodable Documentation

Developers implementing or modifying core logic should be aware of these internal behaviors:

• Property Wrapper Storage: Swift stores property wrappers with an underscore prefix (e.g., @SmartAny var name is stored as _name). The DecodingCache handles this mapping.
• KeyedContainer Initialization: The _convertDictionary() method in KeyedContainer is executed exactly once during container initialization. All subsequent property decoding relies on this transformed dictionary.
• Patcher Type Conversion: Type conversions within a Patcher (e.g., String → Int) must be bi-directionally safe. You must validate that the input is valid (e.g., a valid numeric string) rather than silently returning a default like 0.

SmartCodable is optimized for production environments using the following patterns:

• Lazy Reflection: Mirror reflection is only performed by DecodingCache when default values are explicitly required for the first time, not on every decoding cycle.
• Thread Safety: SafeDictionary uses NSLock to protect the Sentinel logging dictionary.
• Zero-Overhead Logging: The SmartSentinel logging system uses a guard clause (guard debugMode != .none else { return }) at every entry point. In Release environments where debugMode is set to .none, logging incurs zero overhead.

Unlike native Swift Codable, which throws an exception and fails the entire model parsing when encountering missing fields, type mismatches, or null values, SmartCodable implements a graceful degradation strategy.

When a property fails to decode, the library follows this priority order to prevent failure:

1. Type Conversion (Patcher): Attempts to automatically convert types (e.g., converting a JSON string "123" to an Int).
2. Default Value Fallback (DecodingCache): If conversion fails, it falls back to the initial value declared in your model (e.g., var name: String = "Default").
3. Logging (SmartSentinel): If all else fails, it logs the issue without interrupting the parsing process.

Standard Codable throws a DecodingError if a field is missing, is null, or has an incorrect type. SmartCodable provides fault tolerance by attempting to resolve these issues using a specific fallback hierarchy.

When a decoding error occurs, SmartCodable follows this priority order to find a compatible value:

1. Type Transformation: Attempts to convert the existing value to the target type (e.g., converting the string "true" to a Bool).
2. Property Initial Value: If transformation fails, it uses the value assigned to the property during the model's initialization (e.g., var name: String = "Default").
3. Type Default Value: If no initial value is available, it falls back to a type-level default value defined via the Defaultable protocol.

SmartCodable provides resilience against common JSON parsing failures that typically cause standard Apple Codable to throw errors and fail the entire model parsing process.

You can combine Protocol and @SmartFlat to get the best of both worlds: the type safety of protocols and the automated parsing of @SmartFlat. This avoids the repetition of the Protocol-only approach and the lack of common types in the @SmartFlat-only approach.

Pros:

• No manual encoding/decoding implementation.
• Avoids property repetition in subclasses.
• Provides a common type constraint via the protocol.

Cons:

• It is not true class inheritance.

protocol ManBaseModelProtocol {
    var manBase: BaseModel { set get }
}

class BaseModel: SmartCodable {
    required init() {}
    
    var name: String = ""
    var sex: Int = 0
}

class SubModel: SmartCodable, ManBaseModelProtocol {
    required init() {}
    
    @SmartFlat
    var manBase: BaseModel = .init()
    
    var age: Int = 0
}

The SmartCodableOptions struct provides global configuration for decoding behavior. In version 6.1.0+, access to these global settings is thread-safe using internal locking. This ensures that modifying configuration from one thread while decoding on another does not cause data races.

Key configuration properties include:

• numberStrategy: Controls how numbers are converted during decoding.
• ignoreNull: Determines whether null values should be ignored during decoding.

For lightweight sharing of properties, you can use a Protocol-based approach. Define a protocol for the common properties and have your subclasses conform to it.

Pros:

• No manual implementation of subclass encoding/decoding logic required.
• Subclasses share a common type via the protocol.

Cons:

• Every subclass must manually declare and implement the properties defined in the protocol.

protocol BaseModel {
    var name: String { set get }
    var sex: Int { set get }
}

class SubModel: BaseModel, SmartCodable {
    required init() {}
    
    var name: String = ""
    var sex: Int = 0
    
    var age: Int = 0
}

Smart Sentinel provides a visual tree representation of the parsing process. It highlights specific issues such as:

• Type mismatches: e.g., Expected to decode 'Int' but found 'String' instead.
• Missing keys: e.g., No value associated with key.
• Null values: e.g., Expected to decode 'Int' but found 'null' instead.

This allows you to trace exactly where in a nested JSON structure the data deviates from your Swift models.

================================  [Smart Sentinel]  ================================
Array<SomeModel> 👈🏻 👀
   ╆━ Index 0
      ┆┄ a: Expected to decode 'Int' but found 'String' instead.
      ┆┄ b: Expected to decode 'Int' but found 'Array' instead.
      ┆┄ c: No value associated with key.
...

For SmartCodable 5.0+, the recommended way to handle class inheritance is using the @SmartSubclass macro. This macro automatically generates CodingKeys, init(from:), and encode(to:) at compile time, allowing subclasses to inherit properties from a base class without manual boilerplate.

Requirements:

• Swift 5.9+
• Xcode 15+

Usage: Apply @SmartSubclass to the subclass that inherits from a SmartCodable base class.

class BaseModel: SmartCodable {
    var name: String = ""
    required init() { }
}

@SmartSubclass
class Model: BaseModel {
    var age: Int = 0
}

let dict = ["name": "小明", "age": 10] as [String : Any]
guard let model = Model.deserialize(from: dict) else { return }
print(model.age)   // 10
print(model.name)  // 小明