Matchbox Usage

Handle cases with match()

One of the most powerful features of Matchbox is exhaustive pattern matching with the match method, serving as an alternative to switch statements that are not guaranteed to be exhaustive.

Given the following matchbox factory:

export const shapes = matchboxFactory({
  Circle: (radius: number) => ({ radius }),
  Square: (side: number) => ({ side }),
  Rectangle: (width: number, height: number) => ({ width, height }),
});

Pattern Matching with Exhaustive Checking

The most powerful feature of tagged unions created with matchboxFactory is exhaustive pattern matching with the match method:

export const area = someShape.match({
  Circle: ({ radius }) => Math.PI * radius * radius,
  Square: ({ side }) => side * side,
  Rectangle: ({ width, height }) => width * height,
});

Using Default Cases

Sometimes you want to handle multiple states with a single case, or provide a fallback:

export const cornerCount = someShape.match({
  Circle: () => 0,
  _: () => 4, // Default case for Square and Rectangle
});

Non-Exhaustive Matching

You can opt-out of exhaustiveness checking by passing false as the second argument:

export const optionalNickname = someShape.match(
  {
    Circle: ({ radius }) => `Circle with radius ${radius}`,
    Square: ({ side }) => `Square with side ${side}`,
  },
  false
);

Type Guards

Using type guards in Matchbox provides several benefits:

• Type safety: Prevent runtime errors by catching type mismatches at compile time
• Code completion: Get proper IDE suggestions based on narrowed types
• Refactoring safety: When you change a state’s structure, TypeScript will flag all places that need updates
• Exhaustive checking: Ensure all possible states are handled with pattern matching

Type Narrow using is()

Tagged union instances created with matchboxFactory provide automatic type narrowing with the is method:

// Create a Light matchbox with On/Off states
const Light = matchboxFactory({
  Off: undefined,
  On: (percentage = 100) => ({ percentage }),
});

// Create light instances
const light1 = Light.Off();
const light2 = Light.On(75);

// Type guards with automatic type narrowing
if (light2.is("On")) {
  // TypeScript knows light2.data has percentage
  console.log(`Brightness: ${light2.data.percentage}%`);

  // This would be a TypeScript error:
  // console.log(light2.data.invalid); // Error: Property 'invalid' does not exist
}

// Type guards can be used in conditions
function getBrightness(
  light: ReturnType<typeof Light.Off> | ReturnType<typeof Light.On>
) {
  if (light.is("Off")) {
    return 0;
  }
  // TypeScript knows this must be the "On" state with percentage
  return light.data.percentage;
}

console.log(getBrightness(light1)); // 0
console.log(getBrightness(light2)); // 75

Cast using as()

Use the as method for type-safe casting with runtime validation:

import { matchboxFactory } from "matchina";

// Create a Light matchbox with On/Off states
const Light = matchboxFactory({
  Off: undefined,
  On: (percentage = 100) => ({ percentage }),
});

const light = Light.On(80);

// Safe casting with runtime validation
try {
  // This works because light is actually in the "On" state
  const asOn = light.as("On");
  console.log(`Brightness: ${asOn.data.percentage}%`); // Works fine: "Brightness: 80%"

  // This will throw because light is not in the "Off" state
  const asOff = light.as("Off");
  console.log("This line will never execute", asOff);
} catch (e: any) {
  console.error("Cast failed:", e.message); // "Attempted to cast On as Off"
}

// Practical example: only adjust brightness for "On" lights
export function adjustBrightness(
  light: ReturnType<typeof Light.Off> | ReturnType<typeof Light.On>,
  adjustment: number
) {
  try {
    // Try to cast to "On" state
    const onLight = light.as("On");

    // If successful, create a new light with adjusted brightness
    const newBrightness = Math.max(
      0,
      Math.min(100, onLight.data.percentage + adjustment)
    );
    return Light.On(newBrightness);
  } catch {
    // Light is off, return it unchanged
    return light;
  }
}

Filter using with Type Predicates

Matchina also provides filter functions for more complex type guards:

const Shape = matchbox({
  Circle: (radius: number, color: string = "black") => ({ radius, color }),
  Rectangle: (width: number, height: number, color: string = "black") => ({
    width,
    height,
    color,
  }),
  Triangle: (base: number, height: number, color: string = "black") => ({
    base,
    height,
    color,
  }),
});

const shapes = [
  Shape.Circle(5, "red"),
  Shape.Rectangle(10, 20, "blue"),
  Shape.Circle(8, "green"),
  Shape.Triangle(15, 10, "red"),
];

// Filter by key
const circles = shapes.filter(withKey("Circle"));
console.log(`Found ${circles.length} circles`);

// Filter by data property
const redShapes = shapes.filter(withData((data) => data.color === "red"));
console.log(`Found ${redShapes.length} red shapes`);

// Combine filters
const largeCircles = shapes.filter(
  (shape) => shape.is("Circle") && shape.data.radius > 7,
);
console.log(`Found ${largeCircles.length} large circles`);

Next Steps

Now that you understand type guards, explore these related guides:

• Matchbox: Type-Safe Unions - Learn more about the foundation of type guards
• Factory Machines - See how type guards work with state machines
• Lifecycle Hooks - Add hooks for intercepting state changes