Normalize Cycle interface for consistency across libraries

- Rename `current` to `effective`
- Make `datum` and `cycleDuration` internal
- Remove redundant `date` property (use `effectiveDate`)
- Remove `endDate` (use `expirationDate` which now returns exact moment)
- Add `Comparable` conformance
- Add `cycle(for:)` static factory method
- Move factory methods to separate extension for SwiftLint compliance
- Update tests for new API and fix identical operands warning

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: RISCfuture

Sources/SwiftNASR/Cycle.swift

@@ -9,10 +9,10 @@ public struct Cycle: Codable, CustomStringConvertible, Sendable, Identifiable, E
   /// The earliest reference cycle (not necessarily the earliest cycle for
   /// which data is available, but the earliest representable date for a
   /// cycle).
-  public static let datum = Self(year: 2020, month: 12, day: 3)
+  static let datum = Self(year: 2020, month: 12, day: 3)
 
-  /// `true` if this cycle's effectivity period includes the current date.
-  public static var current: Self { effectiveCycle(for: Date())! }
+  /// The currently effective cycle.
+  public static var effective: Self { effectiveCycle(for: Date())! }
 
   private static var calendar: Calendar {
     var calendar = Calendar(identifier: .gregorian)
@@ -21,7 +21,7 @@ public struct Cycle: Codable, CustomStringConvertible, Sendable, Identifiable, E
   }
 
   /// The length of time a cycle is effective for.
-  public static let cycleDuration: DateComponents = .init(day: 28)
+  static let cycleDuration: DateComponents = .init(day: 28)
   private static let negativeCycleDuration: DateComponents = .init(day: -28)
 
   /// The year of the first date of the cycle.
@@ -43,30 +43,32 @@ public struct Cycle: Codable, CustomStringConvertible, Sendable, Identifiable, E
     return dc
   }
 
-  /// A `Date` object representing the first effective day of this cycle.
-  public var date: Date? { Self.calendar.date(from: dateComponents) }
+  /// The effective date of this cycle (midnight UTC when cycle becomes effective).
+  public var effectiveDate: Date? { Self.calendar.date(from: dateComponents) }
 
