JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 83125
  • Score
    100M100P100Q135303F
  • License MIT

Prop types utility for Vue

Package Exports

  • vue-types
  • vue-types/dist

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (vue-types) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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