🚀 Release 0.8.2

Add a short README section under Alternatives, one heading per
alternative (ts-pattern, Effect.Match, match-iz and plain switch), each
saying what it is and what tiny-pattern-ts is or does differently. State
the data-last, pipe-friendly shape in Description.

- measure the footprint: ~0.2 kB minified + gzipped, not the
  unminified ~1.8 kB; ts-pattern is ~2 kB
- correct match-iz: it ships types, it just cannot prove exhaustiveness
- drop switchcase / ts-match (unmaintained)
- check off the backlog task

Resolves: backlog "Add comparison section vs. other TS pattern-matching libs"

CHANGELOG.md

@@ -7,13 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-- restore the README's Synopsis and Examples sections: a quick-start recipe plus
+## [0.8.2] - 2026-09-25
-  real-world examples (primitive-union dispatch, a fallback, a property union
+
-  narrowed by the tagged-union matcher, and a widening variant)
+- write the README's Synopsis and Examples sections
-- document the public API in the README: the four factories, when to use each,
+- document the public API in the README
-  what the `W` (widening) suffix means, and examples that bind the handler-map
-  function once
 - add TSDoc to the four public matcher factories
+- document alternatives
 
 ## [0.8.1] - 2026-09-23
 
@@ -109,7 +108,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - basic setup
 
-[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.1...main
+[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.2...main
+[0.8.2]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.1...0.8.2
 [0.8.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.0...0.8.1
 [0.8.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.7.1...0.8.0
 [0.7.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.7.0...0.7.1

README.md

@@ -38,7 +38,9 @@ assert.equal(phoneOutput, "PHONE: +1 555 0100");
 The main goal of `tiny-pattern-ts` is to make pattern matching type-safe with a
 lean syntax. This is accomplished by being exhaustive and passing typed
 parameters per branch to the handlers — supported by an outstanding
-autocomplete and a tiny footprint.
+autocomplete and a tiny footprint. The matchers are data last and pipe-friendly:
+build the handler map once, then apply the resulting matcher to values
+(`match(value)`, or `pipe(value, match)`).
 
 See [development/library.md](./development/library.md) for the design decisions
 and [Caveats](#caveats) for the limits.
@@ -284,6 +286,43 @@ provable exhaustiveness — to automate what a `switch` and a default arm alread
 cover. The type-level cost of supporting open universes is recorded in
 [development/library.md](./development/library.md#supported-universes).
 
+## Alternatives
+
+### [`ts-pattern`](https://github.com/gvergnaud/ts-pattern)
+
+- is the full structural matcher — nested and partial patterns, guards, unions,
+  captures — exhausting at `.exhaustive()`
+- has a fluent `.with(…)` chain that is heavy on syntax; tiny-pattern-ts is one
+  handler map
+- is about 2 kB minified and gzipped; tiny-pattern-ts is 0.2 kB
+- reach for it when you need a feature tiny-pattern-ts does not cover
+
+### [Effect's `Match`](https://effect.website/docs/code-style/pattern-matching/)
+
+- is the same piped matcher (`Match.type` / `Match.when` / `Match.exhaustive`),
+  but only as part of the `effect` ecosystem
+- tiny-pattern-ts is standalone: no runtime dependency to buy into
+
+### [`match-iz`](https://github.com/shuckster/match-iz)
+
+- expresses patterns in the TC39 proposal's style, deciding each case at runtime
+- is written in JavaScript with hand-maintained declarations, so its types do
+  not prove the cases exhaustive
+- tiny-pattern-ts does: exhaustiveness is a compile-time guarantee, not an
+  `otherwise` fallback
+
+### plain `switch` (baseline)
+
+- is the zero-dependency baseline — pair it with
+  [`eslint-plugin-strict-pattern-matching`](https://www.npmjs.com/package/eslint-plugin-strict-pattern-matching)
+  for exhaustiveness
+- is a statement, not an expression, so it cannot produce a value directly
+- leaves the `never` guard to you; tiny-pattern-ts is an expression and does not
+  need one
+
+The [TC39 pattern-matching proposal](https://github.com/tc39/proposal-pattern-matching)
+is still stage 1, so userland libraries remain the only option today.
+
 ## License
 
 MIT © 2026 tmu. See [LICENSE](./LICENSE).

backlog.tasks

@@ -27,9 +27,9 @@ Documentation:
     → previous section order: title, tagline, Synopsis, Description, Requirements, Examples, API, License, Contributing
     → previous Examples order: literal/exhaustive, typeof, structural/discriminated unions, when, any
 ☐ Create `examples/` directory with runnable snippets
-☐ Add comparison section vs. other TS pattern-matching libs in Readme.md
+✔ Add comparison section vs. other TS pattern-matching libs in Readme.md @done
-    ☐ Why do we do this? => exhaustiveness encoded type safe
+    ✔ Why do we do this? => exhaustiveness encoded type safe @done
-    ☐ Why this form? little syntax, data last, very small, autocomplete, strict typing in the handler; for more features use ts-pattern
+    ✔ Why this form? little syntax, data last, very small, autocomplete, strict typing in the handler; for more features use ts-pattern @done
 ✔ Write migration guide for users coming from discriminated unions @done (9/24/2026, 10:21:17 PM)
 ✔ Create backlog tasks for implementation @done (9/24/2026, 10:21:16 PM)
 ✔ Validate code fences in Markdown (start with README.md) — compile the TypeScript examples against `src/` so the docs cannot drift from the API @done

cspell.json

@@ -45,7 +45,8 @@
         "todotasks",
         "connor",
         "injective",
-        "injectivity"
+        "injectivity",
+        "userland"
     ],
     "ignorePaths": ["dist", "node_modules", "coverage", "*.svg", ".gitignore"]
 }

package-lock.json

@@ -1,12 +1,12 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.8.1",
+    "version": "0.8.2",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "tiny-pattern-ts",
-            "version": "0.8.1",
+            "version": "0.8.2",
             "license": "MIT",
             "dependencies": {
                 "type-fest": "^5.9.0"

package.json

@@ -1,6 +1,6 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.8.1",
+    "version": "0.8.2",
     "description": "Exhaustive, type-safe pattern matching for TypeScript",
     "keywords": [
         "adt",