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 | [![tests][tests]][tests-url]
|
15 | [![coverage][cover]][cover-url]
|
16 | [![GitHub Discussions][discussion]][discussion-url]
|
17 | [![size][size]][size-url]
|
18 |
|
19 | # schema-utils
|
20 |
|
21 | Package for validate options in loaders and plugins.
|
22 |
|
23 | ## Getting Started
|
24 |
|
25 | To begin, you'll need to install `schema-utils`:
|
26 |
|
27 | ```console
|
28 | npm install schema-utils
|
29 | ```
|
30 |
|
31 | ## API
|
32 |
|
33 | **schema.json**
|
34 |
|
35 | ```json
|
36 | {
|
37 | "type": "object",
|
38 | "properties": {
|
39 | "option": {
|
40 | "type": "boolean"
|
41 | }
|
42 | },
|
43 | "additionalProperties": false
|
44 | }
|
45 | ```
|
46 |
|
47 | ```js
|
48 | import schema from "./path/to/schema.json";
|
49 | import { validate } from "schema-utils";
|
50 |
|
51 | const options = { option: true };
|
52 | const configuration = { name: "Loader Name/Plugin Name/Name" };
|
53 |
|
54 | validate(schema, options, configuration);
|
55 | ```
|
56 |
|
57 | ### `schema`
|
58 |
|
59 | Type: `String`
|
60 |
|
61 | JSON schema.
|
62 |
|
63 | Simple example of schema:
|
64 |
|
65 | ```json
|
66 | {
|
67 | "type": "object",
|
68 | "properties": {
|
69 | "name": {
|
70 | "description": "This is description of option.",
|
71 | "type": "string"
|
72 | }
|
73 | },
|
74 | "additionalProperties": false
|
75 | }
|
76 | ```
|
77 |
|
78 | ### `options`
|
79 |
|
80 | Type: `Object`
|
81 |
|
82 | Object with options.
|
83 |
|
84 | ```js
|
85 | import schema from "./path/to/schema.json";
|
86 | import { validate } from "schema-utils";
|
87 |
|
88 | const options = { foo: "bar" };
|
89 |
|
90 | validate(schema, { name: 123 }, { name: "MyPlugin" });
|
91 | ```
|
92 |
|
93 | ### `configuration`
|
94 |
|
95 | Allow to configure validator.
|
96 |
|
97 | There is an alternative method to configure the `name` and`baseDataPath` options via the `title` property in the schema.
|
98 | For example:
|
99 |
|
100 | ```json
|
101 | {
|
102 | "title": "My Loader options",
|
103 | "type": "object",
|
104 | "properties": {
|
105 | "name": {
|
106 | "description": "This is description of option.",
|
107 | "type": "string"
|
108 | }
|
109 | },
|
110 | "additionalProperties": false
|
111 | }
|
112 | ```
|
113 |
|
114 | The last word used for the `baseDataPath` option, other words used for the `name` option.
|
115 | Based on the example above the `name` option equals `My Loader`, the `baseDataPath` option equals `options`.
|
116 |
|
117 | #### `name`
|
118 |
|
119 | Type: `Object`
|
120 | Default: `"Object"`
|
121 |
|
122 | Allow to setup name in validation errors.
|
123 |
|
124 | ```js
|
125 | import schema from "./path/to/schema.json";
|
126 | import { validate } from "schema-utils";
|
127 |
|
128 | const options = { foo: "bar" };
|
129 |
|
130 | validate(schema, options, { name: "MyPlugin" });
|
131 | ```
|
132 |
|
133 | ```shell
|
134 | Invalid configuration object. MyPlugin has been initialised using a configuration object that does not match the API schema.
|
135 | - configuration.optionName should be a integer.
|
136 | ```
|
137 |
|
138 | #### `baseDataPath`
|
139 |
|
140 | Type: `String`
|
141 | Default: `"configuration"`
|
142 |
|
143 | Allow to setup base data path in validation errors.
|
144 |
|
145 | ```js
|
146 | import schema from "./path/to/schema.json";
|
147 | import { validate } from "schema-utils";
|
148 |
|
149 | const options = { foo: "bar" };
|
150 |
|
151 | validate(schema, options, { name: "MyPlugin", baseDataPath: "options" });
|
152 | ```
|
153 |
|
154 | ```shell
|
155 | Invalid options object. MyPlugin has been initialised using an options object that does not match the API schema.
|
156 | - options.optionName should be a integer.
|
157 | ```
|
158 |
|
159 | #### `postFormatter`
|
160 |
|
161 | Type: `Function`
|
162 | Default: `undefined`
|
163 |
|
164 | Allow to reformat errors.
|
165 |
|
166 | ```js
|
167 | import schema from "./path/to/schema.json";
|
168 | import { validate } from "schema-utils";
|
169 |
|
170 | const options = { foo: "bar" };
|
171 |
|
172 | validate(schema, options, {
|
173 | name: "MyPlugin",
|
174 | postFormatter: (formattedError, error) => {
|
175 | if (error.keyword === "type") {
|
176 | return `${formattedError}\nAdditional Information.`;
|
177 | }
|
178 |
|
179 | return formattedError;
|
180 | },
|
181 | });
|
182 | ```
|
183 |
|
184 | ```shell
|
185 | Invalid options object. MyPlugin has been initialized using an options object that does not match the API schema.
|
186 | - options.optionName should be a integer.
|
187 | Additional Information.
|
188 | ```
|
189 |
|
190 | ## Examples
|
191 |
|
192 | **schema.json**
|
193 |
|
194 | ```json
|
195 | {
|
196 | "type": "object",
|
197 | "properties": {
|
198 | "name": {
|
199 | "type": "string"
|
200 | },
|
201 | "test": {
|
202 | "anyOf": [
|
203 | { "type": "array" },
|
204 | { "type": "string" },
|
205 | { "instanceof": "RegExp" }
|
206 | ]
|
207 | },
|
208 | "transform": {
|
209 | "instanceof": "Function"
|
210 | },
|
211 | "sourceMap": {
|
212 | "type": "boolean"
|
213 | }
|
214 | },
|
215 | "additionalProperties": false
|
216 | }
|
217 | ```
|
218 |
|
219 | ### `Loader`
|
220 |
|
221 | ```js
|
222 | import { getOptions } from "loader-utils";
|
223 | import { validate } from "schema-utils";
|
224 |
|
225 | import schema from "path/to/schema.json";
|
226 |
|
227 | function loader(src, map) {
|
228 | const options = getOptions(this);
|
229 |
|
230 | validate(schema, options, {
|
231 | name: "Loader Name",
|
232 | baseDataPath: "options",
|
233 | });
|
234 |
|
235 | // Code...
|
236 | }
|
237 |
|
238 | export default loader;
|
239 | ```
|
240 |
|
241 | ### `Plugin`
|
242 |
|
243 | ```js
|
244 | import { validate } from "schema-utils";
|
245 |
|
246 | import schema from "path/to/schema.json";
|
247 |
|
248 | class Plugin {
|
249 | constructor(options) {
|
250 | validate(schema, options, {
|
251 | name: "Plugin Name",
|
252 | baseDataPath: "options",
|
253 | });
|
254 |
|
255 | this.options = options;
|
256 | }
|
257 |
|
258 | apply(compiler) {
|
259 | // Code...
|
260 | }
|
261 | }
|
262 |
|
263 | export default Plugin;
|
264 | ```
|
265 |
|
266 | ### Allow to disable and enable validation (the `validate` function do nothing)
|
267 |
|
268 | This can be useful when you don't want to do validation for `production` builds.
|
269 |
|
270 | ```js
|
271 | import { disableValidation, enableValidation, validate } from "schema-utils";
|
272 |
|
273 | // Disable validation
|
274 | disableValidation();
|
275 | // Do nothing
|
276 | validate(schema, options);
|
277 |
|
278 | // Enable validation
|
279 | enableValidation();
|
280 | // Will throw an error if schema is not valid
|
281 | validate(schema, options);
|
282 |
|
283 | // Allow to undestand do you need validation or not
|
284 | const need = needValidate();
|
285 |
|
286 | console.log(need);
|
287 | ```
|
288 |
|
289 | Also you can enable/disable validation using the `process.env.SKIP_VALIDATION` env variable.
|
290 |
|
291 | Supported values (case insensitive):
|
292 |
|
293 | - `yes`/`y`/`true`/`1`/`on`
|
294 | - `no`/`n`/`false`/`0`/`off`
|
295 |
|
296 | ## Contributing
|
297 |
|
298 | Please take a moment to read our contributing guidelines if you haven't yet done so.
|
299 |
|
300 | [CONTRIBUTING](./.github/CONTRIBUTING.md)
|
301 |
|
302 | ## License
|
303 |
|
304 | [MIT](./LICENSE)
|
305 |
|
306 | [npm]: https://img.shields.io/npm/v/schema-utils.svg
|
307 | [npm-url]: https://npmjs.com/package/schema-utils
|
308 | [node]: https://img.shields.io/node/v/schema-utils.svg
|
309 | [node-url]: https://nodejs.org
|
310 | [tests]: https://github.com/webpack/schema-utils/workflows/schema-utils/badge.svg
|
311 | [tests-url]: https://github.com/webpack/schema-utils/actions
|
312 | [cover]: https://codecov.io/gh/webpack/schema-utils/branch/master/graph/badge.svg
|
313 | [cover-url]: https://codecov.io/gh/webpack/schema-utils
|
314 | [discussion]: https://img.shields.io/github/discussions/webpack/webpack
|
315 | [discussion-url]: https://github.com/webpack/webpack/discussions
|
316 | [size]: https://packagephobia.com/badge?p=schema-utils
|
317 | [size-url]: https://packagephobia.com/result?p=schema-utils
|