Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lsunsi/reduxswift
Predictable state container for Swift too
https://github.com/lsunsi/reduxswift
redux state-management swift
Last synced: 3 days ago
JSON representation
Predictable state container for Swift too
- Host: GitHub
- URL: https://github.com/lsunsi/reduxswift
- Owner: lsunsi
- License: mit
- Created: 2016-09-03T15:59:09.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2016-10-01T12:07:08.000Z (about 8 years ago)
- Last Synced: 2024-08-22T22:45:13.034Z (3 months ago)
- Topics: redux, state-management, swift
- Language: Swift
- Size: 21.5 KB
- Stars: 39
- Watchers: 7
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ReduxSwift
ReduxSwift is a minimal Swift port of [Redux](https://github.com/reactjs/redux), a popular JavaScript library for application state management.
[](https://swift.org/)
[](https://github.com/Carthage/Carthage)
[](https://swift.org/)
[](https://github.com/lsunsi/ReduxSwift/releases)
[](https://github.com/lsunsi/ReduxSwift/blob/master/LICENSE)
###### Functionality
- Centralized State
- Unidirectional Data Flow
- Functional Reactive Programming
###### Implementation
- Type Safe
- Extensible
- Unobtrusive
## Getting Started
> "The whole state of your app is stored in an object tree inside a single store.
> The only way to change the state tree is to emit an action, an object describing what happened.
> To specify how the actions transform the state tree, you write pure reducers.
> That's it!" - Redux's Documentation
### Application State
The Application State is a container that stores all information needed for your app to render.
Since it's only a data container, it can be of any type from a single Int to a complex Struct.
```swift
struct AppState {
struct Todo {
let text: String
var done: Bool
}
var todos: [Todo] = []
}
```
###### Tips
- Structs are recommended for complex state structures, since they guarantee the reducer can't modify the state directly
- State should be as minimal as possible, which means cheaply derivable data should be excluded from it
### Actions
Actions are structs that describe changes to be made to the Application State.
Since actions are the only way to change it, the action set represents all ways your app can change its own state.
The only requirement for your action types are that they follow the ActionType protocol.
```swift
struct ADD_TODO: ActionType {
let text: String
}
struct DO_TODO: ActionType {
let id: Int
}
struct CLEAN_DONE: ActionType {
}
```
###### Tips
- Although classes can be used to define Actions as well, little data containers like that benefit from the pass-by-value behavior offered by structs
- Actions should carry all information needed by the reducer to make the actual change (more on that next).
### Reducers
Reducers are pure functions that take an action and the current state (if any), and return a new state.
Reducers are required to initialize the state in case of absence and must always return a state instance.
Since these functions must be pure, all data needed for the change to be made have to be included in the action struct.
```swift
func reducer(action: ActionType, state: AppState?) -> AppState {
var state = state ?? AppState.init()
switch action {
case let a as ADD_TODO:
let todo = AppState.Todo(text: a.text, done: false)
state.todos.append(todo)
case let a as DO_TODO:
state.todos[a.id].done = true
case _ as CLEAN_DONE:
let todos = state.todos.filter{!$0.done}
state.todos = todos
default: break
}
return state
}
```
###### Tips
- Reducers can be composed together, making it possible to modularize your state architecture
- Reducers cannot have side-effects, so if you need asynchronous action dispatching you might need to check out some middleware for it
### Fire it up
The State, Actions and Reducers come together in the Store creation.
It exposes the current state through the 'state' property and a single method 'dispatch' used for dispatching actions.
```swift
let store = Store.init(reducer: reducer, state: nil, middlewares: [])
// State.todos => []
store.dispatch(ADD_TODO(text: "Code some Swift!"))
// State.todos => [{text "Code some Swift!", done false}]
store.dispatch(ADD_TODO(text: "Code more Swift!"))
// State.todos => [{text "Code some Swift!", done false}, {text "Code more Swift!", done false}]
store.dispatch(DO_TODO(id: 0))
// State.todos => [{text "Code some Swift!", done true}, {text "Code more Swift!", done false}]
store.dispatch(CLEAN_DONE())
// State.todos => [{text "Code more Swift!", done false}]
```
###### Tips
- The Store can be initialized with a State, making it easy to save and restore it
- Middlewares can be used to enhance the Store functionality (more on that next)
## Going deeper
You just learned about the core concepts of the Redux architecture.
Next we'll talk about two middlewares included in this framework that extend the store functionality to help you integrate it in your application.
### Subscriptions
Everything we learned until now would be pointless if you didn't have a way to get notified about state changes whenever they happen.
This middleware lets you do that in a cool reactive programming way.
```swift
let subs = Subscriptions.init()
let subsStore = Store.init(reducer: reducer, state: nil, middlewares: [subs.middleware])
subs.subscribe(key: 1) {state in
print("state changed!")
}
subs.unsubscribe(key: 1)
```
###### Tips
- Your subscriber id can be of whatever Hashable type, as long as you identify it as the second generic parameter (Int in the previous example)
- Did you know UIView's are Hashable?
### Thunk
This is a basic middleware that enables asynchronous dispatching.
It works alongside an action type called THUNK, that takes a function that takes the Store as it's first parameter.
That way you can dispatch an function that will be responsible for dispatching other actions.
```swift
let thunk = Middlewares.thunk
let thunkStore = Store.init(reducer: reducer, state: nil, middlewares: [thunk])
thunkStore.dispatch(THUNK{store in
_ = store.dispatch(CLEAR_DONE())
})
```
###### Tips
- Your thunk function can use the store reference however they want, including through in background routines
- Thunks are just a basic way of inverting the control flow of the Store. For complex asynchronous workflows you might need to check elsewhere.
### Logger
This middleware is a developer helper that logs action and state in down and up stream through the middleware chain.
That means it will print to console all actions dispatched and the states before and after they were reduced.
```swift
let logger = Middlewares.logger
let loggedStore = Store.init(reducer: reducer, state: nil, middlewares: [logger])
```
## Installation
### Carthage
> This is the recommended way of installing this package.
[Carthage](https://github.com/Carthage/Carthage) is an awesome dependency manager that'll take care of your dependencies without getting in your way.
To install ReduxSwift through Carthage, just follow these steps:
* Add the following line to your Cartfile
```
github "lsunsi/ReduxSwift"
```
* Run the following command to fetch and build your dependencies
```
$ carthage update
```
* Drag the compiled framework from the Carthage folder into your project
* Rejoice!
### Manually
If you prefer to install this package manually, just follow these steps:
* Make sure your project is a git repository. If it isn't, just run this command from your project root folder:
```
$ git init
```
* Add ReduxSwift as a git submodule by running the following command.
```
$ git submodule add https://github.com/lsunsi/ReduxSwift.git
```
* Drag the ReduxSwift.xcodeproj from the newly created ReduxSwift folder to your project.
> It should be nested in your actual project in the Project Navigator.
* Add ReduxSwift to your Embedded Binaries.
> Select your project from the Project Navigator. Then, select your Target and you'll see an Embedded Binaries menu in the General tab.
* Rejoice!
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
## Acknowledgments
* Dan Abramov for bringing Redux to our lives