Endo API documentation - v0.2.0 / Exports / @endo/patterns / PatternMatchers

Interface: PatternMatchers

@endo/patterns.PatternMatchers

Table of contents

Properties

• and
• any
• array
• arrayOf
• bag
• bagOf
• bigint
• boolean
• eq
• eref
• error
• gt
• gte
• key
• kind
• lt
• lte
• map
• mapOf
• nat
• neq
• not
• null
• number
• opt
• or
• partial
• pattern
• promise
• record
• recordOf
• remotable
• scalar
• set
• setOf
• split
• splitArray
• splitRecord
• string
• symbol
• tagged
• undefined

Properties

and

• and: (...subPatts: any[]) => Matcher

Matches against the intersection of all sub-Patterns.

Type declaration

▸ (...subPatts): Matcher

Parameters

Name	Type
...subPatts	any[]

Returns

Matcher

Defined in

patterns/src/types.js:242

---

any

• any: () => Matcher

Matches any Passable.

Type declaration

▸ (): Matcher

Returns

Matcher

Defined in

patterns/src/types.js:239

---

array

• array: (limits?: Partial<AllLimits>) => Matcher

Matches any CopyArray, subject to limits.

Type declaration

▸ (limits?): Matcher

Parameters

Name	Type
limits?	Partial<AllLimits>

Returns

Matcher

Defined in

patterns/src/types.js:304

---

arrayOf

• arrayOf: (subPatt?: any, limits?: Partial<AllLimits>) => Matcher

Matches any CopyArray whose elements are all matched by subPatt if defined, subject to limits.

Type declaration

▸ (subPatt?, limits?): Matcher

Parameters

Name	Type
subPatt?	any
limits?	Partial<AllLimits>

Returns

Matcher

Defined in

patterns/src/types.js:364

---

bag

• bag: (limits?: Partial<AllLimits>) => Matcher

Matches any CopyBag, subject to limits.

Type declaration

▸ (limits?): Matcher

Parameters

Name	Type
limits?	Partial<AllLimits>

Returns

Matcher

Defined in

patterns/src/types.js:310

---

bagOf

• bagOf: (keyPatt?: any, countPatt?: any, limits?: Partial<AllLimits>) => Matcher

Matches any CopyBag whose elements are all matched by keyPatt if defined and the cardinality of each is matched by countPatt if defined, subject to limits. countPatt is expected to rarely be useful, but is provided to minimize surprise.

Type declaration

▸ (keyPatt?, countPatt?, limits?): Matcher

Parameters

Name	Type
keyPatt?	any
countPatt?	any
limits?	Partial<AllLimits>

Returns

Matcher

Defined in

patterns/src/types.js:383

---

bigint

• bigint: (limits?: Partial<AllLimits>) => Matcher

Matches any bigint, subject to limits.

Type declaration

▸ (limits?): Matcher

Parameters

Name	Type
limits?	Partial<AllLimits>

Returns

Matcher

Defined in

patterns/src/types.js:288

---

boolean

• boolean: () => Matcher

Matches true or false.

Type declaration

▸ (): Matcher

Returns

Matcher

Defined in

patterns/src/types.js:281

---

eq

• eq: (key: any) => Matcher

Matches any value that is equal to key.

Type declaration

▸ (key): Matcher

Parameters

Name	Type
key	any

Returns

Matcher

Defined in

patterns/src/types.js:350

---

eref

• eref: (subPatt: any) => any

Matches any Passable that is either matched by subPatt or is a promise object. Note that validation is immediate, so (unlike the TypeScript ERef<T> type) M.eref matches a promise object whose fulfillment value is not matched by subPatt. For describing a top-level parameter, M.callWhen(..., M.await(p), ...) is preferred over M.call(..., M.eref(p), ...) because the former always checks against the sub-Pattern (awaiting fulfillment if necessary) while the latter bypasses such checks when the relevant argument is a promise.

Type declaration

