vest 4.0.0 → 4.0.2-dev-72921c

package/dist/umd/vest.development.js

@@ -1,20 +1,326 @@
 (function (global, factory) {
-  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('n4s'), require('context')) :
-  typeof define === 'function' && define.amd ? define(['exports', 'n4s', 'context'], factory) :
-  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.vest = {}, global.n4s, global.context));
-}(this, (function (exports, n4s, context$1) { 'use strict';
+  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
+  typeof define === 'function' && define.amd ? define(['exports'], factory) :
+  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.vest = {}));
+}(this, (function (exports) { 'use strict';
 
   var assign = Object.assign;
 
+  function isFunction(value) {
+      return typeof value === 'function';
+  }
+
+  function bindNot(fn) {
+      return function () {
+          var args = [];
+          for (var _i = 0; _i < arguments.length; _i++) {
+              args[_i] = arguments[_i];
+          }
+          return !fn.apply(void 0, args);
+      };
+  }
+
+  function isNull(value) {
+      return value === null;
+  }
+  var isNotNull = bindNot(isNull);
+
+  function isUndefined(value) {
+      return value === undefined;
+  }
+  var isNotUndefined = bindNot(isUndefined);
+
+  function isNullish(value) {
+      return isNull(value) || isUndefined(value);
+  }
+  var isNotNullish = bindNot(isNullish);
+
+  function isStringValue(v) {
+      return String(v) === v;
+  }
+
+  function endsWith(value, arg1) {
+      return isStringValue(value) && isStringValue(arg1) && value.endsWith(arg1);
+  }
+  var doesNotEndWith = bindNot(endsWith);
+
+  function equals(value, arg1) {
+      return value === arg1;
+  }
+  var notEquals = bindNot(equals);
+
+  function isNumeric(value) {
+      var str = String(value);
+      var num = Number(value);
+      var result = !isNaN(parseFloat(str)) && !isNaN(Number(value)) && isFinite(num);
+      return Boolean(result);
+  }
+  var isNotNumeric = bindNot(isNumeric);
+
+  function greaterThan(value, gt) {
+      return isNumeric(value) && isNumeric(gt) && Number(value) > Number(gt);
+  }
+
+  function greaterThanOrEquals(value, gte) {
+      return isNumeric(value) && isNumeric(gte) && Number(value) >= Number(gte);
+  }
+
+  // The module is named "isArrayValue" since it
+  // is conflicting with a nested npm dependency.
+  // We may need to revisit this in the future.
+  function isArray(value) {
+      return Boolean(Array.isArray(value));
+  }
+  var isNotArray = bindNot(isArray);
+
+  function inside(value, arg1) {
+      if (isArray(arg1)) {
+          return arg1.indexOf(value) !== -1;
+      }
+      // both value and arg1 are strings
+      if (isStringValue(arg1) && isStringValue(value)) {
+          return arg1.indexOf(value) !== -1;
+      }
+      return false;
+  }
+  var notInside = bindNot(inside);
+
+  function lessThanOrEquals(value, lte) {
+      return isNumeric(value) && isNumeric(lte) && Number(value) <= Number(lte);
+  }
+
+  function isBetween(value, min, max) {
+      return greaterThanOrEquals(value, min) && lessThanOrEquals(value, max);
+  }
+  var isNotBetween = bindNot(isBetween);
+
+  function isBlank(value) {
+      return isNullish(value) || (isStringValue(value) && !value.trim());
+  }
+  var isNotBlank = bindNot(isBlank);
+
+  function isBoolean(value) {
+      return !!value === value;
+  }
+
+  var isNotBoolean = bindNot(isBoolean);
+
   /**
-   * @returns a unique numeric id.
+   * A safe hasOwnProperty access
    */
-  var genId = (function (n) { return function () {
-      return "" + n++;
-  }; })(0);
+  function hasOwnProperty(obj, key) {
+      return Object.prototype.hasOwnProperty.call(obj, key);
+  }
 
-  function isFunction(value) {
-      return typeof value === 'function';
+  function isNumber(value) {
+      return Boolean(typeof value === 'number');
+  }
+  var isNotNumber = bindNot(isNumber);
+
+  function lengthEquals(value, arg1) {
+      return value.length === Number(arg1);
+  }
+  var lengthNotEquals = bindNot(lengthEquals);
+
+  function isEmpty(value) {
+      if (!value) {
+          return true;
+      }
+      else if (isNumber(value)) {
+          return value === 0;
+      }
+      else if (hasOwnProperty(value, 'length')) {
+          return lengthEquals(value, 0);
+      }
+      else if (typeof value === 'object') {
+          return lengthEquals(Object.keys(value), 0);
+      }
+      return true;
+  }
+  var isNotEmpty = bindNot(isEmpty);
+
+  /**
+   * Validates that a given value is an even number
+   */
+  var isEven = function (value) {
+      if (isNumeric(value)) {
+          return value % 2 === 0;
+      }
+      return false;
+  };
+
+  function isNaN$1(value) {
+      return Number.isNaN(value);
+  }
+  var isNotNaN = bindNot(isNaN$1);
+
+  function isNegative(value) {
+      if (isNumeric(value)) {
+          return Number(value) < 0;
+      }
+      return false;
+  }
+  var isPositive = bindNot(isNegative);
+
+  /**
+   * Validates that a given value is an odd number
+   */
+  var isOdd = function (value) {
+      if (isNumeric(value)) {
+          return value % 2 !== 0;
+      }
+      return false;
+  };
+
+  var isNotString = bindNot(isStringValue);
+
+  function isTruthy(value) {
+      return !!value;
+  }
+  var isFalsy = bindNot(isTruthy);
+
+  function isValueOf(value, objectToCheck) {
+      if (isNullish(objectToCheck)) {
+          return false;
+      }
+      for (var key in objectToCheck) {
+          if (objectToCheck[key] === value) {
+              return true;
+          }
+      }
+      return false;
+  }
+  var isNotValueOf = bindNot(isValueOf);
+
+  function lessThan(value, lt) {
+      return isNumeric(value) && isNumeric(lt) && Number(value) < Number(lt);
+  }
+
+  function longerThan(value, arg1) {
+      return value.length > Number(arg1);
+  }
+
+  function longerThanOrEquals(value, arg1) {
+      return value.length >= Number(arg1);
+  }
+
+  function matches(value, regex) {
+      if (regex instanceof RegExp) {
+          return regex.test(value);
+      }
+      else if (isStringValue(regex)) {
+          return new RegExp(regex).test(value);
+      }
+      else {
+          return false;
+      }
+  }
+  var notMatches = bindNot(matches);
+
+  function numberEquals(value, eq) {
+      return isNumeric(value) && isNumeric(eq) && Number(value) === Number(eq);
+  }
+  var numberNotEquals = bindNot(numberEquals);
+
+  function condition(value, callback) {
+      try {
+          return callback(value);
+      }
+      catch (_a) {
+          return false;
+      }
+  }
+
+  function shorterThan(value, arg1) {
+      return value.length < Number(arg1);
+  }
+
+  function shorterThanOrEquals(value, arg1) {
+      return value.length <= Number(arg1);
+  }
+
+  function startsWith(value, arg1) {
+      return isStringValue(value) && isStringValue(arg1) && value.startsWith(arg1);
+  }
+  var doesNotStartWith = bindNot(startsWith);
+
+  // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, max-lines-per-function
+  function rules() {
+      return {
+          condition: condition,
+          doesNotEndWith: doesNotEndWith,
+          doesNotStartWith: doesNotStartWith,
+          endsWith: endsWith,
+          equals: equals,
+          greaterThan: greaterThan,
+          greaterThanOrEquals: greaterThanOrEquals,
+          gt: greaterThan,
+          gte: greaterThanOrEquals,
+          inside: inside,
+          isArray: isArray,
+          isBetween: isBetween,
+          isBlank: isBlank,
+          isBoolean: isBoolean,
+          isEmpty: isEmpty,
+          isEven: isEven,
+          isFalsy: isFalsy,
+          isNaN: isNaN$1,
+          isNegative: isNegative,
+          isNotArray: isNotArray,
+          isNotBetween: isNotBetween,
+          isNotBlank: isNotBlank,
+          isNotBoolean: isNotBoolean,
+          isNotEmpty: isNotEmpty,
+          isNotNaN: isNotNaN,
+          isNotNull: isNotNull,
+          isNotNullish: isNotNullish,
+          isNotNumber: isNotNumber,
+          isNotNumeric: isNotNumeric,
+          isNotString: isNotString,
+          isNotUndefined: isNotUndefined,
+          isNotValueOf: isNotValueOf,
+          isNull: isNull,
+          isNullish: isNullish,
+          isNumber: isNumber,
+          isNumeric: isNumeric,
+          isOdd: isOdd,
+          isPositive: isPositive,
+          isString: isStringValue,
+          isTruthy: isTruthy,
+          isUndefined: isUndefined,
+          isValueOf: isValueOf,
+          lengthEquals: lengthEquals,
+          lengthNotEquals: lengthNotEquals,
+          lessThan: lessThan,
+          lessThanOrEquals: lessThanOrEquals,
+          longerThan: longerThan,
+          longerThanOrEquals: longerThanOrEquals,
+          lt: lessThan,
+          lte: lessThanOrEquals,
+          matches: matches,
+          notEquals: notEquals,
+          notInside: notInside,
+          notMatches: notMatches,
+          numberEquals: numberEquals,
+          numberNotEquals: numberNotEquals,
+          shorterThan: shorterThan,
+          shorterThanOrEquals: shorterThanOrEquals,
+          startsWith: startsWith
+      };
+  }
+
+  var baseRules = rules();
+  function getRule(ruleName) {
+      return baseRules[ruleName];
+  }
+
+  function eachEnforceRule(action) {
+      for (var ruleName in baseRules) {
+          var ruleFn = getRule(ruleName);
+          if (isFunction(ruleFn)) {
+              action(ruleName, ruleFn);
+          }
+      }
   }
 
   function optionalFunctionValue(value) {
@@ -42,6 +348,344 @@
       }, 0);
   }
 
+  // eslint-disable-next-line max-lines-per-function
+  function createContext(init) {
+      var storage = { ancestry: [] };
+      return {
+          bind: bind,
+          run: run,
+          use: use,
+          useX: useX
+      };
+      function useX(errorMessage) {
+          var _a;
+          return ((_a = storage.ctx) !== null && _a !== void 0 ? _a : throwError(defaultTo(errorMessage, 'Context was used after it was closed')));
+      }
+      function run(ctxRef, fn) {
+          var _a;
+          var parentContext = use();
+          var out = assign({}, parentContext ? parentContext : {}, (_a = optionalFunctionValue(init, ctxRef, parentContext)) !== null && _a !== void 0 ? _a : ctxRef);
+          var ctx = set(Object.freeze(out));
+          storage.ancestry.unshift(ctx);
+          var res = fn(ctx);
+          clear();
+          return res;
+      }
+      function bind(ctxRef, fn) {
+          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+          // @ts-ignore - this one's pretty hard to get right
+          var returnedFn = function () {
+              var runTimeArgs = [];
+              for (var _i = 0; _i < arguments.length; _i++) {
+                  runTimeArgs[_i] = arguments[_i];
+              }
+              return run(ctxRef, function () {
+                  return fn.apply(void 0, runTimeArgs);
+              });
+          };
+          return returnedFn;
+      }
+      function use() {
+          return storage.ctx;
+      }
+      function set(value) {
+          return (storage.ctx = value);
+      }
+      function clear() {
+          var _a;
+          storage.ancestry.shift();
+          set((_a = storage.ancestry[0]) !== null && _a !== void 0 ? _a : null);
+      }
+  }
+
+  var ctx = createContext(function (ctxRef, parentContext) {
+      var base = {
+          value: ctxRef.value,
+          meta: ctxRef.meta || {}
+      };
+      if (!parentContext) {
+          return assign(base, {
+              parent: emptyParent
+          });
+      }
+      else if (ctxRef.set) {
+          return assign(base, {
+              parent: function () { return stripContext(parentContext); }
+          });
+      }
+      return parentContext;
+  });
+  function stripContext(ctx) {
+      if (!ctx) {
+          return ctx;
+      }
+      return {
+          value: ctx.value,
+          meta: ctx.meta,
+          parent: ctx.parent
+      };
+  }
+  function emptyParent() {
+      return null;
+  }
+
+  /*! *****************************************************************************
+  Copyright (c) Microsoft Corporation.
+
+  Permission to use, copy, modify, and/or distribute this software for any
+  purpose with or without fee is hereby granted.
+
+  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+  REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+  AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+  LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+  OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+  PERFORMANCE OF THIS SOFTWARE.
+  ***************************************************************************** */
+
+  var __assign = function() {
+      __assign = Object.assign || function __assign(t) {
+          for (var s, i = 1, n = arguments.length; i < n; i++) {
+              s = arguments[i];
+              for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p)) t[p] = s[p];
+          }
+          return t;
+      };
+      return __assign.apply(this, arguments);
+  };
+
+  function __spreadArray(to, from, pack) {
+      if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+          if (ar || !(i in from)) {
+              if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+              ar[i] = from[i];
+          }
+      }
+      return to.concat(ar || Array.prototype.slice.call(from));
+  }
+
+  function isProxySupported() {
+      try {
+          return isFunction(Proxy);
+      }
+      catch (_a) {
+          return false;
+      }
+  }
+
+  function ruleReturn(pass, message) {
+      var output = { pass: pass };
+      if (message) {
+          output.message = message;
+      }
+      return output;
+  }
+  function passing() {
+      return ruleReturn(true);
+  }
+  function defaultToPassing(callback) {
+      return defaultTo(callback, passing());
+  }
+
+  /**
+   * Transform the result of a rule into a standard format
+   */
+  function transformResult(result, ruleName, value) {
+      var args = [];
+      for (var _i = 3; _i < arguments.length; _i++) {
+          args[_i - 3] = arguments[_i];
+      }
+      validateResult(result);
+      // if result is boolean
+      if (isBoolean(result)) {
+          return ruleReturn(result);
+      }
+      else {
+          return ruleReturn(result.pass, optionalFunctionValue.apply(void 0, __spreadArray([result.message, ruleName, value], args)));
+      }
+  }
+  function validateResult(result) {
+      // if result is boolean, or if result.pass is boolean
+      if (isBoolean(result) || (result && isBoolean(result.pass))) {
+          return;
+      }
+      throwError('Incorrect return value for rule: ' + JSON.stringify(result));
+  }
+
+  function enforceEager(value) {
+      var target = {};
+      if (!isProxySupported()) {
+          eachEnforceRule(function (ruleName, ruleFn) {
+              target[ruleName] = genRuleCall(target, ruleFn, ruleName);
+          });
+          return target;
+      }
+      var proxy = new Proxy(target, {
+          get: function (_, ruleName) {
+              var rule = getRule(ruleName);
+              if (rule) {
+                  return genRuleCall(proxy, rule, ruleName);
+              }
+          }
+      });
+      return proxy;
+      function genRuleCall(target, rule, ruleName) {
+          return function ruleCall() {
+              var args = [];
+              for (var _i = 0; _i < arguments.length; _i++) {
+                  args[_i] = arguments[_i];
+              }
+              var transformedResult = transformResult.apply(void 0, __spreadArray([ctx.run({ value: value }, function () { return rule.apply(void 0, __spreadArray([value], args)); }),
+                  ruleName,
+                  value], args));
+              if (!transformedResult.pass) {
+                  if (isEmpty(transformedResult.message)) {
+                      throwError("enforce/" + ruleName + " failed with " + JSON.stringify(value));
+                  }
+                  else {
+                      // Explicitly throw a string so that vest.test can pick it up as the validation error message
+                      throw transformedResult.message;
+                  }
+              }
+              return target;
+          };
+      }
+  }
+
+  function mapFirst(array, callback) {
+      var broke = false;
+      var breakoutValue = null;
+      for (var i = 0; i < array.length; i++) {
+          callback(array[i], breakout, i);
+          if (broke) {
+              return breakoutValue;
+          }
+      }
+      function breakout(value) {
+          broke = true;
+          breakoutValue = value;
+      }
+  }
+
+  // eslint-disable-next-line max-lines-per-function
+  function genEnforceLazy(key) {
+      var registeredRules = [];
+      var lazyMessage;
+      return addLazyRule(key);
+      // eslint-disable-next-line max-lines-per-function
+      function addLazyRule(ruleName) {
+          // eslint-disable-next-line max-lines-per-function
+          return function () {
+              var args = [];
+              for (var _i = 0; _i < arguments.length; _i++) {
+                  args[_i] = arguments[_i];
+              }
+              var rule = getRule(ruleName);
+              registeredRules.push(function (value) {
+                  return transformResult.apply(void 0, __spreadArray([rule.apply(void 0, __spreadArray([value], args)), ruleName, value], args));
+              });
+              var proxy = {
+                  run: function (value) {
+                      return defaultToPassing(mapFirst(registeredRules, function (rule, breakout) {
+                          var _a;
+                          var res = ctx.run({ value: value }, function () { return rule(value); });
+                          if (!res.pass) {
+                              breakout(ruleReturn(!!res.pass, (_a = optionalFunctionValue(lazyMessage, value, res.message)) !== null && _a !== void 0 ? _a : res.message));
+                          }
+                      }));
+                  },
+                  test: function (value) { return proxy.run(value).pass; },
+                  message: function (message) {
+                      if (message) {
+                          lazyMessage = message;
+                      }
+                      return proxy;
+                  }
+              };
+              if (!isProxySupported()) {
+                  eachEnforceRule(function (ruleName) {
+                      proxy[ruleName] = addLazyRule(ruleName);
+                  });
+                  return proxy;
+              }
+              // reassigning the proxy here is not pretty
+              // but it's a cleaner way of getting `run` and `test` for free
+              proxy = new Proxy(proxy, {
+                  get: function (target, key) {
+                      if (getRule(key)) {
+                          return addLazyRule(key);
+                      }
+                      return target[key]; // already has `run` and `test` on it
+                  }
+              });
+              return proxy;
+          };
+      }
+  }
+
+  /**
+   * Enforce is quite complicated, I want to explain it in detail.
+   * It is dynamic in nature, so a lot of proxy objects are involved.
+   *
+   * Enforce has two main interfaces
+   * 1. eager
+   * 2. lazy
+   *
+   * The eager interface is the most commonly used, and the easier to understand.
+   * It throws an error when a rule is not satisfied.
+   * The eager interface is declared in enforceEager.ts and it is quite simple to understand.
+   * enforce is called with a value, and the return value is a proxy object that points back to all the rules.
+   * When a rule is called, the value is mapped as its first argument, and if the rule passes, the same
+   * proxy object is returned. Otherwise, an error is thrown.
+   *
+   * The lazy interface works quite differently. It is declared in genEnforceLazy.ts.
+   * Rather than calling enforce directly, the lazy interface has all the rules as "methods" (only by proxy).
+   * Calling the first function in the chain will initialize an array of calls. It stores the different rule calls
+   * and the parameters passed to them. None of the rules are called yet.
+   * The rules are only invoked in sequence once either of these chained functions are called:
+   * 1. test(value)
+   * 2. run(value)
+   *
+   * Calling run or test will call all the rules in sequence, with the difference that test will only return a boolean value,
+   * while run will return an object with the validation result and an optional message created by the rule.
+   */
+  function genEnforce() {
+      var target = {
+          context: function () { return ctx.useX(); },
+          extend: function (customRules) {
+              assign(baseRules, customRules);
+          }
+      };
+      if (!isProxySupported()) {
+          eachEnforceRule(function (ruleName) {
+              // Only on the first rule access - start the chain of calls
+              target[ruleName] = genEnforceLazy(ruleName);
+          });
+          return assign(enforceEager, target);
+      }
+      return new Proxy(assign(enforceEager, target), {
+          get: function (target, key) {
+              if (key in target) {
+                  return target[key];
+              }
+              if (!getRule(key)) {
+                  return;
+              }
+              // Only on the first rule access - start the chain of calls
+              return genEnforceLazy(key);
+          }
+      });
+  }
+  var enforce = genEnforce();
+
+  /**
+   * @returns a unique numeric id.
+   */
+  var genId = (function (n) { return function () {
+      return "" + n++;
+  }; })(0);
+
   // eslint-disable-next-line max-lines-per-function
   function createState(onStateChange) {
       var state = {
@@ -178,7 +822,7 @@
       };
   }
 
