@endo/patterns

Pattern matching and validation for passable data, with copy-collections and interface guards.

Overview

The @endo/patterns package provides the M namespace for creating pattern matchers that validate passable data and describe behavioral contracts. This is the validation layer above @endo/pass-style, enabling you to check that data matches expected shapes before using it.

Patterns enable:

• Data validation: Check that values match expected types and structures
• Interface contracts: Describe method signatures with InterfaceGuards
• Copy collections: CopySet, CopyBag, CopyMap for passable data structures
• Key comparison: Distributed equality for comparing values across vats

Quick Start

import { M, mustMatch } from '@endo/patterns';

const specimen = harden({ foo: 3, bar: 4 });

const pattern = M.splitRecord(
  { foo: M.number() },                        // required properties
  { bar: M.string(), baz: M.number() }       // optional properties
);

mustMatch(specimen, pattern);
// throws: 'bar?: number 4 - Must be a string'

For best rendering, use the Endo reference docs site.

The M Namespace

The M object provides methods for creating pattern matchers organized into several categories:

Primitive Matchers

Match specific JavaScript types:

M.any()           // Matches any passable
M.undefined()     // Matches undefined
M.null()          // Matches null
M.boolean()       // Matches true or false
M.number()        // Matches any number (including NaN, Infinity)
M.bigint()        // Matches any bigint
M.string()        // Matches any string
M.symbol()        // Matches registered/well-known symbols

// Constrained primitives
M.nat()           // Non-negative bigint
M.gte(5)          // Number >= 5
M.lte(100)        // Number <= 100

Container Matchers

Match copyArray, copyRecord, and other structures:

M.array()         // Any CopyArray
M.record()        // Any CopyRecord
M.set()           // Any CopySet
M.bag()           // Any CopyBag
M.map()           // Any CopyMap

// With constraints
M.array({ maxSize: 10 })          // Array with at most 10 elements
M.string({ maxSize: 100 })        // String with at most 100 characters

// Structured content
M.arrayOf(M.number())             // Array of numbers only
M.recordOf(M.string(), M.number()) // Record with string keys, number values
M.setOf(M.string())               // Set of strings only

Structured Matchers

Match specific shapes:

// Split patterns: required, optional, rest
M.splitArray(
  [M.string(), M.number()],      // required elements
  [M.boolean()],                  // optional elements
  M.any()                         // rest elements
)

M.splitRecord(
  { name: M.string() },           // required properties
  { age: M.number() },            // optional properties
  M.any()                         // rest properties
)

// Partial matches
M.partial({ name: M.string() })  // Has at least 'name' property

// Split auto-detects array vs record
M.split({ x: M.number() }, M.any())

Logical Operators

Combine matchers:

M.and(M.number(), M.gte(0), M.lte(100))   // 0 <= n <= 100
M.or(M.string(), M.number())               // String or number
M.not(M.undefined())                       // Anything except undefined
M.opt(M.string())                          // undefined or string (optional)

Comparison Matchers

Match values relative to a key:

M.eq('hello')     // Equal to 'hello'
M.neq(0)          // Not equal to 0
M.lt(10)          // Less than 10
M.lte(100)        // Less than or equal to 100
M.gte(0)          // Greater than or equal to 0
M.gt(-1)          // Greater than -1

Special Matchers

M.remotable()           // Any remotable object
M.remotable('Counter')  // Remotable with specific label
M.error()               // Any error
M.promise()             // Any promise
M.eref(M.number())      // Number or promise for number (eventual reference)
M.kind('copyArray')     // Specific pass style
M.pattern()             // Any valid pattern
M.key()                 // Any valid Key
M.scalar()              // Any primitive or remotable

Pattern Matching

matches(specimen, pattern)

Returns true if the specimen matches the pattern, false otherwise:

import { M, matches } from '@endo/patterns';

matches(42, M.number());                    // true
matches('hello', M.number());               // false
matches([1, 2, 3], M.arrayOf(M.number())); // true

mustMatch(specimen, pattern, label?)

Throws with a descriptive error if the specimen doesn't match:

import { mustMatch } from '@endo/patterns';

mustMatch(42, M.string());
// throws: "number 42 - Must be a string"

mustMatch(-5, M.and(M.number(), M.gte(0)), 'count');
// throws: "count: number -5 - Must be >= 0"

The error messages are designed to help you understand exactly what was wrong with the data.

Copy Collections

Patterns introduces three passable collection types built on makeTagged():

CopySet

A set of unique Keys (primitives or remotables):

import { makeCopySet } from '@endo/patterns';

const colors = makeCopySet(['red', 'blue', 'green']);

// Elements are sorted in rank order
// Duplicates are removed
// Can be passed between vats

// Pattern for sets
const ColorSet = M.setOf(M.string());
mustMatch(colors, ColorSet);  // passes

Why not use JavaScript Set? JavaScript Sets aren't passable. CopySet is frozen, comparable via keyEQ, and can be efficiently serialized.

CopyBag

A multiset (elements with counts):

import { makeCopyBag } from '@endo/patterns';