▸ (subPatt): any

Parameters

Name	Type
subPatt	any

Returns

any

Defined in

patterns/src/types.js:450

---

error

• error: () => Matcher

Matches any error object. Error objects are Passable, but are neither Keys nor Patterns. They do not have a useful identity.

Type declaration

▸ (): Matcher

Returns

Matcher

Defined in

patterns/src/types.js:321

---

gt

• gt: (rightOperand: any) => Matcher

Matches any value that compareKeys reports as greater than rightOperand.

Type declaration

▸ (rightOperand): Matcher

Parameters

Name	Type
rightOperand	any

Returns

Matcher

Defined in

patterns/src/types.js:360

---

gte

• gte: (rightOperand: any) => Matcher

Matches any value that compareKeys reports as greater than or equal to rightOperand.

Type declaration

▸ (rightOperand): Matcher

Parameters

Name	Type
rightOperand	any

Returns

Matcher

Defined in

patterns/src/types.js:356

---

key

• key: () => Matcher

Matches any value that can be a key in a CopyMap or an element in a CopySet or CopyBag. All matched values are also valid Patterns that match only themselves.

Type declaration

▸ (): Matcher

Returns

Matcher

Defined in

patterns/src/types.js:256

---

kind

• kind: (kind: string) => Matcher

When kind specifies a PassStyle other than "tagged", matches any value having that PassStyle. Otherwise, when kind specifies a known tagged record tag (such as 'copySet', 'copyBag', 'copyMap', or 'match:scalar'), matches any CopyTagged with that tag and a valid tag-specific payload. Otherwise, does not match any value. TODO: Reject attempts to create a kind matcher with unknown kind?

Type declaration

▸ (kind): Matcher

Parameters

Name	Type
kind	string

Returns

Matcher

Defined in

patterns/src/types.js:266

---

lt

• lt: (rightOperand: any) => Matcher

Matches any value that compareKeys reports as less than rightOperand.

Type declaration

▸ (rightOperand): Matcher

Parameters

Name	Type
rightOperand	any

Returns

Matcher

Defined in

patterns/src/types.js:343

---

lte

• lte: (rightOperand: any) => Matcher

Matches any value that compareKeys reports as less than or equal to rightOperand.

Type declaration

▸ (rightOperand): Matcher

Parameters

Name	Type
rightOperand	any

Returns

Matcher

Defined in

patterns/src/types.js:346

---

map

• map: (limits?: Partial<AllLimits>) => Matcher

Matches any CopyMap, subject to limits.

Type declaration

▸ (limits?): Matcher

Parameters

Name	Type
limits?	Partial<AllLimits>

Returns

Matcher

Defined in

patterns/src/types.js:313

---

mapOf

• mapOf: (keyPatt?: any, valuePatt?: any, limits?: Partial<AllLimits>) => Matcher

Matches any CopyMap whose keys are all matched by keyPatt if defined and values are all matched by valuePatt if defined, subject to limits.

Type declaration

▸ (keyPatt?, valuePatt?, limits?): Matcher

Parameters

Name	Type
keyPatt?	any
valuePatt?	any
limits?	Partial<AllLimits>

Returns

Matcher

Defined in

patterns/src/types.js:393

---

nat

• nat: (limits?: Partial<AllLimits>) => Matcher

Matches any non-negative bigint, subject to limits.

Type declaration

▸ (limits?): Matcher

Parameters

Name	Type
limits?	Partial<AllLimits>

Returns

Matcher

Defined in

patterns/src/types.js:291

---

neq

• neq: (key: any) => Matcher

Matches any value that is not equal to key.

Type declaration

▸ (key): Matcher

Parameters

Name	Type
key	any

Returns

Matcher

Defined in

patterns/src/types.js:353

---

not

• not: (subPatt: any) => Matcher

Matches against the negation of the sub-Pattern.

Type declaration

▸ (subPatt): Matcher

Parameters

Name	Type
subPatt	any

