# tiny-pattern-ts

Pattern matching for TypeScript/ESM environments (F#-style, not regex).

## Description

`tiny-pattern-ts` brings F#-style pattern matching to TypeScript. Patterns are
ordinary objects whose `matches` method is a TypeScript type guard, so narrowing
composes the way any other guard does. It is deliberately not a regex engine and
not a macro: there is no transpiler and no DSL to learn, and the type-level
contract is the feature — see [development/library.md](./development/library.md)
for the design decisions and [Caveats](#caveats) for the limits.

## 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).

## API

Yet to be implemented

## Caveats

- **Only finite universes are supported.** The factory must be given a finite
  union of literals; `string`, `number` and template literals are rejected. This
  is what lets the exhaustive overload be proven, so the runtime `dispatch`
  throw stays unreachable through the typed API.
- **A value and its stringification must not both be present.** Object keys
  stringify, so a universe containing both a member and the string it
  stringifies to — `1 | "1"`, `true | "true"`, `null | "null"` — is rejected at
  the factory. Either form alone is fine, and one value's string form may
  coexist with a _different_ value's bare form (`"true" | false`).
- **`symbol` and `bigint` are not supported.** A `symbol` brand is a
  compile-time phantom with nothing to match at runtime, and a `bigint` is not a
  valid property key; neither satisfies the matcher's universe constraint.
- **`NaN` and `-0` cannot be matched specifically.** They have no literal type,
  so both stay part of `number`.

## License

MIT © 2025 tmu. See [LICENSE](./LICENSE).

## Contributing

Contributions are documented in [CONTRIBUTING.md](./CONTRIBUTING.md); the
reasons behind the project's decisions, rejected alternatives, and known issues
live in [development/](./development/README.md). AI coding agents start at
[AGENTS.md](./AGENTS.md).