Added Match.Maybe to allow optional matching with null support

docs/client/full-api/api/check.md

@@ -111,6 +111,10 @@ only if the key is not set as opposed to the value being set to `undefined`.
 
 {{/dtdd}}
 
+{{#dtdd "<code>Match.Maybe(<em>pattern</em>)</code>"}} Behaves like `Match.Optional`
+except it also matches `null`. If used in an object, the behaviour is identical to `Match.optional`.
+{{/dtdd}}
+
 {{#dtdd "<code>Match.OneOf(<em>pattern1</em>, <em>pattern2</em>, ...)</code>"}}
 Matches any value that matches at least one of the provided patterns.
 {{/dtdd}}
@@ -135,4 +139,4 @@ from the call to `check` or `Match.test`. Examples:
 {{/dtdd}}
 </dl>
 
-{{/template}}
+{{/template}}

packages/check/match.js

@@ -47,6 +47,9 @@ Match = {
   Optional: function (pattern) {
     return new Optional(pattern);
   },
+  Maybe: function (pattern) {
+    return new Maybe(pattern);
+  },
   OneOf: function (/*arguments*/) {
     return new OneOf(_.toArray(arguments));
   },
@@ -112,6 +115,8 @@ var Optional = function (pattern) {
   this.pattern = pattern;
 };
 
+var Maybe = Optional;
+
 var OneOf = function (choices) {
   if (_.isEmpty(choices))
     throw new Error("Must provide at least one choice to Match.OneOf");
@@ -245,8 +250,12 @@ var testSubtree = function (value, pattern) {
   }
 
 
-  if (pattern instanceof Optional)
+  if (pattern instanceof Maybe) {
+    pattern = Match.OneOf(undefined, null, pattern.pattern);
+  }
+  else if (pattern instanceof Optional) {
     pattern = Match.OneOf(undefined, pattern.pattern);
+  }
 
   if (pattern instanceof OneOf) {
     for (var i = 0; i < pattern.choices.length; ++i) {
@@ -259,7 +268,7 @@ var testSubtree = function (value, pattern) {
     }
     // XXX this error is terrible
     return {
-      message: "Failed Match.OneOf or Match.Optional validation",
+      message: "Failed Match.OneOf, Match.Maybe or Match.Optional validation",
       path: ""
     };
   }
@@ -319,7 +328,7 @@ var testSubtree = function (value, pattern) {
   var requiredPatterns = {};
   var optionalPatterns = {};
   _.each(pattern, function (subPattern, key) {
-    if (subPattern instanceof Optional)
+    if (subPattern instanceof Optional || subPattern instanceof Maybe)
       optionalPatterns[key] = subPattern.pattern;
     else
       requiredPatterns[key] = subPattern;

packages/check/match_test.js

@@ -41,6 +41,9 @@ Tinytest.add("check - check", function (test) {
         matches(pair[0], type);
         matches(pair[0], Match.Optional(type));
         matches(undefined, Match.Optional(type));
+        matches(pair[0], Match.Maybe(type));
+        matches(undefined, Match.Maybe(type));
+        matches(null, Match.Maybe(type));
         matches(pair[0], Match.Where(function () {
           check(pair[0], type);
           return true;
@@ -98,9 +101,16 @@ Tinytest.add("check - check", function (test) {
   matches({}, {a: Match.Optional(Number)});
   matches({a: 1}, {a: Match.Optional(Number)});
   fails({a: true}, {a: Match.Optional(Number)});
+  matches({}, {a: Match.Maybe(Number)});
+  matches({a: 1}, {a: Match.Maybe(Number)});
+  fails({a: true}, {a: Match.Maybe(Number)});
   // Match.Optional means "or undefined" at the top level but "or absent" in
   // objects.
   fails({a: undefined}, {a: Match.Optional(Number)});
+  // Match.Maybe should behave the same as Match.Optional in objects
+  // including handling nulls
+  fails({a: undefined}, {a: Match.Maybe(Number)});
+  fails({a: null}, {a: Match.Maybe(Number)});
   var F = function () {
     this.x = 123;
   };