♻️ Label arrange-act-assert blocks in specs

Rework every test body into // Arrange / // Act / // Assert blocks
separated by blank lines: the factory is arranged once, the matcher is
built from it in a single act, and all type/runtime checks sink to the
end. index.test.ts adopts the same shape.

Also migrate off expect-type's deprecated toMatchTypeOf: the checks
are assignability tests, so toExtend is the faithful replacement.

src/index.test.ts

@@ -7,44 +7,59 @@ import { expectTypeOf } from "expect-type";
 import { type Matcher, P, match } from "./index.ts";
 
 test("match returns a builder", () => {
+    // Act
     const builder = match("x");
+
+    // Assert
     expectTypeOf(builder).toHaveProperty("with");
     expectTypeOf(builder).toHaveProperty("exhaustive");
     expectTypeOf(builder).toHaveProperty("otherwise");
 });
 
 test("P.literal narrows to its literal type", () => {
+    // Act
     const matcher = P.literal("yes");
-    expectTypeOf(matcher).toMatchTypeOf<Matcher<"yes">>();
+
+    // Assert
+    expectTypeOf(matcher).toExtend<Matcher<"yes">>();
     assert.equal(matcher.matches("yes"), true);
     assert.equal(matcher.matches("no"), false);
 });
 
 test("P.type narrows to the typeof target", () => {
+    // Act
     const matcher = P.type<string>("string");
-    expectTypeOf(matcher).toMatchTypeOf<Matcher<string>>();
+
+    // Assert
+    expectTypeOf(matcher).toExtend<Matcher<string>>();
     assert.equal(matcher.matches("hi"), true);
     assert.equal(matcher.matches(42), false);
 });
 
 test("exhaustive() returns the union of handler return types", () => {
+    // Act
     const result = match<"a" | "b">("a")
         .with(P.literal("a"), () => 1 as const)
         .with(P.literal("b"), () => "two" as const)
         .exhaustive();
 
+    // Assert
     expectTypeOf(result).toEqualTypeOf<1 | "two">();
     assert.equal(result, 1);
 });
 
 test("otherwise() falls back when no case matches", () => {
+    // Act
     const result = match<"x" | "y" | "z">("z")
         .with(P.literal("x"), (v): string => `got ${v}`)
         .otherwise((v): string => `fallback ${v}`);
+
+    // Assert
     assert.equal(result, "fallback z");
 });
 
 test("exhaustive throws when no case matches", () => {
+    // Assert
     assert.throws(
         () =>
             match<"a" | "b" | "c">("c")

src/primitive.test.ts

@@ -16,26 +16,37 @@ import {
 // ============================================================================
 
 test("getPrimitiveUnionMatcherW requires every literal key", () => {
-    const matcher = getPrimitiveUnionMatcherW<"a" | "b">()({
+    // Arrange
+    const factory = getPrimitiveUnionMatcherW<"a" | "b">();
+
+    // Act
+    const matcher = factory({
         a: () => 1 as const,
         b: () => "two" as const,
     });
+
+    // Assert
     // ❌ ReturnsStrict: mixed handler returns widen to their union.
     expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => 1 | "two">();
     // A pattern missing a key must not satisfy the parameter type.
-    const factory = getPrimitiveUnionMatcherW<"a" | "b">();
     expectTypeOf<{
         a: () => number;
-    }>().not.toMatchTypeOf<Parameters<typeof factory>[0]>();
+    }>().not.toExtend<Parameters<typeof factory>[0]>();
     assert.equal(matcher("a"), 1);
     assert.equal(matcher("b"), "two");
 });
 
 test("getPrimitiveUnionMatcherW dispatches on numeric literal keys", () => {
-    const matcher = getPrimitiveUnionMatcherW<1 | 2>()({
+    // Arrange
+    const factory = getPrimitiveUnionMatcherW<1 | 2>();
+
+    // Act
+    const matcher = factory({
         1: (n) => n + 1,
         2: (n) => n * 10,
     });
+
+    // Assert
     expectTypeOf(matcher).toEqualTypeOf<(shape: 1 | 2) => number>();
     assert.equal(matcher(1), 2);
     assert.equal(matcher(2), 20);
@@ -46,10 +57,16 @@ test("getPrimitiveUnionMatcherW dispatches on numeric literal keys", () => {
 // ============================================================================
 
 test("getPrimitiveUnionMatcher infers a single return type shared by all handlers", () => {
-    const matcher = getPrimitiveUnionMatcher<"a" | "b">()({
+    // Arrange
+    const factory = getPrimitiveUnionMatcher<"a" | "b">();
+
+    // Act
+    const matcher = factory({
         a: (): number => 1,
         b: (): 1 | 2 => 2,
     });
+
+    // Assert
     // ✔️ ReturnsStrict: R is the best common return type, not a widening union.
     expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => number>();
     assert.equal(matcher("a"), 1);
@@ -57,7 +74,11 @@ test("getPrimitiveUnionMatcher infers a single return type shared by all handler
 });
 
 test("getPrimitiveUnionMatcher handlers receive the matched literal", () => {
-    const matcher = getPrimitiveUnionMatcher<"on" | "off">()({
+    // Arrange
+    const factory = getPrimitiveUnionMatcher<"on" | "off">();
+
+    // Act
+    const matcher = factory({
         on: (s) => {
             expectTypeOf(s).toEqualTypeOf<"on">();
             return `handler ${s}`;
@@ -67,6 +88,8 @@ test("getPrimitiveUnionMatcher handlers receive the matched literal", () => {
             return `handler ${s}`;
         },
     });
+
+    // Assert
     expectTypeOf(matcher).toEqualTypeOf<(shape: "on" | "off") => string>();
     assert.equal(matcher("on"), "handler on");
     assert.equal(matcher("off"), "handler off");
@@ -77,7 +100,13 @@ test("getPrimitiveUnionMatcher handlers receive the matched literal", () => {
 // ============================================================================
 
 test("getPrimitiveUnionMatcherPartial routes shapes without a handler to _", () => {
-    const matcher = getPrimitiveUnionMatcherPartial<"a" | "b" | "c">()({
+    // Arrange
+    const factory = getPrimitiveUnionMatcherPartial<"a" | "b" | "c">();
+    // Two keys, so `{ a }` lacks only the `_` fallback, nothing else.
+    const sparseFactory = getPrimitiveUnionMatcherPartial<"a" | "b">();
+
+    // Act
+    const matcher = factory({
         a: (): 1 | 2 => 1,
         _: (s): 1 | 2 => {
             // The fallback sees the whole union, not a single literal.
@@ -85,22 +114,29 @@ test("getPrimitiveUnionMatcherPartial routes shapes without a handler to _", ()
             return 2;
         },
     });
+
+    // Assert
     expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | "c") => 1 | 2>();
     // ❌ Exhaustive: gaps are allowed, but only with a `_` fallback.
-    const factory = getPrimitiveUnionMatcherPartial<"a" | "b">();
     expectTypeOf<{
         a: () => number;
-    }>().not.toMatchTypeOf<Parameters<typeof factory>[0]>();
+    }>().not.toExtend<Parameters<typeof sparseFactory>[0]>();
     assert.equal(matcher("a"), 1);
     assert.equal(matcher("b"), 2);
     assert.equal(matcher("c"), 2);
 });
 
 test("getPrimitiveUnionMatcherPartial also accepts an exhaustive pattern", () => {
-    const matcher = getPrimitiveUnionMatcherPartial<"a" | "b">()({
+    // Arrange
+    const factory = getPrimitiveUnionMatcherPartial<"a" | "b">();
+
+    // Act
+    const matcher = factory({
         a: () => "A",
         b: () => "B",
     });
+
+    // Assert
     expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => string>();
     assert.equal(matcher("a"), "A");
     assert.equal(matcher("b"), "B");
@@ -111,17 +147,25 @@ test("getPrimitiveUnionMatcherPartial also accepts an exhaustive pattern", () =>
 // ============================================================================
 
 test("getPrimitiveUnionMatcherPartialW allows gaps and widens to the union of handler returns", () => {
-    const matcher = getPrimitiveUnionMatcherPartialW<"x" | "y" | "z">()({
+    // Arrange
+    const factory = getPrimitiveUnionMatcherPartialW<"x" | "y" | "z">();
+    // Two keys, so `{ x }` lacks only the `_` fallback, nothing else.
+    const sparseFactory = getPrimitiveUnionMatcherPartialW<"x" | "y">();
+
+    // Act
+    const matcher = factory({
         x: () => 1 as const,
         _: () => "fallback" as const,
     });
+
+    // Assert
     expectTypeOf(matcher).toEqualTypeOf<
         (shape: "x" | "y" | "z") => 1 | "fallback"
     >();
-    const factory = getPrimitiveUnionMatcherPartialW<"x" | "y">();
+    // ❌ Exhaustive: gaps are allowed, but only with a `_` fallback.
     expectTypeOf<{
         x: () => number;
-    }>().not.toMatchTypeOf<Parameters<typeof factory>[0]>();
+    }>().not.toExtend<Parameters<typeof sparseFactory>[0]>();
     assert.equal(matcher("x"), 1);
     assert.equal(matcher("y"), "fallback");
     assert.equal(matcher("z"), "fallback");