📝 Bind the handler-map function in every example

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

@@ -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,
 });

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",
  *     });

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,
  *     });