0
# Vue Types
1

2
Vue Types provides a comprehensive collection of configurable prop type definitions for Vue.js components, inspired by React's prop-types. It offers type-safe prop validation utilities that help developers define and validate component props with runtime checks and TypeScript support.
3

4
## Package Information
5

6
- **Package Name**: vue-types
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vue-types`
10
- **Peer Dependency**: Vue 3.x (optional)
11

12
## Core Imports
13

14
```typescript
15
import VueTypes from "vue-types";
16
```
17

18
For named imports:
19

20
```typescript
21
import { string, number, bool, array, object, shape, oneOf } from "vue-types";
22
```
23

24
For CommonJS:
25

26
```javascript
27
const VueTypes = require("vue-types");
28
const { string, number, bool } = require("vue-types");
29
```
30

31
For production builds (shim version):
32

33
```typescript
34
import VueTypes from "vue-types/shim";
35
```
36

37
## Basic Usage
38

39
```typescript
40
import VueTypes from "vue-types";
41

42
// Define component props with validation
43
export default {
44
  props: {
45
    // Basic types with sensible defaults
46
    title: VueTypes.string.isRequired,
47
    count: VueTypes.number.def(0),
48
    isActive: VueTypes.bool.def(false),
49
    
50
    // Complex validation
51
    items: VueTypes.arrayOf(VueTypes.string).def(() => []),
52
    user: VueTypes.shape({
53
      name: VueTypes.string.isRequired,
54
      age: VueTypes.number,
55
      email: VueTypes.string
56
    }).isRequired,
57
    
58
    // Enum-style validation
59
    status: VueTypes.oneOf(['pending', 'success', 'error']).def('pending')
60
  }
61
};
62
```
63

64
## Architecture
65

66
Vue Types is built around several key components:
67

68
- **Core Class**: `VueTypes` class providing all validators as static properties and methods
69
- **Type Definitions**: Comprehensive TypeScript interfaces for all prop types
70
- **Validation System**: Runtime prop validation with detailed error messages
71
- **Default Values**: Sensible default system for common use cases
72
- **Production Shim**: Lightweight version for production builds
73
- **Configuration**: Global settings for warning behavior and logging
74

75
## Capabilities
76

77
### Native Type Validators
78

79
Basic prop validators for JavaScript native types with built-in validation and default value support.
80

81
```typescript { .api }
82
// Basic type validators
83
static get any(): VueTypeValidableDef<any>;
84
static get func(): VueTypeValidableDef<Function>;
85
static get bool(): VueTypeValidableDef<boolean>;
86
static get string(): VueTypeValidableDef<string>;
87
static get number(): VueTypeValidableDef<number>;
88
static get array(): VueTypeValidableDef<any[]>;
89
static get object(): VueTypeValidableDef<Record<string, any>>;
90
static get integer(): VueTypeDef<number>;
91
static get symbol(): VueTypeDef<symbol>;
92
static get nullable(): PropOptions<null>;
93
```
94

95
[Native Type Validators](./native-validators.md)
96

97
### Complex Validators
98

99
Advanced validators for custom types, enums, collections, and object structures.
100

101
```typescript { .api }
102
// Custom validation
103
static custom<T>(validatorFn: ValidatorFunction<T>, warnMsg?: string): VueTypeDef<T>;
104

105
// Enum-style validation
106
static oneOf<T extends readonly any[]>(arr: T): VueTypeDef<T[number]>;
107
static oneOfType<T extends VueProp<any>[]>(arr: T): VueTypeDef<InferType<T[number]>>;
108

109
// Collection validation  
110
static arrayOf<T extends VueProp<any>>(type: T): VueTypeDef<InferType<T>[]>;
111
static objectOf<T extends VueProp<any>>(type: T): VueTypeDef<Record<string, InferType<T>>>;
112

113
// Instance validation
114
static instanceOf<C extends Constructor>(constructor: C): VueTypeDef<InstanceType<C>>;
115

116
// Object structure validation
117
static shape<T extends object>(obj: ShapeObject<T>): VueTypeShape<T>;
118
```
119

120
[Complex Validators](./complex-validators.md)
121

122
### Type Definition System
123

124
Core utilities for creating, extending, and managing prop type definitions.
125

126
```typescript { .api }
127
// Create type definitions
128
function toType<T>(name: string, obj: PropOptions<T>): VueTypeDef<T>;
129
function toValidableType<T>(name: string, obj: PropOptions<T>): VueTypeValidableDef<T>;
130

131
// Extend existing types
132
function fromType<T extends VueTypeDef<any>>(
133
  name: string, 
134
  source: T, 
135
  props?: PropOptions<InferType<T>>
136
): T;
137

138
// Validate values
139
function validateType<T, U>(type: T, value: U, silent?: boolean): string | boolean;
140

141
// Create custom VueTypes classes
142
function createTypes(defs?: Partial<VueTypesDefaults>): VueTypesInterface;
143
```
144

145
[Type Definition System](./type-system.md)
146

147
### Configuration & Utilities
148

149
Configuration options and utility functions for customizing behavior and validation.
150

151
```typescript { .api }
152
// Global configuration
153
interface VueTypesConfig {
154
  silent: boolean;
155
  logLevel: 'log' | 'warn' | 'error' | 'debug' | 'info';
156
}
157

158
const config: VueTypesConfig;
159

160
// Utility methods
161
static utils: {
162
  validate<T, U>(value: T, type: U): boolean;
163
  toType<T>(
164
    name: string,
165
    obj: PropOptions<T>,
166
    validable?: boolean
167
  ): VueTypeDef<T> | VueTypeValidableDef<T>;
168
};
169
```
170

171
[Configuration & Utilities](./config-utilities.md)
172

173
## Type Definitions
174

175
```typescript { .api }
176
// Core type definition interfaces  
177
interface VueTypeDef<T = unknown> extends VueTypeBaseDef<T> {}
178

179
interface VueTypeValidableDef<T = unknown> extends VueTypeBaseDef<T> {
180
  readonly validate: (fn: ValidatorFunction<T>) => this & { validator: ValidatorFunction<T> };
181
}
182

183
interface VueTypeBaseDef<T = unknown> extends PropOptions<T> {
184
  _vueTypes_name: string;
185
  readonly def: (def?: DefaultType<T>) => this & { default: DefaultType<T> };
186
  readonly isRequired: this & { required: true };
187
}
188

189
// Shape validator types
190
interface VueTypeShape<T> extends VueTypeBaseDef<T> {
191
  readonly loose: VueTypeLooseShape<T>;
192
}
193

194
interface VueTypeLooseShape<T> extends VueTypeBaseDef<T> {
195
  readonly loose: VueTypeLooseShape<T>;
196
  readonly _vueTypes_isLoose: true;
197
}
198

199
// Utility types
200
type ValidatorFunction<T> = (value: T, props?: Record<string, unknown>) => boolean;
201
type DefaultType<T> = T extends NativeType ? T : DefaultFactory<T>;
202
type DefaultFactory<T> = (() => T) | T;
203
```
204

205
## Error Handling
206

207
Vue Types includes comprehensive error handling and warning systems:
208

209
- **Runtime Validation**: All validators perform runtime type checking with detailed error messages
210
- **Silent Mode**: Global configuration to suppress validation warnings
211
- **Custom Messages**: Support for custom error messages in validators
212
- **Development Mode**: Full validation in development, optional lightweight mode for production
213
- **TypeScript Integration**: Compile-time type checking alongside runtime validation