StateStore API updates & docs

Sources/Puredux/Store/StateStore.swift

@@ -36,20 +36,12 @@ public struct StateStore<State, Action> {
 }
 
 public extension StateStore {
-    @available(*, deprecated, renamed: "init(_:qos:reducer:)", message: "Actions Interceptor will be removed in 2.0, use AsyncAction instead.")
-    init(_ initialState: State,
-         interceptor: @escaping (Action, @escaping Dispatch<Action>) -> Void,
-         qos: DispatchQoS = .userInteractive,
-         reducer: @escaping Reducer<State, Action>) {
-
-        self.init(storeObject: RootStoreNode.initRootStore(
-            initialState: initialState,
-            interceptor: interceptor,
-            qos: qos,
-            reducer: reducer
-        ))
-    }
-
+    /** Initializes a new StateStore with provided initial state, qos, and reducer
+        - Parameter initialState: The initial state for the store
+        - Parameter qos: defines the DispatchQueue QoS that reducer will be performed on
+        - Parameter reducer: The function that is called on every dispatched Action and performs state mutations
+        - Returns: `StateStore<State, Action>`
+    */
     init(_ initialState: State,
          qos: DispatchQoS = .userInteractive,
          reducer: @escaping Reducer<State, Action>) {
@@ -76,6 +68,73 @@ extension StateStore {
 }
 
 public extension StateStore {
+    /**
+     Initializes a new child StateStore with initial state
+     - Parameter initialState: The initial state for the store
+     - Parameter reducer: The function that is called on every dispatched Action and performs state mutations
+     - Returns: `StateStore<State, Action>`
+
+     ChildStore is a composition of root store and newly created local store.
+
+     When action is dispatched to RootStore:
+     - action is delivered to root store's reducer
+     - action is not delivered to child store's reducer
+     - root & child stores subscribers receive updates
+     - AsyncAction dispatches result actions to RootStore
+
+     When action is dispatched to ChildStore:
+     - action is delivered to root store's reducer
+     - action is delivered to child store's reducer
+     - root & child stores subscribers receive updates
+     - AsyncAction dispatches result actions to ChildStore
+     */
+    func with<T>(_ initialState: T,
+                 reducer: @escaping Reducer<T, Action>) -> StateStore<(State, T), Action> {
+
+        StateStore<(State, T), Action>(
+            storeObject: storeObject.createChildStore(
+                initialState: initialState,
+                stateMapping: { ($0, $1) },
+                reducer: reducer
+            )
+        )
+    }
+}
+
+public extension StateStore {
+    @available(*, deprecated, renamed: "init(_:qos:reducer:)", message: "Actions Interceptor will be removed in 2.0, use AsyncAction instead.")
+    init(_ initialState: State,
+         interceptor: @escaping (Action, @escaping Dispatch<Action>) -> Void,
+         qos: DispatchQoS = .userInteractive,
+         reducer: @escaping Reducer<State, Action>) {
+
+        self.init(storeObject: RootStoreNode.initRootStore(
+            initialState: initialState,
+            interceptor: interceptor,
+            qos: qos,
+            reducer: reducer
+        ))
+    }
+
+}
+
+public extension StateStore {
+    @available(*, deprecated, renamed: "stateStore(_:stateMapping:qos:reducer:)", message: "Will be removed in 2.0")
+    func childStore<LocalState, ResultState>(
+        initialState: LocalState,
+        stateMapping: @escaping (State, LocalState) -> ResultState,
+        qos: DispatchQoS = .userInteractive,
+        reducer: @escaping Reducer<LocalState, Action>) -> StateStore<ResultState, Action> {
+
+            stateStore(
+                initialState,
+                stateMapping: stateMapping,
+                qos: qos,
+                reducer: reducer
+            )
+    }
+
+    @available(*, deprecated, message: "Use with(_:reducer) and store transformations instead. Will be removed in 2.0. ")
     func stateStore<LocalState, ResultState>(
         _ initialState: LocalState,
         stateMapping: @escaping (State, LocalState) -> ResultState,
@@ -94,6 +153,7 @@ public extension StateStore {
             )
         }
 
+    @available(*, deprecated, message: "Use with(_:reducer) and store transformations instead. Will be removed in 2.0.")
     func stateStore<LocalState, ResultState>(
         _ initialState: LocalState,
         stateMapping: @escaping (State, LocalState) -> ResultState,
@@ -112,19 +172,14 @@ public extension StateStore {
 }
 
 extension StateStore {
-
+    @available(*, deprecated, message: "Qos parameter will have no effect. Root store's QoS is used. Use with(_:reducer) and store transformations instead. Will be removed in 2.0.")
     public func stateStore<T>(
         _ state: T,
         qos: DispatchQoS = .userInitiated,
         reducer: @escaping Reducer<T, Action>
 
     ) -> StateStore<(State, T), Action> {
 
-        stateStore(
-            state,
-            stateMapping: { ($0, $1) },
-            qos: qos,
-            reducer: reducer
-        )
+        with(state, reducer: reducer)
     }
 }

Sources/Puredux/Store/StoreOf.swift

@@ -25,22 +25,42 @@ public struct StoreOf<T> {
 }
 
 public extension StoreOf {
-    func with<U, State, Action>(
-        _ state: U,
-        reducer: @escaping Reducer<U, Action>) -> StateStore<(State, U), Action> where T == StateStore<State, Action> {
+    /**
+     Initializes a new child StateStore with initial state
+     - Parameter initialState: The initial state for the store
+     - Parameter reducer: The function that is called on every dispatched Action and performs state mutations
+     - Returns: `StateStore<(Root, Local), Action>`
+
+     ChildStore is a composition of root store and newly created local store.
+
+     When action is dispatched to RootStore:
+     - action is delivered to root store's reducer
+     - action is not delivered to child store's reducer
+     - root & child stores subscribers receive updates
+     - AsyncAction dispatches result actions to RootStore
+
+     When action is dispatched to ChildStore:
+     - action is delivered to root store's reducer
+     - action is delivered to child store's reducer
+     - root & child stores subscribers receive updates
+     - AsyncAction dispatches result actions to ChildStore
+     */
+    func with<Root, Local, Action>(
+        _ initialState: Local,
+        reducer: @escaping Reducer<Local, Action>) -> StateStore<(Root, Local), Action> where T == StateStore<Root, Action> {
 
-        wrappedValue.stateStore(
-            state,
+        wrappedValue.with(
+            initialState,
             reducer: reducer
         )
     }
 
-    func with<U, State, Action>(
-        _ state: U,
-        reducer: @escaping Reducer<U, Action>) -> StateStore<(State, U), Action>? where T == StateStore<State, Action>? {
+    func with<Root, Local, Action>(
+        _ initialState: Local,
+        reducer: @escaping Reducer<Local, Action>) -> StateStore<(Root, Local), Action>? where T == StateStore<Root, Action>? {
 
-        wrappedValue?.stateStore(
-            state,
+        wrappedValue?.with(
+            initialState,
             reducer: reducer
         )
     }