git.iko.soy/rowtype-yoga/purescript-record-studio
on main help sign in
rowtype-yoga/purescript-record-studio/README.md
184 lines 3.9 kB history raw
1# purescript-record-studio 📀📀📀
3You finally scored a record deal.
5## Usage guide
7### Assert two records have the same keys with `SameKeys`
9```purescript
10-- An example of a function that requires `{|r1}` and `{|r2}` to have the same keys
11sameKeys :: forall r1 r2. SameKeys r1 r2 => {|r1} -> {|r2} -> Unit
12sameKeys _ _ = unit
13let _ = sameKeys { b: "hi", a: 4, c: 4 } { b: "hu", a: "ha" }
14-- Won't compile: The key "c" is missing from the second record
15```
17### Merge records with `//`
18Easily merge two records:
20```purescript
21{ a: 5, b: "B" } // { b: false, c: "c" }
22-- { a: 5, b: false, c: "c" }
23```
25This is similar to the `...` operator in ES6:
27PureScript:
28```purescript
29import Record.Studio ((//))
30rec1 = { a: 1 }
31rec2 = { b: 4, c: 8 }
32result = rec1 // rec2
33```
35JS:
36```js
37const rec1 = { a: 1 }
38const rec2 = { b: 4, c: 8 }
39const result = { ...rec1, ...rec2 }
40```
42### Shrink records with `shrink`
43Easily adjust a record with too many keys:
44```purescript
45import Record.Studio (shrink)
46-- We want to call this
47-- fn :: { a :: Int } -> Int
49-- We have this
50myRec :: { a :: Int, b :: String }
51myRec = { a: 4, b: "Hello!" }
53-- Use shrink!
54result = fn (shrink myRec)
55```
57### Get a record's keys at runtime with `keys`
58```purescript
59import Record.Studio (keys)
61theKeys :: Array String
62theKeys = keys { a: 3, b: "ooh" }
63-- ["a", "b"]
64```
66### `sequenceRecord`
67Recursively sequence a type constructor out of a record.
69```purescript
70let
71 input :: SequenceInput
72 input =
73 { a: Just 10
74 , b: "hello"
75 , c:
76 { d: Just "world"
77 , e: true
78 , f: { g: Just true }
79 }
80 , h: 10
81 }
83 expected :: Maybe SequenceOutput
84 expected = Just
85 { a: 10
86 , b: "hello"
87 , c:
88 { d: "world"
89 , e: true
90 , f: { g: true }
91 }
92 , h: 10
93 }
94(sequenceRecord input) `shouldEqual` expected
95```
97### `mapUniformRecord`
99Recursively map a function over a record where all entries have the same value.
100This is often better at type inference than `mapRecord`
101```purescript
102 (mapUniformRecord (_ + 1) { a: 1, b: 2 }) `shouldEqual` { a: 2, b: 3}
103```
105### `mapRecord`
107Recursively map a function over a record.
108```purescript
109let
110 input :: MapInput
111 input =
112 { a: 10
113 , b: "hello"
114 , c:
115 { d: Just "world"
116 , e: 20
117 , f: { g: true, h: 30 }
118 }
119 , i: 40
120 }
122 f :: Int -> String
123 f i = show (i + 1)
125 expected :: MapOutput
126 expected =
127 { a: "11"
128 , b: "hello"
129 , c:
130 { d: Just "world"
131 , e: "21"
132 , f: { g: true, h: "31" }
133 }
134 , i: "41"
135 }
136(mapRecord f input) `shouldEqual` expected
137```
139### `mapRecordKind`
141Recursively map a natural transformation over a record.
143```purescript
144 let
145 input :: MapKInput
146 input =
147 { a: Right 10
148 , b: "hello"
149 , c:
150 { d: Left "world"
151 , e: 20
152 , f: { g: Right true, h: Left "broken" }
153 }
154 , i: Just 40
155 }
157 nt :: Either String ~> Maybe
158 nt = hush
160 expected :: MapKOutput
161 expected =
162 { a: Just 10
163 , b: "hello"
164 , c:
165 { d: Nothing
166 , e: 20
167 , f: { g: Just true, h: Nothing }
168 }
169 , i: Just 40
170 }
171(mapRecordKind nt input) `shouldEqual` expected
172```
174### `key`
176Get the only field name of a Record with one field as a `Proxy`
178```purescript
179SingletonRecord.key { foo: unit } `shouldEqual` (Proxy :: Proxy "foo")
180```
182## Licence
183This is a fork of [heterogeneous-extrablatt](https://github.com/sigma-andex/purescript-heterogeneous-extrablatt), which is licenced under MIT. See the [original licence](./LICENCES/heterogeneous-extrablatt.LICENCE). This work is similarly licenced under [MIT](./LICENCE).
184It includes part of [`purescript-record-extra`](https://github.com/justinwoo/purescript-record-extra) as an inline dependency, which is licenced under MIT, see [original licence](./LICENCES/record-extra.LICENCE).