ObjectSchema Package

Overview

A JavaScript object merge/validation utility where you can define a different merge and validation strategy for each key. This is helpful when you need to validate complex data structures and then merge them in a way that is more complex than Object.assign(). This is used in the @eslint/config-array package but can also be used on its own.

Installation

For Node.js and compatible runtimes:

npm install @eslint/object-schema
# or
yarn add @eslint/object-schema
# or
pnpm install @eslint/object-schema
# or
bun add @eslint/object-schema

For Deno:

deno add @eslint/object-schema

Usage

Import the ObjectSchema constructor:

// using ESM
import { ObjectSchema } from "@eslint/object-schema";

// using CommonJS
const { ObjectSchema } = require("@eslint/object-schema");

const schema = new ObjectSchema({
    // define a definition for the "downloads" key
    downloads: {
        required: true,
        merge(value1 = 0, value2) {
            return value1 + value2;
        },
        validate(value) {
            if (typeof value !== "number") {
                throw new Error("Expected downloads to be a number.");
            }
        },
    },

    // define a strategy for the "versions" key
    versions: {
        required: true,
        merge(value1 = [], value2) {
            return value1.concat(value2);
        },
        validate(value) {
            if (!Array.isArray(value)) {
                throw new Error("Expected versions to be an array.");
            }
        },
    },
});

const record1 = {
    downloads: 25,
    versions: ["v1.0.0", "v1.1.0", "v1.2.0"],
};

const record2 = {
    downloads: 125,
    versions: ["v2.0.0", "v2.1.0", "v3.0.0"],
};

// make sure the records are valid
schema.validate(record1);
schema.validate(record2);

// merge together (schema.merge() accepts any number of objects)
const result = schema.merge(record1, record2);

// result looks like this:
// {
// 	downloads: 150,
// 	versions: ["v1.0.0", "v1.1.0", "v1.2.0", "v2.0.0", "v2.1.0", "v3.0.0"],
// }

Tips and Tricks

Named merge strategies

Instead of specifying a merge() method, you can specify one of the following strings to use a default merge strategy:

• "assign" - use Object.assign() to merge the two values into one object.
• "overwrite" - the second value always replaces the first.
• "replace" - the second value replaces the first if the second is not undefined.

For example:

const schema = new ObjectSchema({
    name: {
        merge: "replace",
        validate() {},
    },
});

Named validation strategies

Instead of specifying a validate() method, you can specify one of the following strings to use a default validation strategy:

• "array" - value must be an array.
• "boolean" - value must be a boolean.
• "number" - value must be a number.
• "object" - value must be a non-null object, including arrays and non-plain objects.
• "object?" - value must be an object or null, including arrays and non-plain objects.
• "string" - value must be a string.
• "string!" - value must be a non-empty string.

For example:

const schema = new ObjectSchema({
    name: {
        merge: "replace",
        validate: "string",
    },
});

Built-in strategy classes

The package also exports the built-in merge and validation strategies as two classes with static methods:

• MergeStrategy - built-in merge functions (assign, overwrite, replace).
• ValidationStrategy - built-in validation functions (array, boolean, number, object, object?, string, string!).

These are the same strategies used when you specify a strategy by name (for example, merge: "replace"). You can reference the functions directly if you prefer passing a function instead of a string:

import {
    ObjectSchema,
    MergeStrategy,
    ValidationStrategy,
} from "@eslint/object-schema";

const schema = new ObjectSchema({
    name: {
        required: true,
        merge: MergeStrategy.replace,
        validate: ValidationStrategy["string!"],
    },
    options: {
        required: false,
        merge: MergeStrategy.assign,
        validate: ValidationStrategy["object?"],
    },
});

Note: Because object? and string! aren't valid identifiers, you must access them using bracket notation (for example, ValidationStrategy["object?"]).

Subschemas

If you are defining a key that is, itself, an object, you can simplify the process by using a subschema. Instead of defining merge() and validate(), set a schema property that contains a schema definition, like this:

const schema = new ObjectSchema({
    name: {
        schema: {
            first: {
                merge: "replace",
                validate: "string",
            },
            last: {
                merge: "replace",
                validate: "string",
            },
        },
    },
});

schema.validate({
    name: {
        first: "n",
        last: "z",
    },
});

Remove Keys During Merge

If the merge strategy for a key returns undefined, then the key will not appear in the final object. For example:

const schema = new ObjectSchema({
    date: {
        merge() {
            return undefined;
        },
        validate(value) {
            if (isNaN(Date.parse(value))) {
                throw new Error("Invalid date.");
            }
        },
    },
});

const object1 = { date: "5/5/2005" };
const object2 = { date: "6/6/2006" };

const result = schema.merge(object1, object2);

console.log("date" in result); // false

Requiring Another Key Be Present

If you'd like the presence of one key to require the presence of another key, you can use the requires property to specify an array of other properties that any key requires. For example:

const schema = new ObjectSchema({
    date: {
        merge() {
            return undefined;
        },
        validate(value) {
            if (isNaN(Date.parse(value))) {
                throw new Error("Invalid date.");
            }
        },
    },
    time: {
        requires: ["date"],
        merge(first, second) {
            return second;
        },
        validate(value) {
            // ...
        },
    },
});

// throws error: Key "time" requires keys "date".
schema.validate({
    time: "13:45",
});

In this example, even though date is an optional key, it is required to be present whenever time is present.

License

Apache 2.0

Sponsors

The following companies, organizations, and individuals support ESLint's ongoing maintenance and development. Become a Sponsor to get your logo on our READMEs and website.

Platinum Sponsors

Gold Sponsors

Silver Sponsors

Bronze Sponsors

Technology Sponsors