AltiAntonov/SafeDecoding

Features

• @SafeDecodable for optional field failure isolation
• SafeDecodingFallbackProvider for typed fallback values on required fields
• @SafeFallbackDecodable for fallback-backed required-value decoding
• SafeJSONDecoder for app-level JSON decode plus report capture
• missing safe fields decode to nil
• broken safe fields do not fail the whole model
• broken fallback-backed fields emit placeholder diagnostics and use the provider value
• placeholder diagnostics for decode issues shipped in 0.1.0 and carried through the released 0.3.x line

The current public API is intentionally centered on:

• SafeDecodable
• SafeDecodingFallbackProvider
• SafeFallbackDecodable
• SafeJSONDecoder
• SafeDecodingReport
• SafeDecodingDiagnostics
• SafeDecodingIssue

Installation

dependencies: [
    .package(url: "https://github.com/AltiAntonov/SafeDecoding.git", from: "0.4.0")
]

Then add the product to your target:

.target(
    name: "YourApp",
    dependencies: [
        .product(name: "SafeDecoding", package: "SafeDecoding")
    ]
)

Quick Start

import SafeDecoding

enum UnknownRoleFallback: SafeDecodingFallbackProvider {
    static let fallbackValue = "unknown"
}

struct User: Decodable {
    let id: Int
    @SafeDecodable var name: String?
    @SafeFallbackDecodable<UnknownRoleFallback> var role: String
}

If name is missing or malformed, decoding still succeeds and name becomes nil. If role is present but malformed, decoding still succeeds and role becomes "unknown".

For example, this dirty payload still decodes:

{
  "id": 7,
  "name": 404,
  "role": 42
}

name falls back to nil, while role falls back to the typed provider value.

Safe JSON Decoder

Use SafeJSONDecoder as the app-level entry point when you want the decoded value and a structured report in one call.

let result = try SafeJSONDecoder().decode(User.self, from: data)

let user = result.value
let report = result.report

SafeJSONDecoder is a convenience wrapper around JSONDecoder and SafeDecodingDiagnostics.capture. It does not implement a custom decoder and it does not reconstruct partial models when standard Decodable initialization fails.

You can inject a configured JSONDecoder:

let decoder = JSONDecoder()
decoder.keyDecodingStrategy = .convertFromSnakeCase

let safeDecoder = SafeJSONDecoder(jsonDecoder: decoder)
let result = try safeDecoder.decode(User.self, from: data)

Reports

Use SafeDecodingDiagnostics.capture when you want structured issue inspection around an existing decode call. 0.3.0 introduced the structured report API, and 0.3.1 stabilized the issue formatting. SafeJSONDecoder is the higher-level convenience wrapper for app code that wants the same report alongside the decoded value.

let result = try SafeDecodingDiagnostics.capture {
    try JSONDecoder().decode(User.self, from: data)
}

let user = result.value
let report = result.report

if report.hasIssues {
    for issue in report.issues {
        print(issue.fieldPath, issue.errorDescription)
    }
}

This keeps the decoded model usable while giving the caller explicit access to the recovered-field issues.

Typed Fallbacks

Use SafeDecodingFallbackProvider when the field is required by your model shape but upstream data is noisy.

import SafeDecoding

enum UnknownCountryFallback: SafeDecodingFallbackProvider {
    static let fallbackValue = "ZZ"
}

struct Shipment: Decodable {
    let id: String
    @SafeFallbackDecodable<UnknownCountryFallback> var destinationCountryCode: String
}

Dirty vendor payload:

{
  "id": "shp_4815",
  "destinationCountryCode": 404
}

Decoded result:

let shipment = try JSONDecoder().decode(Shipment.self, from: data)
shipment.destinationCountryCode // "ZZ"

The fallback provider is explicit and typed, so the call site makes the recovery behavior visible in the model declaration instead of burying it in custom decoding code.

When To Use

Use SafeDecoding when:

• you consume third-party or drift-prone APIs
• one broken field should not discard the whole payload
• you want typed defaults for required fields without writing custom init(from:)
• you want to stay in the Codable model

Good Fits

• third-party APIs with inconsistent optional field quality
• apps that want to preserve valid model data instead of failing the whole decode
• codebases that prefer a small wrapper-based entry point over manual parsing
• models that need explicit fallback values such as "unknown", "ZZ", or sentinel enums
• teams that want placeholder diagnostics today and richer reporting later

Weaker Fits

• strict backend contracts you fully control
• schema validation workflows
• rich reporting pipelines that need more than placeholder diagnostics
• cases where silent fallback values would hide contract breakage you should fail fast on

Runtime Semantics

• @SafeDecodable is scoped to optional-like wrapped values
• @SafeFallbackDecodable uses the decoded value when decoding succeeds
• if a fallback-backed field is present but malformed, a placeholder diagnostic is emitted and the provider value is used
• the 0.3.0 reporting API is additive and non-breaking relative to 0.2.0, and 0.3.1 keeps that surface stable
• missing safe fields decode to nil
• broken safe fields emit a placeholder diagnostic and fall back to nil
• diagnostics are intentionally lightweight in 0.1.0 through 0.3.1

Documentation

README.md is the primary package documentation for the currently shipped package surface.

Swift Package Index metadata is configured in .spi.yml so the package page can reflect the current target and author metadata cleanly.

Testing

0.1.0 ships with Swift Testing coverage for valid values, missing keys, broken values, and diagnostic capture. 0.2.0 extends that coverage to typed fallback-backed decoding behavior, and 0.3.0 adds report capture coverage that 0.3.1 keeps stable.

Package Metadata

Repository: AltiAntonov/SafeDecoding

Stars: 0

Forks: 0

Open issues: 0

Default branch: main

Primary language: swift

License: MIT

README: README.md