Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit1d34826

Browse files
authored
DocC core types: WIP (#120)
* DocC core types* Exchange swiftdocs for docc* Running DocC to html, not working well* Update Jazzy* Update Github Actions environment* Lifting docs
1 parent4d7b494 commit1d34826

File tree

1,662 files changed

+120550
-14602
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

1,662 files changed

+120550
-14602
lines changed

‎.github/workflows/swift.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ on:
88

99
jobs:
1010
build:
11-
runs-on:macos-latest
11+
runs-on:macos-11
1212
steps:
1313
-name:Cache Mint
1414
uses:actions/cache@v2

‎Makefile‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: set-version pod-push mint test code-coverage-summary code-coverage-details code-coverage-file code-coverage-upload lint-check lint-autocorrect sourcery jazzyswiftdoc prebuild notify-telegram help
1+
.PHONY: set-version pod-push mint test code-coverage-summary code-coverage-details code-coverage-file code-coverage-upload lint-check lint-autocorrect sourcery jazzydocc prebuild notify-telegram help
22
.DEFAULT_GOAL := help
33

44
# Version
@@ -71,6 +71,15 @@ lint-autocorrect:
7171
sourcery:
7272
mint run sourcery
7373

74+
# Docc
75+
docc:
76+
xcodebuild docbuild -scheme"SwiftRex-Package" -sdk iphonesimulator -configuration Debug -destination"platform=iOS Simulator,name=iPhone SE (2nd generation),OS=15.0" SYMROOT=tmp
77+
mint run docc2html -f tmp/Debug-iphonesimulator/SwiftRex.doccarchive docs/docc/SwiftRex
78+
mint run docc2html -f tmp/Debug-iphonesimulator/CombineRex.doccarchive docs/docc/CombineRex
79+
mint run docc2html -f tmp/Debug-iphonesimulator/RxSwiftRex.doccarchive docs/docc/RxSwiftRex
80+
mint run docc2html -f tmp/Debug-iphonesimulator/ReactiveSwiftRex.doccarchive docs/docc/ReactiveSwiftRex
81+
rm -rf tmp
82+
7483
# Jazzy
7584

7685
jazzy:
@@ -79,9 +88,6 @@ jazzy:
7988
bundleexec jazzy --module RxSwift --swift-build-tool spm --build-tool-arguments -Xswiftc,-swift-version,-Xswiftc,5 --output docs/api/RxSwiftRex
8089
bundleexec jazzy --module SwiftRex --swift-build-tool spm --build-tool-arguments -Xswiftc,-swift-version,-Xswiftc,5 --output docs/api
8190

82-
swiftdoc:
83-
mint run swift-doc generate Sources --module-name SwiftRex --output docs/swiftdocs --format html
84-
8591
# Pre-Build
8692

8793
prebuild: sourcery lint-autocorrect lint-check
@@ -128,8 +134,8 @@ help:
128134
@echo make jazzy
129135
@echo -- generates documentation
130136
@echo
131-
@echo makeswiftdoc
132-
@echo"-- generatesdocumentation (alternative API docs, not fully working yet)"
137+
@echo makedocc
138+
@echo"-- generatesDocC documentation"
133139
@echo
134140
@echo make prebuild
135141
@echo -- runs the pre-build phases

‎Mintfile‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
1-
realm/SwiftLint@0.43.1
2-
krzysztofzablocki/Sourcery@0.18.0
1+
realm/SwiftLint@0.45.0
2+
krzysztofzablocki/Sourcery@1.6.0
3+
DoccZz/docc2html@0.4.5

‎Package.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// swift-tools-version:5.3
1+
// swift-tools-version:5.5
22
import PackageDescription
33

44
letpackage=Package(

‎README.md‎

Lines changed: 789 additions & 201 deletions
Large diffs are not rendered by default.

‎Sources/SwiftRex/CoreTypes/Pipeline/MiddlewareProtocol.swift‎

Lines changed: 51 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,63 @@
1+
/// ``MiddlewareProtocol`` is a plugin, or a composition of several plugins, that are assigned to the app global ``StoreType`` pipeline in order to
2+
/// handle each action received (``InputActionType``), to execute side-effects in response, and eventually dispatch more actions
3+
/// (``OutputActionType``) in the process. It can also access the most up-to-date ``StateType`` while handling an incoming action.
14
publicprotocolMiddlewareProtocol{
2-
/**
3-
The Action type that this `Middleware` knows how to handle, so the store will forward actions of this type to this middleware.
4-
Thanks to optics, this action can be a sub-action lifted to a global action type in order to compose with other middlewares acting on the global
5-
action of an app. Please check `lift(inputActionMap:outputActionMap:stateMap:)` for more details.
6-
*/
5+
/// The Action type that this ``MiddlewareProtocol`` knows how to handle, so the store will forward actions of this type to this middleware.
6+
///
7+
/// Most of the times middlewares don't need to handle all possible actions from the whole global action tree, so we can decide to allow it to
8+
/// focus only on a subset of the action.
9+
///
10+
/// In this case, this action type can be a subset to be lifted to a global action type in order to compose with other middlewares acting on the
11+
/// global action of an app. Please check <doc:Lifting> for more details.
712
associatedtypeInputActionType
813

9-
/**
10-
The Action type that this `Middleware` will eventually trigger back to the store in response of side-effects. This can be the same as
11-
`InputActionType` or different, in case you want to separate your enum in requests and responses.
12-
Thanks to optics, this action can be a sub-action lifted to a global action type in order to compose with other middlewares acting on the global
13-
action of an app. Please check `lift(inputActionMap:outputActionMap:stateMap:)` for more details.
14-
*/
14+
/// The Action type that this ``MiddlewareProtocol`` will eventually trigger back to the store in response of side-effects. This can be the same
15+
/// as ``InputActionType`` or different, in case you want to separate your enum in requests and responses.
16+
///
17+
/// Most of the times middlewares don't need to dispatch all possible actions of the whole global action tree, so we can decide to allow it to
18+
/// dispatch only a subset of the action, or not dispatch any action at all, so the ``OutputActionType`` can safely be set to `Never`.
19+
///
20+
/// In this case, this action type can be a subset to be lifted to a global action type in order to compose with other middlewares acting on the
21+
/// global action of an app. Please check <doc:Lifting> for more details.
1522
associatedtypeOutputActionType
1623

17-
/**
18-
The State part that this `Middleware` needs to read in order to make decisions. This middleware will be able to read the most up-to-date
19-
`StateType` from the store at any point in time, but it can never write or make changes to it. In some cases, middleware don't need reading the
20-
whole global state, so we can decide to allowonly a sub-state, or maybe this middleware doesn't need to read anystate,so the `StateType`can
21-
safely be set to `Void`.
22-
Thanks to lenses, this state can be a sub-state lifted to a global state in order to compose with other middlewares acting on the global state
23-
of an app. Please check `lift(inputActionMap:outputActionMap:stateMap:)` for more details.
24-
*/
24+
/// The State part that this ``MiddlewareProtocol`` needs to read in order to make decisions. This middleware will be able to read the most
25+
/// up-to-date ``StateType`` from the store while handling an incoming action, but it can never write or make changes to it.
26+
///
27+
/// Most of the times middlewares don't need reading thewhole global state, so we can decide to allowit to read only a subset of thestate,or
28+
/// maybe this middleware doesn't need to read any state, so the ``StateType`` can safely be set to `Void`.
29+
///
30+
/// In this case, this state type can be a subset to be lifted to a global state in order to compose with other middlewares acting on the global state
31+
/// of an app. Please check <doc:Lifting> for more details.
2532
associatedtypeStateType
2633

34+
/// Handles the incoming actions and may or not start async tasks, check the latest state at any point or dispatch additional actions.
35+
///
36+
/// This is a good place for side-effects such as async tasks, timers, web, database, file access, background execution, access device sensors,
37+
/// perform analytics, tracking, logging and telemetry. You can schedule tasks to run after the reducer changed the global state, this will happen
38+
/// in the ``IO`` closure you must return from this function.
39+
///
40+
/// In case no side-effect is required for certain action, returning ``IO/pure()`` should suffice.
41+
///
42+
/// You can only dispatch new actions to the store from inside the ``IO`` closure.
43+
///
44+
/// > **_IMPORTANT:_** this will be called on the main queue, never perform expensive work on it. You should perform side-effects only in the
45+
/// ``IO`` block and care about running things in background. You don't have to return to the main queue to dispatch actions, however, the store
46+
/// will take care of that.
47+
///
48+
/// - Parameters:
49+
/// - action: the incoming action to be handled
50+
/// - dispatcher: information about the action source, representing the entity that created and dispatched the action
51+
/// - state: a closure that, once called, will return the most up-to-date state. In the scope of this function, the state wasn't handled by
52+
/// reducers yet, but in the context of the ``IO`` block you should expect the state to be changed already.
53+
/// - Returns: an ``IO`` closure where you can run side-effects and dispatch new actions to the store
2754
func handle(action:InputActionType, from dispatcher:ActionSource, state:@escapingGetState<StateType>)->IO<OutputActionType>
2855

29-
/**
30-
Middleware setup. This function will be called before actions are handled to the middleware, so you can configure your middleware with the given
31-
parameters. You can hold any of them if you plan to read the state or dispatch new actions.
32-
You can initialize and start timers or async tasks in here or in the `handle(action:next)` function, but never before this function is called,
33-
otherwise the middleware would not yet be running from a store.
34-
Because no actions are delivered to this middleware before the `receiveContext(getState:output:)` is called, you can safely keep implicit
35-
unwrapped versions of `getState` and `output` as properties of your concrete middleware, and set them from the arguments of this function.
36-
37-
- Parameters:
38-
- getState: a closure that allows the middleware to read the current state at any point in time
39-
- output: an action handler that allows the middleware to dispatch new actions at any point in time
40-
*/
56+
/// Middleware setup. This function is deprecated and should never be used.
57+
///
58+
/// - Parameters:
59+
/// - getState: a closure that allows the middleware to read the current state at any point in time
60+
/// - output: an action handler that allows the middleware to dispatch new actions at any point in time
4161
@available(
4262
*,
4363
deprecated,

‎Sources/SwiftRex/CoreTypes/Pipeline/Reducer.swift‎

Lines changed: 1 addition & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,4 @@
1-
/**
2-
⚙ `Reducer` is a pure function wrapped in a monoid container, that takes an action and the current state to calculate
3-
the new state.
4-
5-
The `Middleware` pipeline will be notified about actions, or even trigger new ones, but what they can NOT do is
6-
changing the app state. Middlewares have read-only access to the up-to-date state of our apps, but when mutations are
7-
required we must use the `Reducer` function:
8-
9-
```
10-
(ActionType, StateType) -> StateType
11-
```
12-
13-
Given an action and the current state, returns the calculated state. This function will be executed in the last stage
14-
of an action handling, when all middlewares had the chance to read the action and start their own side-effects.
15-
16-
It's important to understand that reducer is a synchronous operations that calculates a new state without any kind of
17-
side-effect, so never add properties to the `Reducer` structs or call any external function. If you are tempted to do
18-
that, please create a middleware. Reducers are also responsible for keeping the consistency of a state, so it's always
19-
good to do a final sanity check before changing the state, like for example check other dependant properties that must
20-
be changed together.
21-
22-
Once the reducer function executes, the store will update its single source of truth with the new calculated state,
23-
and propagate it to all its observers, that will react to the new state and update Views, for example.
24-
25-
This function is wrapped in a struct to overcome some Swift limitations, for example, allowing us to compose multiple
26-
reducers into one (monoid operation, where two or more reducers become a single one) or lifting reducers from local
27-
types to global types. The ability to lift reducers allow us to create small reducers, specialized in parts of our
28-
state only, written in different frameworks and modules, and later plugged into a bigger state and action handler by
29-
providing a way to map state and actions between the global and local ones. For more information about that, please
30-
check the functions `lift(actionGetter:stateGetter:stateSetter:)` and `lift(action:state:)`.
31-
32-
A possible implementation of a reducer would be:
33-
```
34-
let volumeReducer = Reducer<VolumeAction, VolumeState> = { action, currentState in
35-
switch action {
36-
case .louder:
37-
return VolumeState(
38-
isMute: currentState.isMute,
39-
volume: min(100, currentState.volume + 5)
40-
)
41-
case .quieter:
42-
return VolumeState(
43-
isMute: currentState.isMute,
44-
volume: max(0, currentState.volume - 5)
45-
)
46-
case .toggleMute:
47-
return VolumeState(
48-
isMute: !currentState.isMute,
49-
volume: currentState.volume
50-
)
51-
}
52-
}
53-
```
54-
55-
Please notice from the example above the following good practices:
56-
- No `DispatchQueue`, threading, operation queue, promises, reactive code in there
57-
- All you need to implement this function is provided by the arguments `action` and `currentState`, don't use any other
58-
variable coming from global scope, not even for reading purposes. If you need something else, it should be in the state
59-
- Do not start side-effects, requests, I/O, database calls
60-
- Avoid `default` when writing `switch`/`case` statements. That way the compiler will help you more
61-
- Make the action and the state generic parameters as much specialized as you can. If volume state is part of a bigger
62-
state, you should not be tempted to pass the whole big state into this reducer. Make it short, brief and specialized,
63-
this also helps preventing `default` case or having to re-assign properties that are never mutated by this reducer.
64-
```
65-
┌─────┐ ┌─────┐
66-
│ │ handle ┌──────────┐ request ┌ ─ ─ ─ ─ response ┌──────────┐ dispatch │ │
67-
│ │ ┌─────────▶│Middleware├─────────────▶ External│─────────────▶│Middleware│───────────▶│Store│─ ─ ▶ ...
68-
│ │ │ Action │ Pipeline │ side-effects │ World side-effects │ callback │ New Action │ │
69-
│ │ │ └──────────┘ ─ ─ ─ ─ ┘ └──────────┘ └─────┘
70-
┌──────┐ dispatch │ │ │
71-
│Button│─────────▶│Store│──▶│ ┌────────┐
72-
└──────┘ Action │ │ │ ┌─▶│ View 1 │
73-
│ │ │ ┌─────┐ │ └────────┘
74-
│ │ │ reduce ┌──────────┐ │ │ onNext │ ┌────────┐
75-
│ │ └─────────▶│ Reducer ├───────────▶│Store│────────────▶├─▶│ View 2 │
76-
│ │ Action │ Pipeline │ New state │ │ New state │ └────────┘
77-
└─────┘ + └──────────┘ └─────┘ │ ┌────────┐
78-
State └─▶│ View 3 │
79-
└────────┘
80-
```
81-
*/
1+
/// `Reducer` is a pure function wrapped in a monoid container, that takes an action and the current state to calculate the new state.
822
publicstructReducer<ActionType, StateType>{
833
/**
844
Execute the wrapped reduce function. You must provide the parameters `action: ActionType` (the action to be

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp