📝 Improve docs after split
This commit is contained in:
tmu committed
1 parent
74c39e1346
commit
5e7d40b013
6 files changed
+17
-228
No files matched your search
@@ -4,10 +4,6 @@ Pattern matching for TypeScript/ESM environments (F#-style, not regex).
|
||||
|
||||
## Synopsis
|
||||
|
||||
```sh
|
||||
npm install tiny-pattern-ts
|
||||
```
|
||||
|
||||
```ts
|
||||
import { match, P } from "tiny-pattern-ts";
|
||||
|
||||
@@ -20,14 +16,6 @@ const reply = (answer: "yes" | "no") =>
|
||||
reply("yes"); // "agreed"
|
||||
```
|
||||
|
||||
### Requirements
|
||||
|
||||
- **Node.js >= 26** (`engines` field; pinned via `.node-version`).
|
||||
- **TypeScript >= 5.0** to consume the published declarations. The emitted `.d.ts`
|
||||
use `const` type parameters (TS 5.0) and keep their relative `.ts` specifiers;
|
||||
both resolve on TS >= 5.0 in `node10` / `node16` / `nodenext` / `bundler`.
|
||||
- The package is **ESM-only** (no CommonJS shim).
|
||||
|
||||
## Description
|
||||
|
||||
`tiny-pattern-ts` gives TypeScript the shape of F#-style pattern matching:
|
||||
@@ -43,6 +31,14 @@ The type-level contract is the feature — see
|
||||
[development/library.md](./development/library.md) for the design decisions and
|
||||
the known limitations.
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Node.js >= 26** (`engines` field; pinned via `.node-version`).
|
||||
- **TypeScript >= 5.0** to consume the published declarations. The emitted `.d.ts`
|
||||
use `const` type parameters (TS 5.0) and keep their relative `.ts` specifiers;
|
||||
both resolve on TS >= 5.0 in `node10` / `node16` / `nodenext` / `bundler`.
|
||||
- The package is **ESM-only** (no CommonJS shim).
|
||||
|
||||
## Examples
|
||||
|
||||
### Literal matching and `exhaustive()`
|
||||
@@ -163,108 +159,7 @@ const firstNumber = (items: readonly unknown[]): number | undefined =>
|
||||
|
||||
## API
|
||||
|
||||
### `match(value)`
|
||||
|
||||
```ts
|
||||
const match: <T>(value: T) => MatchBuilder<T, never>;
|
||||
```
|
||||
|
||||
Starts a matching chain for `value`. The builder is immutable: every `.with`
|
||||
returns a new builder, so a partially built chain can be reused.
|
||||
|
||||
#### `.with(pattern, handler)`
|
||||
|
||||
```ts
|
||||
with<U extends T, V>(pattern: Matcher<U>, handler: (value: U) => V): MatchBuilder<T, R | V>;
|
||||
```
|
||||
|
||||
Adds a case. `handler` receives the value narrowed to `U`, and its return type
|
||||
`V` is added to the builder's result union `R`. A pattern whose narrowed type is
|
||||
not assignable to the matched value's type is a compile error.
|
||||
|
||||
#### `.exhaustive()`
|
||||
|
||||
```ts
|
||||
exhaustive(): R;
|
||||
```
|
||||
|
||||
Returns the result of the first matching case. Throws
|
||||
`tiny-pattern-ts: match.exhaustive() called with no matching case` if none
|
||||
matched. It does not statically prove that every union member is covered.
|
||||
|
||||
#### `.otherwise(handler)`
|
||||
|
||||
```ts
|
||||
otherwise(handler: (value: T) => R): R;
|
||||
```
|
||||
|
||||
Like a final catch-all case: runs `handler` if no earlier case matched. Unlike
|
||||
`.exhaustive()`, it never throws.
|
||||
|
||||
### `P.literal(value)`
|
||||
|
||||
```ts
|
||||
const P.literal: <const L extends string | number | boolean | null | undefined>(
|
||||
value: L,
|
||||
) => Matcher<L>;
|
||||
```
|
||||
|
||||
Matches a single literal with `===` and narrows to its literal type.
|
||||
|
||||
### `P.type(type)`
|
||||
|
||||
```ts
|
||||
const P.type: <T>(
|
||||
type: "string" | "number" | "boolean" | "bigint" | "symbol" | "undefined" | "object" | "function",
|
||||
) => Matcher<T>;
|
||||
```
|
||||
|
||||
Matches a `typeof` result and narrows to the explicitly supplied `T`. `T` is not
|
||||
inferred from the name, so the type parameter and the runtime name must agree.
|
||||
|
||||
### `P.when(predicate)`
|
||||
|
||||
```ts
|
||||
const P.when: <T>(predicate: (value: unknown) => value is T) => Matcher<T>;
|
||||
```
|
||||
|
||||
Wraps a type guard as a matcher. This is the constructor to prefer when you can
|
||||
express the check as a guard.
|
||||
|
||||
### `P.any(predicate)`
|
||||
|
||||
```ts
|
||||
const P.any: <T>(predicate: (value: unknown) => boolean) => Matcher<T>;
|
||||
```
|
||||
|
||||
Wraps a boolean predicate and declares the narrowed type `T` yourself. Use it
|
||||
only when a type guard is not expressible; prefer `P.when`.
|
||||
|
||||
### `P.shape(shape, refine?)`
|
||||
|
||||
```ts
|
||||
const P.shape: <S extends object, T extends S>(
|
||||
shape: S,
|
||||
refine?: (value: S) => value is T,
|
||||
) => Matcher<T>;
|
||||
```
|
||||
|
||||
Matches an object that has every key of `shape`. A shape value that is a
|
||||
`Matcher` is applied; otherwise the value is compared with `===`. Pass `refine`
|
||||
to narrow to `T`; without it, the matched type is `S`.
|
||||
|
||||
### Types
|
||||
|
||||
```ts
|
||||
interface Matcher<T> {
|
||||
readonly matches: (value: unknown) => value is T;
|
||||
}
|
||||
|
||||
type Pattern<T> = Matcher<T>;
|
||||
```
|
||||
|
||||
Every pattern constructor returns a `Matcher<T>`. `Pattern<T>` is an alias kept
|
||||
for readability.
|
||||
Yet to be implemented
|
||||
|
||||
## License
|
||||
|
||||
|
||||
Reference in new issue
Block a user