146 lines
3.6 KiB
Markdown
146 lines
3.6 KiB
Markdown
# Result[T] API Reference
|
|
|
|
## Constructors
|
|
|
|
| Function | Description |
|
|
| --- | --- |
|
|
| `mo.Ok[T](value T)` | Creates a successful Result |
|
|
| `mo.Err[T](err error)` | Creates a failed Result |
|
|
| `mo.Errf[T](format string, a ...any)` | Creates failed Result with formatted error message |
|
|
| `mo.TupleToResult[T](value T, err error)` | Converts Go's (T, error) tuple — Ok if err is nil, Err otherwise |
|
|
| `mo.Try[T](f func() (T, error))` | Executes function, wraps result — Ok on success, Err on error |
|
|
|
|
### Do Notation
|
|
|
|
```go
|
|
result := mo.Do(func() int {
|
|
a := mo.Ok(10).MustGet() // panics if Err -> caught by Do
|
|
b := mo.Ok(32).MustGet()
|
|
return a + b
|
|
})
|
|
// Ok(42)
|
|
```
|
|
|
|
`mo.Do` executes a closure and catches any panic from `MustGet()` calls, converting them to `Err`. This enables imperative-style code with monadic error propagation.
|
|
|
|
## Query Methods
|
|
|
|
| Method | Returns | Description |
|
|
| --- | --- | --- |
|
|
| `IsOk()` | `bool` | True if Result is successful |
|
|
| `IsError()` | `bool` | True if Result is a failure |
|
|
| `Error()` | `error` | Returns the error, or nil if Ok |
|
|
| `Get()` | `(T, error)` | Returns value and error (Go-style) |
|
|
| `MustGet()` | `T` | Returns value or panics — use only inside `mo.Do` |
|
|
|
|
## Value Extraction
|
|
|
|
| Method | Returns | Description |
|
|
| -------------------- | ------- | ------------------------------ |
|
|
| `OrElse(fallback T)` | `T` | Value if Ok, fallback if Err |
|
|
| `OrEmpty()` | `T` | Value if Ok, zero value if Err |
|
|
|
|
## Transformations
|
|
|
|
### Map — transform successful value
|
|
|
|
```go
|
|
result := mo.Ok(42).
|
|
Map(func(v int) (int, error) {
|
|
return v * 2, nil
|
|
})
|
|
// Ok(84)
|
|
|
|
// Errors short-circuit
|
|
result := mo.Err[int](errors.New("fail")).
|
|
Map(func(v int) (int, error) {
|
|
return v * 2, nil // never called
|
|
})
|
|
// Err("fail")
|
|
```
|
|
|
|
**Go limitation:** Result.Map takes `func(T) (T, error)` — the input and output types must be the same `T`. Returning a non-nil error converts Ok to Err. To change the type (e.g. `Result[[]byte]` to `Result[Config]`), use sub-package `result.Map` or `mo.Do` notation — see [Pipelines Reference](./pipelines.md).
|
|
|
|
### MapValue — transform without error possibility
|
|
|
|
```go
|
|
result := mo.Ok(42).MapValue(func(v int) int {
|
|
return v * 2
|
|
})
|
|
// Ok(84) — no error possible in the mapper
|
|
```
|
|
|
|
### MapErr — transform error state
|
|
|
|
```go
|
|
result := mo.Err[int](errors.New("fail")).
|
|
MapErr(func(err error) (int, error) {
|
|
return 0, fmt.Errorf("wrapped: %w", err)
|
|
})
|
|
// Err("wrapped: fail")
|
|
```
|
|
|
|
### FlatMap — chain Results
|
|
|
|
```go
|
|
func parseAge(s string) mo.Result[int] {
|
|
v, err := strconv.Atoi(s)
|
|
return mo.TupleToResult(v, err)
|
|
}
|
|
|
|
func validateAge(age int) mo.Result[int] {
|
|
if age < 0 || age > 150 {
|
|
return mo.Errf[int]("invalid age: %d", age)
|
|
}
|
|
return mo.Ok(age)
|
|
}
|
|
|
|
result := parseAge("25").FlatMap(func(age int) mo.Result[int] {
|
|
return validateAge(age)
|
|
})
|
|
// Ok(25)
|
|
```
|
|
|
|
### Match — handle both cases
|
|
|
|
```go
|
|
result.Match(
|
|
func(v int) (int, error) {
|
|
fmt.Println("Success:", v)
|
|
return v, nil
|
|
},
|
|
func(err error) (int, error) {
|
|
fmt.Println("Error:", err)
|
|
return 0, err
|
|
},
|
|
)
|
|
```
|
|
|
|
### ForEach — side effect on success
|
|
|
|
```go
|
|
result.ForEach(func(v int) {
|
|
fmt.Println("Got:", v) // only executes if Ok
|
|
})
|
|
```
|
|
|
|
## Conversion
|
|
|
|
```go
|
|
either := result.ToEither() // Either[error, T]
|
|
// Ok(42) -> Right(42)
|
|
// Err(e) -> Left(e)
|
|
```
|
|
|
|
## JSON Serialization
|
|
|
|
Result marshals to JSON-RPC format:
|
|
|
|
```go
|
|
// Ok(42) marshals to:
|
|
{"result": 42}
|
|
|
|
// Err("fail") marshals to:
|
|
{"error": {"message": "fail"}}
|
|
```
|