Utilities

Utility methods are methods designed to functionally manipulate a schema definition.

AST examples are provided, where applicable, for the sake of completeness.

nullable#

nullable(isNullable: boolean = true)

Indicates whether null is a valid value for this schema.

ast
functional

isValidSync(createSchema({nullable:true}), nullable()),null); // true
isValidSync(createSchema({}) ,null); // false

Note: nullable() === nullable(true)

typeError#

typeError(string | ({value,label}) => string)

Sets the error message for the typeError. value and label are available as interpolation parameters.

def#

def(value | () => value)

Sets the default value of a schema when the provided value is undefined.

ast
functional

cast(createSchema({default:'jim'})); // "jim"
cast(createSchema({default:() => new Date()})), undefined); // Sun Mar 15 2020 11:26:32 GMT-0300 (Atlantic Daylight 

label#

label(string | () => string)

Sets the label on a schema - used for interpolation in error messages.

ast
functional

{
    schema:'string',
    label:'firstName'
}

meta#

Sets the meta property on a schema

ast
functional

{
    schema:'string',
    meta: {
        someKey:'someVal'
    }
}

tests#

tests(...ValidatorDefinition[])

Adds tests to a schema

ast
functional

const schema = {
    schema: 'string',
    tests: ['required',['min',10]]
};

test#

(name: string,TestFn: (value,{schema,options}) => boolean | ValidationError | Promise<boolean | ValidationError>)

Functional way to create a validator

const isJim = test('isJim',value => value === 'jim');

const async = test('asyncValidator',async value => {
    try {
        await doSomething(value);
        return true;
    } catch(err) {
        return false;
    }
});

mixed(tests(isJim,async));

// create a validator that accepts an argument
const isThing = (arg) => test('isThing',value => value === arg);
mixed(tests(isThing('one')));

transforms#

transforms(...TransformFn[])

Adds transforms to a schema

ast
functional

const schema = {
    schema: 'string',
    transforms: ['strip','uppercase']
};

conditions#

conditions(...Condition[])

Adds conditions to a schema

ast
functional

const schema = {
    schema: 'string',
    conditions: [
        {
            when: { fieldA: { tests: [['is','jim']] } },
            then: { tests: [['min', 10]] },
            otherwise: { tests: [['min', 20]] }
        }
    ]
};

when/condition#

when is an alias of the condition

ast
functional

const schema = {
    schema:'string',
    conditions: [
        {
            when: {
                dep1: { tests:['required', ['is','jim']] },
                dep2: { schema: 'number', tests: [['min',10],['max',20]]}
            },
            then:{
                schema: 'string',
                tests: ['required']
            },
            otherwise:{
                schema: 'number',
                tests: [['min',10]]
            }
        }
    ]
}

ref#

Create a reference to another field or context

ast
functional

const schema = {
    schema: 'object',
    shape: {
        fieldA: {
            schema: 'string',
            tests: [['oneOf',[{ref:'fieldA'},ref:{'$context.field'}]]]
        }
    }
}

The following two utility method are used to manipulate a schema definition

without#

without(property: string, schema: Schema, ...refs: any[]): Schema

Removes a property from a schema definition. If the property is an array it removes any reference given by ...refs from the array.

const schema = string(label('my field'));
const labelessSchema = without('label', schema);

// IMPORTANT: schema !== labelessSchema

const minTest = min(10);
const maxTest = max(20);

const schema = string(tests(minTest, maxTest));

// returns a schema without minTest
const withoutMin = without('test', schema, minTest);

of#

of(schema: Schema)

Defines the inner schema of an array schema.

ast
functional

{
    schema: 'array',
    of: { schema: 'number', tests: [['min',10]] }
}

shape#

shape({[key: string]: Schema})

Defines the inner schema of an object schema.

ast
functional

{
    schema: 'object',
    shape: {
        fieldA: { schema: 'number', tests: [['min', 10]] },
        fieldB: { schema: 'string', tests: ['required'] }
    }
}

withoutAny#

withoutAny(property: string, schema: Schema): Schema

Removes all transforms/conditions/tests from a schema

const schema = string(tests(min(10),max(20)));
const withoutValidations = withoutAny('test',schema);

warnings#

warnings(shouldWarn: boolean = false)

There are certain warnings that occur in @zuze/schema that you may want to suppress in a production environment. Warnings are enabled by default and can be turned off by calling warnings(false).