Simple Remote Data (SRD) is a fully static land compliant implementation of the Remote Data type in TypeScript - built with Higer Kinded Types (HKT's) inspired by fp-ts and Elm Remote Data.
The idea for using HKT's in TypeScript is based on Lightweight higher-kinded polymorphism.
With yarn
yarn add srdor if you prefer npm
npm i srdor if you don't like bundlers, no need to install, just import directly from a CDN:
<script type="module">
import { SRD } from 'https://cdn.skypack.dev/srd';
</script>SRD supports CJS, UMD and ESM bundle outputs.
import React, { useState, useEffect } from 'react'
import { SRD, notAsked, loading, failure, success } from 'srd'
const App = () => {
const [rd, setRd] = useState(notAsked())
useEffect(() => {
setRd(loading())
fetch('...')
.then((data) => setRd(success(data)))
.catch((err) => setRd(failure(err)))
}, [])
return SRD.match({
notAsked: () => <div>Empty</div>,
loading: () => <div>Loading...</div>,
failure: (err) => <div>{err}</div>,
success: (data) => <div>{data}</div>,
}, rd)
}SRD works even better with Typescript! Declare your RD type once and have typescript powerfully infer it everywhere! Like magic!
import React, { useState, useEffect } from 'react'
import { SRD, RD, notAsked, loading, failure, success } from 'srd'
import { Person, getPerson } from './people'
const App = () => {
const [rd, setRd] = useState<RD<string, Person>>(notAsked())
useEffect(() => {
setRd(loading())
getPerson(123)
.then((person) => setRd(success(person)))
.catch((err) => setRd(failure(err)))
}, [])
return SRD.match({
notAsked: () => <div>Empty</div>,
loading: () => <div>Loading...</div>,
failure: (msg) => <div>{msg}</div>,
success: (person) => <div>{person}</div>,
}, rd)
}SRD comes with many of the Static Land functions that we all know and love. Here is a breakdown of all the supported algebras and utilities:
For comparing 2 SRD's to see if they are the same type.
*Note: This only compares the data types and not the inner value. So
Success(5) != Failure(5)butSuccess(5) == Success(80).
equals :: (RD e a, RD e b) -> booleanimport { SRD, success, notAsked } from 'SRD'
SRD.equals(success(5), notAsked()) // falseAllowing the SRD to be mapped over by the function provided.
map :: (a -> b, RD e a) -> RD e bimport { SRD, success, loading } from 'SRD'
const double = x => x * 2
const rd1 = success(4)
const rd2 = loading()
SRD.map(double, rd1) // success(8)
SRD.map(double, rd2) // loading()Allowing the type to be bimapped over by the functions provided. Common usecase is for when you need to map and mapFailure in one shot.
bimap :: (e -> b, a -> c, RD e a) -> RD b cimport { SRD, success, failure } from 'SRD'
const double = x => x * 2
const formatErr = err => `Something went wrong: ${err}`
const rd1 = success(4)
const rd2 = failure('404 not found')
SRD.bimap(formatErr, double, rd1) // success(8)
SRD.bimap(formatErr, double, rd2) // failure('Something went wrong: 404 not found')Apply a function wrapped in a SRD to a value wrapped in a SRD.
ap :: (RD e (a -> b), RD e a) -> RD e bimport { SRD, success, failure } from 'SRD'
const double = x => x * 2
const formatErr = err => `Something went wrong: ${err}`
const rd1 = success(4)
const rd2 = failure('404 not found')
SRD.ap(success(double), rd1)) // success(8)
SRD.ap(success(double), rd2)) // failure('404 not found')Always returns a success with whatever value is passed within.
of :: a -> RD e aimport { SRD } from 'SRD'
SRD.of(4) // success(4)Provide a default value to be returned when an SRD is not a success type.
alt :: (RD e a, RD e a) -> RD e aimport { SRD, success, loading, notAsked } from 'SRD'
SRD.alt(success(4), notAsked()) // success(4)
SRD.alt(success(50), success(4)) // success(4)
SRD.alt(loading(), notAsked()) // loading()
SRD.alt(loading(), success(4)) // success(4)Similar to map but the callback must return another SRD.
chain :: (a -> RD e b, RD e a) -> RD e bimport { SRD, success, failure, notAsked } from 'SRD'
SRD.chain(x => success(x * 2), success(4)) // success(8)
SRD.chain(x => success(x * 2), notAsked()) // notAsked()
SRD.chain(x => failure('failed'), success(4)) // failure('failed')Provide a mapper object for each SRD type and whichever type the SRD is - that function will run.
data Matcher e a ::
{ notAsked :: () -> c
, loading :: () -> c
, failure :: e -> c
, success :: a -> c
}
match :: (Matcher e a -> c, RD e a) -> cimport { SRD, success } from 'SRD'
SRD.match({
notAsked: () => 'Empty',
loading: () => 'Loading...',
failure: e => `Err: ${e}`,
success: data => `My data is ${data}`
}, success(4)) // My data is 4Similar to map but instead of running the callback on a success, it calls it on a failure.
mapFailure :: (e -> b, RD e a) -> RD b aimport { SRD, success, failure } from 'SRD'
SRD.mapFailure(x => `hello ${x}`, success(4)) // success(4)
SRD.mapFailure(x => `hello ${x}`, failure('bob')) // failure('hello bob')Similar to map but takes 2 SRD's instead of one, and if both are a success, the provided callback will be called.
map2 :: (a b -> c, RD e a, RD e b) -> RD e cimport { SRD, success, failure } from 'SRD'
SRD.map2((x, y) => x + y, success(4), success(8)) // success(12)
SRD.map2((x, y) => x + y, failure('bob'), success(8)) // failure('bob')
SRD.map2((x, y) => x + y, success(8), failure('bob')) // failure('bob')Similar to map2 but takes 3 SRD's instead of two, and if all three are a success, the provided callback will be called.
map3 :: (a b c -> d, RD e a, RD e b, RD e c) -> RD e dimport { SRD, success, failure, notAsked, loading } from 'SRD'
const add3 = (x, y, z) = x + y + z
SRD.map3(add3, success(4), success(8), success(10)) // success(22)
SRD.map3(add3, failure('bob'), success(8), notAsked()) // failure('bob')
SRD.map3(add3, success(8), loading(), failure('bob')) // loading()Similar to alt, but unwraps the SRD from it's type and runs the callback on it. If the SRD is a success the inner value is passed to the callback and returned, any other value the default is returned.
unwrap :: (b, a -> b, RD e a) -> bimport { SRD, success, notAsked, loading } from 'SRD'
const double = x => x * 2
SRD.unwrap(6, double, success(8)) // 16
SRD.unwrap(6, double, notAsked()) // 6
SRD.unwrap(6, double, loading()) // 6Similar to unwrap, but takes a default thunk instead of a default value.
unpack :: (() -> b, a -> b, RD e a) -> bimport { SRD, success, notAsked, loading } from 'SRD'
const double = x => x * 2
SRD.unpack(() => 6, double, success(8)) // 16
SRD.unpack(() => 6, double, notAsked()) // 6
SRD.unpack(() => 6, double, loading()) // 6Takes a default value and an SRD. If the SRD is a success then the inner value is returned, otherwise the default value is returned.
withDefault :: (a, RD e a) -> aimport { SRD, success, notAsked, loading } from 'SRD'
SRD.withDefault(4, success(8)) // 8
SRD.withDefault(4, notAsked()) // 4
SRD.withDefault(4, loading()) // 4Takes an SRD and returns a boolean if it is a success type.
isSuccess :: (RD e a) -> boolimport { SRD, success, notAsked } from 'SRD'
SRD.isSuccess(success(8)) // true
SRD.isSuccess(notAsked()) // falseTakes an SRD and returns a boolean if it is a failure type.
isFailure :: (RD e a) -> boolimport { SRD, success, failure } from 'SRD'
SRD.isFailure(success(8)) // false
SRD.isFailure(failure()) // trueTakes an SRD and returns a boolean if it is a notAsked type.
isNotAsked :: (RD e a) -> boolimport { SRD, success, notAsked } from 'SRD'
SRD.isNotAsked(success(8)) // false
SRD.isNotAsked(notAsked()) // trueTakes an SRD and returns a boolean if it is a loading type.
isLoading :: (RD e a) -> boolimport { SRD, success, loading } from 'SRD'
SRD.isLoading(success(8)) // false
SRD.isLoading(loading()) // true