If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/tristanhimmelman/ObjectMapper shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 23+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 64% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live tristanhimmelman/ObjectMapper repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tristanhimmelman/ObjectMapper.

What it runs against: a local clone of tristanhimmelman/ObjectMapper — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in tristanhimmelman/ObjectMapper | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 768 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tristanhimmelman/ObjectMapper. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tristanhimmelman/ObjectMapper.git
#   cd ObjectMapper
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of tristanhimmelman/ObjectMapper and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tristanhimmelman/ObjectMapper(\\.git)?\\b" \\
  && ok "origin remote is tristanhimmelman/ObjectMapper" \\
  || miss "origin remote is not tristanhimmelman/ObjectMapper (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Sources/Mappable.swift" \\
  && ok "Sources/Mappable.swift" \\
  || miss "missing critical file: Sources/Mappable.swift"
test -f "Sources/Map.swift" \\
  && ok "Sources/Map.swift" \\
  || miss "missing critical file: Sources/Map.swift"
test -f "Sources/Mapper.swift" \\
  && ok "Sources/Mapper.swift" \\
  || miss "missing critical file: Sources/Mapper.swift"
test -f "Sources/TransformType.swift" \\
  && ok "Sources/TransformType.swift" \\
  || miss "missing critical file: Sources/TransformType.swift"
test -f "Sources/Operators.swift" \\
  && ok "Sources/Operators.swift" \\
  || miss "missing critical file: Sources/Operators.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 768 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~738d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/tristanhimmelman/ObjectMapper"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

ObjectMapper is a Swift framework that provides declarative, bidirectional JSON-to-object mapping using the custom <- operator. It eliminates boilerplate serialization code by letting you define how model properties (classes, structs, enums) map to/from JSON keys in a single mapping(map:Map) method, with built-in support for nested objects, arrays, dictionaries, and custom type transformations. Single-library structure: Sources/ contains the core mapping engine (Mappable.swift, Map.swift, Mapper.swift), a rich transform type system (DateTransform.swift, EnumTransform.swift, CodableTransform.swift), operator overloads (Operators.swift, TransformOperators.swift), and protocol-based design for extensibility. Tests/ holds test suite. Multi-target support via xcschemes for iOS, Mac, tvOS, watchOS.

iOS/macOS/tvOS/watchOS Swift developers building networked applications who need to convert API responses (JSON) into strongly-typed model objects without writing tedious manual parsing code or dealing with Codable's rigidity.

Production-ready and actively maintained. The project has a solid foundation (322KB Swift codebase), CI/CD via Travis CI (.travis.yml), multi-platform support (iOS, macOS, tvOS, watchOS schemes in .xcodeproj), and supports modern Swift versions via Package.swift and multiple versioned variants (Package@swift-4.2.swift). Last updates visible in privacy manifest addition (Sources/Resources/PrivacyInfo.xcprivacy) indicate recent maintenance.

Low risk for established projects. Single maintainer (tristanhimmelman) is a known concern, but the library has minimal external dependencies (inspect ObjectMapper.podspec), no breaking changes visible in stable API, and is widely used in production apps. Risk is primarily around future maintenance if the maintainer deprioritizes it, not code quality or stability.

Recent activity shows Apple privacy manifest compliance (PrivacyInfo.xcprivacy added), continued Swift Package Manager support maintenance, and likely bug fixes/refinements. No major feature development visible; this is a mature library in maintenance mode, focusing on compatibility with newer Swift/iOS versions.

git clone https://github.com/tristanhimmelman/ObjectMapper.git
cd ObjectMapper
open ObjectMapper.xcworkspace
# Build via Xcode or: swift build

Daily commands: This is a library, not an executable. Run tests via: swift test or open ObjectMapper.xcworkspace and run the test target. For real-world usage, add to your project via CocoaPods, Carthage, or Swift Package Manager and import ObjectMapper.