-  var context = context$1.createContext(function (ctxRef, parentContext) {
+  var context = createContext(function (ctxRef, parentContext) {
       return parentContext
           ? null
           : assign({}, {
@@ -186,6 +830,7 @@
                   tests: {},
                   groups: {}
               },
+              inclusion: {},
               isolate: {
                   type: IsolateTypes.DEFAULT,
                   keys: {
@@ -197,28 +842,6 @@
           }, ctxRef);
   });
 
-  function bindNot(fn) {
-      return function () {
-          var args = [];
-          for (var _i = 0; _i < arguments.length; _i++) {
-              args[_i] = arguments[_i];
-          }
-          return !fn.apply(void 0, args);
-      };
-  }
-
-  // The module is named "isArrayValue" since it
-  // is conflicting with a nested npm dependency.
-  // We may need to revisit this in the future.
-  function isArray(value) {
-      return Boolean(Array.isArray(value));
-  }
-
-  function isNull(value) {
-      return value === null;
-  }
-  var isNotNull = bindNot(isNull);
-
   // This is sort of a map/filter in one function.
   // Normally, behaves like a nested-array map
   // Returning `null` will drop the element from the array
@@ -264,31 +887,11 @@
       return current;
   }
 
-  function isUndefined(value) {
-      return value === undefined;
-  }
-
-  function isNullish(value) {
-      return isNull(value) || isUndefined(value);
-  }
-
-  function isStringValue(v) {
-      return String(v) === v;
-  }
-
   function shouldUseErrorAsMessage(message, error) {
       // kind of cheating with this safe guard, but it does the job
       return isUndefined(message) && isStringValue(error);
   }
 
-  function lengthEquals(value, arg1) {
-      return value.length === Number(arg1);
-  }
-
-  function longerThan(value, arg1) {
-      return value.length > Number(arg1);
-  }
-
   /**
    * Creates a cache function
    */
@@ -604,34 +1207,6 @@
       return context.useX().isolate.type === IsolateTypes.EACH;
   }
 
-  /**
-   * A safe hasOwnProperty access
-   */
-  function hasOwnProperty(obj, key) {
-      return Object.prototype.hasOwnProperty.call(obj, key);
-  }
-
-  function isNumber(value) {
-      return Boolean(typeof value === 'number');
-  }
-
-  function isEmpty(value) {
-      if (!value) {
-          return true;
-      }
-      else if (isNumber(value)) {
-          return value === 0;
-      }
-      else if (hasOwnProperty(value, 'length')) {
-          return lengthEquals(value, 0);
-      }
-      else if (typeof value === 'object') {
-          return lengthEquals(Object.keys(value), 0);
-      }
-      return true;
-  }
-  var isNotEmpty = bindNot(isEmpty);
-
   function nonMatchingFieldName(testObject, fieldName) {
       return !!fieldName && !matchingFieldName(testObject, fieldName);
   }
@@ -719,42 +1294,6 @@
       return testKey;
   }
 
