vue-types

vue-types

Prop type definitions for Vue.js. Compatible with both Vue 1.x and 2.x

Introduction

vue-types is a collection of configurable prop type definitions for Vue.js components, inspired by React's prop-types.

When to use

While basic prop type definition in Vue is simple and convenient, detailed prop validation can become verbose on complex components. This is the case for vue-types.

Instead of:

export default {
  props: {
    id: {
      type: Number,
      default: 10
    },
    name: {
      type: String,
      required: true
    },
    age: {
      type: Number,
      validator(value) {
        return Number.isInteger(value)
      }
    },
    nationality: String
  },
  methods: {
    // ...
  }
};

You may write:

import VueTypes from 'vue-types';

export default {
  props: {
    id: VueTypes.number.def(10),
    name: VueTypes.string.isRequired,
    age: VueTypes.integer,
    // No need for `default` or `required` key, so keep it simple
    nationality: String
  },
  methods: {
    // ...
  }
}

Installation

NPM package

npm install vue-types --save
# or
yarn add vue-types

CDN delivered <script>

add the following script tags before your code

<script src="https://unpkg.com/vue-types"></script>

Usage with eslint-plugin-vue

When used in a project with eslint-plugin-vue, the linter might report errors related to the vue/require-default-prop rule.

To prevent that error use eslint-plugin-vue-types

Documentation

Native Types

Most native types come with:

• a default value,
• a .def() method to reassign the default value for the current prop
• a isRequired flag to set the required: true key

const numProp = vueTypes.number
// numProp === { type: Number, default : 0}

const numPropCustom = vueTypes.number.def(10)
// numPropCustom ===  { type: Number, default : 10}

const numPropRequired = vueTypes.number.isRequired
// numPropRequired ===  { type: Number, required : true}

const numPropRequiredCustom = vueTypes.number.def(10).isRequired
// numPropRequiredCustom ===  { type: Number, default: 10, required : true}

VueTypes.any

Validates any type of value and has no default value.

VueTypes.array

Validates that a prop is an array primitive.

• default: an empty array

Note: Vue prop validation requires Array definitions to provide default value as a factory function. VueTypes.array.def() accepts both factory functions and arrays. In the latter case, VueTypes will convert the value to a factory function for you.

VueTypes.bool

Validates boolean props.

• default: true

VueTypes.func

Validates that a prop is a function.

• default: an empty function

VueTypes.number

Validates that a prop is a number.

• default: 0

VueTypes.integer

Validates that a prop is an integer.

• default: 0

VueTypes.object

Validates that a prop is an object.

• default: an empty object

Note: Vue prop validation requires Object definitions to provide default value as a factory function. VueTypes.object.def() accepts both factory functions and plain objects. In the latter case, VueTypes will convert the value to a factory function for you.

VueTypes.string

Validates that a prop is a string.

• default: ''

VueTypes.symbol

VueTypes.symbol

Validates that a prop is a Symbol.

• default: none

Native Types Configuration

All native types (with the exception of any) come with a sensible default value. In order to modify or disable it you can set the global option vueTypes.sensibleDefaults:

//use vue-types default (this is the "default" value)
vueTypes.sensibleDefaults = true

//disable all sensible defaults.
//Use .def(...) to set one
vueTypes.sensibleDefaults = false

//assign an object in order to specify custom defaults
vueTypes.sensibleDefaults = {
  string: 'mystringdefault'
  //...
}

Custom Types

Custom types are a special kind of types useful to describe complex validation requirements. By design each custom type:

• doesn't have any sensible default value
• has a .def() method to assign a default value on the current prop
• has an isRequired flag to set the required: true key

const oneOfPropDefault = vueTypes.oneOf([0, 1]).def(1)
// oneOfPropDefault.default === 1

const oneOfPropRequired = vueTypes.oneOf([0, 1]).isRequired
// oneOfPropRequired.required ===  true

const oneOfPropRequiredCustom = vueTypes.oneOf([0, 1]).def(1).isRequired
// oneOfPropRequiredCustom.default ===  1
// oneOfPropRequiredCustom.required === true

VueTypes.instanceOf()