• Sources/Mappable.swift — Core protocol defining the contract for JSON-serializable objects; all model classes implement this
• Sources/Map.swift — Central mapping engine that orchestrates key-value extraction and transformation during serialization/deserialization
• Sources/Mapper.swift — Public API entry point for converting JSON dictionaries to/from Mappable objects
• Sources/TransformType.swift — Protocol defining custom transformation rules; foundational for all value converters in the framework
• Sources/Operators.swift — Operator overloads (<-) that enable the declarative mapping syntax used throughout the codebase
• Sources/ImmutableMappable.swift — Protocol for immutable struct mapping, extending core Mappable with init-based patterns

Add a new custom Transform for a domain type

1. Create a new file in Sources/ implementing TransformType protocol with fromJSON() and toJSON() methods (Sources/CustomTransform.swift (new))
2. Define the transform's input and output associated types (typically (String, MyType) or similar) (Sources/CustomTransform.swift)
3. In your Mappable.mapping() method, apply the transform using <-> operator with the custom transform instance (YourModel.swift (user code))
4. Add test cases in Tests/ObjectMapperTests/CustomTransformTests.swift to verify round-trip serialization (Tests/ObjectMapperTests/CustomTransformTests.swift)

Map a nested JSON structure to a model object

1. Create a Mappable model class/struct conforming to Mappable protocol (YourModel.swift (user code))
2. In the mapping() function, use nested key paths with dot notation (e.g., "user.profile.name") to map deeply nested JSON (YourModel.swift)
3. For array fields, use standard Swift Array syntax; ObjectMapper will iterate and map each element (YourModel.swift)
4. Call Mapper<YourModel>().map(JSON: json) or .mapArray(JSONArray: jsonArray) to hydrate from JSON (YourController.swift (user code))
5. Verify nested mapping with integration tests referencing NestedArrayTests.swift patterns (Tests/ObjectMapperTests/NestedArrayTests.swift)

Create an immutable struct model with ObjectMapper

1. Conform struct to ImmutableMappable protocol instead of Mappable (YourModel.swift (user code))
2. Implement init?(map: Map) initializer that calls map.extract() instead of the mutable mapping() func (YourModel.swift)
3. Define all properties as immutable (let) since initialization happens in init only (YourModel.swift)
4. Instantiate via Mapper<YourModel>().map(JSON: json) which returns optional (YourController.swift (user code))
5. Review ImmutableTests.swift for struct mapping patterns and test coverage (Tests/ObjectMapperTests/ImmutableTests.swift)

Add context-aware mapping logic (e.g., user role determines field parsing)

1. Create a custom Map context dictionary with contextual metadata before mapping (YourController.swift (user code))
2. Pass context as third parameter: Mapper(context: ["userRole": "admin"]).map(JSON: json) (YourController.swift)
3. In your model's mapping() function, read context via map.context to conditionally map fields (YourModel.swift)
4. Reference MapContextTests.swift to understand context dictionary patterns and testing approach (Tests/ObjectMapperTests/MapContextTests.swift)

• Swift (primary language) — Type-safe, expressive syntax with protocols enables elegant operator overloading (<-) for intuitive mapping DSL
• Protocol-oriented design (Mappable, TransformType) — Allows composition of custom transforms and polymorphic behavior without tight coupling to concrete types
• Operator overloading — Enables declarative, concise mapping syntax that reduces boilerplate in model definitions
• SPM + CocoaPods + Carthage — Multi-platform distribution strategy maximizes accessibility across different Swift dependency ecosystems

• Mutable Mappable protocol as primary pattern over immutable-first approach

  • Why: Balances ease-of-use with Swift's class/struct duality; classes commonly used for mutable models
  • Consequence: Immutable support relegated to optional ImmutableMappable; adds API surface area

• Nested key paths via string dot notation (e.g., 'user.profile.id') over type-safe keypaths

  • Why: Simpler API, works with dynamic JSON structures without compile-time type info
  • Consequence: No compile-time verification of key existence; typos only caught at runtime

• Generic TransformType protocol over hardcoded built-in transforms

  • Why: Extensibility: users can define domain-specific conversions without framework modification
  • Consequence: Users must implement fromJSON/toJSON for custom types; learning curve for first transform

