ts-network
v1.0.0
Published
A TypeScript datatype representing network state which taking advantage of discriminated unions(or tagged unions, algebraic data types)
Downloads
8
Maintainers
Readme
TypeScript Network Types
A TypeScript datatype representing network state which taking advantage of discriminated unions (or tagged unions, algebraic data types).
The Problem
When representing network state, the following data structure is commonly used:
var state = {
isFetching: true, // whether we are fetching the data
data: [], // the data we fetched
error: {}, // failed to fetch the data, but got an error
}
We may raise the following questions:
- What does it mean if
isFetching === true
anderror
field also exists? Refetching after failed? Can it mean something else? - What does it mean if all of the three fields exist?
- When rendering the UI, which field should I read first?
- How can I distinguish between initial page(not requested) and empty page(response with empty data)? by checking
data === null
ordata.length === 0
?
As we can see, it is hard to reason about by using this data structure, and it exists some impossible state.
A Solution
The above data structure is not a good model of the network state. Actually, network states are consist of:
- haven't start the request(
NotRequested
) - the request started, and haven't get the response yet(
Requesting
) - the request succeeded, responded with some data(
Succeeded
) - the request failed, responded with error(
Failed
)
And in some cases, we can refresh the data:
- refreshing by restart the request after succeeded(
Refreshing
) - refresh succeeded, got the new data(
RefreshSucceeded
) - refresh failed, got an error(
RefreshFailed
)
This is how this library trying to solve the problem. See the solution at the following Usage section.
Usage
import {
NetworkState,
getNotRequested,
getRequesting,
getSucceeded,
getFailed,
} from 'ts-network'
type User = {
id: number
name: string
email: string
}
type NetworkError = {
statusCode: number
message: number
}
type UserListRequestState = NetworkState<User[], NetworkError>
// How to set the state
function getUserListRequestState(action: Action) {
switch (action.type) {
case 'user-list-request-started':
return getRequesting()
case 'user-list-request-succeeded':
return getSucceeded(action.response)
case 'user-list-request-failed':
return getFailed(action.error)
default:
return getNotRequested()
}
}
// How to use the state to render UI
function render(userListRequest: UserListRequestState): UIElement {
switch (userListRequest.kind) {
case 'not-requested':
// render initial page
case 'requesting':
// render loading page
case 'succeeded':
// render user list by using `userListRequest.data`
case 'failed':
// render error message by using `userListRequest.error`
// TypeScript will raise an error if you misspell the case (like `case 'fialed':`).
// You can skip the `default` case if you have already checked all the kinds.
// And if you only check some kinds and without the `default` case, TypeScript
// will raise an error. (You should turn on `strictNullChecks` first)
}
}
API
See https://vincentbel.github.io/ts-network.
FAQ
Why are there no RefreshSucceeded
state?
Because in common use case, after refreshing succeeded, we will rerender the UI with the new data we fetched, and turning the UI to Succeeded
state waiting for another refreshing. So, using Succeeded
state is enough.
If in your special case you need to store the previous data after refreshing succeeded, you should construct your own network state. like
interface RefreshSucceeded<D> {
kind: 'refresh-succeed'
prevData: D
data: D
}
type MySpecialNetworkState<D, E> =
| NotRequested
// ...
| RefreshingSucceeded<D>
Thanks
This library is largely inspired by the post How Elm Slays a UI Antipattern. And the talk Making Impossible States Impossible is great to watch.
License
MIT.