shelving/schema/ArraySchema.js

Toolkit for using data in JavaScript.

import { getUniqueArray, isArray } from "../util/array.js";
import { validateArray } from "../util/validate.js";
import { Schema } from "./Schema.js";
/**
 * Define a valid array.
 *
 * Validates arrays and ensures the array's items match a specified format.
 * Only returns a new instance of the object if it changes (for immutability).
 *
 * @example
 *  const schema = new ArraySchema({ min: 1, max: 2, default: [10,11,12], required: true });
 *  schema.validate([1,2,3], schema); // Returns [1,2,3]
 *  schema.validate(undefined, schema); // Returns [10,11,12] (due to value)
 *  schema.validate([4,5,6,7], schema); // Returns [4,5,6] (due to max)
 *  schema.validate(9999, schema); // Throws Invalid('Must be array')
 *  schema.validate([], schema); // Throws Required
 *  schema.validate([1,2], schema); // Throws Invalid('Needs at least 3 items')
 *
 * @example
 *  const schema = new ArraySchema({ schema: Array });
 *  schema.validate(["a", "a"], schema); // Returns ["a", "a"]
 *  schema.validate(["a", null], schema); // Throws Invalids({ "1": Invalid('Must be a string') });
 */
export class ArraySchema extends Schema {
    items;
    unique;
    min;
    max;
    separator;
    constructor({ items, one = items.one, many = items.many, title = "Items", placeholder = `No ${many}`, unique = false, min = 0, max = Number.POSITIVE_INFINITY, separator = ",", value = [], ...options }) {
        super({ one, many, title, placeholder, value, ...options });
        this.items = items;
        this.unique = unique;
        this.min = min;
        this.max = max;
        this.separator = separator;
    }
    validate(unsafeValue = this.value) {
        const unsafeArray = typeof unsafeValue === "string" ? unsafeValue.split(this.separator).filter(Boolean) : unsafeValue;
        if (!isArray(unsafeArray))
            throw "Must be array";
        const validArray = validateArray(unsafeArray, this.items);
        const uniqueArray = this.unique ? getUniqueArray(validArray) : validArray;
        if (uniqueArray.length < this.min)
            throw uniqueArray.length ? `Minimum ${this.min} ${this.many}` : "Required";
        if (uniqueArray.length > this.max)
            throw `Maximum ${this.max} ${this.many}`;
        return uniqueArray;
    }
}
/** Valid array with specifed items. */
export const ARRAY = (items) => new ArraySchema({ items });