Returns

Matcher

Defined in

patterns/src/types.js:249

---

null

• null: () => null

Returns null, which matches only itself.

Type declaration

▸ (): null

Returns

null

Defined in

patterns/src/types.js:340

---

number

• number: () => Matcher

Matches any floating point number, including NaN and either signed Infinity.

Type declaration

▸ (): Matcher

Returns

Matcher

Defined in

patterns/src/types.js:284

---

opt

• opt: (subPatt: any) => any

Matches any Passable that is matched by subPatt or is the exact value undefined.

Type declaration

▸ (subPatt): any

Parameters

Name	Type
subPatt	any

Returns

any

Defined in

patterns/src/types.js:461

---

or

• or: (...subPatts: any[]) => Matcher

Matches against the union of all sub-Patterns (requiring a successful match against at least one).

Type declaration

▸ (...subPatts): Matcher

Parameters

Name	Type
...subPatts	any[]

Returns

Matcher

Defined in

patterns/src/types.js:245

---

partial

• partial: (basePatt: CopyRecord<any> | CopyArray<any>, rest?: any) => Matcher

Deprecated. Use M.splitArray or M.splitRecord instead. An array or record is split into the first part that is matched by basePatt, and the remainder, which is matched against rest if present. M.partial differs from M.split in the handling of data that is described in basePatt but absent in a provided specimen:

• For a CopyRecord, M.partial ignores properties of basePatt that are not present on the specimen.
• For a CopyArray, M.partial ignores elements of basePatt at indices beyond the maximum index of the specimen.

Type declaration

▸ (basePatt, rest?): Matcher

Parameters

Name	Type
basePatt	CopyRecord<any> | CopyArray<any>
rest?	any

Returns

Matcher

Defined in

patterns/src/types.js:439

---

pattern

• pattern: () => Matcher

Matches any Pattern that can be used to characterize Passables. A Pattern cannot contain promises or errors, as these are not stable enough to usefully match.

Type declaration

▸ (): Matcher

Returns

Matcher

Defined in

patterns/src/types.js:261

---

promise

• promise: () => Matcher

Matches any promise object. Promises are Passable, but are neither Keys nor Patterns. They do not have a useful identity.

Type declaration

▸ (): Matcher

Returns

Matcher

Defined in

patterns/src/types.js:326

---

record

• record: (limits?: Partial<AllLimits>) => Matcher

Matches any CopyRecord, subject to limits.

Type declaration

▸ (limits?): Matcher

Parameters

Name	Type
limits?	Partial<AllLimits>

Returns

Matcher

Defined in

patterns/src/types.js:301

---

recordOf

• recordOf: (keyPatt?: any, valuePatt?: any, limits?: Partial<AllLimits>) => Matcher

Matches any CopyRecord whose keys are all matched by keyPatt if defined and values are all matched by valuePatt if defined, subject to limits.

Type declaration

▸ (keyPatt?, valuePatt?, limits?): Matcher

Parameters

Name	Type
keyPatt?	any
valuePatt?	any
limits?	Partial<AllLimits>

Returns

Matcher

Defined in

patterns/src/types.js:371

---

remotable

• remotable: (label?: string) => Matcher

Matches a far object or its remote presence. The optional label is purely for diagnostic purposes and does not add any constraints.

Type declaration

▸ (label?): Matcher

Parameters

Name	Type
label?	string

Returns

Matcher

Defined in

patterns/src/types.js:316

---

scalar

• scalar: () => Matcher

Matches any Passable primitive value or Remotable. All matched values are Keys.

Type declaration

▸ (): Matcher

Returns

Matcher

Defined in

patterns/src/types.js:252

---

set

• set: (limits?: Partial<AllLimits>) => Matcher

Matches any CopySet, subject to limits.

Type declaration

▸ (limits?): Matcher

Parameters

Name	Type
limits?	Partial<AllLimits>

Returns

Matcher

Defined in

