feat: introduce chain delay strategy (#79)

Author: ns-vasilev

README.md

@@ -148,6 +148,45 @@ do {
 - Attempt 4: After 2 seconds
 - Attempt 5: After 2 seconds
 
+### Linear Strategy
+
+Delays grow proportionally with each attempt — a middle ground between constant and exponential:
+
+```swift
+import Typhoon
+
+// Retry up to 4 times with linearly increasing delays
+let service = RetryPolicyService(
+    strategy: .linear(retry: 3, duration: .seconds(1))
+)
+```
+
+**Retry Timeline:**
+- Attempt 1: Immediate
+- Attempt 2: After 1 second  (1 × 1)
+- Attempt 3: After 2 seconds (1 × 2)
+- Attempt 4: After 3 seconds (1 × 3)
+
+### Fibonacci Strategy
+
+Delays follow the Fibonacci sequence — grows faster than linear but slower than exponential:
+
+```swift
+import Typhoon
+
+let service = RetryPolicyService(
+    strategy: .fibonacci(retry: 5, duration: .seconds(1))
+)
+```
+
+**Retry Timeline:**
+- Attempt 1: Immediate
+- Attempt 2: After 1 second
+- Attempt 3: After 1 second
+- Attempt 4: After 2 seconds
+- Attempt 5: After 3 seconds
+- Attempt 6: After 5 seconds
+
 ### Exponential Strategy
 
 Ideal for avoiding overwhelming a failing service by progressively increasing wait times:
@@ -159,6 +198,7 @@ import Typhoon
 let service = RetryPolicyService(
     strategy: .exponential(
         retry: 3,
+        jitterFactor: 0,
         multiplier: 2.0,
         duration: .seconds(1)
     )
@@ -211,6 +251,71 @@ do {
 - Reduces load spikes on recovering services
 - Improves overall system resilience
 
+### Custom Strategy
+
+Provide your own delay logic by implementing `IRetryDelayStrategy`:
+
+```swift
+import Typhoon
+
+struct QuadraticDelayStrategy: IRetryDelayStrategy {
+    func delay(forRetry retries: UInt) -> UInt64? {
+        let seconds = Double(retries * retries) // 0s, 1s, 4s, 9s...
+        return UInt64(seconds * 1_000_000_000)
+    }
+}
+
+let service = RetryPolicyService(
+    strategy: .custom(retry: 4, strategy: QuadraticDelayStrategy())
+)
+```
+
+### Chain Strategy
+
+Combines multiple strategies executed sequentially. Each strategy runs independently with its own delay logic, making it ideal for phased retry approaches — e.g. react quickly first, then back off gradually.
+
+```swift
+import Typhoon
+
+let service = RetryPolicyService(
+    strategy: .chain([
+        // Phase 1: 3 quick attempts with constant delay
+        .init(retries: 3, strategy: ConstantDelayStrategy(duration: .milliseconds(100))),
+        // Phase 2: 3 slower attempts with exponential backoff
+        .init(retries: 3, strategy: ExponentialDelayStrategy(
+            duration: .seconds(1),
+            multiplier: 2.0,
+            jitterFactor: 0.1,
+            maxInterval: .seconds(60)
+        ))
+    ])
+)
+
+do {
+    let result = try await service.retry {
+        try await fetchDataFromAPI()
+    }
+} catch {
+    print("Failed after all phases")
+}
+```
+
+**Retry Timeline:**
+```
+Attempt 1: immediate
+Attempt 2: 100ms  ┐
+Attempt 3: 100ms  ├─ Phase 1: Constant
+Attempt 4: 100ms  ┘
+Attempt 5: 1s     ┐
+Attempt 6: 2s     ├─ Phase 2: Exponential
+Attempt 7: 4s     ┘
+```
+
+The total retry count is calculated automatically from the sum of all entries — no need to specify it manually.
+
+Each strategy in the chain uses **local indexing**, meaning every phase starts its delay calculation from zero. This ensures each strategy behaves predictably regardless of its position in the chain.
+
+
 ## Common Use Cases
 
 ### Network Requests

Sources/Typhoon/Classes/RetrySequence/Strategies/ChainDelayStrategy.swift

@@ -0,0 +1,75 @@
+//
+// Typhoon
+// Copyright © 2026 Space Code. All rights reserved.
+//
+
+/// A delay strategy that chains multiple strategies sequentially.
+///
+/// Exhausts each strategy in order before moving to the next.
+///
+/// ### Example
+/// ```swift
+/// let strategy = ChainDelayStrategy(strategies: [
+///     (retries: 3, strategy: ConstantDelayStrategy(duration: .milliseconds(100))),
+///     (retries: 2, strategy: ExponentialDelayStrategy(duration: .seconds(1), ...))
+/// ])
+/// ```
+public struct ChainDelayStrategy: IRetryDelayStrategy {
+    // MARK: - Types
+
+    /// Represents a single retry configuration entry.
+    public struct Entry: Sendable {
+        /// The maximum number of retry attempts.
+        public let retries: UInt
+
+        /// The delay strategy that determines how long to wait
+        /// between retry attempts.
+        public let strategy: IRetryDelayStrategy
+
+        /// Creates a new retry configuration entry.
+        ///
+        /// - Parameters:
+        ///   - retries: The maximum number of retry attempts.
+        ///   - strategy: The delay strategy applied between attempts.
+        public init(retries: UInt, strategy: IRetryDelayStrategy) {
+            self.retries = retries
+            self.strategy = strategy
+        }
+    }
+
+    // MARK: - Properties
+
+    /// Ordered retry configuration entries.
+    private let entries: [Entry]
+
+    /// The total number of retries supported by this chain.
+    public let totalRetries: UInt
+
+    // MARK: - Initialization
+
+    /// Creates a chained delay strategy.
+    ///
+    /// - Parameter entries: Ordered retry configuration entries.
+    ///   Strategies are evaluated in the order provided.
+    public init(entries: [Entry]) {
+        self.entries = entries
+        totalRetries = entries.reduce(0) { $0 + $1.retries }
+    }
+
+    // MARK: - IRetryDelayStrategy
+
+    /// Returns the delay for a given retry index.
+    public func delay(forRetry retries: UInt) -> UInt64? {
+        var offset: UInt = 0
+
+        for entry in entries {
+            if retries < offset + entry.retries {
+                let localRetry = retries - offset
+                return entry.strategy.delay(forRetry: localRetry)
+            }
+            offset += entry.retries
+        }
+
+        return nil
+    }
+}

Sources/Typhoon/Classes/Strategy/RetryPolicyStrategy.swift

@@ -78,6 +78,8 @@ public enum RetryPolicyStrategy: Sendable {
     }
 }
 
+// MARK: Strategy
+
 extension RetryPolicyStrategy {
     var strategy: IRetryDelayStrategy {
         switch self {
@@ -99,3 +101,19 @@ extension RetryPolicyStrategy {
         }
     }
 }
+
+// MARK: - Chain
+
+public extension RetryPolicyStrategy {
+    /// Creates a `.custom` retry strategy using a chained delay strategy.
+    ///
+    /// The total number of retries is automatically calculated
+    /// as the sum of all provided entries.
+    ///
+    /// - Parameter entries: Ordered delay strategy entries.
+    /// - Returns: A `.custom` strategy wrapping `ChainDelayStrategy`.
+    static func chain(_ entries: [ChainDelayStrategy.Entry]) -> RetryPolicyStrategy {
+        let chain = ChainDelayStrategy(entries: entries)
+        return .custom(retry: chain.totalRetries, strategy: chain)
+    }
+}

Tests/TyphoonTests/UnitTests/RetryPolicyServiceTests.swift

@@ -3,7 +3,7 @@
 // Copyright © 2023 Space Code. All rights reserved.
 //
 
-import Typhoon
+@testable import Typhoon
 import XCTest
 
 // MARK: - RetryPolicyServiceTests
@@ -360,6 +360,32 @@ final class RetryPolicyServiceTests: XCTestCase {
         let attempts = await counter.getValue()
         XCTAssertEqual(attempts, .defaultRetryCount + 1)
     }
+
+    func test_thatChainDelayStrategy_worksWithRetryPolicyService() async throws {
+        // given
+        let counter = Counter()
+        let service = RetryPolicyService(
+            strategy: .custom(
+                retry: 5,
+                strategy: ChainDelayStrategy(entries: [
+                    .init(retries: 3, strategy: ConstantDelayStrategy(duration: .nanoseconds(1))),
+                    .init(retries: 2, strategy: ConstantDelayStrategy(duration: .nanoseconds(1))),
+                ])
+            )
+        )
+
+        // when
+        do {
+            _ = try await service.retry {
+                _ = await counter.increment()
+                throw URLError(.unknown)
+            }
+        } catch {}
+
+        // then
+        let attempts = await counter.getValue()
+        XCTAssertEqual(attempts, 6)
+    }
 }
 
 // MARK: - Counter

Tests/TyphoonTests/UnitTests/RetrySequenceTests.swift

@@ -227,6 +227,118 @@ final class RetrySequenceTests: XCTestCase {
         XCTAssertEqual(result[7], 128, accuracy: 13)
     }
 
+    func test_thatChainDelayStrategy_returnsDelaysFromFirstStrategy() {
+        // given
+        let sut = ChainDelayStrategy(entries: [
+            .init(retries: 3, strategy: ConstantDelayStrategy(duration: .seconds(1))),
+            .init(retries: 2, strategy: ConstantDelayStrategy(duration: .seconds(5))),
+        ])
+
+        // then
+        XCTAssertNotNil(sut.delay(forRetry: 0))
+        XCTAssertNotNil(sut.delay(forRetry: 1))
+        XCTAssertNotNil(sut.delay(forRetry: 2))
+    }
+
+    func test_thatChainDelayStrategy_switchesToSecondStrategy_afterFirstExhausted() {
+        // given
+        let firstDelay: UInt64 = 1_000_000_000
+        let secondDelay: UInt64 = 5_000_000_000
+
+        let sut = ChainDelayStrategy(entries: [
+            .init(retries: 3, strategy: ConstantDelayStrategy(duration: .seconds(1))),
+            .init(retries: 2, strategy: ConstantDelayStrategy(duration: .seconds(5))),
+        ])
+
+        // then
+        XCTAssertEqual(sut.delay(forRetry: 0), firstDelay)
+        XCTAssertEqual(sut.delay(forRetry: 1), firstDelay)
+        XCTAssertEqual(sut.delay(forRetry: 2), firstDelay)
+        XCTAssertEqual(sut.delay(forRetry: 3), secondDelay)
+        XCTAssertEqual(sut.delay(forRetry: 4), secondDelay)
+    }
+
+    func test_thatChainDelayStrategy_returnsNil_whenAllStrategiesExhausted() {
+        // given
+        let sut = ChainDelayStrategy(entries: [
+            .init(retries: 3, strategy: ConstantDelayStrategy(duration: .seconds(1))),
+            .init(retries: 2, strategy: ConstantDelayStrategy(duration: .seconds(5))),
+        ])
+
+        // then
+        XCTAssertNil(sut.delay(forRetry: 5))
+    }
+
+    func test_thatRetrySequenceCreatesASequence_whenStrategyIsChainWithDifferentDelays() {
+        // given
+        let sequence = RetrySequence(
+            strategy: .chain([
+                .init(retries: 3, strategy: ConstantDelayStrategy(duration: .nanoseconds(1))),
+                .init(retries: 3, strategy: ExponentialDelayStrategy(
+                    duration: .nanoseconds(1),
+                    multiplier: 2.0,
+                    jitterFactor: 0.0,
+                    maxInterval: nil
+                )),
+            ])
+        )
+
+        // when
+        let result: [UInt64] = sequence.map { $0 }
+
+        // then
+        XCTAssertEqual(result, [1, 1, 1, 1, 2, 4])
+    }
+
+    func test_thatChainStrategy_automaticallyCalculatesTotalRetries() {
+        // given
+        let entries: [ChainDelayStrategy.Entry] = [
+            .init(retries: 3, strategy: ConstantDelayStrategy(duration: .nanosecond)),
+            .init(retries: 2, strategy: ConstantDelayStrategy(duration: .nanosecond)),
+        ]
+
+        // when
+        let strategy = RetryPolicyStrategy.chain(entries)
+
+        // then
+        XCTAssertEqual(strategy.retries, 5)
+    }
+
+    func test_thatChainStrategy_returnsCustomStrategy() {
+        // given
+        let entries: [ChainDelayStrategy.Entry] = [
+            .init(retries: 3, strategy: ConstantDelayStrategy(duration: .nanosecond)),
+            .init(retries: 2, strategy: ConstantDelayStrategy(duration: .nanosecond)),
+        ]
+
+        // when
+        let strategy = RetryPolicyStrategy.chain(entries)
+
+        // then
+        if case .custom = strategy {
+            XCTAssertTrue(true)
+        } else {
+            XCTFail("Expected .custom strategy")
+        }
+    }
+
+    func test_thatRetrySequenceCreatesASequence_whenStrategyIsChain() {
+        // given
+        let sequence = RetrySequence(
+            strategy: .chain([
+                .init(retries: 3, strategy: ConstantDelayStrategy(duration: .nanosecond)),
+                .init(retries: 2, strategy: ConstantDelayStrategy(duration: .nanosecond)),
+            ])
+        )
+
+        // when
+        let result: [UInt64] = sequence.map { $0 }
+
+        // then
+        XCTAssertEqual(result.count, 5)
+        XCTAssertEqual(result, [1, 1, 1, 1, 1])
+    }
+
     // MARK: Helpers
 
     private func toSeconds(_ nanos: UInt64) -> Double {