feat: hex prefix

API.md

@@ -2823,8 +2823,9 @@ Requires the string value to be a valid hexadecimal string.
 
 - `options` - optional settings:
   - `byteAligned` - Boolean specifying whether you want to check that the hexadecimal string is byte aligned. If `convert` is `true`, a `0` will be added in front of the string in case it needs to be aligned. Defaults to `false`.
+  - `prefix` - Boolean or `optional`. When `true`, the string will be considered valid if prefixed with `0x` or `0X`. When `false`, the prefix is forbidden. When `optional`, the string will be considered valid if prefixed or not prefixed at all. Defaults to `false`.
 ```js
-const schema = Joi.string().hex();
+const schema = Joi.string().hex({ prefix: 'optional' });
 ```
 
 Possible validation errors: [`string.hex`](#stringhex), [`string.hexAlign`](#stringhexalign)

lib/index.d.ts

@@ -368,6 +368,15 @@ declare namespace Joi {
          * @default false
          */
         byteAligned?: boolean;
+        /**
+         * controls whether the prefix `0x` or `0X` is allowed (or required) on hex strings.
+         * When `true`, the prefix must be provided.
+         * When `false`, the prefix is forbidden.
+         * When `optional`, the prefix is allowed but not required.
+         *
+         * @default false
+         */
+        prefix?: boolean | 'optional';
     }
 
     interface IpOptions {

lib/types/string.js

@@ -27,7 +27,11 @@ const internals = {
         }
     },
     dataUriRegex: /^data:[\w+.-]+\/[\w+.-]+;((charset=[\w-]+|base64),)?(.*)$/,
-    hexRegex: /^[a-f0-9]+$/i,
+    hexRegex: {
+        withPrefix: /^0x[0-9a-f]+$/i,
+        withOptionalPrefix: /^(?:0x)?[0-9a-f]+$/i,
+        withoutPrefix: /^[0-9a-f]+$/i
+    },
     ipRegex: Ip.regex({ cidr: 'forbidden' }).regex,
     isoDurationRegex: /^P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$/,
 
@@ -368,16 +372,22 @@ module.exports = Any.extend({
         hex: {
             method(options = {}) {
 
-                Common.assertOptions(options, ['byteAligned']);
+                Common.assertOptions(options, ['byteAligned', 'prefix']);
 
-                options = { byteAligned: false, ...options };
+                options = { byteAligned: false, prefix: false, ...options };
                 Assert(typeof options.byteAligned === 'boolean', 'byteAligned must be boolean');
+                Assert(typeof options.prefix === 'boolean' || options.prefix === 'optional', 'prefix must be boolean or "optional"');
 
                 return this.$_addRule({ name: 'hex', args: { options } });
             },
             validate(value, helpers, { options }) {
 
-                if (!internals.hexRegex.test(value)) {
+                const re = options.prefix === 'optional' ?
+                    internals.hexRegex.withOptionalPrefix :
+                    options.prefix === true ?
+                        internals.hexRegex.withPrefix :
+                        internals.hexRegex.withoutPrefix;
+                if (!re.test(value)) {
                     return helpers.error('string.hex');
                 }
 

test/types/string.js

@@ -1215,6 +1215,58 @@ describe('string', () => {
                 ]
             });
         });
+
+        it('describes a hex string', () => {
+
+            expect(Joi.string().hex().describe()).to.equal({
+                type: 'string',
+                rules: [{
+                    name: 'hex',
+                    args: {
+                        options: {
+                            byteAligned: false,
+                            prefix: false
+                        }
+                    }
+                }]
+            });
+            expect(Joi.string().hex({ byteAligned: true }).describe()).to.equal({
+                type: 'string',
+                rules: [{
+                    name: 'hex',
+                    args: {
+                        options: {
+                            byteAligned: true,
+                            prefix: false
+                        }
+                    }
+                }]
+            });
+            expect(Joi.string().hex({ prefix: true }).describe()).to.equal({
+                type: 'string',
+                rules: [{
+                    name: 'hex',
+                    args: {
+                        options: {
+                            byteAligned: false,
+                            prefix: true
+                        }
+                    }
+                }]
+            });
+            expect(Joi.string().hex({ prefix: 'optional' }).describe()).to.equal({
+                type: 'string',
+                rules: [{
+                    name: 'hex',
+                    args: {
+                        options: {
+                            byteAligned: false,
+                            prefix: 'optional'
+                        }
+                    }
+                }]
+            });
+        });
     });
 
     describe('domain()', () => {
@@ -4487,6 +4539,49 @@ describe('string', () => {
                 }]
             ]);
         });
+
+        it('validates an hexadecimal string with prefix explicitly required', () => {
+
+            const rule = Joi.string().hex({ prefix: true }).strict();
+            Helper.validate(rule, [
+                ['0123456789abcdef', false, {
+                    message: '"value" must only contain hexadecimal characters',
+                    path: [],
+                    type: 'string.hex',
+                    context: { value: '0123456789abcdef', label: 'value' }
+                }],
+                ['0x0123456789abcdef', true],
+                ['0X0123456789abcdef', true]
+            ]);
+        });
+
+        it('validates an hexadecimal string with optional prefix', () => {
+
+            const rule = Joi.string().hex({ prefix: 'optional' }).strict();
+            Helper.validate(rule, [
+                ['0123456789abcdef', true],
+                ['0x0123456789abcdef', true],
+                ['0X0123456789abcdef', true],
+                ['0123456789abcdefg', false, {
+                    message: '"value" must only contain hexadecimal characters',
+                    path: [],
+                    type: 'string.hex',
+                    context: { value: '0123456789abcdefg', label: 'value' }
+                }],
+                ['0x0123456789abcdefg', false, {
+                    message: '"value" must only contain hexadecimal characters',
+                    path: [],
+                    type: 'string.hex',
+                    context: { value: '0x0123456789abcdefg', label: 'value' }
+                }],
+                ['0X0123456789abcdefg', false, {
+                    message: '"value" must only contain hexadecimal characters',
+                    path: [],
+                    type: 'string.hex',
+                    context: { value: '0X0123456789abcdefg', label: 'value' }
+                }]
+            ]);
+        });
     });
 
     describe('hostname()', () => {