StoreFlowable.swift

KO | EN

gitlite — search

#javascript #python #ai #golang #android #rust #deep-learning #linux #java #awesome #security #ios #mcp #open-source

StoreFlowable.swift

(★ 17)

Repository pattern support library for Swift with Concurrency.

StoreFlowable.swift Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# StoreFlowable.swift

[![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/kazakago/storeflowable.swift.svg)](https://github.com/KazaKago/StoreFlowable.swift/releases/latest)
[![Test](https://github.com/KazaKago/StoreFlowable.swift/workflows/Test/badge.svg)](https://github.com/KazaKago/StoreFlowable.swift/actions?query=workflow%3ATest)
[![License](https://img.shields.io/github/license/kazakago/storeflowable.swift.svg)](https://raw.githubusercontent.com/kazakago/StoreFlowable.swift/main/LICENSE)
[![Swift Version Compatibility](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2FKazaKago%2FStoreFlowable.swift%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/KazaKago/StoreFlowable.swift)
[![Platform Compatibility](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2FKazaKago%2FStoreFlowable.swift%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/KazaKago/StoreFlowable.swift)

[Repository pattern](https://msdn.microsoft.com/en-us/library/ff649690.aspx) support library for Swift with Concurrency.  
Available for iOS or any Swift projects.

### Related projects

- [StoreFlowable.kt (for Kotlin)](https://github.com/KazaKago/StoreFlowable.kt)
- [StoreFlowable.dart (for Dart)](https://github.com/KazaKago/StoreFlowable.dart)

## Overview

This library provides remote and local cache abstraction and observation with [Swift Concurrency](https://docs.swift.org/swift-book/LanguageGuide/Concurrency.html).  
Created according to the following 5 policies.

- **Repository pattern**
    - Abstract remote and local data acquisition.
- **Single Source of Truth**
    - Looks like a single source from the user side.
- **Observer pattern**
    - Observing data with Combine Framework.
- **Return value as soon as possible**
- **Representing the state of data**

The following is the class structure of Repository pattern using this library.

![README-SWIFT-1 (1)](https://user-images.githubusercontent.com/7742104/174244655-ab06ff3a-b5bd-444a-b0e9-380b74a9dd3b.jpg)

The following is an example of screen display using [`LoadingState`](Sources/StoreFlowable/Core/LoadingState.swift).

![https://user-images.githubusercontent.com/7742104/125714730-381eee65-4126-4ee8-991a-7fc64dfb325c.jpg](https://user-images.githubusercontent.com/7742104/125714730-381eee65-4126-4ee8-991a-7fc64dfb325c.jpg)

## Install

Install as [Swift Package Manager](https://swift.org/package-manager/) exchanging `*.*.*` for the latest tag. [![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/kazakago/storeflowable.swift.svg)](https://github.com/KazaKago/StoreFlowable.swift/releases/latest)

```swift
dependencies: [
    .package(url: "https://github.com/KazaKago/StoreFlowable.swift.git", from: "*.*.*"),
],
```

## Get started

There are only 2 things you have to implement:

- Create a class to manage the in-app cache.
- Create a class to get data from origin server.

### 1. Create a class to manage the in-app cache

First, create a class that inherits [`Cacher<PARAM: Hashable, DATA>`](Sources/StoreFlowable/cacher/Cacher.swift).  
Put the type you want to use as a param in `<PARAM: Hashable>`. If you don't need the param, put in the [`UnitHash`](Sources/StoreFlowable/UnitHash.swift).

```swift
class UserCacher: Cacher<UserId, UserData> {
    static let shared = UserCacher()
    private override init() {}
}
```

[`Cacher<PARAM: Hashable, DATA>`](Sources/StoreFlowable/Cacher/Cacher.swift) needs to be used in Singleton pattern.

### 2. Create a class to get data from origin server

Next, create a class that implements [`Fetcher`](Sources/StoreFlowable/Fetcher/Fetcher.swift).  
Put the type you want to use as a Data in `DATA` associatedtype.

An example is shown below.

```swift
struct UserFetcher : Fetcher {

typealias PARAM = UserId
    typealias DATA = UserData

private let userApi = UserApi()

func fetch(param: UserId) async throws -> UserData {
        userApi.fetch(userId: param)
    }
}
```

You need to prepare the API access class.  
In this case, `UserApi` classe.

### 3. Build StoreFlowable from Cacher & Fetcher class

After that, you can get the [`StoreFlowable<DATA>`](Sources/StoreFlowable/StoreFlowable.swift) class from the [`AnyStoreFlowable.from()`](Sources/StoreFlowable/StoreFlowableExtension.swift) method.  
Be sure to go through the created [`StoreFlowable<DATA>`](Sources/StoreFlowable/StoreFlowable.swift) class when getting / updating data.

```swift
let userFlowable: AnyStoreFlowable<UserData> = AnyStoreFlowable.from(cacher: userCacher, fetcher: userFetcher, param: userId)
let userStateSequence: LoadingStateSequence<UserData> = userFlowable.publish()
```

You can get the data in the form of [`LoadingStateSequence<DATA>`](Sources/StoreFlowable/Core/LoadingStateSequence.swift) (Same as `AsyncSequence<LoadingState<DATA>>`) by using the [`publish()`](Sources/StoreFlowable/StoreFlowable.swift) method.  
[`LoadingState`](Sources/StoreFlowable/Core/LoadingState.swift) is a [enum](https://docs.swift.org/swift-book/LanguageGuide/Enumerations.html) that holds raw data.

### 4. Subscribe `FlowLoadingState<DATA>`

You can observe the data by for-in [`AsyncSequence`](https://developer.apple.com/documentation/swift/asyncsequence).  
and branch the data state with [`doAction()`](Sources/StoreFlowable/Core/LoadingState.swift) method or `switch` statement.

```swift
for await userState in userStateSequence {
    userState.doAction(
        onLoading: { (content: UserData?) in
            ...
        },
        onCompleted: { (content: UserData, _, _) in
            ...
        },
        onError: { (error: Error) in
            ...
        }
    )
}
```

## Example

Refer to the [**example module**](example) for details. This module works as an Android app.  
See [GithubMetaCacher](Example/Example/Cacher/GithubMetaCacher.swift) + [GithubMetaFetcher](Example/Example/Fetcher/GithubMetaFetcher.swift) or [GithubUserCacher](Example/Example/Cacher/GithubUserCacher.swift) + [GithubUserFetcher](Example/Example/Fetcher/GithubUserFetcher.swift).

This example accesses the [Github API](https://docs.github.com/en/free-pro-team@latest/rest).

## Other usage of `StoreFlowable` class

### Get data without [LoadingState](Sources/StoreFlowable/Core/LoadingState.swift) enum

If you don't need value flow and [`LoadingState`](Sources/StoreFlowable/Core/LoadingState.swift) enum, you can use [`requireData()`](Sources/StoreFlowable/StoreFlowable.swift) or [`getData()`](Sources/StoreFlowable/StoreFlowable.swift).  
[`requireData()`](Sources/StoreFlowable/StoreFlowable.swift) throws an Error if there is no valid cache and fails to get new data.  
[`getData()`](Sources/StoreFlowable/StoreFlowable.swift) returns nil instead of Error.

```swift
public extension StoreFlowable {
    func getData(from: GettingFrom = .both) async -> DATA?
    func requireData(from: GettingFrom = .both) async throws -> DATA
}
```

[`GettingFrom`](Sources/StoreFlowable/GettingFrom.swift) parameter specifies where to get the data.

```swift
public enum GettingFrom {
    // Gets a combination of valid cache and remote. (Default behavior)
    case both
    // Gets only remotely.
    case origin
    // Gets only locally.
    case cache
}
```

However, use [`requireData()`](Sources/StoreFlowable/StoreFlowable.swift) or [`getData()`](Sources/StoreFlowable/StoreFlowable.swift) only for one-shot data acquisition, and consider using [`publish()`](Sources/StoreFlowable/StoreFlowable.swift) if possible.

### Refresh data

If you want to ignore the cache and get new data, add `forceRefresh` parameter to [`publish()`](Sources/StoreFlowable/StoreFlowable.swift).

```swift
public extension StoreFlowable {
    func publish(forceRefresh: Bool = false) -> LoadingStateSequence<DATA>
}
```

Or you can use [`refresh()`](Sources/StoreFlowable/StoreFlowable.swift) if you are already observing the `Publisher`.

```swift
public protocol StoreFlowable {
    func refresh() async
}
```

### Validate cache data

Use [`validate()`](Sources/StoreFlowable/StoreFlowable.swift) if you want to verify that the local cache is valid.  
If invalid, get new data remotely.

```swift
public protocol StoreFlowable {
    func validate() async
}
```

### Update cache data

If you want to update the local cache, use the [`update()`](Sources/StoreFlowable/StoreFlowable.swift) method.  
`Publisher` observers will be notified.

```swift
public protocol StoreFlowable {
    func update(newData: DATA?) async
}
```

## `LoadingStateSequence<DATA>` operators

### Map `LoadingStateSequence<DATA>`

Use [`mapContent(transform)`](Sources/StoreFlowable/Core/LoadingStateSequenceMapper.swift) to transform content in `LoadingStateSequence<DATA>`.

```swift
let state: LoadingStateSequence<Int> = ...
let mappedState: LoadingStateSequence<String> = state.mapContent { value: Int in
    value.toString()
}
```

### Combine multiple `LoadingStateSequence<DATA>`

Use [`combineState(state, transform)`](Sources/StoreFlowable/Core/LoadingStateSequenceCombiner.swift) to combine multiple `LoadingStateSequence<DATA>`.

```swift
let state1: LoadingStateSequence<Int> = ...
let state2: LoadingStateSequence<Int> = ...
let combinedState: LoadingStateSequence<Int> = state1.combineState(state2) { value1: Int, value2: Int in
    value1 + value2
}
```

## Manage Cache

### Manage cache expire time

You can easily set the cache expiration time. Override expireSeconds variable in your [`Cacher<PARAM: Hashable, DATA>`](Sources/StoreFlowable/Cacher/Cacher.swift) class.
The default value is `TimeInterval.infinity` (= will NOT expire).

```swift
class UserCacher: Cacher<UserId, UserData> {
    static let shared = UserCacher()
    private override init() {}

override var expireSeconds: TimeInterval {
        get { TimeInterval(60 * 30) } // expiration time is 30 minutes.
    }
}
```

### Persist data

If you want to make the cached data persistent, override the method of your [`Cacher<PARAM: Hashable, DATA>`](Sources/StoreFlowable/Cacher/Cacher.swift) class.

```swift
class UserCacher: Cacher<UserId, UserData> {
    static let shared = UserCacher()
    private override init() {}

override var expireSeconds: TimeInterval {
        get { TimeInterval(60 * 30) } // expiration time is 30 minutes.
    }

// Save the data for each parameter in any store.
    override func saveData(data: GithubMeta?, param: UnitHash) async {
        ...
    }

// Get the data from the store for each parameter.
    override func loadData(param: UnitHash) async -> GithubMeta? {
        ...
    }

// Save the epoch time for each parameter to manage the expiration time.
    // If there is no expiration time, no override is needed.
    override func saveDataCachedAt(epochSeconds: Double, param: UnitHash) async {
        ...
    }

// Get the date for managing the expiration time for each parameter.
    // If there is no expiration time, no override is needed.
    override func loadDataCachedAt(param: UnitHash) async -> Double? {
        ...
    }
}
```

## Pagination support

This library includes Pagination support.

Inherit [`PaginationCacher<PARAM: Hashable, DATA>`](Sources/StoreFlowable/Cacher/PaginationCacher.swift) & [`PaginationFetcher`](Sources/StoreFlowable/Fetcher/PaginationFetcher.swift) instead of [`Cacher<PARAM: Hashable, DATA>`](Sources/StoreFlowable/StoreFlowableFactory.swift) & [`Fetcher`](Sources/StoreFlowable/Fetcher/Fetcher.swift).

An example is shown below.

```swift
class UserListCacher: PaginationCacher<UnitHash, UserData> {
    static let shared = UserListCacher()
    private override init() {}
}

struct UserListFetcher : PaginationFetcher {

typealias PARAM = UnitHash
    typealias DATA = UserData

private let userListApi = UserListApi()

func fetch(param: UnitHash) async throws -> PaginationFetcher.Result<UserData> {
        let fetched = userListApi.fetch(pageToken: nil)
        return PaginationFetcher.Result(data: fetched.data, nextKey: fetched.nextPageToken)
    }

func fetchNext(nextKey: String, param: UnitHash) async throws -> PaginationFetcher.Result<UserData> {
        let fetched = userListApi.fetch(pageToken: nextKey)
        return PaginationFetcher.Result(data: fetched.data, nextKey: fetched.nextPageToken)
    }
}
```

You need to additionally implements [`fetchNext(nextKey: String, param: PARAM)`](Sources/StoreFlowable/Fetcher/PaginationFetcher.swift).

And then, You can get the state of additional loading from the `next` parameter of `onCompleted {}`.

```swift
let userFlowable = AnyStoreFlowable.from(cacher: userListCacher, fetcher: userListFetcher)
for await loadingState in userFlowable.publish() {
    loadingState.doAction(
        onLoading: { (content: UserData?) in
            // Whole (Initial) data loading.
        },
        onCompleted: { (content: UserData, next: AdditionalLoadingState, _) in
            // Whole (Initial) data loading completed.
            next.doAction(
                onFixed: { (canRequestAdditionalData: Bool) in
                    // No additional processing.
                },
                onLoading: {
                    // Additional data loading.
                },
                onError: { (error: Error) in
                    // Additional loading error.
                }
            )
        },
        onError: { (error: Error) in
            // Whole (Initial) data loading error.
        }
    )
}
```

To display in the [`UITableView`](https://developer.apple.com/documentation/uikit/uitableview), Please use the difference update function. See also [`UITableViewDiffableDataSource`](https://developer.apple.com/documentation/uikit/uitableviewdiffabledatasource).

### Request additional data

You can request additional data for paginating using the [`requestNextData()`](Sources/StoreFlowable/Pagination/OneWay/PaginationStoreFlowable.swift) method.

```swift
public extension PaginationStoreFlowable {
    func requestNextData(continueWhenError: Bool = true) async
}
```

## Pagination Example

The [GithubOrgsCacher](Example/Example/Cacher/GithubOrgsCacher.swift) + [GithubOrgsFetcher](Example/Example/Fetcher/GithubOrgsFetcher.swift) or [GithubReposCacher](Example/Example/Cacher/GithubReposCacher.swift) + [GithubReposFetcher](Example/Example/Fetcher/GithubReposFetcher.swift) classes in [**example module**](Example) implement pagination.

## License

This project is licensed under the **Apache-2.0 License** - see the [LICENSE](LICENSE) file for details.

StoreFlowable.swift

StoreFlowable.swift Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

StoreFlowable.swift

StoreFlowable.swift Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README