47 |
48 | Let's create a Redux counter application with Types-First UI. We will include basic pending/error handling and a mock API call to show slightly more complexity than the normal counter app.
49 |
50 | ```typescript
51 | // 1. Create State Tree interface / initialState
52 | export interface State {
53 | counter: number;
54 | error: string;
55 | pendingRequest: boolean;
56 | };
57 |
58 | export const initialState: State = {
59 | counter: 0,
60 | error: '',
61 | pendingRequest: false
62 | };
63 |
64 | // 2. Create ActionTypes enum
65 | export enum ActionTypes = {
66 | ADD_REQUEST = 'ADD_REQUEST',
67 | ADD_FAIL = 'ADD_FAIL'
68 | ADD_SUCCESS = 'ADD_SUCCESS'
69 | };
70 |
71 | // 3. Create Action interfaces
72 | export interface Actions {
73 | [ActionTypes.ADD_REQUEST]: { type: ActionTypes.ADD_REQUEST, payload: { tryAdd: number } };
74 | [ActionTypes.ADD_FAIL]: { type: ActionTypes.ADD_FAIL, payload: { error: string } };
75 | [ActionTypes.ADD_SUCCESS]: { type: ActionTypes.ADD_SUCCESS, payload: { newCount: number} };
76 | };
77 |
78 | export type AppActions = Actions[keyof Actions]; // creates Union type of actions that we will pass in to createTypesafeRedux
79 | ```
80 |
81 | The first thing we want to do is define the interfaces of our application. The entire UI depends on state and action interfaces, so it makes sense to start with them first. Additionally, most maintenance work involves adding or modifying actions, so keeping them in one place is helpful for maintainability. Any changes to these interfaces should propagate down to the rest of the system. When we talk about "unidirectional" types, we are referring to these two interfaces driving downstream functions and utilities.
82 |
83 | ```typescript
84 | // 4. Define any Epic Dependencies
85 | export interface EpicDependencies {
86 | // Represents API call
87 | counterAddSvc: {
88 | add: (tryAdd: number) => Observable<{ newCount: number } | { error: string }>;
89 | };
90 | }
91 | ```
92 |
93 | Our Redux application has little knowledge of the outside world. Its focus is around actions and how those actions affect the state atom. We use [Epics](#epics) as a primitive for side effects, but the logic of those side effects should live behind "Services", which generically encapsulate any API that returns an observable. This is helpful for testing and separation of concerns.
94 |
95 | ```typescript
96 | // 5. Pass our interfaces to createTypesafeRedux
97 | import { createTypesafeRedux } from 'types-first-ui';
98 |
99 | export const { path, selector, action, createApp } = createTypesafeRedux<
100 | State,
101 | AppActions,
102 | EpicDependencies
103 | >();
104 | ```
105 |
106 | Now we can use these interfaces to drive our typesafe "utility" functions. These are the functions you will use to build your Redux application. Any changes to the interfaces described above will be immediately reflected in these function signatures.
107 |
108 | ```typescript
109 | // 6a. Create paths using the 'path' utility function from createTypesafeRedux
110 | export const Paths = {
111 | counter: path(['counter'], 0),
112 | error: path(['error'], ''),
113 | pendingRequest: path(['pendingRequest']),
114 | };
115 |
116 | // 6b. Create selectors using 'selector' util function from createTypesafeRedux
117 | export const doubleCounter = selector(Paths.counter, counter => {
118 | return counter * 2;
119 | });
120 | ```
121 |
122 | We now use the utility functions from `createTypesafeRedux` to create our [Paths](#path) and [Selectors](#selector). Generically, these represent observables of derived values from your state tree. Specifically, Paths are a directly referenceable property on your state tree; Selectors are derived values that are computed as a function of input Paths and Selectors.
123 |
124 | Additionally, Paths include utility get, set, & unset functions that will be used in your reducers.
125 |
126 | ```typescript
127 | import { flow } from 'types-first-ui';
128 |
129 | // 7. Implement Actions: use 'action' util function from createTypesafeRedux
130 | const addRequest = action(ActionTypes.ADD_REQUEST, {
131 | reducer: (state, action) => {
132 | // action inferred as {type: ActionTypes.ADD_REQUEST, payload: {tryAdd: number} }
133 | return Paths.pendingRequest.set(true)(state);
134 | },
135 | epic: (action$, { counterAddSvc }) => {
136 | return action$.pipe(
137 | mergeMap(action => {
138 | // action inferred as {type: ActionTypes.ADD_REQUEST, payload: {tryAdd: number} }
139 | return counterAddSvc.add(action.payload.tryAdd).pipe(
140 | map(newCount => {
141 | // API call was successful
142 | return addSuccess.creator({ newCount });
143 | }),
144 | catchError(error => {
145 | // API call failed
146 | return addFail.creator({ error });
147 | })
148 | );
149 | })
150 | );
151 | },
152 | });
153 |
154 | const addSuccess = action(ActionTypes.ADD_SUCCESS, {
155 | reducer: (state, action) => {
156 | const togglePending = Paths.pendingRequest.set(false);
157 | const updateCounter = Paths.counter.set(action.payload.newCount);
158 | return flow(
159 | togglePending,
160 | updateCounter
161 | )(state);
162 | },
163 | });
164 |
165 | const addFail = action(ActionTypes.ADD_FAIL, {
166 | reducer: (state, action) => {
167 | const togglePending = Paths.pendingRequest.set(false);
168 | const updateError = Paths.error.set(action.payload.error);
169 | return flow(
170 | togglePending,
171 | updateError
172 | )(state);
173 | },
174 | });
175 |
176 | export const ActionsMap = {
177 | [ActionTypes.ADD_REQUEST]: addRequest,
178 | [ActionTypes.ADD_SUCCESS]: addSuccess,
179 | [ActionTypes.ADD_FAIL]: addFail,
180 | };
181 | ```
182 |
183 | This is the primary focus of the developer when creating Redux applications. Given a set of actions and a state tree, we now need to implement the concrete instances of these actions.
184 | This may include reducers, epics, both, or neither. The return type of `action` is an [ActionImplementation](#action-implementation). The exported ActionsMap represents an exhaustive collection of implementations for each action type that we defined in our initial interfaces. It will be passed into our `createApp` function below.
185 |
186 | ```typescript
187 | // 8. Create the app instance
188 | const app = createApp({
189 | actions: ActionsMap,
190 | initialState,
191 | });
192 |
193 | // 9. Initialize the app instance by creating & binding to a new redux store
194 | app.createStore({
195 | epicDependencies: {
196 | // concrete instance of interface
197 | counterAddSvc: CounterAddSvc,
198 | },
199 | // enables redux dev tools
200 | dev: true,
201 | });
202 |
203 | export default app;
204 | ```
205 |
206 | With our concrete instances, we can now create our app instance. This is used to bridge React and Redux--the app exposes a `connect` function that mirrors the Redux variation, except with support for our path and selector primitives. We use an explicit import of the app rather than a `Provider` component using React's context API.
207 |
208 | ```typescript
209 | import { ActionCreator } from 'types-first-ui';
210 | // helper utility to extract ActionCreator type given the discriminant
211 | // useful to minimize boilerplate in ActionProps
212 | type Creator