unionize

The match method allows you to handle union members using pure functions instead of switch statements.

It supports two usage patterns:

1. Directly: Actions.match(action, { ... })
2. Curried: const handler = Actions.match({ ... }); handler(action);

To handle the remaining cases, provide a default key in the cases object. If default is not provided, the match must be exhaustive.

const todosReducer = (state: Todo[] = [], action: Action) =>
  Actions.match(action, {
    ADD_TODO: ({ id, text }) => [...state, { id, text, completed: false }],
    TOGGLE_TODO: ({ id }) =>
      state.map(todo => todo.id === id ? { ...todo, completed: !todo.completed } : todo),
    default: a => state
  });

// Curried version for reusable handlers
const getIdFromAction = Actions.match({
  ADD_TODO: ({ id }) => id,
  TOGGLE_TODO: ({ id }) => id,
  default: a => { throw new Error(`Action type ${a.type} does not have an associated id`); },
});

const id = getIdFromAction(Actions.ADD_TODO({ id: '123', text: 'hi' }));

Use unionize to define a set of tagged union types by providing a mapping of tags to value types.

• Use ofType<T>() to define the value type for a tag.
• Use {} for "empty" types (tags with no payload).
• By default, the tag property is named "tag".
• If you omit the value property name in the config, the value type is intersected directly with the tag (e.g., { tag: 'TYPE' } & { id: string }). In this case, the value type must be an object type.
• If you provide a value property name in the config, the value will be nested under that key (e.g., { type: 'TYPE', payload: { id: string } }). This is required if your value type is a primitive (like a string union).

import { unionize, ofType } from 'unionize';

// Default behavior (tag: 'tag')
const Actions = unionize({
  ADD_TODO: ofType<{ id: string; text: string }>(),
  CLEAR_TODOS: {}, 
});

// Custom property names (e.g., FSA compliant)
const FSA_Actions = unionize({
  ADD_TODO: ofType<{ id: string; text: string }>(),
  SET_VISIBILITY_FILTER: ofType<'SHOW_ALL' | 'SHOW_ACTIVE' | 'SHOW_COMPLETED'>(),
}, {
  tag: 'type',
  value: 'payload',
});

The unionize() function creates a tagged union from a record mapping tags to value types. It provides variant constructors, type predicates (is), type casting (as), pattern matching (match), and transformations (transform).

Configuration Options

• tag: The name of the property used to identify the variant (defaults to 'tag').
• value: The name of the property that holds the variant's data. If not specified, the data is merged directly into the object itself.

Usage Patterns

1. Merged Data (Default)

When value is not specified, the variant data is spread into the object alongside the tag.

2. Wrapped Data

When value is specified, the variant data is nested under that property name.

import { unionize, ofType } from 'unionize';

// Define the union
const Shape = unionize({
  circle: ofType<{ radius: number }>(),
  square: ofType<{ side: number }>(),
}, { tag: 'type' });

// 1. Using Creators
const myCircle = Shape.circle({ radius: 10 }); // { type: 'circle', radius: 10 }

// 2. Using Type Predicates (is)
if (Shape.is.circle(myCircle)) {
  console.log(myCircle.radius); // Type safe
}

// 3. Using Pattern Matching (match)
const area = Shape.match({
  circle: (c) => Math.PI * c.radius ** 2,
  square: (s) => s.side ** 2,
  default: (v) => 0
})(myCircle);

// 4. Using Type Casting (as)
try {
  const s = Shape.as.square(myCircle);
} catch (e) {
  // Throws error if tag doesn't match
}

The match function allows you to perform exhaustive pattern matching on a union variant. It supports two calling signatures:

1. match(cases, variant): Returns the result of the matching case.
2. match(cases)(variant): Returns a function that accepts a variant.

Match Cases

• Exhaustive: Provide a handler for every tag in the record. The default property must not be used.
• With Default: Provide handlers for some tags and a default handler for any variant that doesn't match the provided keys.

Note: If you use a default case, the handler receives the full variant object. If you do not use a default case, the handlers receive the extracted value (if using the value config option) or the object itself (if using the default merged behavior).

// Example of exhaustive match
const result = Shape.match({
  circle: (c) => `Circle with ${c.radius}`,
  square: (s) => `Square with ${s.side}`
})(myCircle);

// Example of match with default
const resultWithDefault = Shape.match({
  circle: (c) => `Circle`,
  default: (v) => `Unknown variant: ${v.tag}`
})(myCircle);