Skip to content

SWIFT_FACADE_MODULE_SPLIT.md

Latest commit

 

History

History
82 lines (59 loc) · 4.56 KB

SWIFT_FACADE_MODULE_SPLIT.md

File metadata and controls

82 lines (59 loc) · 4.56 KB

Swift Facade Module Split

This document defines the target direction for a Swift-first facade while keeping the Objective-C implementation as the stable behavioral core.

Current State

The Swift facade is split into feature-aligned targets. libPhoneNumberIOSSwift remains as a non-UI umbrella target and depends on:

  • libPhoneNumber
  • libPhoneNumberGeocoding
  • libPhoneNumberShortNumber

This is convenient for users who want one import, but it makes every Swift facade consumer link optional geocoding and short-number features even when they only need parsing, formatting, and validation.

Carrier, timezone, and SwiftUI enrichment modules are separate opt-in products and are not part of the umbrella module.

Goals

  • Keep Objective-C as the source of truth for parsing, formatting, validation, geocoding, and short-number behavior.
  • Let Swift consumers depend on a smaller core facade without pulling geocoding metadata or short-number APIs.
  • Use import libPhoneNumberIOSSwift as the umbrella module.
  • Keep CocoaPods and Swift Package Manager product names predictable.

Non-Goals

  • Do not rewrite libphonenumber behavior in Swift.
  • Do not rename or destabilize the Objective-C public API.
  • Do not reintroduce third-party CocoaPods names owned by other maintainers.

Target Module Layout

Module Depends on Public surface
libPhoneNumberSwiftCore libPhoneNumber PhoneNumber, PhoneNumberUtility, AsYouTypeFormatter, Swift enums/errors
libPhoneNumberSwiftGeocoding libPhoneNumberSwiftCore, libPhoneNumberGeocoding PhoneNumberGeocoder
libPhoneNumberSwiftShortNumber libPhoneNumberSwiftCore, libPhoneNumberShortNumber ShortNumberUtility, short-number cost/type wrappers
libPhoneNumberSwiftCarrier libPhoneNumberSwiftCore, libPhoneNumberCarrier PhoneNumberCarrierMapper
libPhoneNumberSwiftTimeZones libPhoneNumberSwiftCore, libPhoneNumberTimeZones PhoneNumberTimeZonesMapper
libPhoneNumberSwiftUI libPhoneNumberSwiftCore, SwiftUI PhoneNumberTextField, PhoneNumberFieldStyle, validation state
libPhoneNumberSwiftUIEnrichment libPhoneNumberSwiftUI, libPhoneNumberSwiftCarrier, libPhoneNumberSwiftTimeZones CarrierTimeZonesPhoneNumberEnricher
libPhoneNumberIOSSwift core, geocoding, short-number facade modules Umbrella import

The umbrella module should contain little or no behavior. Its purpose is compatibility and convenience.

CocoaPods Direction

Prefer explicit podspecs or subspecs that mirror the Swift Package products:

  • libPhoneNumber-iOS-SwiftCore
  • libPhoneNumber-iOS-SwiftGeocoding
  • libPhoneNumber-iOS-SwiftShortNumber
  • libPhoneNumber-iOS-SwiftCarrier
  • libPhoneNumber-iOS-SwiftTimeZones
  • libPhoneNumber-iOS-SwiftUI
  • libPhoneNumber-iOS-SwiftUIEnrichment
  • libPhoneNumber-iOS-Swift as an umbrella pod

The umbrella pod should remain available and continue to depend on the core, geocoding, and short-number Swift facade modules. Carrier, timezone, and SwiftUI remain opt-in because they add metadata or UI-specific dependencies. New README examples should recommend libPhoneNumber-iOS-SwiftCore for parse/format-only apps.

Migration Plan

  1. Document the split and keep the current product unchanged. Done.
  2. Move Swift facade files into feature-aligned directories without changing public symbols. Done.
  3. Add SPM targets/products for core, geocoding, short-number, and umbrella modules. Done.
  4. Add matching CocoaPods packaging and lint checks. Done.
  5. Update README examples to recommend the smallest product for each workflow. Done.
  6. Keep the umbrella product until at least one minor release after the split.

Acceptance Criteria

  • A Swift app that only parses and formats phone numbers can depend on libPhoneNumberSwiftCore without linking geocoding metadata.
  • The umbrella module uses import libPhoneNumberIOSSwift, avoiding third-party CocoaPods names.
  • The Swift facade tests cover both the umbrella module and each split module.
  • CI runs swift test, swift build -c release, version consistency checks, and CocoaPods lint for every shipped podspec.
  • Any new Swift wrapper still delegates behavior to the Objective-C core.

Verification Checklist

  • Run swift scripts/checkVersionConsistency.swift after adding products or podspecs.
  • Run swift test and LC_ALL=ko_KR.UTF-8 LANG=ko_KR.UTF-8 swift test.
  • Run pod lib lint for all Swift facade podspecs.
  • Inspect the package graph to confirm libPhoneNumberSwiftCore does not depend on geocoding, short-number, carrier, timezone, or SwiftUI targets.