Skip to content

Commit 336b195

Browse files
CopilotTheAngryByrd
Copilot
and
TheAngryByrd
authored
Add missing gitbook documentation for all undocumented public API surface (#354)
* Initial plan * Add comprehensive documentation for all missing functions and methods Co-authored-by: TheAngryByrd <1490044+TheAngryByrd@users.noreply.github.com> * Fix invalid F# in asyncResult/catch.md example 1 Co-authored-by: TheAngryByrd <1490044+TheAngryByrd@users.noreply.github.com> * Clarify concurrent semantics in cancellableTaskResult/parallelZip.md Example 3 Co-authored-by: TheAngryByrd <1490044+TheAngryByrd@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: TheAngryByrd <1490044+TheAngryByrd@users.noreply.github.com>
1 parent 9cf1c54 commit 336b195

60 files changed

Lines changed: 2978 additions & 38 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎gitbook/SUMMARY.md‎

Lines changed: 63 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -39,18 +39,23 @@
3939
* [bindNull](option/bindNull.md)
4040
* [Computation Expression](option/ce.md)
4141
* [either](option/either.md)
42+
* [ignore](option/ignore.md)
4243
* [map](option/map.md)
4344
* [map2](option/map2.md)
4445
* [map3](option/map3.md)
4546
* [sequenceAsync](option/sequenceAsync.md)
47+
* [sequenceAsyncResult](option/sequenceAsyncResult.md)
4648
* [sequenceResult](option/sequenceResult.md)
4749
* [sequenceTask](option/sequenceTask.md)
4850
* [sequenceTaskResult](option/sequenceTaskResult.md)
4951
* [tee Functions](option/teeFunctions.md)
5052
* [traverseAsync](option/traverseAsync.md)
53+
* [traverseAsyncResult](option/traverseAsyncResult.md)
5154
* [traverseResult](option/traverseResult.md)
5255
* [traverseTask](option/traverseTask.md)
5356
* [traverseTaskResult](option/traverseTaskResult.md)
57+
* [tryGetValue](option/tryGetValue.md)
58+
* [tryParse](option/tryParse.md)
5459
* [zip](option/zip.md)
5560
* Lists
5661
* [traverseOptionM](option/traverseOptionM.md)
@@ -89,16 +94,21 @@
8994
* AsyncResult
9095
* [apply](asyncResult/apply.md)
9196
* [bind](asyncResult/bind.md)
97+
* [catch](asyncResult/catch.md)
9298
* [check](asyncResult/check.md)
9399
* [Computation Expression](asyncResult/ce.md)
100+
* [eitherMap](asyncResult/eitherMap.md)
94101
* [error](asyncResult/error.md)
95102
* [foldResult](asyncResult/foldResult.md)
103+
* [getOrReraise](asyncResult/getOrReraise.md)
96104
* [ignore](asyncResult/ignore.md)
97105
* [map](asyncResult/map.md)
98106
* [map2](asyncResult/map2.md)
99107
* [map3](asyncResult/map3.md)
100108
* [mapError](asyncResult/mapError.md)
109+
* [ok](asyncResult/ok.md)
101110
* [Operators](asyncResult/operators.md)
111+
* [orElse Functions](asyncResult/orElseFunctions.md)
102112
* [Other Functions](asyncResult/others.md)
103113
* [zip](asyncResult/zip.md)
104114
* [zipError](asyncResult/zipError.md)
@@ -191,14 +201,17 @@
191201
* [check](taskResult/check.md)
192202
* [catch](taskResult/catch.md)
193203
* [Computation Expression](taskResult/ce.md)
204+
* [error](taskResult/error.md)
205+
* [foldResult](taskResult/foldResult.md)
194206
* [ignore](taskResult/ignore.md)
195207
* [map](taskResult/map.md)
196208
* [map2](taskResult/map2.md)
197209
* [map3](taskResult/map3.md)
198210
* [mapError](taskResult/mapError.md)
211+
* [ok](taskResult/ok.md)
199212
* [Operators](taskResult/operators.md)
213+
* [orElse Functions](taskResult/orElseFunctions.md)
200214
* [Other Functions](taskResult/others.md)
201-
* [error](taskResult/error.md)
202215
* [zip](taskResult/zip.md)
203216
* [zipError](taskResult/zipError.md)
204217
* Lists
@@ -225,52 +238,61 @@
225238

226239
* [Validation](validation/index.md)
227240
* [apply](validation/apply.md)
241+
* [bind](validation/bind.md)
228242
* [Computation Expression](validation/ce.md)
229243
* [error](validation/error.md)
230244
* [map](validation/map.md)
231245
* [map2](validation/map2.md)
232246
* [map3](validation/map3.md)
233247
* [mapError](validation/mapError.md)
234248
* [mapErrors](validation/mapErrors.md)
249+
* [ok](validation/ok.md)
235250
* [Operators](validation/operators.md)
251+
* [orElse Functions](validation/orElse.md)
236252
* [zip](validation/zip.md)
237253
* Transforms
238254
* [ofChoice](validation/ofChoice.md)
239255
* [ofResult](validation/ofResult.md)
240256

241257
* [AsyncValidation](asyncValidation/index.md)
242258
* [apply](asyncValidation/apply.md)
259+
* [bind](asyncValidation/bind.md)
243260
* [Computation Expression](asyncValidation/ce.md)
244261
* [error](asyncValidation/error.md)
245262
* [map](asyncValidation/map.md)
246263
* [map2](asyncValidation/map2.md)
247264
* [map3](asyncValidation/map3.md)
248265
* [mapError](asyncValidation/mapError.md)
249266
* [mapErrors](asyncValidation/mapErrors.md)
267+
* [ok](asyncValidation/ok.md)
250268
* [Operators](asyncValidation/operators.md)
269+
* [orElse Functions](asyncValidation/orElse.md)
251270
* [zip](asyncValidation/zip.md)
252271
* Transforms
253272
* [ofChoice](asyncValidation/ofChoice.md)
254273
* [ofResult](asyncValidation/ofResult.md)
255274

256275
* [TaskValidation](taskValidation/index.md)
257276
* [apply](taskValidation/apply.md)
277+
* [bind](taskValidation/bind.md)
258278
* [Computation Expression](taskValidation/ce.md)
259279
* [error](taskValidation/error.md)
260280
* [map](taskValidation/map.md)
261281
* [map2](taskValidation/map2.md)
262282
* [map3](taskValidation/map3.md)
263283
* [mapError](taskValidation/mapError.md)
264284
* [mapErrors](taskValidation/mapErrors.md)
285+
* [ok](taskValidation/ok.md)
265286
* [Operators](taskValidation/operators.md)
287+
* [orElse Functions](taskValidation/orElse.md)
266288
* [zip](taskValidation/zip.md)
267289
* Transforms
268290
* [ofChoice](taskValidation/ofChoice.md)
269291
* [ofResult](taskValidation/ofResult.md)
270292

271293
* FsToolkit.ErrorHandling.AsyncSeq
272294
* AsyncSeq
273-
* [Computation Expression](pr.md)
295+
* [Computation Expression](asyncSeq/ce.md)
274296

275297
* FsToolkit.ErrorHandling.IcedTasks
276298
* CancellableTaskOption
@@ -286,27 +308,30 @@
286308
* [apply](cancellableTaskResult/apply.md)
287309
* [bind](cancellableTaskResult/bind.md)
288310
* [Computation Expression](cancellableTaskResult/ce.md)
289-
* [getCancellationToken](pr.md)
311+
* [getCancellationToken](cancellableTaskResult/getCancellationToken.md)
290312
* [map](cancellableTaskResult/map.md)
291313
* [Operators](cancellableTaskResult/operators.md)
292314
* [Other Functions](cancellableTaskResult/others.md)
293-
* [zip](pr.md)
294-
* [parallelZip](pr.md)
315+
* [singleton](cancellableTaskResult/singleton.md)
316+
* [zip](cancellableTaskResult/zip.md)
317+
* [parallelZip](cancellableTaskResult/parallelZip.md)
295318

296319
* [CancellableTaskValidation](cancellableTaskValidation/index.md)
297320
* [apply](cancellableTaskValidation/apply.md)
298-
* [bind](pr.md)
321+
* [bind](cancellableTaskValidation/bind.md)
299322
* [Computation Expression](cancellableTaskValidation/ce.md)
300323
* [error](cancellableTaskValidation/error.md)
301-
* [getCancellationToken](pr.md)
302-
* [map](pr.md)
324+
* [getCancellationToken](cancellableTaskValidation/getCancellationToken.md)
325+
* [map](cancellableTaskValidation/map.md)
303326
* [map2](cancellableTaskValidation/map2.md)
304327
* [map3](cancellableTaskValidation/map3.md)
305-
* [mapError](pr.md)
306-
* [mapErrors](pr.md)
328+
* [mapError](cancellableTaskValidation/mapError.md)
329+
* [mapErrors](cancellableTaskValidation/mapErrors.md)
307330
* [Operators](cancellableTaskValidation/operators.md)
308-
* [zip](pr.md)
309-
* [parallelZip](pr.md)
331+
* [orElse Functions](cancellableTaskValidation/orElse.md)
332+
* [singleton](cancellableTaskValidation/singleton.md)
333+
* [zip](cancellableTaskValidation/zip.md)
334+
* [parallelZip](cancellableTaskValidation/parallelZip.md)
310335
* Transforms
311336
* [ofChoice](cancellableTaskValidation/ofChoice.md)
312337
* [ofResult](cancellableTaskValidation/ofResult.md)
@@ -329,41 +354,41 @@
329354

330355
* FsToolkit.ErrorHandling.JobResult
331356
* Job
332-
* [apply](pr.md)
333-
* [map2](pr.md)
334-
* [map3](pr.md)
335-
* [singleton](pr.md)
336-
* [zip](pr.md)
357+
* [apply](job/apply.md)
358+
* [map2](job/map2.md)
359+
* [map3](job/map3.md)
360+
* [singleton](job/singleton.md)
361+
* [zip](job/zip.md)
337362

338363
* JobOption
339-
* [apply](pr.md)
340-
* [bind](pr.md)
341-
* [ce](jobOption/ce.md)
342-
* [either](pr.md)
343-
* [map](pr.md)
364+
* [apply](jobOption/apply.md)
365+
* [bind](jobOption/bind.md)
366+
* [Computation Expression](jobOption/ce.md)
367+
* [either](jobOption/either.md)
368+
* [map](jobOption/map.md)
344369

345370
* JobResult
346371
* [apply](jobResult/apply.md)
347372
* [bind](jobResult/bind.md)
348-
* [catch](pr.md)
373+
* [catch](jobResult/catch.md)
349374
* [Computation Expression](jobResult/ce.md)
350375
* [error](jobResult/error.md)
351-
* [fromTask](pr.md)
352-
* [fromUnitTask](pr.md)
376+
* [fromTask](jobResult/fromTask.md)
377+
* [fromUnitTask](jobResult/fromUnitTask.md)
353378
* [ignore](jobResult/ignore.md)
354379
* [map](jobResult/map.md)
355380
* [map2](jobResult/map2.md)
356381
* [map3](jobResult/map3.md)
357382
* [mapError](jobResult/mapError.md)
358383
* [Operators](jobResult/operators.md)
359384
* [Other Functions](jobResult/others.md)
360-
* [zip](pr.md)
361-
* [zipError](pr.md)
385+
* [zip](jobResult/zip.md)
386+
* [zipError](jobResult/zipError.md)
362387
* Lists
363-
* [traverseJobResultM](pr.md)
364-
* [sequenceJobResultM](pr.md)
365-
* [traverseJobResultA](pr.md)
366-
* [sequenceJobResultA](pr.md)
388+
* [traverseJobResultM](list/traverseJobResultM.md)
389+
* [sequenceJobResultM](list/sequenceJobResultM.md)
390+
* [traverseJobResultA](list/traverseJobResultA.md)
391+
* [sequenceJobResultA](list/sequenceJobResultA.md)
367392
* Transforms
368393
* [ofAsync](jobResult/ofAsync.md)
369394
* [ofJob](jobResult/ofJob.md)
@@ -372,13 +397,13 @@
372397
* [fromUnitTask](jobResult/fromUnitTask.md)
373398

374399
* JobResultOption
375-
* [apply](pr.md)
376-
* [bind](pr.md)
377-
* [Computation Expression](pr.md)
378-
* [ignore](pr.md)
379-
* [map](pr.md)
380-
* [map2](pr.md)
381-
* [map3](pr.md)
400+
* [apply](jobResultOption/apply.md)
401+
* [bind](jobResultOption/bind.md)
402+
* [Computation Expression](jobResultOption/ce.md)
403+
* [ignore](jobResultOption/ignore.md)
404+
* [map](jobResultOption/map.md)
405+
* [map2](jobResultOption/map2.md)
406+
* [map3](jobResultOption/map3.md)
382407

383408
* General Docs
384409
* [Bind Mappings](bindMappings.md)

‎gitbook/asyncResult/catch.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
## AsyncResult.catch
2+
3+
Namespace: `FsToolkit.ErrorHandling`
4+
5+
Catches exceptions thrown by an async computation and maps them to the `Error` case using the provided function. If the async computation completes successfully with an `Ok` or `Error` value, that value is returned unchanged.
6+
7+
## Function Signature:
8+
9+
```fsharp
10+
(exn -> 'error) -> Async<Result<'ok, 'error>> -> Async<Result<'ok, 'error>>
11+
```
12+
13+
## Examples
14+
15+
### Example 1
16+
17+
Catching any exception and converting it to a string error:
18+
19+
```fsharp
20+
let result : Async<Result<int, string>> =
21+
async { return failwith "something went wrong" }
22+
|> Async.map Ok
23+
|> AsyncResult.catch (fun ex -> ex.Message)
24+
// evaluates to Error "something went wrong"
25+
```
26+
27+
### Example 2
28+
29+
Wrapping a potentially throwing async call in an `AsyncResult`:
30+
31+
```fsharp
32+
let safeFetch (url: string) : Async<Result<string, string>> =
33+
async {
34+
use client = new System.Net.Http.HttpClient()
35+
return! client.GetStringAsync(url) |> Async.AwaitTask |> Async.map Ok
36+
}
37+
|> AsyncResult.catch (fun ex -> sprintf "HTTP error: %s" ex.Message)
38+
```
39+
40+
### Example 3
41+
42+
When no exception is thrown, the result passes through unchanged:
43+
44+
```fsharp
45+
AsyncResult.ok 42
46+
|> AsyncResult.catch (fun _ -> "error")
47+
// evaluates to Ok 42
48+
```

‎gitbook/asyncResult/eitherMap.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
## AsyncResult.eitherMap
2+
3+
Namespace: `FsToolkit.ErrorHandling`
4+
5+
Applies one of two mapping functions to an `Async<Result<'okInput, 'errorInput>>`: the first function is applied if the result is `Ok`, and the second is applied if the result is `Error`.
6+
7+
## Function Signature:
8+
9+
```fsharp
10+
('okInput -> 'okOutput)
11+
-> ('errorInput -> 'errorOutput)
12+
-> Async<Result<'okInput, 'errorInput>>
13+
-> Async<Result<'okOutput, 'errorOutput>>
14+
```
15+
16+
## Examples
17+
18+
### Example 1
19+
20+
Transforming both the Ok and Error branches of an async result:
21+
22+
```fsharp
23+
let result : Async<Result<string, int>> =
24+
AsyncResult.ok 42
25+
|> AsyncResult.eitherMap
26+
(fun n -> sprintf "Got %d" n)
27+
(fun err -> -1)
28+
// evaluates to Ok "Got 42"
29+
```
30+
31+
### Example 2
32+
33+
Mapping an Error value while the Ok path is unchanged in type:
34+
35+
```fsharp
36+
let result : Async<Result<string, string>> =
37+
AsyncResult.error 404
38+
|> AsyncResult.eitherMap
39+
(fun s -> s.ToUpper())
40+
(fun code -> sprintf "Error code: %d" code)
41+
// evaluates to Error "Error code: 404"
42+
```
43+
44+
### Example 3
45+
46+
Normalising both branches to the same type before consuming:
47+
48+
```fsharp
49+
let displayMessage : Async<string> =
50+
fetchData ()
51+
|> AsyncResult.eitherMap
52+
(fun data -> sprintf "Success: %s" data)
53+
(fun err -> sprintf "Failed: %s" err)
54+
|> AsyncResult.foldResult id id
55+
```

0 commit comments

Comments
 (0)