61 lines
2.6 KiB
Markdown
61 lines
2.6 KiB
Markdown
---
|
|
name: native-monad-query
|
|
description: "Query<T,E> API reference. ALWAYS invoke when using OkSome, OkNone, ErrNone, Query, QueryPromise, Query.from, Query.all, Query.partition, query.match(3 args), query.filter(NO errorFactory). Do not guess Query methods — consult this skill."
|
|
---
|
|
|
|
# Query<T, E> Usage Guide
|
|
|
|
## Quick Reference
|
|
|
|
Query is a three-state monad: success-with-value (`OkSome`), success-without-value (`OkNone`), error (`ErrNone`).
|
|
|
|
| Method | OkSome | OkNone | ErrNone |
|
|
|--------|--------|--------|---------|
|
|
| `isSome()` | `this is OkSome<T>` | `this is never` | `this is never` |
|
|
| `isNone()` | `this is never` | `this is OkNone` | `this is never` |
|
|
| `isErr()` | `this is never` | `this is never` | `this is ErrNone<E>` |
|
|
| `map(fn)` | `(fn: (v: T) => U) => OkSome<U>` | `() => OkNone` | `() => ErrNone<E>` |
|
|
| `mapErr(fn)` | `() => OkSome<T>` | `() => OkNone` | `(fn: (e: E) => F) => ErrNone<F>` |
|
|
| `flatMap(fn)` | `(fn: (v: T) => R) => R` | `() => this` | `() => this` |
|
|
| `flatMapErr(fn)` | `() => this` | `() => this` | `(fn: (e: E) => R) => R` |
|
|
| `match(a, b, c)` | 3 callbacks | 3 callbacks | 3 callbacks |
|
|
| `filter(pred)` | NO errorFactory | `() => OkNone` | `() => ErrNone<E>` |
|
|
| `toNullable()` | `T` | `null` | `null` |
|
|
| `toUndefined()` | `T` | `undefined` | `undefined` |
|
|
|
|
## Critical Rules
|
|
|
|
1. `match()` takes exactly **3 callbacks**: `(onSome, onNone, onErr)` — NOT 2.
|
|
2. `filter()` takes ONLY a predicate — NO `errorFactory` (unlike Result). Failed filter returns `OkNone`, not `ErrNone`.
|
|
3. `flatMap` constraint: `R extends Query<any, any>` — callback must return a Query.
|
|
4. `flatMapErr` constraint: `R extends Query<any, any>` — callback must return a Query.
|
|
5. Type guards: `isSome()` → `.value`, `isErr()` → `.err`. `OkNone` has neither.
|
|
6. `OkSome` stores `.value`. `ErrNone` stores `.err`. `OkNone` has no data properties.
|
|
7. `okNone()` returns a frozen singleton.
|
|
|
|
## Anti-Patterns
|
|
|
|
```typescript
|
|
// WRONG — match with 2 callbacks (that's Result/Option, not Query)
|
|
query.match(onSome, onErr);
|
|
|
|
// CORRECT — Query.match always takes 3
|
|
query.match(
|
|
(value) => handleValue(value),
|
|
() => handleEmpty(),
|
|
(error) => handleError(error),
|
|
);
|
|
```
|
|
|
|
```typescript
|
|
// WRONG — filter with errorFactory (that's Result, not Query)
|
|
query.filter((v) => v > 0, () => new Error("bad"));
|
|
|
|
// CORRECT — Query.filter only takes predicate, returns OkNone on failure
|
|
query.filter((v) => v > 0);
|
|
```
|
|
|
|
## Namespace & Async Methods
|
|
|
|
Read `references/api-surface.md` for the complete Query namespace (`.from`, `.all`, `.partition`, `.compact`, `.some`, `.every`) and QueryPromise namespace.
|