Skip to content

Add CodableKitCore Shared Options Target #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
WendellXY merged 2 commits into from
Dec 31, 2025
Merged

Add CodableKitCore Shared Options Target #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1c4c347
Add CodableKitCore shared options target
WendellXY Dec 31, 2025
8f711c4
Format files
WendellXY Dec 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion Package.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,13 @@ let package = Package(
.package(url: "https://github.com/swiftlang/swift-syntax.git", "600.0.0"..<"603.0.0")
],
targets: [
.target(
name: "CodableKitCore"
),
.macro(
name: "CodableKitMacros",
dependencies: [
"CodableKitCore",
.product(name: "SwiftSyntax", package: "swift-syntax"),
.product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
.product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
Expand All @@ -36,7 +40,8 @@ let package = Package(
.target(
name: "CodableKit",
dependencies: [
"CodableKitMacros"
"CodableKitCore",
"CodableKitMacros",
]
),
.testTarget(
Expand Down
234 changes: 3 additions & 231 deletions Sources/CodableKit/CodableKeyOptions.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,237 +2,9 @@
// CodableKeyOptions.swift
// CodableKit
//
// Created by WendellXY on 2024/5/14
// Copyright © 2024 WendellXY. All rights reserved.
// Compatibility shim: the canonical definitions live in `CodableKitCore`.
//

public struct CodableKeyOptions: OptionSet, Sendable {
public let rawValue: Int32
import CodableKitCore

public init(rawValue: Int32) {
self.rawValue = rawValue
}

/// The default options for a `CodableKey`, which is equivalent to an empty set.
public static let `default`: Self = []

/// A convenience option combining ``transcodeRawString`` and ``useDefaultOnFailure`` for safe JSON string transcoding.
///
/// This option provides a safer way to handle string-encoded JSON by automatically falling back to
/// default values or `nil` when the JSON string is invalid or malformed. It's equivalent to
/// `[.transcodeRawString, .useDefaultOnFailure]`.
///
/// Example usage with invalid JSON handling:
///
/// ```json
/// {
/// "name": "Tom",
/// "validCar": "{\"brand\":\"XYZ\",\"year\":9999}",
/// "invalidCar": "corrupted json string",
/// "optionalCar": null
/// }
/// ```
///
/// ```swift
/// @Codable
/// struct Person {
/// let name: String
///
/// // Successfully decodes valid JSON string
/// @CodableKey(options: .safeTranscodeRawString)
/// var validCar: Car = Car(brand: "Default", year: 2024)
///
/// // Uses default value for invalid JSON string
/// @CodableKey(options: .safeTranscodeRawString)
/// var invalidCar: Car = Car(brand: "Default", year: 2024)
///
/// // Becomes nil for invalid JSON string or null
/// @CodableKey(options: .safeTranscodeRawString)
/// var optionalCar: Car?
/// }
/// ```
///
/// - Note: This is a convenience option. It's identical to using
/// `@CodableKey(options: [.transcodeRawString, .useDefaultOnFailure])`
/// - Important: When using this option, ensure your properties either:
/// - Have an explicit default value, or
/// - Are optional (implicitly having `nil` as default)
public static let safeTranscodeRawString: Self = [.transcodeRawString, .useDefaultOnFailure]

/// The key will be ignored during encoding and decoding.
///
/// This option is useful when you want to add a local or runtime-only property to the structure without creating
/// another structure.
///
/// - Important: Using the `.ignored` option for an enum case may lead to runtime issues if you attempt to decode
/// or encode the enum with that case using the `.ignored` option.
public static let ignored = Self(rawValue: 1 << 0)

/// The key will be explicitly set to `nil` (`null`) when encoding and decoding.
/// By default, the key will be omitted if the value is `nil`.
public static let explicitNil = Self(rawValue: 1 << 1)

/// If the key has a custom CodableKey, a computed property will be generated to access the key; otherwise, this
/// option is ignored.
///
/// For example, if you have a custom key `myKey` and the original key `key`, a computed property `myKey` will be
/// generated to access the original key `key`.
///
/// ```swift
/// @Codable
/// struct MyStruct {
/// @CodableKey("key", options: .generateCustomKey)
/// var myKey: String
/// }
/// ```
///
/// The generated code will be:
/// ```swift
/// struct MyStruct {
/// var myKey: String
/// var key: String {
/// myKey
/// }
/// }
/// ```
public static let generateCustomKey = Self(rawValue: 1 << 2)

/// Transcode the value between raw string and the target type.
///
/// This option enables automatic conversion between a JSON string representation and a
/// strongly-typed model during encoding and decoding. The property type must conform to
/// the appropriate coding protocol based on usage:
/// - For decoding: must conform to `Decodable`
/// - For encoding: must conform to `Encodable`
/// - For both operations: must conform to `Codable` (which combines both protocols)
///
/// This is particularly useful when dealing with APIs that encode nested objects as
/// string-encoded JSON, eliminating the need for custom encoding/decoding logic.
///
/// For example, given this JSON response where `car` is a string-encoded JSON object:
///
/// ```json
/// {
/// "name": "Tom",
/// "car": "{\"brand\":\"XYZ\",\"year\":9999}"
/// }
/// ```
///
/// You can decode it directly into typed models:
///
/// ```swift
/// @Codable
/// struct Car {
/// let brand: String
/// let year: Int
/// }
///
/// @Codable
/// struct Person {
/// let name: String
/// @CodableKey(options: .transcodeRawString)
/// var car: Car
/// }
/// ```
///
/// When dealing with potentially invalid JSON strings, you can combine with other options.
/// For example:
///
/// ```json
/// {
/// "name": "Tom",
/// "car": "invalid json string"
/// }
/// ```
///
/// ```swift
/// @Codable
/// struct SafePerson {
/// let name: String
///
/// // Will use the default car when JSON string is invalid
/// @CodableKey(options: [.transcodeRawString, .useDefaultOnFailure])
/// var car: Car = Car(brand: "Default", year: 2024)
///
/// // Will be nil when JSON string is invalid
/// @CodableKey(options: [.transcodeRawString, .useDefaultOnFailure])
/// var optionalCar: Car?
/// }
/// ```
///
/// Without this option, you would need to:
/// 1. First decode the car field as a String
/// 2. Parse that string into JSON data
/// 3. Decode the JSON data into the Car type
/// 4. Implement the reverse process for encoding
///
/// The `transcodeRawString` option handles all these steps automatically.
///
/// - Note: The property type must conform to the appropriate coding protocol based on usage:
/// `Decodable` for decoding, `Encodable` for encoding, or `Codable` for both.
/// A compile-time error will occur if the type does not satisfy these requirements.
/// - Important: The string value must contain valid JSON that matches the structure of
/// the target type. If the JSON is invalid or doesn't match the expected structure,
/// a decoding error will be thrown at runtime. See ``useDefaultOnFailure`` option
/// for handling invalid JSON strings gracefully.
public static let transcodeRawString = Self(rawValue: 1 << 3)

/// Use the default value or `nil` when decoding or encoding fails.
///
/// This option provides fallback behavior when coding operations fail, with two scenarios:
///
/// 1. For properties with explicit default values:
/// ```swift
/// @CodableKey(options: .useDefaultOnFailure)
/// var status: Status = .unknown
/// ```
/// The default value (`.unknown`) will be used when decoding fails.
///
/// 2. For optional properties:
/// ```swift
/// @CodableKey(options: .useDefaultOnFailure)
/// var status: Status?
/// ```
/// The property will be set to `nil` when decoding fails.
///
/// This is particularly useful for:
/// - Enum properties where the raw value might not match any defined cases
/// - Handling backward compatibility when adding new properties
/// - Gracefully handling malformed or unexpected data
///
/// Example handling an enum with invalid raw value:
/// ```swift
/// enum Status: String, Codable {
/// case active
/// case inactive
/// case unknown
/// }
///
/// struct User {
/// let id: Int
/// @CodableKey(options: .useDefaultOnFailure)
/// var status: Status = .unknown // Will use .unknown if JSON contains invalid status
/// }
///
/// // JSON: {"id": 1, "status": "invalid_value"}
/// // Decodes without error, status will be .unknown
/// ```
///
/// - Note: This option must be used with either:
/// - A property that has an explicit default value
/// - An optional property (which implicitly has `nil` as default)
/// - Important: Without this option, decoding failures would throw an error and halt the
/// entire decoding process. With this option, failures are handled gracefully
/// by falling back to the default value or `nil`.
public static let useDefaultOnFailure = Self(rawValue: 1 << 4)

/// Decode the value in a lossy way for collections.
///
/// - For arrays and sets: invalid elements are dropped.
/// - For dictionaries: entries with invalid values (or keys that cannot be
/// converted from JSON string keys) are dropped.
///
/// This option is useful when you want to tolerate partially-invalid data
/// from APIs without failing the entire decode.
public static let lossy = Self(rawValue: 1 << 5)
}
public typealias CodableKeyOptions = CodableKitCore.CodableKeyOptions
2 changes: 2 additions & 0 deletions Sources/CodableKit/CodableKit.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@
// Created by Wendell on 3/30/24.
//

import CodableKitCore

/// A macro that generates complete `Codable` conformance for structs and classes.
///
/// This macro automatically generates all the boilerplate code needed for `Codable` conformance,
Expand Down
33 changes: 4 additions & 29 deletions Sources/CodableKit/CodableOptions.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,35 +2,10 @@
// CodableOptions.swift
// CodableKit
//
// Created by Wendell Wang on 2025/1/13.
// Compatibility shim: the canonical definitions live in `CodableKitCore`.
//

/// Options that customize the behavior of the `@Codable` macro expansion.
public struct CodableOptions: OptionSet, Sendable {
public let rawValue: Int32
import CodableKitCore

public init(rawValue: Int32) {
self.rawValue = rawValue
}

/// The default options, which perform standard Codable expansion with super encode/decode calls.
public static let `default`: Self = []

/// Skips generating super encode/decode calls in the expanded code.
///
/// Use this option when the superclass doesn't conform to `Codable`.
/// When enabled:
/// - Replaces `super.init(from: decoder)` with `super.init()`
/// - Removes `super.encode(to: encoder)` call entirely
public static let skipSuperCoding = Self(rawValue: 1 << 0)

/// Skips adding protocol conformances (`Codable`/`Decodable`/`Encodable`) to the generated extension.
///
/// Use this option when you want to explicitly declare the conformance on the type yourself, e.g.:
///
/// ```swift
/// @Codable(options: .skipProtocolConformance)
/// struct User: Codable { ... }
/// ```
public static let skipProtocolConformance = Self(rawValue: 1 << 1)
}
/// Options that customize the behavior of the `@Codable` / `@Decodable` / `@Encodable` macro expansion.
public typealias CodableOptions = CodableKitCore.CodableOptions
48 changes: 48 additions & 0 deletions Sources/CodableKitCore/CodableKeyOptions.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
//
// CodableKeyOptions.swift
// CodableKitCore
//
// Shared (runtime + macro implementation) option definitions.
//

public struct CodableKeyOptions: OptionSet, Sendable {
public let rawValue: Int32

public init(rawValue: Int32) {
self.rawValue = rawValue
}

/// The default options for a `CodableKey`, which is equivalent to an empty set.
public static let `default`: Self = []

/// A convenience option combining ``transcodeRawString`` and ``useDefaultOnFailure`` for safe JSON string transcoding.
///
/// This option provides a safer way to handle string-encoded JSON by automatically falling back to
/// default values or `nil` when the JSON string is invalid or malformed. It's equivalent to
/// `[.transcodeRawString, .useDefaultOnFailure]`.
public static let safeTranscodeRawString: Self = [.transcodeRawString, .useDefaultOnFailure]

/// The key will be ignored during encoding and decoding.
public static let ignored = Self(rawValue: 1 << 0)

/// The key will be explicitly set to `nil` (`null`) when encoding and decoding.
/// By default, the key will be omitted if the value is `nil`.
public static let explicitNil = Self(rawValue: 1 << 1)

/// If the key has a custom CodableKey, a computed property will be generated to access the key; otherwise, this
/// option is ignored.
public static let generateCustomKey = Self(rawValue: 1 << 2)

/// Transcode the value between raw string and the target type.
public static let transcodeRawString = Self(rawValue: 1 << 3)

/// Use the default value or `nil` when decoding or encoding fails.
public static let useDefaultOnFailure = Self(rawValue: 1 << 4)

/// Decode the value in a lossy way for collections.
///
/// - For arrays and sets: invalid elements are dropped.
/// - For dictionaries: entries with invalid values (or keys that cannot be
/// converted from JSON string keys) are dropped.
public static let lossy = Self(rawValue: 1 << 5)
}
36 changes: 36 additions & 0 deletions Sources/CodableKitCore/CodableOptions.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
//
// CodableOptions.swift
// CodableKitCore
//
// Shared (runtime + macro implementation) option definitions.
//

/// Options that customize the behavior of the `@Codable` / `@Decodable` / `@Encodable` macro expansion.
public struct CodableOptions: OptionSet, Sendable {
public let rawValue: Int32

public init(rawValue: Int32) {
self.rawValue = rawValue
}

/// The default options, which perform standard Codable expansion with super encode/decode calls.
public static let `default`: Self = []

/// Skips generating super encode/decode calls in the expanded code.
///
/// Use this option when the superclass doesn't conform to `Codable`.
/// When enabled:
/// - Replaces `super.init(from: decoder)` with `super.init()`
/// - Removes `super.encode(to: encoder)` call entirely
public static let skipSuperCoding = Self(rawValue: 1 << 0)

/// Skips adding protocol conformances (`Codable`/`Decodable`/`Encodable`) to the generated extension.
///
/// Use this option when you want to explicitly declare the conformance on the type yourself, e.g.:
///
/// ```swift
/// @Codable(options: .skipProtocolConformance)
/// struct User: Codable { ... }
/// ```
public static let skipProtocolConformance = Self(rawValue: 1 << 1)
}
Loading