-  /*! *****************************************************************************
-  Copyright (c) Microsoft Corporation.
-
-  Permission to use, copy, modify, and/or distribute this software for any
-  purpose with or without fee is hereby granted.
-
-  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-  REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-  AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-  LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-  OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-  PERFORMANCE OF THIS SOFTWARE.
-  ***************************************************************************** */
-
-  var __assign = function() {
-      __assign = Object.assign || function __assign(t) {
-          for (var s, i = 1, n = arguments.length; i < n; i++) {
-              s = arguments[i];
-              for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p)) t[p] = s[p];
-          }
-          return t;
-      };
-      return __assign.apply(this, arguments);
-  };
-
-  function __spreadArray(to, from, pack) {
-      if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-          if (ar || !(i in from)) {
-              if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-              ar[i] = from[i];
-          }
-      }
-      return to.concat(ar || from);
-  }
-
   function either(a, b) {
       return !!a !== !!b;
   }
@@ -1263,13 +1802,14 @@
       return !!context.useX().skipped;
   }
   //Checks whether a certain test profile excluded by any of the exclusion groups.
-  // eslint-disable-next-line complexity, max-statements
+  // eslint-disable-next-line complexity, max-statements, max-lines-per-function
   function isExcluded(testObject) {
       var fieldName = testObject.fieldName, groupName = testObject.groupName;
       if (isExcludedIndividually())
           return true;
       var context$1 = context.useX();
       var exclusion = context$1.exclusion;
+      var inclusion = context$1.inclusion;
       var keyTests = exclusion.tests;
       var testValue = keyTests[fieldName];
       // if test is skipped
@@ -1299,8 +1839,12 @@
       if (isTestIncluded)
           return false;
       // If there is _ANY_ `only`ed test (and we already know this one isn't) return true
-      // Otherwise return false
-      return hasIncludedTests(keyTests);
+      if (hasIncludedTests(keyTests)) {
+          // Check if inclusion rules for this field (`include` hook)
+          return !optionalFunctionValue(inclusion[fieldName]);
+      }
+      // We're done here. This field is not excluded
+      return false;
   }
   // eslint-disable-next-line max-statements
   function isMissingFromIncludedGroup(groupName) {
@@ -1405,6 +1949,29 @@
       throwError("Wrong arguments passed to group. Group " + error + ".");
   }
 
