Type safety with Matchbox

Pattern Matching with Exhaustive Checking

One of the most powerful features of Matchbox is exhaustive pattern matching with the match method:

// Calculate area with pattern matching
const getArea = (shape) => shape.match({
  Circle: ({ radius }) => Math.PI * radius * radius,
  Rectangle: ({ width, height }) => width * height,
  Triangle: ({ base, height }) => (base * height) / 2,
});

// TypeScript error if you forget a case!
const getPerimeter = (shape) => shape.match({
  Circle: ({ radius }) => 2 * Math.PI * radius,
  Rectangle: ({ width, height }) => 2 * (width + height),
  // Error: Property 'Triangle' is missing in type '...'
});

Type Guards

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

Type-Safe Casting with Runtime Validation

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;
  }
}

Advanced Type Guards with Filters

Matchina also provides filter functions for more complex type guards:

import { matchbox, withKey, withData } from "matchina";
// ---cut---
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`);

Benefits of Type Guards

• 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

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