class Person {
  // ...
}

export default {
  props: {
    user: VueTypes.instanceOf(Person)
  }
}

Validates that a prop is an instance of a JavaScript constructor. This uses JavaScript's instanceof operator.

VueTypes.oneOf()

Validates that a prop is one of the provided values.

export default {
  props: {
    genre: VueTypes.oneOf(['action', 'thriller'])
  }
}

VueTypes.oneOfType()

Validates that a prop is an object that could be one of many types. Accepts both simple and vue-types types.

export default {
  props: {
    theProp: VueTypes.oneOfType([
      String,
      VueTypes.integer,
      VueTypes.instanceOf(Person)
    ])
  }
}

VueTypes.arrayOf()

Validates that a prop is an array of a certain type.

export default {
  props: {
    theProp: VueTypes.arrayOf(String)
  }
}

//accepts: ['my', 'string']
//rejects: ['my', 1]

VueTypes.objectOf()

Validates that a prop is an object with values of a certain type.

export default {
  props: {
    userData: VueTypes.objectOf(String)
  }
}

//accepts: userData = {name: 'John', surname: 'Doe'}
//rejects: userData = {name: 'John', surname: 'Doe', age: 30}

VueTypes.shape()

Validates that a prop is an object taking on a particular shape. Accepts both simple and vue-types types. You can set shape's properties as required but (obviously) you cannot use .def(). On the other hand you can use def() to set a default value for the shape itself. Like VueTypes.array and VueTypes.object, you can pass to .def() either a factory function returning an object or a plain object.

export default {
  props: {
    userData: VueTypes.shape({
      name: String,
      age: VueTypes.integer,
      id: VueTypes.integer.isRequired
    }).def(() => { name: 'John' })
  }
}

// default value = {name: 'John'}
//accepts: userData = {name: 'John', age: 30, id: 1}
//rejects: userData = {name: 'John', age: 'wrong data', id: 1}
//rejects: userData = {name: 'John', age: 'wrong data'} --> missing required `id` key

By default .shape() won't validate objects with properties not defined in the shape. To allow partial matching use the loose flag:

export default {
  props: {
    userData: VueTypes.shape({
      name: String,
      id: VueTypes.integer.isRequired
    }),
    userDataLoose: VueTypes.shape({
      name: String,
      id: VueTypes.integer.isRequired
    }).loose
  }
}

//accepts: userData = {name: 'John', id: 1}
//rejects: userData = {name: 'John', age: 30, id: 1}
//accepts: userData2 = {name: 'John', age: 30, id: 1} --> loose matching

VueTypes.custom()

Validates prop values against a custom validator function.

function minLength(value) {
    return typeof value === 'string' && value.length >= 6
  }

export default {
  props: {
    theProp: VueTypes.custom(minLength)
  }
}

//accepts: 'string'
//rejects: 'my', 1

Note that the passed-in function name will be used as the custom validator name in warnings.

You can pass a validation error message as second argument as well:

function minLength(value) {
    return typeof value === 'string' && value.length >= 6
  }

export default {
  props: {
    theProp: VueTypes.custom(
      minLength,
      'theProp is not a string or is too short'
    )
  }
}

Utilities

vue-types exposes some utility functions on the .utils property:

VueTypes.utils.validate(value, type)

Checks a value against a type definition

VueTypes.utils.validate('John', VueTypes.string) //true

VueTypes.utils.validate('John', { type: String }) //true

Note that this utility won't check for isRequired flag, but will execute any custom validator function is provided.

const isJohn = {
  type: String,
  validator(value) {
    return value.length === 'John'
  }
}

VueTypes.utils.validate('John', isJohn) //true
VueTypes.utils.validate('Jane', isJohn) //false

VueTypes.utils.toType(name, obj)

Will convert a plain object to a VueTypes' type object with .def() and isRequired modifiers:

const password = {
  type: String,
  validator(value) {
    //very raw!
    return value.length > 10
  }
}

const passwordType = VueTypes.utils.toType('password', password)

export default {
  props: {
    password: passwordType.isRequired
  }
}

License

MIT

Copyright (c) 2018 Marco Solazzi