@apideck/reva
v0.2.1
Published
[![npm (scoped)](https://img.shields.io/npm/v/@apideck/reva?color=brightgreen)](https://npmjs.com/@apideck/reva) [![npm](https://img.shields.io/npm/dm/@apideck/reva)](https://npmjs.com/@apideck/reva) [![GitHub Workflow Status](https://img.shields.io/githu
Downloads
312
Readme
@apideck/reva 🕵
Server-side request validator for Node.js based on OpenAPI
- Supports all OpenAPI parameters
- Based on AJV
- Readable and helpful errors (by @apideck/better-ajv-errors)
- High quality TypeScript definitions included
- Minimal footprint: 42 kB including AJV (gzip + minified)
Install
$ yarn add @apideck/reva
or
$ npm i @apideck/reva
Usage
Create a Reva instance and call the validate
method with your OpenAPI operation and your request data.
import { Reva } from '@apideck/reva';
const reva = new Reva();
const result = reva.validate({
operation, // OpenAPI operation
request: {
headers: { 'X-My-Header': 'value', Cookie: 'Key=Value' },
pathParameters: { id: 'ed55e7a3' },
queryParameters: { order_by: 'created' },
body: { name: 'Jane Doe' },
},
});
if (result.ok) {
// Valid request!
} else {
// Invalid request, result.errors contains validation errors
console.log(result.errors);
// {
// "ok": false,
// "errors": [
// {
// "path": "request.query",
// "message": "'order_by' property must be equal to one of the allowed values",
// "suggestion": "Did you mean 'created_at'?",
// "context": { "errorType": "enum", "allowedValues": ["created_at", "updated_at"] }
// },
// {
// "path": "request.header",
// "message": "request.header must have required property 'x-required-header'",
// "context": { "errorType": "required" }
// },
// {
// "path": "request.body",
// "message": "'name' property is not expected to be here",
// "context": { "errorType": "additionalProperties" }
// }
// ]
// }
}
API
Reva
Reva is the main Request validation class. You can optionally pass options to the constructor.
new Reva(options?: RevaOptions)
Parameters
options: RevaOptions
allowAdditionalParameters?: true | OpenApiParameterType[]
Allow additional parameters to be passed that are not defined in the OpenAPI operation. Usetrue
to allow all parameter types to have additional parameters. Default value:['header', 'cookie']
partialBody?: boolean
Ignore required properties on the requestBody. This option is useful for update endpoints where a subset of required properties is allowed. Default value:false
groupedParameters?: OpenApiParameterType[]
Validate multiple OpenAPI parameter types as one schema. This is useful for APIs where parameters (query
,path
, etc) are combined into a singleparameters
object. Default value:[]
paramAjvOptions?: AjvOptions
Custom AJV options for request param validation.bodyAjvOptions?: AjvOptions
Custom AJV options for request body validation.
reva.validate(options: RevaValidateOptions)
Validate requests based on OpenAPI. Parameter validation uses type coercion, request body validation does not. When a Content-Type header is passed, it has to match a Content-Type defined in the OpenAPI operation. Default Content-Type is application/json
.
Parameters
options: RevaValidateOptions
operation: OpenApiOperation
Your OpenAPI operation object to validate againstrequest: RevaRequest
The request data to validate. All properties are optionalqueryParameters?: Record<string, unknown>
Query parameters to validateheaders?: Record<string, unknown>
Headers to validatepathParameters?: Record<string, unknown>
Path parameters to validatebody?: unknown
Request body to validate
options?: RevaOptions
Override options set in the Reva constructor
Return Value
Result<ValidationError>
ok: boolean
Indicates if the request is valid or noterrors?: ValidationError[]
Array of formatted errors. Only populated whenResult.ok
isfalse
message: string
Formatted error messagesuggestion?: string
Optional suggestion based on provided data and schemapath: string
Object path where the error occurred (example:.foo.bar.0.quz
)context: { errorType: DefinedError['keyword']; [additionalContext: string]: unknown }
errorType
iserror.keyword
proxied fromajv
.errorType
can be used as a key for i18n if needed. There might be additional properties on context, based on the type of error.