+  function include(fieldName) {
+      var context$1 = context.useX();
+      var inclusion = context$1.inclusion, exclusion = context$1.exclusion;
+      if (!fieldName) {
+          return { when: when };
+      }
+      inclusion[fieldName] = defaultTo(exclusion.tests[fieldName], true);
+      return { when: when };
+      function when(condition) {
+          var context$1 = context.useX();
+          var inclusion = context$1.inclusion, exclusion = context$1.exclusion;
+          inclusion[fieldName] = function () {
+              if (hasOwnProperty(exclusion.tests, fieldName)) {
+                  return defaultTo(exclusion.tests[fieldName], true);
+              }
+              if (isStringValue(condition)) {
+                  return Boolean(exclusion.tests[condition]);
+              }
+              return optionalFunctionValue(condition, optionalFunctionValue(produceDraft));
+          };
+      }
+  }
+
   /**
    * Conditionally omits tests from the suite.
    *
@@ -1472,8 +2039,6 @@
       });
   }
 
-  var isNotString = bindNot(isStringValue);
-
   function isPromise(value) {
       return value && isFunction(value.then);
   }
@@ -1683,6 +2248,7 @@
       }
   }
 
+  /* eslint-disable jest/valid-title */
   // eslint-disable-next-line max-lines-per-function
   function bindTestMemo(test) {
       var cache = createCache(100); // arbitrary cache size
@@ -1760,19 +2326,15 @@
       ctx.currentTest.warn();
   }
 
-  var VERSION = "3.3.0";
+  var VERSION = "4.0.2-dev-72921c";
 
-  Object.defineProperty(exports, 'enforce', {
-    enumerable: true,
-    get: function () {
-      return n4s.enforce;
-    }
-  });
   exports.VERSION = VERSION;
   exports.context = context;
   exports.create = create;
   exports.each = each;
+  exports.enforce = enforce;
   exports.group = group;
+  exports.include = include;
   exports.omitWhen = omitWhen;
   exports.only = only;
   exports.optional = optional;