Warning. Closes #1958

API.md

@@ -58,6 +58,8 @@
  - [`any.unit(name)`](#anyunitname)
  - [`any.valid(...values)` - aliases: `only`, `equal`](#anyvalidvalues---aliases-only-equal)
  - [`any.validate(value, [options])`](#anyvalidatevalue-options)
+ - [`any.warn()`](#anywarn)
+ - [`any.warning(code, [context])`](#anywarningcode-context)
  - [`any.when(condition, options)`](#anywhencondition-options)
  - [`alternatives` - inherits from `Any`](#alternatives---inherits-from-any)
  - [`alternatives.try(schemas)`](#alternativestryschemas)
@@ -1013,8 +1015,8 @@ Applies a set of rule options to the current ruleset or last rule added where:
  rule overriding the first. Defaults to `false`.
  - `message` - a single message string or a messages object where each key is an error code and
  corresponding message string as value. The object is the same as the `messages` used as an option in
- [`any.validate()`](#anyvalidatevalue-options).
-  The strings can be plain messages or a message template.
+ [`any.validate()`](#anyvalidatevalue-options). The strings can be plain messages or a message template.
+ - `warn` - if `true`, turns any error generated by the ruleset to warnings.
 
 When applying rule options, the last rule (e.g. `min()`) is used unless there is an active ruleset defined
 (e.g. `$.min().max()`) in which case the options are applied to all the provided rules. Once `rules()` is
@@ -1191,6 +1193,45 @@ catch (err) {
 }
 ```
 
+#### `any.warn()`
+
+Same as [`rule({ warn: true })`](#anyruleoptions).
+
+Note that `warn()` will terminate the current ruleset and cannot be followed by another
+rule option. Use [`rule()`](#anyruleoptions) to apply multiple rule options.
+
+#### `any.warning(code, [context])`
+
+Generates a warning where:
+- `code` - the warning code. Can be an existing error code or a custom code. If a custom code is
+ used, a matching error message definition must be configured via [`any.message()`](#anymessagemessage),
+ [`any.prefs()`](#anyprefsoptions--aliases-preferences-options), or validation `messages` option.
+- `context` - optional context object.
+
+Warnings are reported separately from errors via the `warning` key when [`any.validate()`](#anyvalidatevalue-options)
+is called synchroniously, or called asynchroniously with the `warnings` option set to `true`.
+
+```js
+const schema = Joi.any()
+ .warning('custom.x', { w: 'world' })
+ .message({ 'custom.x': 'hello {#w}!' });
+
+const { value, error, warning } = schema.validate('anything');
+
+// value -> 'anything';
+// error -> null
+// warning -> { message: 'hello world!', details: [...] }
+
+// or
+
+try {
+ const { value, warning } = await schema.validate('anything', { warnings: true });
+ // value -> 'anything';
+ // warning -> { message: 'hello world!', details: [...] }
+}
+catch (err) { }
+```
+
 #### `any.when(condition, options)`
 
 Converts the type into an [`alternatives`](#alternatives---inherits-from-any) type with the

lib/common.js

@@ -33,7 +33,8 @@ exports.defaults = {
  noDefaults: false,
  presence: 'optional',
  skipFunctions: false,
- stripUnknown: false
+ stripUnknown: false,
+ warnings: false
 };
 
 

lib/schemas.js

@@ -34,7 +34,8 @@ exports.preferences = Joi.object({
  objects: Joi.boolean()
  })
  .or('arrays', 'objects')
- .allow(true, false)
+ .allow(true, false),
+ warnings: Joi.boolean()
 })
  .strict();
 

lib/types/any.js

@@ -251,11 +251,6 @@ module.exports = internals.Any = class {
  return this._flag('label', name);
  }
 
- message(message) {
-
- return this.rule({ message });
- }
-
  meta(meta) {
 
  Hoek.assert(meta !== undefined, 'Meta cannot be undefined');
@@ -279,6 +274,7 @@ module.exports = internals.Any = class {
 
  Hoek.assert(prefs.context === undefined, 'Cannot override context');
  Hoek.assert(prefs.externals === undefined, 'Cannot override externals');
+ Hoek.assert(prefs.warnings === undefined, 'Cannot override warnings');
 
  Common.checkPreferences(prefs);
 
@@ -297,44 +293,6 @@ module.exports = internals.Any = class {
  return this._flag('presence', 'required');
  }
 
- rule(options) {
-
- Common.assertOptions(options, ['keep', 'message']);
-
- Hoek.assert(this._ruleset !== false, 'Cannot apply rules to empty ruleset');
- const start = this._ruleset === null ? this._tests.length - 1 : this._ruleset;
- Hoek.assert(start >= 0 && start < this._tests.length, 'Cannot apply rules to empty ruleset');
-
- options = Object.assign({}, options); // Shallow cloned
-
- if (options.message) {
- options.message = Messages.compile(options.message);
- }
-
- const obj = this.clone();
-
- for (let i = start; i < obj._tests.length; ++i) {
- obj._tests[i] = Object.assign({}, obj._tests[i], options);
- }
-
- obj._ruleset = false;
- return obj;
- }
-
- get ruleset() {
-
- Hoek.assert(!this._inRuleset(), 'Cannot start a new ruleset without closing the previous one');
-
- const obj = this.clone();
- obj._ruleset = obj._tests.length;
- return obj;
- }
-
- get $() {
-
- return this.ruleset;
- }
-
  strict(enabled) {
 
  const obj = this.clone();
@@ -590,6 +548,49 @@ module.exports = internals.Any = class {
  return this._ids.labels(path);
  }
 
+ message(message) {
+
+ return this.rule({ message });
+ }
+
+ rule(options) {
+
+ Common.assertOptions(options, ['keep', 'message', 'warn']);
+
+ Hoek.assert(this._ruleset !== false, 'Cannot apply rules to empty ruleset');
+ const start = this._ruleset === null ? this._tests.length - 1 : this._ruleset;
+ Hoek.assert(start >= 0 && start < this._tests.length, 'Cannot apply rules to empty ruleset');
+
+ options = Object.assign({}, options); // Shallow cloned
+
+ if (options.message) {
+ options.message = Messages.compile(options.message);
+ }
+
+ const obj = this.clone();
+
+ for (let i = start; i < obj._tests.length; ++i) {
+ obj._tests[i] = Object.assign({}, obj._tests[i], options);
+ }
+
+ obj._ruleset = false;
+ return obj;
+ }
+
+ get ruleset() {
+
+ Hoek.assert(!this._inRuleset(), 'Cannot start a new ruleset without closing the previous one');
+
+ const obj = this.clone();
+ obj._ruleset = obj._tests.length;
+ return obj;
+ }
+
+ get $() {
+
+ return this.ruleset;
+ }
+
  tailor(targets) {
 
  Hoek.assert(!this._inRuleset(), 'Cannot tailor inside a ruleset');
@@ -617,6 +618,18 @@ module.exports = internals.Any = class {
  return Validator.entry(value, this, options);
  }
 
+ warn() {
+
+ return this.rule({ warn: true });
+ }
+
+ warning(code, local) {
+
+ Hoek.assert(code && typeof code === 'string', 'Invalid warning code');
+
+ return this._rule('warning', { args: { code, local }, multi: true, warn: true });
+ }
+
  // Internals
 
  _default(flag, value, description) {
@@ -783,7 +796,12 @@ module.exports = internals.Any = class {
  obj._ruleset = null;
  }
 
- obj._tests.push({ rule, name, arg: options.args });
+ const test = { rule, name, arg: options.args };
+ if (rule.warn) {
+ test.warn = true;
+ }
+
+ obj._tests.push(test);
 
  return obj;
  }
@@ -895,4 +913,8 @@ internals.Any.prototype._casts = {
 
 internals.Any.prototype._rules = {
 
+ warning: function (value, helpers, { code, local }) {
+
+ return helpers.error(code, local);
+ }
 };

lib/validator.js

@@ -6,7 +6,9 @@ const Common = require('./common');
 const Errors = require('./errors');
 
 
-const internals = {};
+const internals = {
+ result: Symbol('result')
+};
 
 
 exports.entry = function (value, schema, prefs) {
@@ -15,29 +17,37 @@ exports.entry = function (value, schema, prefs) {
  Common.checkPreferences(prefs);
  }
 
- const mainstay = { externals: [] };
+ const mainstay = { externals: [], warnings: [] };
  const settings = Common.preferences(Common.defaults, prefs);
  const state = schema._stateEntry({ mainstay });
  const result = exports.validate(value, schema, state, settings);
  const error = Errors.process(result.errors, value);
 
  Hoek.assert(!mainstay.externals.length || settings.externals, 'Cannot validate a schema with external rules without the externals flag');
 
+ this.value = value;
+ this.error = error;
+
+ const outcome = { value: result.value, error };
+ if (mainstay.warnings.length) {
+ outcome.warning = Errors.details(mainstay.warnings);
+ }
+
  if (error ||
  !mainstay.externals.length) {
 
- return new internals.Promise(result.value, error);
+ return new internals.Promise(outcome, settings);
  }
 
- return internals.externals(mainstay.externals, result.value);
+ return internals.externals(mainstay.externals, outcome, settings);
 };
 
 
-internals.externals = function (externals, final) {
+internals.externals = function (externals, outcome, prefs) {
 
  return new Promise(async (resolve, reject) => {
 
- let root = final;
+ let root = outcome.value;
 
  for (const { external, path, label } of externals) {
  let value = root;
@@ -72,7 +82,7 @@ internals.externals = function (externals, final) {
  }
  }
 
- resolve(root);
+ resolve(prefs.warnings ? Object.assign(outcome, { value: root }) : root);
  });
 };
 
@@ -260,29 +270,46 @@ exports.validate = function (value, schema, state, prefs) {
  ret = ret || schema._rules[rule.rule](value, helpers, args, rule); // Use ret if already set to error
  }
 
- if (ret instanceof Errors.Report) {
- internals.error(ret, test);
- if (prefs.abortEarly) {
- return internals.finalize(value, schema, original, [ret], state, prefs);
+ const result = internals.rule(ret, test);
+ if (result.errors) {
+ if (test.warn) {
+ state.mainstay.warnings.push(...result.errors);
+ continue;
  }
 
- errors.push(ret);
- }
- else if (Array.isArray(ret) && // Array implies not abortEarly
- ret[0] instanceof Errors.Report) {
+ if (prefs.abortEarly) {
+ return internals.finalize(value, schema, original, result.errors, state, prefs);
+ }
 
- ret.forEach((report) => internals.error(report, test));
- errors.push(...ret);
+ errors.push(...result.errors);
  }
  else {
- value = ret;
+ value = result.value;
  }
  }
 
  return internals.finalize(value, schema, original, errors, state, prefs);
 };
 
 
+internals.rule = function (ret, test) {
+
+ if (ret instanceof Errors.Report) {
+ internals.error(ret, test);
+ return { errors: [ret] };
+ }
+
+ if (Array.isArray(ret) &&
+ ret[0] instanceof Errors.Report) {
+
+ ret.forEach((report) => internals.error(report, test));
+ return { errors: ret };
+ }
+
+ return { value: ret };
+};
+
+
 internals.error = function (report, { message }) {
 
  if (message) {
@@ -448,10 +475,10 @@ internals.trim = function (value, schema) {
 
 internals.Promise = class {
 
- constructor(value, errors) {
+ constructor(result, prefs) {
 
- this.value = value;
- this.error = errors;
+ Object.assign(this, result);
+ this[internals.result] = prefs.warnings ? result : result.value;
  }
 
  then(resolve, reject) {
@@ -460,7 +487,7 @@ internals.Promise = class {
  return Promise.reject(this.error).catch(reject);
  }
 
- return Promise.resolve(this.value).then(resolve);
+ return Promise.resolve(this[internals.result]).then(resolve);
  }
 
  catch(reject) {
@@ -469,6 +496,6 @@ internals.Promise = class {
  return Promise.reject(this.error).catch(reject);
  }
 
- return Promise.resolve(this.value);
+ return Promise.resolve(this[internals.result]);
  }
 };