patterns/src/types.js:307

---

setOf

• setOf: (keyPatt?: any, limits?: Partial<AllLimits>) => Matcher

Matches any CopySet whose elements are all matched by keyPatt if defined, subject to limits.

Type declaration

▸ (keyPatt?, limits?): Matcher

Parameters

Name	Type
keyPatt?	any
limits?	Partial<AllLimits>

Returns

Matcher

Defined in

patterns/src/types.js:376

---

split

• split: (basePatt: CopyRecord<any> | CopyArray<any>, rest?: any) => Matcher

Deprecated. Use M.splitArray or M.splitRecord instead. An array or record is split into the first part that is matched by basePatt, and the remainder, which is matched against rest if present.

Type declaration

▸ (basePatt, rest?): Matcher

Parameters

Name	Type
basePatt	CopyRecord<any> | CopyArray<any>
rest?	any

Returns

Matcher

Defined in

patterns/src/types.js:432

---

splitArray

• splitArray: (required: any[], optional?: any[], rest?: any) => Matcher

Matches any array --- typically an arguments list --- consisting of

• an initial portion matched by required, and
• a middle portion of length up to the length of optional that is matched by the equal-length prefix of optional if optional is defined, and
• a remainder that is matched by rest if rest is defined. The array must be at least as long as required but its remainder can be arbitrarily short. Any array elements beyond the summed length of required and optional are collected and matched against rest.

Type declaration

▸ (required, optional?, rest?): Matcher

Parameters

Name	Type
required	any[]
optional?	any[]
rest?	any

Returns

Matcher

Defined in

patterns/src/types.js:401

---

splitRecord

• splitRecord: (required: CopyRecord<any>, optional?: CopyRecord<any>, rest?: any) => Matcher

Matches any CopyRecord that can be split into component CopyRecords as follows:

• all properties corresponding with a property of required
• all properties corresponding with a property of optional but not corresponding with a property of required
• all other properties where the first component is matched by required, the second component is matched by the subset of optional corresponding with its properties if optional is defined, and the third component is matched by rest if defined. The CopyRecord must have all properties that appear on required, but may omit properties that appear on optional.

Type declaration

▸ (required, optional?, rest?): Matcher

Parameters

Name	Type
required	CopyRecord<any>
optional?	CopyRecord<any>
rest?	any

Returns

Matcher

Defined in

patterns/src/types.js:416

---

string

• string: (limits?: Partial<AllLimits>) => Matcher

Matches any string, subject to limits.

Type declaration

▸ (limits?): Matcher

Parameters

Name	Type
limits?	Partial<AllLimits>

Returns

Matcher

Defined in

patterns/src/types.js:294

---

symbol

• symbol: (limits?: Partial<AllLimits>) => Matcher

Matches any registered or well-known symbol, subject to limits.

Type declaration

▸ (limits?): Matcher

Parameters

Name	Type
limits?	Partial<AllLimits>

Returns

Matcher

Defined in

patterns/src/types.js:297

---

tagged

• tagged: (tagPatt?: any, payloadPatt?: any) => Matcher

For matching an arbitrary Passable Tagged object, whether it has a recognized kind or not. If tagPatt is omitted, it defaults to M.string(). If payloadPatt is omitted, it defaults to M.any().

Type declaration

▸ (tagPatt?, payloadPatt?): Matcher

Parameters

Name	Type
tagPatt?	any
payloadPatt?	any

Returns

Matcher

Defined in

patterns/src/types.js:275

---

undefined

• undefined: () => Matcher

Matches the exact value undefined. All keys including undefined are already valid Patterns and so can validly represent themselves. But optional Pattern arguments (patt = undefined) => ... treat explicit undefined as omission of the argument. Thus, when a passed Pattern does not also need to be a Key, we recommend passing M.undefined() rather than undefined.

Type declaration

▸ (): Matcher

Returns

Matcher

Defined in

patterns/src/types.js:331