Merge pull request #177 from yumemi-inc/codex/setup-wrapper-docs

Introduce Setup alias for Store DSL

Author: hkusu

README.md

@@ -69,6 +69,7 @@ It keeps surrounding helper layers intentionally small, so dependencies and feat
 - [Middleware](#middleware)
   - [Logging](#logging)
   - [Message](#message)
+- [Project-specific AppStore Wrapper](#project-specific-appstore-wrapper)
 - [Testing Store](#testing-store)
 
 ## Installation
@@ -207,7 +208,7 @@ class CounterStore(
     counterRepository: CounterRepository,
 ): Store<CounterState, CounterAction, CounterEvent> by Store(
     initialState = CounterState(count = 0),
-    configure = {
+    setup = {
         state<CounterState> {
             // ...
         }
@@ -886,6 +887,78 @@ val mainStore: Store<MainState, MainAction, MainEvent> = Store {
 ```
 </details>
 
+## Project-specific AppStore Wrapper
+
+In larger projects, it can be useful to wrap `Store(...)` in a project-specific `AppStore(...)`.
+
+This allows you to centralize shared behavior such as common middleware, exception handling, and state persistence.
+It also gives you a place to prepare an extra setup hook for testing and debugging.
+
+```kt
+fun <S : State, A : Action, E : Event> AppStore(
+    initialState: S,
+    extraSetup: Setup<S, A, E> = {},
+    setup: Setup<S, A, E>,
+): Store<S, A, E> = Store(initialState) {
+    middleware(AppLoggingMiddleware())
+    exceptionHandler(AppExceptionHandler)
+
+    setup()
+    extraSetup()
+}
+```
+
+A feature Store can then focus on its own state transitions and actions:
+
+```kt
+fun CounterStore(
+    counterRepository: CounterRepository,
+    extraSetup: Setup<CounterState, CounterAction, CounterEvent> = {},
+): Store<CounterState, CounterAction, CounterEvent> = AppStore(
+    initialState = CounterState(count = 0),
+    extraSetup = extraSetup,
+) {
+    state<CounterState> {
+        action<CounterAction.Increment> {
+            val count = state.count + 1
+            counterRepository.set(count)
+            nextState(state.copy(count = count))
+        }
+    }
+}
+```
+
+For tests or debug builds, you can inject only the additional behavior you need:
+
+```kt
+val recordedEvents = mutableListOf<CounterEvent>()
+
+val store = CounterStore(
+    counterRepository = repository,
+    extraSetup = {
+        coroutineContext(testDispatcher)
+        middleware(
+            Middleware(
+                afterEventEmit = { _, event ->
+                    recordedEvents += event
+                },
+            ),
+        )
+    },
+)
+```
+
+This pattern is useful for:
+
+- applying project-wide middleware and exception handling
+- injecting test- or debug-only middleware
+- overriding `coroutineContext` in tests
+- keeping feature Store definitions focused on business logic
+
+Avoid using `extraSetup` to redefine `state {}` or `anyState {}` handlers, because handler selection depends on registration order.
+
+Also note that middleware execution order should not be relied on.
+
 ## Testing Store
 
 Tart's architecture makes writing unit tests for your *Store* straightforward.

tart-core/src/commonMain/kotlin/io/yumemi/tart/core/StoreBuilder.kt

@@ -363,32 +363,37 @@ class StoreBuilder<S : State, A : Action, E : Event> internal constructor() {
 }
 
 /**
- * Creates a Store instance with the specified initial state and optional configuration.
+ * Store DSL setup block.
+ */
+typealias Setup<S, A, E> = StoreBuilder<S, A, E>.() -> Unit
+
+/**
+ * Creates a Store instance with the specified initial state and optional setup.
  *
  * @param initialState The initial state of the store
- * @param configure Optional configuration block to customize the store
+ * @param setup Optional setup block to customize the store
  * @return A configured Store instance
  */
 fun <S : State, A : Action, E : Event> Store(
     initialState: S,
-    configure: StoreBuilder<S, A, E>.() -> Unit,
+    setup: Setup<S, A, E>,
 ): Store<S, A, E> {
     return StoreBuilder<S, A, E>().apply {
         initialState(initialState)
-        configure()
+        setup()
     }.build()
 }
 
 /**
- * Creates a Store instance with configuration provided in the block.
+ * Creates a Store instance with setup provided in the block.
  * The initial state must be set within the block using initialState().
  *
- * @param configure Configuration block to customize the store
+ * @param setup Setup block to customize the store
  * @return A configured Store instance
  * @throws IllegalArgumentException if the initial state is not set in the block
  */
 fun <S : State, A : Action, E : Event> Store(
-    configure: StoreBuilder<S, A, E>.() -> Unit,
+    setup: Setup<S, A, E>,
 ): Store<S, A, E> {
-    return StoreBuilder<S, A, E>().apply(configure).build()
+    return StoreBuilder<S, A, E>().apply(setup).build()
 }