@caruuto/api-validator
v2.0.0
Published
Validation package for API
Downloads
6
Readme
API validator
A module for validating API documents
Installation
Install the module via npm:
npm install @caruuto/api-validator
Usage
The module exports a constructor method that expects the following named parameters relating to the instance of API you're working with:
i18nFieldCharacter
: the character used to represent the language variation of a field, as defined by thei18n.fieldCharacter
configuration property (default::
)internalFieldPrefix
: the character used to prefix internal API fields, as defined by theinternalFieldPrefix
configuration property (default:_
)
const Validator = require('@caruuto/api-validator')
const myValidator = new Validator({
i18nFieldCharacter: ':',
internalFieldPrefix: '_'
})
The Validator
class contains the following methods.
validateAccessMatrix(matrix, fieldName)
Validates an access matrix. An optional fieldName
can be supplied, which will be used in the error objects as the path of the field being validated.
// Throws error:
// > [
// > {"field": "foo.invalidType", "code": "ERROR_INVALID_ACCESS_TYPE"},
// > {"field": "foo.update.invalidKey", "code": "ERROR_INVALID_ACCESS_VALUE"}
// > ]
myValidator.validateAccessMatrix(
{
create: true,
invalidType: true,
update: {
invalidKey: true
}
},
'foo'
)
// > undefined
myValidator.validateAccessMatrix({
create: true,
delete: {
filter: {
someField: 'someValue'
}
}
})
validateDocument({document, isUpdate, schema})
Validates a document against a collection schema. It returns a Promise that is resolved with undefined
if no validation errors occur, or rejected with an array of errors if validation fails.
If isUpdate
is set to true
, the method does not throw a validation error if a required field is missing from the candidate document, because it is inferred that a partial update, as opposed to a full document, is being evaluated.
const mySchema = {
title: {
type: 'string',
validation: {
minLength: 10
}
}
}
// Rejected Promise:
// > [{"field": "title", "code": "ERROR_MIN_LENGTH"}]
myValidator
.validateDocument({
document: {
title: 'great'
},
schema: mySchema
})
.catch(console.log)
// Resolved Promise:
// > undefined
myValidator.validateDocument({
document: {
title: 'super amazing!'
},
schema: mySchema
})
validateDocuments({documents, schema})
Same as validateDocument
but expects an array of documents (as the documents
property) and performs validation on each one of them, aborting the process once one of the documents fails validation.
validateSchemaField(name, schema)
Validates a field schema, evaluating whether name
is a valid field name and whether schema
is a valid schema object.
// Rejected Promise:
// > [{"field": "fields.title", "code": "ERROR_MISSING_FIELD_TYPE"}]
myValidator
.validateSchemaField('title', {
validation: {
minLength: 10
}
})
.catch(console.log)
// Resolved Promise:
// > undefined
myValidator.validateDocument({
type: 'string',
validation: {
minLength: 10
}
})
validateSchemaFieldName(name)
Validates a field name.
// Rejected Promise:
// > [{"field": "fields.$no-good$", "code": "ERROR_INVALID_FIELD_NAME"}]
myValidator.validateSchemaFieldName('$no-good$').catch(console.log)
// Resolved Promise:
// > undefined
myValidator.validateSchemaFieldName('all-good')
validateSchemaFields(fields)
Validates an entire fields
object from a candidate collection schema. It runs validateSchemaField
on the individual fields.
// Rejected Promise:
// > [{"field": "fields", "code": "ERROR_EMPTY_FIELDS"}]
myValidator.validateSchemaFields({}).catch(console.log)
// Resolved Promise:
// > undefined
myValidator.validateSchemaFieldName({
title: {
type: 'string',
validation: {
minLength: 10
}
}
})
validateSchemaSettings(settings)
Validates an entire settings
object from a candidate collection schema.
// Rejected Promise:
// > [{"field": "fields.displayName", "code": "ERROR_INVALID_SETTING"}]
myValidator
.validateSchemaSettings({
displayName: ['should', 'be', 'a', 'string']
})
.catch(console.log)
// Resolved Promise:
// > undefined
myValidator.validateSchemaSettings({
displayName: 'I am a string'
})
validateValue({schema, value})
Validates a candidate value against a field schema. It returns a Promise that is resolved with undefined
if no validation errors occur, or rejected with an error object if validation fails.
const mySchema = {
title: {
type: 'string',
validation: {
minLength: 10
}
}
}
// Rejected Promise:
// > {"field": "title", "code": "ERROR_MIN_LENGTH"}
myValidator
.validateField({
schema: mySchema,
value: 'great'
})
.catch(console.log)
// Resolved Promise:
// > undefined
myValidator.validateDocument({
schema: mySchema,
value: 'super amazing!'
})
When a validationCallback
property is found in schema
, it is used as a callback function that allows the user to supply additional validation logic that will be executed after the normal validation runs. This function can trigger a validation error by returning a rejected Promise.