joi 7.2.0 → 7.3.0

package/API.md

@@ -1,5 +1,5 @@
 <!-- version -->
-# 7.2.0 API Reference
+# 7.3.0 API Reference
 <!-- versionstop -->
 
 <img src="https://raw.github.com/hapijs/joi/master/images/validation.png" align="right" />
@@ -12,6 +12,7 @@
   - [`assert(value, schema, [message])`](#assertvalue-schema-message)
   - [`attempt(value, schema, [message])`](#attemptvalue-schema-message)
   - [`isRef(ref)`](#isrefref)
+  - [`reach(schema, path)`](#reachschema-path)
   - [`any`](#any)
     - [`any.allow(value)`](#anyallowvalue)
     - [`any.valid(value)` - aliases: `only`, `equal`](#anyvalidvalue---aliases-only-equal)
@@ -131,7 +132,11 @@ Validates a value using the given schema and options where:
   - `allowUnknown` - when `true`, allows object to contain unknown keys which are ignored. Defaults to `false`.
   - `skipFunctions` - when `true`, ignores unknown keys with a function value. Defaults to `false`.
   - `stripUnknown` - when `true`, unknown keys are deleted (only when value is an object or an array). Defaults to `false`.
-  - `language` - overrides individual error messages, when `'label'` is set, it overrides the key name in the error message. Defaults to no override (`{}`).
+  - `language` - overrides individual error messages. Defaults to no override (`{}`). Messages apply the following rules :
+    - variables are put between curly braces like `{{var}}`, if prefixed by a `!` like `{{!var}}`, it will be html escaped
+    - strings are always preceeded by the key name, unless a `{{key}}` is found elsewhere or if the string is prefixed by a `!!`
+    - when `'label'` is set, it overrides the key name in the error message
+    - to better understand the structure of the language, it's advised to have a look at the existing messages you want to override [here](lib/language.js)
   - `presence` - sets the default presence requirements. Supported modes: `'optional'`, `'required'`, and `'forbidden'`.
     Defaults to `'optional'`.
   - `context` - provides an external data set to be used in [references](#refkey-options). Can only be set as an external option to
@@ -219,6 +224,15 @@ const ref = Joi.ref('a');
 Joi.isRef(ref); // returns true
 ```
 
+### `reach(schema, path)`
+
+Get a sub-schema of an existing schema based on a path. Path separatar is a dot (`.`).
+
+```js
+const schema = Joi.object({ foo: Joi.object({ bar: Joi.number() }});
+const number = Joi.reach(schema, 'foo.bar');
+```
+
 ### `any`
 
 Generates a schema object that matches any data type.
@@ -498,7 +512,7 @@ Considers anything that matches the schema to be empty (`undefined`).
 - `schema` - any object or joi schema to match. An undefined schema unsets that rule.
 
 ```js
-const schema = Joi.string().empty('');
+let schema = Joi.string().empty('');
 schema.validate(''); // returns { error: null, value: undefined }
 schema = schema.empty();
 schema.validate(''); // returns { error: "value" is not allowed to be empty, value: '' }
@@ -520,7 +534,7 @@ array.validate(['a', 'b', 'a'], (err, value) => { });
 Allow this array to be sparse. `enabled` can be used with a falsy value to go back to the default behavior.
 
 ```javascript
-const schema = Joi.array().sparse(); // undefined values are now allowed
+let schema = Joi.array().sparse(); // undefined values are now allowed
 schema = schema.sparse(false); // undefined values are now denied
 ```
 
@@ -1260,7 +1274,7 @@ const schema = Joi.object({
 
 Specifies the maximum number of string characters where:
 - `limit` - the maximum number of string characters allowed.
-- `encoding` - is specified, the string length is calculated in bytes using the provided encoding.
+- `encoding` - if specified, the string length is calculated in bytes using the provided encoding.
 
 ```javascript
 const schema = Joi.string().max(10);
@@ -1384,6 +1398,7 @@ Requires the string value to be a valid [RFC 3986](http://tools.ietf.org/html/rf
 
 - `options` - optional settings:
     - `scheme` - Specifies one or more acceptable Schemes, should only include the scheme name. Can be an Array or String (strings are automatically escaped for use in a Regular Expression).
+    - `allowRelative` - Allow relative URIs. Defaults to `false`.
 
 ```javascript
 // Accept git or git http/https

package/README.md

@@ -6,11 +6,19 @@ Object schema description language and validator for JavaScript objects.
 [![Build Status](https://secure.travis-ci.org/hapijs/joi.svg)](http://travis-ci.org/hapijs/joi)
 [![Dependencies Status](https://david-dm.org/hapijs/joi.svg)](https://david-dm.org/hapijs/joi)
 [![DevDependencies Status](https://david-dm.org/hapijs/joi/dev-status.svg)](https://david-dm.org/hapijs/joi#info=devDependencies)
+[![Known Vulnerabilities](https://snyk.io/test/npm/joi/badge.svg)](https://snyk.io/test/npm/joi)
 
 [![Join the chat at https://gitter.im/hapijs/joi](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/hapijs/joi?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 Lead Maintainer: [Nicolas Morel](https://github.com/marsup)
 
+# Introduction
+
+Imagine you run facebook and you want visitors to sign up on the website with real names and not something like `l337_p@nda` in the first name field. How would you define the limitations of what can be inputted and validate it against the set rules? 
+
+This is joi, joi allows you to create *blueprints* or *schemas* for JavaScript objects (an object that stores information) to ensure *validation* of key information.
+
+
 # Example
 
 ```javascript
@@ -87,4 +95,4 @@ When validating a schema:
 * Rules are defined in an additive fashion and evaluated in order after whitelist and blacklist checks.
 
 # API
-See the [API Reference](API.md).
+See the [API Reference](https://github.com/hapijs/joi/blob/v7.3.0/API.md).

package/generate-readme-toc.js

@@ -9,13 +9,18 @@ const Package = require('./package.json');
 // Declare internals
 
 const internals = {
-    filename: './API.md'
+    api: {
+        filename: './API.md',
+        contents: Fs.readFileSync('./API.md', 'utf8')
+    },
+    readme: {
+        filename: './README.md',
+        contents: Fs.readFileSync('./README.md', 'utf8')
+    }
 };
 
+internals.generateToc = function () {
 
-internals.generate = function () {
-
-    const api = Fs.readFileSync(internals.filename, 'utf8');
     const tocOptions = {
         bullets: '-',
         slugify: function (text) {
@@ -26,10 +31,19 @@ internals.generate = function () {
         }
     };
 
-    const output = Toc.insert(api, tocOptions)
-        .replace(/<!-- version -->(.|\n)*<!-- versionstop -->/, '<!-- version -->\n# ' + Package.version + ' API Reference\n<!-- versionstop -->');
+    const api = Toc.insert(internals.api.contents, tocOptions)
+        .replace(/<!-- version -->(.|\n)*<!-- versionstop -->/, `<!-- version -->\n# ${Package.version} API Reference\n<!-- versionstop -->`);
+
+    Fs.writeFileSync(internals.api.filename, api);
+};
+
+internals.generateLink = function () {
+    // create absolute URL for versioned docs
+    const readme = internals.readme.contents
+        .replace(/\[API Reference\]\(.*\)/gi, `[API Reference](${Package.homepage || ''}/blob/v${Package.version}/${internals.api.filename.substr(2)})`);
 
-    Fs.writeFileSync(internals.filename, output);
+    Fs.writeFileSync(internals.readme.filename, readme);
 };
 
-internals.generate();
+internals.generateToc();
+internals.generateLink();

package/lib/any.js

@@ -219,8 +219,6 @@ internals.Any.prototype.concat = function (schema) {
 
 internals.Any.prototype._test = function (name, arg, func) {
 
-    Hoek.assert(!this._flags.allowOnly, 'Cannot define rules when valid values specified');
-
     const obj = this.clone();
     obj._tests.push({ func, name, arg });
     return obj;
@@ -279,8 +277,6 @@ internals.Any.prototype.allow = function () {
 
 internals.Any.prototype.valid = internals.Any.prototype.only = internals.Any.prototype.equal = function () {
 
-    Hoek.assert(!this._tests.length, 'Cannot set valid values when rules specified');
-
     const obj = this.allow.apply(this, arguments);
     obj._flags.allowOnly = true;
     return obj;
@@ -769,10 +765,7 @@ internals.Set = function () {
 
 internals.Set.prototype.add = function (value, refs) {
 
-    Hoek.assert(value === null || value === undefined || value instanceof Date || Buffer.isBuffer(value) || Ref.isRef(value) || (typeof value !== 'function' && typeof value !== 'object'), 'Value cannot be an object or function');
-
-    if (typeof value !== 'function' &&
-        this.has(value, null, null, false)) {
+    if (!Ref.isRef(value) && this.has(value, null, null, false)) {
 
         return;
     }

package/lib/index.js

@@ -2,6 +2,7 @@
 
 // Load modules
 
+const Hoek = require('hoek');
 const Any = require('./any');
 const Cast = require('./cast');
 const Ref = require('./ref');
@@ -147,6 +148,30 @@ internals.root = function () {
         return result.value;
     };
 
+    root.reach = function (schema, path) {
+
+        Hoek.assert(schema && schema.isJoi, 'you must provide a joi schema');
+        Hoek.assert(typeof path === 'string', 'path must be a string');
+
+        if (path === '') {
+            return schema;
+        }
+
+        const parts = path.split('.');
+        const children = schema._inner.children;
+        if (!children) {
+            return;
+        }
+
+        const key = parts[0];
+        for (let i = 0; i < children.length; ++i) {
+            const child = children[i];
+            if (child.key === key) {
+                return this.reach(child.schema, path.substr(key.length + 1));
+            }
+        }
+    };
+
     return root;
 };
 

package/lib/object.js

@@ -145,6 +145,11 @@ internals.Object.prototype._base = function (value, state, options) {
 
     const unprocessed = Hoek.mapToObject(Object.keys(target));
 
+    // Children mustn't inherit the current label if it exists
+    const childOptions = options.language && options.language.label ?
+        Hoek.applyToDefaults(options, { language: { label: null } }, true) :
+        options;
+
     if (this._inner.children) {
         for (let i = 0; i < this._inner.children.length; ++i) {
             const child = this._inner.children[i];
@@ -154,9 +159,9 @@ internals.Object.prototype._base = function (value, state, options) {
             delete unprocessed[key];
 
             const localState = { key, path: (state.path || '') + (state.path && key ? '.' : '') + key, parent: target, reference: state.reference };
-            const result = child.schema._validate(item, localState, options);
+            const result = child.schema._validate(item, localState, childOptions);
             if (result.errors) {
-                errors.push(this.createError('object.child', { key, reason: result.errors }, localState, options));
+                errors.push(this.createError('object.child', { key, reason: result.errors }, localState, childOptions));
 
                 if (options.abortEarly) {
                     return finish();
@@ -231,7 +236,7 @@ internals.Object.prototype._base = function (value, state, options) {
             (this._flags.allowUnknown !== undefined ? !this._flags.allowUnknown : !options.allowUnknown)) {
 
             for (let i = 0; i < unprocessedKeys.length; ++i) {
-                errors.push(this.createError('object.allowUnknown', null, { key: unprocessedKeys[i], path: state.path + (state.path ? '.' : '') + unprocessedKeys[i] }, options));
+                errors.push(this.createError('object.allowUnknown', null, { key: unprocessedKeys[i], path: state.path + (state.path ? '.' : '') + unprocessedKeys[i] }, childOptions));
             }
         }
     }

package/lib/string/rfc3986.js

@@ -162,14 +162,25 @@ internals.generate = function () {
      */
     const segment = pcharOnly + '*';
     const segmentNz = pcharOnly + '+';
+    const segmentNzNc = '[' + unreserved + pctEncoded + subDelims + '@' + ']+';
+    const pathEmpty = '';
     const pathAbEmpty = '(?:\\/' + segment + ')*';
     const pathAbsolute = '\\/(?:' + segmentNz + pathAbEmpty + ')?';
     const pathRootless = segmentNz + pathAbEmpty;
+    const pathNoScheme = segmentNzNc + pathAbEmpty;
 
     /**
      * hier-part = "//" authority path
      */
-    internals.rfc3986.hierPart = '(?:\\/\\/' + authority + pathAbEmpty + or + pathAbsolute + or + pathRootless + ')';
+    internals.rfc3986.hierPart = '(?:' + '(?:\\/\\/' + authority + pathAbEmpty + ')' + or + pathAbsolute + or + pathRootless + ')';
+
+    /**
+     * relative-part = "//" authority path-abempty
+     *                 / path-absolute
+     *                 / path-noscheme
+     *                 / path-empty
+     */
+    internals.rfc3986.relativeRef = '(?:' + '(?:\\/\\/' + authority + pathAbEmpty  + ')' + or + pathAbsolute + or + pathNoScheme + or + pathEmpty + ')';
 
     /**
      * query = *( pchar / "/" / "?" )

package/lib/string/uri.js

@@ -9,7 +9,7 @@ const RFC3986 = require('./rfc3986');
 
 const internals = {
     Uri: {
-        createUriRegex: function (optionalScheme) {
+        createUriRegex: function (optionalScheme, allowRelative) {
 
             let scheme = RFC3986.scheme;
 
@@ -20,10 +20,17 @@ const internals = {
                 scheme = '(?:' + optionalScheme + ')';
             }
 
+            const withScheme = '(?:' + scheme + ':' + RFC3986.hierPart + ')';
+            const prefix = allowRelative ? '(?:' + withScheme + '|' + RFC3986.relativeRef + ')' : withScheme;
+
             /**
              * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
+             *
+             * OR
+             *
+             * relative-ref = relative-part [ "?" query ] [ "#" fragment ]
              */
-            return new RegExp('^' + scheme + ':' + RFC3986.hierPart + '(?:\\?' + RFC3986.query + ')?' + '(?:#' + RFC3986.fragment + ')?$');
+            return new RegExp('^' + prefix + '(?:\\?' + RFC3986.query + ')?' + '(?:#' + RFC3986.fragment + ')?$');
         }
     }
 };

package/lib/string.js

@@ -273,6 +273,7 @@ internals.String.prototype.ip = function (ipOptions) {
 internals.String.prototype.uri = function (uriOptions) {
 
     let customScheme = '';
+    let allowRelative = false;
     let regex = internals.uriRegex;
 
     if (uriOptions) {
@@ -305,10 +306,14 @@ internals.String.prototype.uri = function (uriOptions) {
                 }
             }
         }
+
+        if (uriOptions.allowRelative) {
+            allowRelative = true;
+        }
     }
 
-    if (customScheme) {
-        regex = Uri.createUriRegex(customScheme);
+    if (customScheme || allowRelative) {
+        regex = Uri.createUriRegex(customScheme, allowRelative);
     }
 
     return this._test('uri', uriOptions, (value, state, options) => {

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "joi",
   "description": "Object schema validation",
-  "version": "7.2.0",
+  "version": "7.3.0",
+  "homepage": "https://github.com/hapijs/joi",
   "repository": "git://github.com/hapijs/joi",
   "main": "lib/index.js",
   "keywords": [
@@ -27,7 +28,7 @@
     "test": "lab -t 100 -a code -L",
     "test-cov-html": "lab -r html -o coverage.html -a code",
     "toc": "node generate-readme-toc.js",
-    "version": "npm run toc && git add API.md"
+    "version": "npm run toc && git add API.md README.md"
   },
   "license": "BSD-3-Clause"
 }

package/test/any.js

@@ -171,6 +171,39 @@ describe('any', () => {
             expect(schema).to.deep.equal({ type: 'object', label: 'lbl' });
             done();
         });
+
+        it('does not leak into sub objects', (done) => {
+
+            const schema = Joi.object({ a: Joi.number() }).label('foo');
+            schema.validate({ a: 'a' }, (err, value) => {
+
+                expect(err).to.exist();
+                expect(err.message).to.equal('child "a" fails because ["a" must be a number]');
+                done();
+            });
+        });
+
+        it('does not leak into sub objects from an array', (done) => {
+
+            const schema = Joi.array().items(Joi.object({ a: Joi.number() }).label('foo')).label('bar');
+            schema.validate([{ a: 'a' }], (err, value) => {
+
+                expect(err).to.exist();
+                expect(err.message).to.equal('"bar" at position 0 fails because [child "a" fails because ["a" must be a number]]');
+                done();
+            });
+        });
+
+        it('does not leak into unknown keys', (done) => {
+
+            const schema = Joi.object({ a: Joi.number() }).label('foo');
+            schema.validate({ b: 'a' }, (err, value) => {
+
+                expect(err).to.exist();
+                expect(err.message).to.equal('"b" is not allowed');
+                done();
+            });
+        });
     });
 
     describe('strict()', () => {
@@ -1470,27 +1503,6 @@ describe('any', () => {
 
     describe('Set', () => {
 
-        describe('add()', () => {
-
-            it('throws when adding a non ref function', (done) => {
-
-                expect(() => {
-
-                    Joi.valid(() => { });
-                }).to.throw('Value cannot be an object or function');
-                done();
-            });
-
-            it('throws when adding an object function', (done) => {
-
-                expect(() => {
-
-                    Joi.valid({});
-                }).to.throw('Value cannot be an object or function');
-                done();
-            });
-        });
-
         describe('has()', () => {
 
             it('compares date to null', (done) => {
@@ -1508,6 +1520,7 @@ describe('any', () => {
                 expect(any._valids.has(new Buffer(''))).to.equal(false);
                 done();
             });
+
         });
 
         describe('values()', () => {
@@ -1559,7 +1572,7 @@ describe('any', () => {
 
                 expect(() => {
 
-                    Joi.any().valid(true, 1, 'hello', new Date());
+                    Joi.any().valid(true, 1, 'hello', new Date(), Symbol('foo'), () => {}, {});
                 }).not.to.throw();
                 done();
             });
@@ -1572,6 +1585,38 @@ describe('any', () => {
                 }).to.throw(Error, 'Cannot call allow/valid/invalid with undefined');
                 done();
             });
+
+            it('validates differents types of values', (done) => {
+
+                expect(Joi.valid(1).validate(1).error).to.be.null();
+                expect(Joi.valid(1).validate(2).error).to.exist();
+
+                const d = new Date();
+                expect(Joi.valid(d).validate(new Date(d.getTime())).error).to.be.null();
+                expect(Joi.valid(d).validate(new Date(d.getTime() + 1)).error).to.exist();
+
+                const str = 'foo';
+                expect(Joi.valid(str).validate(str).error).to.be.null();
+                expect(Joi.valid(str).validate('foobar').error).to.exist();
+
+                const s = Symbol('foo');
+                expect(Joi.valid(s).validate(s).error).to.be.null();
+                expect(Joi.valid(s).validate(Symbol('foo')).error).to.exist();
+
+                const o = {};
+                expect(Joi.valid(o).validate(o).error).to.be.null();
+                expect(Joi.valid(o).validate({}).error).to.exist();
+
+                const f = () => {};
+                expect(Joi.valid(f).validate(f).error).to.be.null();
+                expect(Joi.valid(f).validate(() => {}).error).to.exist();
+
+                const b = new Buffer('foo');
+                expect(Joi.valid(b).validate(b).error).to.be.null();
+                expect(Joi.valid(b).validate(new Buffer('foobar')).error).to.exist();
+
+                done();
+            });
         });
 
         describe('invalid()', () => {

package/test/index.js

@@ -1691,4 +1691,71 @@ describe('Joi', () => {
             done();
         });
     });
+
+    describe('reach()', () => {
+
+        it('should fail without any parameter', (done) => {
+
+            expect(() => Joi.reach()).to.throw('you must provide a joi schema');
+            done();
+        });
+
+        it('should fail when schema is not a joi object', (done) => {
+
+            expect(() => Joi.reach({ foo: 'bar' }, 'foo')).to.throw('you must provide a joi schema');
+            done();
+        });
+
+        it('should fail without a proper path', (done) => {
+
+            const schema = Joi.object();
+            expect(() => Joi.reach(schema)).to.throw('path must be a string');
+            expect(() => Joi.reach(schema, true)).to.throw('path must be a string');
+            done();
+        });
+
+        it('should return undefined when no keys are defined', (done) => {
+
+            const schema = Joi.object();
+            expect(Joi.reach(schema, 'a')).to.be.undefined();
+            done();
+        });
+
+        it('should return undefined when key is not found', (done) => {
+
+            const schema = Joi.object().keys({ a: Joi.number() });
+            expect(Joi.reach(schema, 'foo')).to.be.undefined();
+            done();
+        });
+
+        it('should return a schema when key is found', (done) => {
+
+            const a = Joi.number();
+            const schema = Joi.object().keys({ a });
+            expect(Joi.reach(schema, 'a')).to.equal(a);
+            done();
+        });
+
+        it('should return undefined on a schema that does not support reach', (done) => {
+
+            const schema = Joi.number();
+            expect(Joi.reach(schema, 'a')).to.be.undefined();
+            done();
+        });
+
+        it('should return a schema when deep key is found', (done) => {
+
+            const bar = Joi.number();
+            const schema = Joi.object({ foo: Joi.object({ bar }) });
+            expect(Joi.reach(schema, 'foo.bar')).to.equal(bar);
+            done();
+        });
+
+        it('should return undefined when deep key is not found', (done) => {
+
+            const schema = Joi.object({ foo: Joi.object({ bar: Joi.number() }) });
+            expect(Joi.reach(schema, 'foo.baz')).to.be.undefined();
+            done();
+        });
+    });
 });