1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
<div align="center">
<a href="http://json-schema.org">
<img width="200"
src="https://cdn.rawgit.com/webpack-contrib/schema-utils/master/.github/json-schema-logo.svg">
</a>
<a href="https://github.com/webpack/webpack">
<img width="200" src="https://webpack.js.org/assets/icon-square-big.svg">
</a>
</div>
[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![chat][chat]][chat-url]
# schema-utils
Webpack Schema Validation Utilities
Validates `options` objects against a [JSON Schema](http://json-schema.org) and
displays the output beautifully.
<img width="645"
src="https://cdn.rawgit.com/webpack-contrib/schema-utils/master/.github/pretty.png">
## Requirements
This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.
## Getting Started
To begin, you'll need to install `schema-utils`:
```console
$ npm install @webpack-contrib/schema-utils --save-dev
```
## API
When using the API directly, the main entry point is the `serve` function, which
is the default export of the module.
```js
const validate = require('@webpack-contrib/schema-utils');
const schema = require('path/to/schema.json');
const target = { ... }; // the options object to validate
const name = '...'; // the load or plugin name validate() is being used in
validate({ name, schema, target });
```
### serve(options)
Returns `true` if validation succeeded, `false` validation failed and options
allow the function to return a value. (see options below).
### options
Type: `Object`
Options for initializing and controlling the server provided. The option names
listed below belong to the `options` object.
#### `exit`
Type: `Boolean`
Default: `false`
If `true`, will instruct the validator to end the process with an error code of
`1`.
#### `log`
Type: `Boolean`
Default: `false`
If `true`, will instruct the validator to log the results of the validation (in
the event of a failure) in a
[webpack-style log output](https://github.com/webpack-contrib/webpack-log). This
is typically used with `throw: false`.
<img width="500"
src="https://cdn.rawgit.com/webpack-contrib/schema-utils/master/.github/output-log-true.png">
#### `name`
Type: `String`
Default: `undefined`
_**Required**_
A `String` specifying the name of the loader or plugin utilizing the validator.
#### `schema`
Type: `String|Object`
Default: `undefined`
_**Required**_
A `String` specifying the filesystem path to the schema used for validation.
Alternatively, you may specify an `object` containing the JSON-parsed schema.
#### `target`
Type: `Object`
Default: `undefined`
_**Required**_
An `Object` containing the options to validate against the specified schema.
#### `throw`
Type: `Boolean`
Default: `true`
By default the validator will throw an error and display validation results upon
failure. If this option is set to `false`, the validator will not throw an error.
This is typically used in situations where a return value of `false` for
`validate()` is sufficient, a stack trace is uneeded, or when
[webpack-style log output](https://github.com/webpack-contrib/webpack-log) is
preferred.
<img width="645"
src="https://cdn.rawgit.com/webpack-contrib/schema-utils/master/.github/output-throws-true.png">
## Examples
Below is a basic example of how this validator might be used:
```json
# schema.json
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"test": {
"anyOf": [
{ "type": "array" },
{ "type": "string" },
{ "instanceof": "RegExp" }
]
},
"transform": {
"instanceof": "Function"
},
"sourceMap": {
"type": "boolean"
}
},
"additionalProperties": false
}
```
### Use in a Loader
```js
const { getOptions } = require('loader-utils');
const validate = require('@webpack-contrib/schema-utils');
import schema from 'path/to/schema.json'
function loader (src, map) {
const options = getOptions(this) || {};
validate({ name: 'Loader Name', schema, target: options });
// Code...
}
```
### Use in a Plugin
```js
const validate = require('@webpack-contrib/schema-utils');
const schema = require('path/to/schema.json');
class Plugin {
constructor (options) {
validate({ name: 'Plugin Name', schema, target: options });
this.options = options;
}
apply (compiler) {
// Code...
}
}
```
## License
#### [MIT](./LICENSE)
[npm]: https://img.shields.io/npm/v/schema-utils.svg
[npm-url]: https://npmjs.com/package/schema-utils
[node]: https://img.shields.io/node/v/schema-utils.svg
[node-url]: https://nodejs.org
[deps]: https://david-dm.org/webpack-contrib/schema-utils.svg
[deps-url]: https://david-dm.org/webpack-contrib/schema-utils
[tests]: https://img.shields.io/circleci/project/github/webpack-contrib/schema-utils.svg
[tests-url]: https://circleci.com/gh/webpack-contrib/schema-utils
[cover]: https://codecov.io/gh/webpack-contrib/schema-utils/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/schema-utils
[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
[chat-url]: https://gitter.im/webpack/webpack
|