-  /// The last date when this cycle is effective.
-  public var endDate: Date? {
-    guard let date else { return nil }
-    return Self.calendar.date(byAdding: Self.cycleDuration, to: date)
+  /// The expiration date of this cycle (midnight UTC when cycle expires).
+  ///
+  /// This is the exact moment the cycle expires, which is also the effective date of the next cycle.
+  public var expirationDate: Date? {
+    guard let effectiveDate else { return nil }
+    return Self.calendar.date(byAdding: Self.cycleDuration, to: effectiveDate)
   }
 
   /// The range of times when this cycle is effective.
+  ///
+  /// The range starts at `effectiveDate` and ends at `expirationDate` (exclusive).
   public var dateRange: DateInterval? {
-    guard let date else { return nil }
-    guard let endDate else { return nil }
-
-    return DateInterval(start: date, end: endDate)
+    guard let effectiveDate, let expirationDate else { return nil }
+    return DateInterval(start: effectiveDate, end: expirationDate)
   }
 
   /// Whether or not this cycle is currently effective.
   public var isEffective: Bool { contains(Date()) }
 
   /// The next active cycle following this one.
   public var next: Self? {
-    guard let endDate else { return nil }
-    let components = Self.calendar.dateComponents([.year, .month, .day], from: endDate)
+    guard let expirationDate else { return nil }
+    let components = Self.calendar.dateComponents([.year, .month, .day], from: expirationDate)
     guard let year = components.year,
       let month = components.month,
       let day = components.day
@@ -76,8 +78,9 @@ public struct Cycle: Codable, CustomStringConvertible, Sendable, Identifiable, E
 
   /// The previously active cycle before this one.
   public var previous: Self? {
-    guard let date else { return nil }
-    guard let prevDate = Self.calendar.date(byAdding: Self.negativeCycleDuration, to: date) else {
+    guard let effectiveDate else { return nil }
+    guard let prevDate = Self.calendar.date(byAdding: Self.negativeCycleDuration, to: effectiveDate)
+    else {
       return nil
     }
     let components = Self.calendar.dateComponents([.year, .month, .day], from: prevDate)
@@ -116,7 +119,7 @@ public struct Cycle: Codable, CustomStringConvertible, Sendable, Identifiable, E
               ``datum`` date.
    */
   public static func effectiveCycle(for date: Date) -> Self? {
-    guard var cycle = datum.date else { return nil }
+    guard var cycle = datum.effectiveDate else { return nil }
     guard date >= cycle else { return nil }
 
     var lastCycle = cycle
@@ -157,3 +160,23 @@ public struct Cycle: Codable, CustomStringConvertible, Sendable, Identifiable, E
     case year, month, day
   }
 }
+
+extension Cycle: Comparable {
+  public static func < (lhs: Cycle, rhs: Cycle) -> Bool {
+    if lhs.year != rhs.year { return lhs.year < rhs.year }
+    if lhs.month != rhs.month { return lhs.month < rhs.month }
+    return lhs.day < rhs.day
+  }
+}
+
+// MARK: - Factory Methods
+
+extension Cycle {
+  /// Returns the cycle that contains the given date.
+  ///
+  /// - Parameter date: The date to find the cycle for.
+  /// - Returns: The cycle containing the date, or `nil` if the date is before the datum.
+  public static func cycle(for date: Date) -> Self? {
+    effectiveCycle(for: date)
+  }
+}

Sources/SwiftNASR/Downloaders/ArchiveDataDownloader.swift

@@ -13,13 +13,13 @@ public final class ArchiveDataDownloader: Downloader {
   public let session: URLSession
 
   public init(cycle: Cycle? = nil, format: DataFormat = .txt) {
-    self.cycle = cycle ?? .current
+    self.cycle = cycle ?? .effective
     self.format = format
     session = .shared
   }
 
   public init(cycle: Cycle? = nil, format: DataFormat = .txt, session: URLSession = .shared) {
-    self.cycle = cycle ?? .current
+    self.cycle = cycle ?? .effective
     self.format = format
     self.session = session
   }

Sources/SwiftNASR/Downloaders/ArchiveFileDownloader.swift

@@ -16,7 +16,7 @@ public final class ArchiveFileDownloader: Downloader {
   public let location: URL?
 
   public init(cycle: Cycle? = nil, format: DataFormat = .txt) {
-    self.cycle = cycle ?? .current
+    self.cycle = cycle ?? .effective
     self.format = format
     session = .shared
     location = nil
@@ -28,7 +28,7 @@ public final class ArchiveFileDownloader: Downloader {
     location: URL? = nil,
     session: URLSession = .shared
   ) {
-    self.cycle = cycle ?? .current
+    self.cycle = cycle ?? .effective
     self.format = format
     self.location = location
     self.session = session

Sources/SwiftNASR/Downloaders/Downloader.swift

@@ -76,7 +76,7 @@ extension Downloader {
   public var cycleURL: URL {
     switch format {
       case .txt:
-        let cycleString = cycleDateFormatter.string(from: cycle.date!)
+        let cycleString = cycleDateFormatter.string(from: cycle.effectiveDate!)
         return URL(
           string:
             "https://nfdc.faa.gov/webContent/28DaySub/28DaySubscription_Effective_\(cycleString).zip"
@@ -87,7 +87,7 @@ extension Downloader {
         formatter.locale = Locale(identifier: "en_US")
         formatter.timeZone = TimeZone(identifier: "UTC")
         formatter.dateFormat = "dd_MMM_yyyy"
-        let csvDateString = formatter.string(from: cycle.date!)
+        let csvDateString = formatter.string(from: cycle.effectiveDate!)
         return URL(
           string: "https://nfdc.faa.gov/webContent/28DaySub/extra/\(csvDateString)_CSV.zip"
         )!

Tests/SwiftNASRTests/CycleSpec.swift

@@ -56,5 +56,92 @@ final class CycleSpec: QuickSpec {
         expect(cycle.description).to(equal("2021-01-28"))
       }
     }
+
+    describe("effective") {
+      it("returns the currently effective cycle") {
+        let effective = Cycle.effective
+        expect(effective.isEffective).to(beTrue())
+      }
+    }
+
+    describe("cycle(for:)") {
+      it("returns the cycle for a given date") {
+        let dateComponents = DateComponents(year: 2021, month: 2, day: 21)
+        let cycle = Cycle.cycle(for: calendar.date(from: dateComponents)!)
+
+        expect(cycle).toNot(beNil())
+        expect(cycle?.year).to(equal(2021))
+        expect(cycle?.month).to(equal(1))
+        expect(cycle?.day).to(equal(28))
+      }
+
+      it("returns nil for dates before datum") {
+        let dateComponents = DateComponents(year: 1903, month: 12, day: 17)
+        let cycle = Cycle.cycle(for: calendar.date(from: dateComponents)!)
+
+        expect(cycle).to(beNil())
+      }
+    }
+
+    describe("previous and next") {
+      var dateComponents: DateComponents { .init(year: 2021, month: 1, day: 28) }
+      var cycle: Cycle { .effectiveCycle(for: calendar.date(from: dateComponents)!)! }
+
+      it("returns the previous cycle") {
+        let previous = cycle.previous
+        expect(previous).toNot(beNil())
+        expect(previous?.year).to(equal(2020))
+        expect(previous?.month).to(equal(12))
+        expect(previous?.day).to(equal(31))
+      }
+
+      it("returns the next cycle") {
+        let next = cycle.next
+        expect(next).toNot(beNil())
+        expect(next?.year).to(equal(2021))
+        expect(next?.month).to(equal(2))
+        expect(next?.day).to(equal(25))
+      }
+    }
+
+    describe("Comparable") {
+      it("compares cycles correctly") {
+        let older = Cycle(year: 2021, month: 1, day: 28)
+        let newer = Cycle(year: 2021, month: 2, day: 25)
+        let same = Cycle(year: 2021, month: 1, day: 28)
+
+        expect(older < newer).to(beTrue())
+        expect(newer > older).to(beTrue())
+        expect(older == same).to(beTrue())
+      }
+    }
+
+    describe("dateRange") {
+      var dateComponents: DateComponents { .init(year: 2021, month: 1, day: 28) }
+      var cycle: Cycle { .effectiveCycle(for: calendar.date(from: dateComponents)!)! }
+
+      it("returns a date interval covering the cycle") {
+        let dateRange = cycle.dateRange
+        expect(dateRange).toNot(beNil())
+
+        // Duration should be 28 days
+        let expectedDuration: TimeInterval = 28 * 24 * 60 * 60
+        expect(dateRange?.duration).to(equal(expectedDuration))
+      }
+    }
+
+    describe("expirationDate") {
+      var dateComponents: DateComponents { .init(year: 2021, month: 1, day: 28) }
+      var cycle: Cycle { .effectiveCycle(for: calendar.date(from: dateComponents)!)! }
+
+      it("returns the exact expiration moment") {
+        let expirationDate = cycle.expirationDate
+        expect(expirationDate).toNot(beNil())
+
+        // expirationDate should equal the next cycle's effectiveDate
+        let nextCycle = cycle.next
+        expect(expirationDate).to(equal(nextCycle?.effectiveDate))
+      }
+    }
   }
 }