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 | import schema from "./path/to/schema.json";
|
87 | import { validate } from "schema-utils";
|
88 |
|
89 | const options = { foo: "bar" };
|
90 |
|
91 | validate(schema, { name: 123 }, { name: "MyPlugin" });
|
92 | ```
|
93 |
|
94 | ### `configuration`
|
95 |
|
96 | Allow to configure validator.
|
97 |
|
98 | There is an alternative method to configure the `name` and`baseDataPath` options via the `title` property in the schema.
|
99 | For example:
|
100 |
|
101 | ```json
|
102 | {
|
103 | "title": "My Loader options",
|
104 | "type": "object",
|
105 | "properties": {
|
106 | "name": {
|
107 | "description": "This is description of option.",
|
108 | "type": "string"
|
109 | }
|
110 | },
|
111 | "additionalProperties": false
|
112 | }
|
113 | ```
|
114 |
|
115 | The last word used for the `baseDataPath` option, other words used for the `name` option.
|
116 | Based on the example above the `name` option equals `My Loader`, the `baseDataPath` option equals `options`.
|
117 |
|
118 | #### `name`
|
119 |
|
120 | Type: `Object`
|
121 | Default: `"Object"`
|
122 |
|
123 | Allow to setup name in validation errors.
|
124 |
|
125 | ```js
|
126 | import schema from "./path/to/schema.json";
|
127 | import { validate } from "schema-utils";
|
128 |
|
129 | const options = { foo: "bar" };
|
130 |
|
131 | validate(schema, options, { name: "MyPlugin" });
|
132 | ```
|
133 |
|
134 | ```shell
|
135 | Invalid configuration object. MyPlugin has been initialised using a configuration object that does not match the API schema.
|
136 | - configuration.optionName should be a integer.
|
137 | ```
|
138 |
|
139 | #### `baseDataPath`
|
140 |
|
141 | Type: `String`
|
142 | Default: `"configuration"`
|
143 |
|
144 | Allow to setup base data path in validation errors.
|
145 |
|
146 | ```js
|
147 | import schema from "./path/to/schema.json";
|
148 | import { validate } from "schema-utils";
|
149 |
|
150 | const options = { foo: "bar" };
|
151 |
|
152 | validate(schema, options, { name: "MyPlugin", baseDataPath: "options" });
|
153 | ```
|
154 |
|
155 | ```shell
|
156 | Invalid options object. MyPlugin has been initialised using an options object that does not match the API schema.
|
157 | - options.optionName should be a integer.
|
158 | ```
|
159 |
|
160 | #### `postFormatter`
|
161 |
|
162 | Type: `Function`
|
163 | Default: `undefined`
|
164 |
|
165 | Allow to reformat errors.
|
166 |
|
167 | ```js
|
168 | import schema from "./path/to/schema.json";
|
169 | import { validate } from "schema-utils";
|
170 |
|
171 | const options = { foo: "bar" };
|
172 |
|
173 | validate(schema, options, {
|
174 | name: "MyPlugin",
|
175 | postFormatter: (formattedError, error) => {
|
176 | if (error.keyword === "type") {
|
177 | return `${formattedError}\nAdditional Information.`;
|
178 | }
|
179 |
|
180 | return formattedError;
|
181 | },
|
182 | });
|
183 | ```
|
184 |
|
185 | ```shell
|
186 | Invalid options object. MyPlugin has been initialized using an options object that does not match the API schema.
|
187 | - options.optionName should be a integer.
|
188 | Additional Information.
|
189 | ```
|
190 |
|
191 | ## Examples
|
192 |
|
193 | **schema.json**
|
194 |
|
195 | ```json
|
196 | {
|
197 | "type": "object",
|
198 | "properties": {
|
199 | "name": {
|
200 | "type": "string"
|
201 | },
|
202 | "test": {
|
203 | "anyOf": [
|
204 | { "type": "array" },
|
205 | { "type": "string" },
|
206 | { "instanceof": "RegExp" }
|
207 | ]
|
208 | },
|
209 | "transform": {
|
210 | "instanceof": "Function"
|
211 | },
|
212 | "sourceMap": {
|
213 | "type": "boolean"
|
214 | }
|
215 | },
|
216 | "additionalProperties": false
|
217 | }
|
218 | ```
|
219 |
|
220 | ### `Loader`
|
221 |
|
222 | ```js
|
223 | import { getOptions } from "loader-utils";
|
224 | import { validate } from "schema-utils";
|
225 |
|
226 | import schema from "path/to/schema.json";
|
227 |
|
228 | function loader(src, map) {
|
229 | const options = getOptions(this);
|
230 |
|
231 | validate(schema, options, {
|
232 | name: "Loader Name",
|
233 | baseDataPath: "options",
|
234 | });
|
235 |
|
236 | // Code...
|
237 | }
|
238 |
|
239 | export default loader;
|
240 | ```
|
241 |
|
242 | ### `Plugin`
|
243 |
|
244 | ```js
|
245 | import { validate } from "schema-utils";
|
246 |
|
247 | import schema from "path/to/schema.json";
|
248 |
|
249 | class Plugin {
|
250 | constructor(options) {
|
251 | validate(schema, options, {
|
252 | name: "Plugin Name",
|
253 | baseDataPath: "options",
|
254 | });
|
255 |
|
256 | this.options = options;
|
257 | }
|
258 |
|
259 | apply(compiler) {
|
260 | // Code...
|
261 | }
|
262 | }
|
263 |
|
264 | export default Plugin;
|
265 | ```
|
266 |
|
267 | ## Contributing
|
268 |
|
269 | Please take a moment to read our contributing guidelines if you haven't yet done so.
|
270 |
|
271 | [CONTRIBUTING](./.github/CONTRIBUTING.md)
|
272 |
|
273 | ## License
|
274 |
|
275 | [MIT](./LICENSE)
|
276 |
|
277 | [npm]: https://img.shields.io/npm/v/schema-utils.svg
|
278 | [npm-url]: https://npmjs.com/package/schema-utils
|
279 | [node]: https://img.shields.io/node/v/schema-utils.svg
|
280 | [node-url]: https://nodejs.org
|
281 | [deps]: https://david-dm.org/webpack/schema-utils.svg
|
282 | [deps-url]: https://david-dm.org/webpack/schema-utils
|
283 | [tests]: https://github.com/webpack/schema-utils/workflows/schema-utils/badge.svg
|
284 | [tests-url]: https://github.com/webpack/schema-utils/actions
|
285 | [cover]: https://codecov.io/gh/webpack/schema-utils/branch/master/graph/badge.svg
|
286 | [cover-url]: https://codecov.io/gh/webpack/schema-utils
|
287 | [chat]: https://badges.gitter.im/webpack/webpack.svg
|
288 | [chat-url]: https://gitter.im/webpack/webpack
|
289 | [size]: https://packagephobia.com/badge?p=schema-utils
|
290 | [size-url]: https://packagephobia.com/result?p=schema-utils
|