Check

Documentation on how to use check, Meteor's type checking library.

The check package includes pattern checking functions useful for checking the types and structure of variables and an extensible library of patterns to specify which types you are expecting.

To add check (or Match) to your application, run this command in your terminal:

meteor add check

check

Summary:

Check that a value matches a pattern. If the value does not match the pattern, throw a Match.Error. By default, it will throw immediately at the first error encountered. Pass in { throwAllErrors: true } to throw all errors.

Particularly useful to assert that arguments to a function have the right types and structure.

Arguments:

Source code

Name	Type	Description	Required
value	Any	The value to check	Yes
pattern	MatchPattern	The pattern to match value against	Yes
options	Object	Additional options for check	No

Options:

Name	Type	Description	Required
throwAllErrors	Boolean	If true, throw all errors	No

Meteor methods and publish functions can take arbitrary EJSON types as arguments, but most functions expect their arguments to be of a particular type. check is a lightweight function for checking that arguments and other values are of the expected type. For example:

import { check } from "meteor/check";
import { Meteor } from "meteor/meteor";
Meteor.publish("chatsInRoom", function (roomId) {
  // Make sure `roomId` is a string, not an arbitrary Mongo selector object.
  check(roomId, String);
  return Chats.find({ room: roomId });
});

Meteor.methods({
  addChat(roomId, message) {
    check(roomId, String);
    check(message, {
      text: String,
      timestamp: Date,
      // Optional, but if present must be an array of strings.
      tags: Match.Maybe([String]),
    });

    // Do something with the message...
  },
});

If the match fails, check throws a Match.Error describing how it failed. If this error gets sent over the wire to the client, it will appear only as Meteor.Error(400, 'Match Failed'). The failure details will be written to the server logs but not revealed to the client.

Match.test

Summary:

Returns true if the value matches the pattern.

Arguments:

Source code

Name	Type	Description	Required
value	Any	The value to check	Yes
pattern	MatchPattern	The pattern to match value against	Yes

Match.test can be used to identify if a variable has a certain structure.

import { Match } from "meteor/check";

// Will return true for `{ foo: 1, bar: 'hello' }` or similar.
Match.test(value, { foo: Match.Integer, bar: String });

// Will return true if `value` is a string.
Match.test(value, String);

// Will return true if `value` is a string or an array of numbers.
Match.test(value, Match.OneOf(String, [Number]));

This can be useful if you have a function that accepts several different kinds of objects, and you want to determine which was passed in.

Match Patterns

The following patterns can be used as pattern arguments to check and Match.test:

Match.Any

Matches any value.

import { Match } from "meteor/check";
// Will return true for any value.
Match.test(value, Match.Any);

String, Number, Boolean, undefined, null

Matches a primitive of the given type.

import { Match } from "meteor/check";
let result;
// Will return true if `value` is a string.
result = Match.test(value, String);
console.log(result); // true

// Will return true if `value` is a number.
result = Match.test(value, Number);
console.log(result); // true

// Will return true if `value` is a boolean.
result = Match.test(value, Boolean);
console.log(result); // true

Match.Integer

Matches a signed 32-bit integer. Doesn't match Infinity, -Infinity, or NaN.

import { Match } from "meteor/check";
let result;
// Will return true if `value` is an integer.
result = Match.test(value, Match.Integer);
console.log(result); // true

[pattern]

A one-element array matches an array of elements, each of which match pattern. For example, [Number] matches a (possibly empty) array of numbers; [Match.Any] matches any array.

import { Match } from "meteor/check";
let result;
// Will return true if `value` is an array of numbers.
result = Match.test(value, [Number]);
console.log(result); // true

{ key1: pattern1, key2: pattern2, ... }

Matches an Object with the given keys, with values matching the given patterns. If any pattern is a Match.Maybe or Match.Optional, that key does not need to exist in the object. The value may not contain any keys not listed in the pattern. The value must be a plain Object with no special prototype.

import { Match } from "meteor/check";
let result;
// Will return true if `value` is an object with keys 'foo' and 'bar'.
result = Match.test(value, { foo: String, bar: Number });
console.log(result); // true

Match.ObjectIncluding({ key1: pattern1, key2: pattern2, ... })

Matches an Object with the given keys; the value may also have other keys with arbitrary values.

import { Match } from "meteor/check";
let result;
// Will return true if `value` is an object with keys 'foo' and 'bar'.
result = Match.test(value, Match.ObjectIncluding({ foo: String, bar: Number }));
console.log(result); // true

Object

Matches any plain Object with any keys; equivalent to Match.ObjectIncluding({}).

import { Match } from "meteor/check";
let result;
// Will return true if `value` is an object.
result = Match.test(value, Object);
console.log(result); // true

Match.Maybe(pattern)

Matches either undefined, null, or pattern. If used in an object, matches only if the key is not set as opposed to the value being set to undefined or null. This set of conditions was chosen because undefined arguments to Meteor Methods are converted to null when sent over the wire.

import { Match, check } from "meteor/check";
// In an object
const pattern = { name: Match.Maybe(String) };

check({ name: "something" }, pattern); // OK
check({}, pattern); // OK
check({ name: undefined }, pattern); // Throws an exception
check({ name: null }, pattern); // Throws an exception

// Outside an object
check(null, Match.Maybe(String)); // OK
check(undefined, Match.Maybe(String)); // OK

Match.Optional(pattern)

Behaves like Match.Maybe except it doesn't accept null. If used in an object, the behavior is identical to Match.Maybe.

Match.OneOf(pattern1, pattern2, ...)

Matches any value that matches at least one of the provided patterns.

Any constructor function (eg, Date)

Matches any element that is an instance of that type.

import { Match } from "meteor/check";
let result;

// Will return true if `value` is a Date.
result = Match.test(value, Date);

Match.Where(condition)

Calls the function condition with the value as the argument. If condition returns true, this matches. If condition throws a Match.Error or returns false, this fails. If condition throws any other error, that error is thrown from the call to check or Match.test. Examples:

import { Match, check } from "meteor/check";

check(buffer, Match.Where(EJSON.isBinary));

const NonEmptyString = Match.Where((x) => {
  check(x, String);
  return x.length > 0;
});

check(arg, NonEmptyString);