1 | <div align="center">
|
2 | <a href="http://json-schema.org">
|
3 | <img width="160" height="160"
|
4 | src="https://raw.githubusercontent.com/webpack-contrib/schema-utils/master/.github/assets/logo.png">
|
5 | </a>
|
6 | <a href="https://github.com/webpack/webpack">
|
7 | <img width="200" height="200"
|
8 | src="https://webpack.js.org/assets/icon-square-big.svg">
|
9 | </a>
|
10 | </div>
|
11 |
|
12 | [![npm][npm]][npm-url]
|
13 | [![node][node]][node-url]
|
14 | [![deps][deps]][deps-url]
|
15 | [![tests][tests]][tests-url]
|
16 | [![coverage][cover]][cover-url]
|
17 | [![chat][chat]][chat-url]
|
18 | [![size][size]][size-url]
|
19 |
|
20 | # schema-utils
|
21 |
|
22 | Package for validate options in loaders and plugins.
|
23 |
|
24 | ## Getting Started
|
25 |
|
26 | To begin, you'll need to install `schema-utils`:
|
27 |
|
28 | ```console
|
29 | npm install schema-utils
|
30 | ```
|
31 |
|
32 | ## API
|
33 |
|
34 | **schema.json**
|
35 |
|
36 | ```json
|
37 | {
|
38 | "type": "object",
|
39 | "properties": {
|
40 | "option": {
|
41 | "type": ["boolean"]
|
42 | }
|
43 | },
|
44 | "additionalProperties": false
|
45 | }
|
46 | ```
|
47 |
|
48 | ```js
|
49 | import schema from './path/to/schema.json';
|
50 | import validate from 'schema-utils';
|
51 |
|
52 | const options = { option: true };
|
53 | const configuration = { name: 'Loader Name/Plugin Name/Name' };
|
54 |
|
55 | validate(schema, options, configuration);
|
56 | ```
|
57 |
|
58 | ### `schema`
|
59 |
|
60 | Type: `String`
|
61 |
|
62 | JSON schema.
|
63 |
|
64 | Simple example of schema:
|
65 |
|
66 | ```json
|
67 | {
|
68 | "type": "object",
|
69 | "properties": {
|
70 | "name": {
|
71 | "description": "This is description of option.",
|
72 | "type": "string"
|
73 | }
|
74 | },
|
75 | "additionalProperties": false
|
76 | }
|
77 | ```
|
78 |
|
79 | ### `options`
|
80 |
|
81 | Type: `Object`
|
82 |
|
83 | Object with options.
|
84 |
|
85 | ```js
|
86 | validate(
|
87 | schema,
|
88 | {
|
89 | name: 123,
|
90 | },
|
91 | { name: 'MyPlugin' }
|
92 | );
|
93 | ```
|
94 |
|
95 | ### `configuration`
|
96 |
|
97 | Allow to configure validator.
|
98 |
|
99 | There is an alternative method to configure the `name` and`baseDataPath` options via the `title` property in the schema.
|
100 | For example:
|
101 |
|
102 | ```json
|
103 | {
|
104 | "title": "My Loader options",
|
105 | "type": "object",
|
106 | "properties": {
|
107 | "name": {
|
108 | "description": "This is description of option.",
|
109 | "type": "string"
|
110 | }
|
111 | },
|
112 | "additionalProperties": false
|
113 | }
|
114 | ```
|
115 |
|
116 | The last word used for the `baseDataPath` option, other words used for the `name` option.
|
117 | Based on the example above the `name` option equals `My Loader`, the `baseDataPath` option equals `options`.
|
118 |
|
119 | #### `name`
|
120 |
|
121 | Type: `Object`
|
122 | Default: `"Object"`
|
123 |
|
124 | Allow to setup name in validation errors.
|
125 |
|
126 | ```js
|
127 | validate(schema, options, { name: 'MyPlugin' });
|
128 | ```
|
129 |
|
130 | ```shell
|
131 | Invalid configuration object. MyPlugin has been initialised using a configuration object that does not match the API schema.
|
132 | - configuration.optionName should be a integer.
|
133 | ```
|
134 |
|
135 | #### `baseDataPath`
|
136 |
|
137 | Type: `String`
|
138 | Default: `"configuration"`
|
139 |
|
140 | Allow to setup base data path in validation errors.
|
141 |
|
142 | ```js
|
143 | validate(schema, options, { name: 'MyPlugin', baseDataPath: 'options' });
|
144 | ```
|
145 |
|
146 | ```shell
|
147 | Invalid options object. MyPlugin has been initialised using an options object that does not match the API schema.
|
148 | - options.optionName should be a integer.
|
149 | ```
|
150 |
|
151 | #### `postFormatter`
|
152 |
|
153 | Type: `Function`
|
154 | Default: `undefined`
|
155 |
|
156 | Allow to reformat errors.
|
157 |
|
158 | ```js
|
159 | validate(schema, options, {
|
160 | name: 'MyPlugin',
|
161 | postFormatter: (formattedError, error) => {
|
162 | if (error.keyword === 'type') {
|
163 | return `${formattedError}\nAdditional Information.`;
|
164 | }
|
165 |
|
166 | return formattedError;
|
167 | },
|
168 | });
|
169 | ```
|
170 |
|
171 | ```shell
|
172 | Invalid options object. MyPlugin has been initialized using an options object that does not match the API schema.
|
173 | - options.optionName should be a integer.
|
174 | Additional Information.
|
175 | ```
|
176 |
|
177 | ## Examples
|
178 |
|
179 | **schema.json**
|
180 |
|
181 | ```json
|
182 | {
|
183 | "type": "object",
|
184 | "properties": {
|
185 | "name": {
|
186 | "type": "string"
|
187 | },
|
188 | "test": {
|
189 | "anyOf": [
|
190 | { "type": "array" },
|
191 | { "type": "string" },
|
192 | { "instanceof": "RegExp" }
|
193 | ]
|
194 | },
|
195 | "transform": {
|
196 | "instanceof": "Function"
|
197 | },
|
198 | "sourceMap": {
|
199 | "type": "boolean"
|
200 | }
|
201 | },
|
202 | "additionalProperties": false
|
203 | }
|
204 | ```
|
205 |
|
206 | ### `Loader`
|
207 |
|
208 | ```js
|
209 | import { getOptions } from 'loader-utils';
|
210 | import validateOptions from 'schema-utils';
|
211 |
|
212 | import schema from 'path/to/schema.json';
|
213 |
|
214 | function loader(src, map) {
|
215 | const options = getOptions(this) || {};
|
216 |
|
217 | validateOptions(schema, options, {
|
218 | name: 'Loader Name',
|
219 | baseDataPath: 'options',
|
220 | });
|
221 |
|
222 | // Code...
|
223 | }
|
224 |
|
225 | export default loader;
|
226 | ```
|
227 |
|
228 | ### `Plugin`
|
229 |
|
230 | ```js
|
231 | import validateOptions from 'schema-utils';
|
232 |
|
233 | import schema from 'path/to/schema.json';
|
234 |
|
235 | class Plugin {
|
236 | constructor(options) {
|
237 | validateOptions(schema, options, {
|
238 | name: 'Plugin Name',
|
239 | baseDataPath: 'options',
|
240 | });
|
241 |
|
242 | this.options = options;
|
243 | }
|
244 |
|
245 | apply(compiler) {
|
246 | // Code...
|
247 | }
|
248 | }
|
249 |
|
250 | export default Plugin;
|
251 | ```
|
252 |
|
253 | ## Contributing
|
254 |
|
255 | Please take a moment to read our contributing guidelines if you haven't yet done so.
|
256 |
|
257 | [CONTRIBUTING](./.github/CONTRIBUTING.md)
|
258 |
|
259 | ## License
|
260 |
|
261 | [MIT](./LICENSE)
|
262 |
|
263 | [npm]: https://img.shields.io/npm/v/schema-utils.svg
|
264 | [npm-url]: https://npmjs.com/package/schema-utils
|
265 | [node]: https://img.shields.io/node/v/schema-utils.svg
|
266 | [node-url]: https://nodejs.org
|
267 | [deps]: https://david-dm.org/webpack/schema-utils.svg
|
268 | [deps-url]: https://david-dm.org/webpack/schema-utils
|
269 | [tests]: https://github.com/webpack/schema-utils/workflows/schema-utils/badge.svg
|
270 | [tests-url]: https://github.com/webpack/schema-utils/actions
|
271 | [cover]: https://codecov.io/gh/webpack/schema-utils/branch/master/graph/badge.svg
|
272 | [cover-url]: https://codecov.io/gh/webpack/schema-utils
|
273 | [chat]: https://badges.gitter.im/webpack/webpack.svg
|
274 | [chat-url]: https://gitter.im/webpack/webpack
|
275 | [size]: https://packagephobia.now.sh/badge?p=schema-utils
|
276 | [size-url]: https://packagephobia.now.sh/result?p=schema-utils
|