schema-utils

Package for validate options in loaders and plugins.

Getting Started

To begin, you'll need to install schema-utils:

1npm install schema-utils

API

schema.json

1{
2  "type": "object",
3  "properties": {
4    "option": {
5      "type": "boolean"
6    }
7  },
8  "additionalProperties": false
9}

1import schema from "./path/to/schema.json";
2import { validate } from "schema-utils";
3
4const options = { option: true };
5const configuration = { name: "Loader Name/Plugin Name/Name" };
6
7validate(schema, options, configuration);

schema

Type: String

JSON schema.

Simple example of schema:

1{
2  "type": "object",
3  "properties": {
4    "name": {
5      "description": "This is description of option.",
6      "type": "string"
7    }
8  },
9  "additionalProperties": false
10}

options

Type: Object

Object with options.

1import schema from "./path/to/schema.json";
2import { validate } from "schema-utils";
3
4const options = { foo: "bar" };
5
6validate(schema, { name: 123 }, { name: "MyPlugin" });

configuration

Allow to configure validator.

There is an alternative method to configure the name andbaseDataPath options via the title property in the schema. For example:

1{
2  "title": "My Loader options",
3  "type": "object",
4  "properties": {
5    "name": {
6      "description": "This is description of option.",
7      "type": "string"
8    }
9  },
10  "additionalProperties": false
11}

The last word used for the baseDataPath option, other words used for the name option. Based on the example above the name option equals My Loader, the baseDataPath option equals options.

name

Type: Object Default: "Object"

Allow to setup name in validation errors.

1import schema from "./path/to/schema.json";
2import { validate } from "schema-utils";
3
4const options = { foo: "bar" };
5
6validate(schema, options, { name: "MyPlugin" });

1Invalid configuration object. MyPlugin has been initialised using a configuration object that does not match the API schema.
2 - configuration.optionName should be a integer.

baseDataPath

Type: String Default: "configuration"

Allow to setup base data path in validation errors.

1import schema from "./path/to/schema.json";
2import { validate } from "schema-utils";
3
4const options = { foo: "bar" };
5
6validate(schema, options, { name: "MyPlugin", baseDataPath: "options" });

1Invalid options object. MyPlugin has been initialised using an options object that does not match the API schema.
2 - options.optionName should be a integer.

postFormatter

Type: Function Default: undefined

Allow to reformat errors.

1import schema from "./path/to/schema.json";
2import { validate } from "schema-utils";
3
4const options = { foo: "bar" };
5
6validate(schema, options, {
7  name: "MyPlugin",
8  postFormatter: (formattedError, error) => {
9    if (error.keyword === "type") {
10      return `${formattedError}\nAdditional Information.`;
11    }
12
13    return formattedError;
14  },
15});

1Invalid options object. MyPlugin has been initialized using an options object that does not match the API schema.
2 - options.optionName should be a integer.
3   Additional Information.

Examples

schema.json

1{
2  "type": "object",
3  "properties": {
4    "name": {
5      "type": "string"
6    },
7    "test": {
8      "anyOf": [
9        { "type": "array" },
10        { "type": "string" },
11        { "instanceof": "RegExp" }
12      ]
13    },
14    "transform": {
15      "instanceof": "Function"
16    },
17    "sourceMap": {
18      "type": "boolean"
19    }
20  },
21  "additionalProperties": false
22}

Loader

1import { getOptions } from "loader-utils";
2import { validate } from "schema-utils";
3
4import schema from "path/to/schema.json";
5
6function loader(src, map) {
7  const options = getOptions(this);
8
9  validate(schema, options, {
10    name: "Loader Name",
11    baseDataPath: "options",
12  });
13
14  // Code...
15}
16
17export default loader;

Plugin

1import { validate } from "schema-utils";
2
3import schema from "path/to/schema.json";
4
5class Plugin {
6  constructor(options) {
7    validate(schema, options, {
8      name: "Plugin Name",
9      baseDataPath: "options",
10    });
11
12    this.options = options;
13  }
14
15  apply(compiler) {
16    // Code...
17  }
18}
19
20export default Plugin;

Allow to disable and enable validation (the validate function do nothing)

This can be useful when you don't want to do validation for production builds.

1import { disableValidation, enableValidation, validate } from "schema-utils";
2
3// Disable validation
4disableValidation();
5// Do nothing
6validate(schema, options);
7
8// Enable validation
9enableValidation();
10// Will throw an error if schema is not valid
11validate(schema, options);
12
13// Allow to undestand do you need validation or not
14const need = needValidate();
15
16console.log(need);

Also you can enable/disable validation using the process.env.SKIP_VALIDATION env variable.

Supported values (case insensitive):

• yes/y/true/1/on
• no/n/false/0/off

Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

CONTRIBUTING

License

MIT