• Optional context dictionary on Map for conditional logic vs. static enum variants

  • Why: Dynamic, flexible; supports arbitrary application state without framework configuration
  • Consequence: Context

No complex hidden traps, but note: (1) init?(map:Map) is failable and can return nil, used to validate objects during deserialization; (2) The <- operator's direction matters—use it consistently in mapping(map:Map) for predictable serialization; (3) Nested objects and arrays require the nested type to also conform to Mappable; (4) Custom Transforms must handle both directions (fromJSON/toJSON) even if one is a no-op; (5) Dictionary and array mappings are order-dependent in some edge cases if you rely on key ordering.

• Operator Overloading (DSL via <-) — ObjectMapper's entire API hinges on redefining the <- operator to create an expressive, readable domain-specific language for declarative property mapping instead of imperative getter/setter code.
• Protocol-Oriented Programming (Mappable, TransformType) — The library uses Swift protocols as extension points—Mappable for model contracts, TransformType for pluggable type converters—enabling flexible composition without inheritance.
• Bidirectional Data Binding — The same mapping(map:Map) method definition works for both serialization (object→JSON) and deserialization (JSON→object) by inspecting the Map's direction, reducing code duplication.
• Type Transformation Pipeline — Custom TransformType implementations allow runtime conversion of raw JSON values (strings, numbers) into strongly-typed properties (Date, URL, Enum), centralizing validation and parsing logic.
• Generic Programming (Swift Generics) — ObjectMapper leverages generics extensively (e.g., TransformOf<T>) to handle arbitrary type conversions and nested collections without code generation or reflection.
• Failable Initialization Pattern — Using init?(map:Map) as a failable initializer allows ObjectMapper to validate objects during deserialization and reject invalid JSON at the type level (returns nil for bad data).
• Immutable Value Semantics (ImmutableMappable) — Sources/ImmutableMappable.swift provides an alternative protocol for functional programming patterns where objects are immutable; important for thread-safe concurrent mapping in Swift's struct-based designs.

• SwiftyJSON/SwiftyJSON — Lightweight JSON parsing library often used in combination with ObjectMapper for safer dictionary access during mapping.
• Alamofire/Alamofire — Popular HTTP networking library; ObjectMapper is frequently paired with Alamofire to deserialize API responses directly into model objects.
• moya/Moya — Abstraction layer over Alamofire that supports ObjectMapper plugins for automatic JSON-to-model deserialization in network requests.
• Realm/realm-swift — Realm Swift ORM; ObjectMapper can map API JSON into Realm model objects for local persistence.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for URLTransform and HexColorTransform

The Sources directory contains URLTransform.swift and HexColorTransform.swift, but there are no corresponding test files (URLTransformTests.swift, HexColorTransformTests.swift) visible in Tests/ObjectMapperTests/. These transforms handle specialized data types and edge cases (invalid URLs, malformed hex colors, various color formats) that warrant dedicated test suites similar to existing CustomTransformTests.swift and DataTransformTests.swift.