const inventory = makeCopyBag([
  ['apples', 5n],
  ['oranges', 3n],
  ['apples', 2n]   // counts are combined
]);

// Result: [['apples', 7n], ['oranges', 3n]]

const InventoryPattern = M.bagOf(M.string(), M.bigint());
mustMatch(inventory, InventoryPattern);

CopyMap

A map from Keys to Passable values:

import { makeCopyMap } from '@endo/patterns';

const balances = makeCopyMap([
  ['alice', 100],
  ['bob', 50]
]);

// Keys are sorted in rank order
// Can use any Key as a key (not just strings!)

const remotableKey = Far('Key', {});
const map = makeCopyMap([[remotableKey, 'value']]);

const BalancesPattern = M.mapOf(M.string(), M.number());
mustMatch(balances, BalancesPattern);

Why not use plain objects? CopyMap supports:

• Any Key as a key (objects, remotables, not just strings)
• Efficient key comparison using compareKeys()
• Subset relationships for partial ordering

Interface Guards

InterfaceGuards describe behavioral contracts for objects, particularly useful with @endo/exo:

Creating Interface Guards

import { M } from '@endo/patterns';

const CounterI = M.interface('Counter', {
  // Synchronous method
  increment: M.call(M.number()).returns(M.number()),

  // Method with optional arguments
  reset: M.call().optional(M.number()).returns(),

  // Method with rest arguments
  add: M.call(M.number()).rest(M.number()).returns(M.number()),

  // Async method (awaits arguments)
  asyncOp: M.callWhen(M.string()).returns(M.string())
});

Method Guard Structure

// Basic call: call(required args...)
M.call(M.string(), M.number())

// With optional args
M.call(M.string()).optional(M.number())

// With rest args
M.call(M.string()).rest(M.any())

// Specify return type
M.call(M.string()).returns(M.number())

// Async method (awaits promise args)
M.callWhen(M.remotable()).returns(M.string())

Integration with Exo

InterfaceGuards are enforced automatically by exos:

import { makeExo } from '@endo/exo';
import { M } from '@endo/patterns';

const CounterI = M.interface('Counter', {
  increment: M.call(M.number()).returns(M.number())
});

const counter = makeExo('Counter', CounterI, {
  increment(n) {
    // n is guaranteed to be a number by the guard
    return count += n;
  }
});

counter.increment(5);      // OK
counter.increment('5');    // throws: Must be a number

This is the foundation of defensive programming in Endo: guards validate inputs automatically, so your methods can focus on business logic.

Key Comparison

Keys can be compared for equality and ordering:

keyEQ(key1, key2)

Tests if two Keys are equal using distributed equality semantics:

import { keyEQ } from '@endo/patterns';

keyEQ('hello', 'hello');        // true
keyEQ(42, 42);                  // true
keyEQ([1, 2], [1, 2]);          // true (compares content)

const r1 = Far('Obj', {});
const r2 = Far('Obj', {});
keyEQ(r1, r1);                  // true (same remotable)
keyEQ(r1, r2);                  // false (different remotables)

compareKeys(key1, key2)

Returns a comparison result implementing a partial order:

• 0: Keys are equal
• -1: key1 < key2
• 1: key1 > key2
• NaN: Keys are incomparable

import { compareKeys, keyLT, keyGT } from '@endo/patterns';

compareKeys('a', 'b');          // -1
compareKeys(5, 5);              // 0
compareKeys(10, 3);             // 1

// Convenience functions
keyLT('a', 'b');                // true
keyGT(10, 3);                   // true

// Incomparable keys
const r1 = Far('A', {});
const r2 = Far('B', {});
compareKeys(r1, r2);            // NaN (different remotables)

Why partial order? Not all Keys can be compared. For example, different remotables have no defined ordering, and CopySets use subset relationships.

Key, Pattern, and Passable Hierarchy

Understanding the type hierarchy:

Passable (everything that can pass)
├── Error
├── Promise
├── Key (stable, comparable)
│   ├── Primitives (null, undefined, boolean, number, bigint, string, symbol)
│   ├── Remotable
│   ├── CopyArray<Key>
│   ├── CopyRecord<Key>
│   ├── CopySet<Key>
│   ├── CopyBag<Key>
│   └── CopyMap<Key, Passable>
└── Pattern (describes a set of Passables)
    ├── Key (matches itself)
    └── Key-like with Matcher leaves

• Passable: Can cross vat boundaries (from @endo/pass-style)
• Key: Stable and comparable subset of Passable
• Pattern: Describes a subset of Passables for matching

Integration with Endo Packages

• Foundation: @endo/pass-style - What can be passed (Passables)
• Enforcement: @endo/exo - Use InterfaceGuards for automatic validation
• Communication: @endo/eventual-send - Send messages to validated objects

Complete Tutorial: See Message Passing for a comprehensive guide showing how patterns work with pass-style, exo, and eventual-send.

Deep Dives

For implementation details:

• marshal vs patterns abstraction levels - kindOf vs passStyleOf vs typeof
• Type definitions - Complete TypeScript type definitions