From c878e60ff24dff7b6a9b948ba72acfc515311b45 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Thomas=20M=C3=BCller?= <thomas.mi.iller.gitea.tmu@gmail.com>
Date: Wed, 23 Sep 2026 22:33:43 +0000
Subject: [PATCH] :memo: Bind the handler-map function in every example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Each README and JSDoc example now assigns the function that takes the
handler object (the factory result, or the tagged key step) to a match…
variable and reuses it, so the builder is created once instead of per
call.
---
 README.md              | 15 ++++++++++++---
 src/primitive-union.ts |  6 ++++--
 src/tagged-union.ts    |  6 ++++--
 3 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index a7abf31..6042d20 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,9 @@ The package exports four factories. Two axes pick one:
 | `getTaggedUnionMatcher<T>()`     | the value is a discriminated object and all handlers return the same type | one common `R`        |
 | `getTaggedUnionMatcherW<T>()`    | the value is a discriminated object and handlers return different types   | union of the handlers |
 
+Bind the function that takes the handler map to a `match…` variable once and
+reuse it; the examples below do this, so the builder is allocated once.
+
 ### Primitive-union matchers
 
 `getPrimitiveUnionMatcher<T>()` takes the finite universe `T` and returns a
@@ -46,7 +49,9 @@ matcher: a function from `T` to the common return type.
 ```ts
 import { getPrimitiveUnionMatcher } from "tiny-pattern-ts";
 
-const reply = getPrimitiveUnionMatcher<"yes" | "no">()({
+const matchAnswer = getPrimitiveUnionMatcher<"yes" | "no">();
+
+const reply = matchAnswer({
     yes: () => "agreed",
     no: () => "declined",
 });
@@ -58,7 +63,9 @@ Add a fallback as the second argument to leave members unhandled; the fallback
 receives the remainder:
 
 ```ts
-const label = getPrimitiveUnionMatcher<"yes" | "no" | "maybe">()(
+const matchLabel = getPrimitiveUnionMatcher<"yes" | "no" | "maybe">();
+
+const label = matchLabel(
     { yes: () => "agreed", no: () => "declined" },
     (other) => `not sure: ${other}`, // other: "maybe"
 );
@@ -79,7 +86,9 @@ import { getTaggedUnionMatcher } from "tiny-pattern-ts";
 type Shape =
     { kind: "circle"; radius: number } | { kind: "square"; side: number };
 
-const area = getTaggedUnionMatcher<Shape>()("kind")({
+const matchShape = getTaggedUnionMatcher<Shape>()("kind");
+
+const area = matchShape({
     circle: (s) => Math.PI * s.radius ** 2,
     square: (s) => s.side ** 2,
 });
diff --git a/src/primitive-union.ts b/src/primitive-union.ts
index 622c0d9..3d988d1 100644
--- a/src/primitive-union.ts
+++ b/src/primitive-union.ts
@@ -111,7 +111,8 @@ const dispatch =
  * @typeParam T - The finite universe of primitive members to match.
  * @returns A builder for the handler map, or the handler map plus a fallback.
  * @example
- *     const describe = getPrimitiveUnionMatcher<"yes" | "no">()({
+ *     const matchAnswer = getPrimitiveUnionMatcher<"yes" | "no">();
+ *     const describe = matchAnswer({
  *         yes: () => "agreed",
  *         no: () => "declined",
  *     });
@@ -133,7 +134,8 @@ export const getPrimitiveUnionMatcher = <
  * @typeParam T - The finite universe of primitive members to match.
  * @returns A builder for the handler map, or the handler map plus a fallback.
  * @example
- *     const reply = getPrimitiveUnionMatcherW<"yes" | "no">()({
+ *     const matchReply = getPrimitiveUnionMatcherW<"yes" | "no">();
+ *     const reply = matchReply({
  *         yes: () => 1,
  *         no: () => "declined",
  *     });
diff --git a/src/tagged-union.ts b/src/tagged-union.ts
index 7a18a29..d3a2acd 100644
--- a/src/tagged-union.ts
+++ b/src/tagged-union.ts
@@ -173,7 +173,8 @@ const dispatch =
  *         | { kind: "circle"; radius: number }
  *         | { kind: "square"; side: number };
  *
- *     const area = getTaggedUnionMatcher<Shape>()("kind")({
+ *     const matchShape = getTaggedUnionMatcher<Shape>()("kind");
+ *     const area = matchShape({
  *         circle: (s) => Math.PI * s.radius ** 2,
  *         square: (s) => s.side ** 2,
  *     });
@@ -194,7 +195,8 @@ export const getTaggedUnionMatcher = <
  * @typeParam T - The discriminated-union type to match.
  * @returns A function that takes the discriminant property's name.
  * @example
- *     const describe = getTaggedUnionMatcherW<Shape>()("kind")({
+ *     const matchShape = getTaggedUnionMatcherW<Shape>()("kind");
+ *     const describe = matchShape({
  *         circle: () => "round",
  *         square: () => 4,
  *     });