• [ ] Create Tests/ObjectMapperTests/URLTransformTests.swift with test cases for valid URLs, invalid URLs, nil values, and encoded URL strings
• [ ] Create Tests/ObjectMapperTests/HexColorTransformTests.swift with test cases for valid hex formats (#RRGGBB, #RRGGBBAA), invalid formats, and platform-specific color conversions
• [ ] Verify tests run on all platforms (iOS, macOS, tvOS, watchOS) via existing xcscheme configurations

Migrate .travis.yml CI to GitHub Actions workflows

The repo uses deprecated Travis CI (.travis.yml) for continuous integration. GitHub Actions is now the standard and offers better integration with GitHub, faster execution, and improved maintainability. This would modernize the pipeline while maintaining multi-platform testing (iOS, macOS, tvOS, watchOS) already defined in the xcscheme files.

• [ ] Create .github/workflows/swift-build-test.yml that builds and tests all four platforms (using xcodebuild or swift test)
• [ ] Include test matrix for multiple Swift versions (aligned with Package@swift-4.swift and Package@swift-4.2.swift)
• [ ] Add status badge to README.md pointing to GitHub Actions instead of Travis CI

Add test suite for CodableTransform interoperability with Codable protocol

Sources/CodableTransform.swift exists and provides a bridge between ObjectMapper and Swift's native Codable protocol, but Tests/ObjectMapperTests/CodableTests.swift may only test basic Codable conformance. A dedicated test suite should verify the transform handles edge cases like nested Codable objects, encoding/decoding errors, nil values, and performance characteristics.

• [ ] Expand or create comprehensive CodableTransform tests covering custom Codable types with nested structures
• [ ] Add test cases for error handling when Codable.init(from:) throws during mapping
• [ ] Test interoperability with other transforms (e.g., CodableTransform wrapping DateTransform or EnumTransform) as shown in TransformOf.swift

• Add comprehensive unit tests for Sources/EnumTransform.swift and Sources/TransformOf.swift—these are powerful features with minimal visible test coverage in the repo structure.
• Document and add examples for the Codable integration (Sources/CodableTransform.swift) showing how to bridge ObjectMapper with Swift's native Codable protocol in the README.
• Add a concrete example in Sources/ or a separate Examples/ folder showing how to map complex nested API responses (e.g., a paginated list of users with nested posts) to demonstrate the library's depth.

ObjectMapper is a JSON serialization library with generally sound security practices for its primary purpose. However, the framework lacks built-in protections against common JSON-based attacks including type confusion, malicious URLs, deeply nested payloads, and oversized data. Since ObjectMapper is designed to deserialize untrusted JSON from external sources, developers using this framework should implement defense-in-depth strategies including input validation, size limits, type checking, and URL scheme validation at the application level. No hardcoded secrets, SQL injection risks, or infrastructure issues were identified. The main risk is that developers may not implement adequate input validation when using ObjectMapper with untrusted data sources.

• Medium · Potential Type Confusion in JSON Deserialization — Sources/FromJSON.swift, Sources/Mapper.swift, Sources/Map.swift. ObjectMapper performs automatic JSON to object mapping without strict type validation. This could allow attackers to inject unexpected data types that bypass validation logic if not carefully handled by implementers. The framework converts JSON values to Swift types implicitly, which may lead to type confusion vulnerabilities if custom transforms don't validate input types. Fix: Implement strict type validation in custom Transform implementations. Document best practices for developers using ObjectMapper to validate input types before mapping. Consider adding optional strict mode validation.
• Medium · Unsafe URL Transformation — Sources/URLTransform.swift. The URLTransform implementation converts strings to URLs without validating the URL scheme or preventing potentially dangerous schemes like 'javascript:', 'data:', or 'file://'. This could enable injection of malicious URLs if mapped from untrusted JSON sources. Fix: Implement URL scheme validation in URLTransform to whitelist safe schemes (http, https, ftp). Reject URLs with dangerous schemes by default. Document the validation behavior in the framework documentation.
• Low · Potential Denial of Service via Deeply Nested Objects — Sources/Mapper.swift, Sources/Map.swift. ObjectMapper recursively maps nested objects without apparent depth limits. Maliciously crafted JSON with extremely deep nesting could cause stack overflow or excessive memory consumption, leading to denial of service. Fix: Implement configurable maximum nesting depth limits. Add safeguards to detect and reject excessively nested JSON structures. Document recommended maximum nesting depths for production use.
• Low · Missing Input Size Validation — Sources/Mapper.swift. No apparent validation of JSON payload size or array element counts before mapping. Large payloads could consume excessive memory or processing time. Fix: Implement configurable size limits for JSON payloads and array elements. Add warnings in documentation about processing untrusted JSON from external sources. Consider implementing streaming deserialization for large datasets.
• Low · Date Transform Potential Format String Issues — Sources/CustomDateFormatTransform.swift, Sources/DateFormatterTransform.swift, Sources/ISO8601DateTransform.swift. Custom date format transforms accept arbitrary format strings that could potentially be exploited if user input influences the format string without sanitization. Fix: Ensure date format strings come only from trusted sources (application code, not user input). Document that format strings should never be derived from untrusted JSON data. Consider whitelisting allowed date formats.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.