Installation and Usage

Introduction

You can install the library using your favorite package manager:

yarn add @rattus-orm/plugin-zod-validate

@rattus-orm/plugin-zod-validate uses database events for type checking implementation, so it can be used with any Data Provider. To enable validation, invoke the plugin factory in the use method of your database:

import { createDatabase } from '@rattus-orm/core'

const db = createDatabase({
  connection: 'entities',
  dataProvider: new ObjectDataProvider(),
  plugins: [RattusZodValidationPlugin()]
})

db.start()

Non-Strict Mode

By default, the validator operates in non-strict mode, meaning no exception will be thrown in case of failed data validation:

class User extends Model {
  public static entity = 'user'

  @NumberField(0)
  public id: number

  @StringField('')
  public name: string
}

db.getRepository(User).save({ id: 'asdasd', name: 'test' })
// No error will occur, only a warning in the console: 
// 
// Data validation failed (connection.user):
// 1. Invalid number: "asdasd" (user.id)

Strict Mode

If you prefer to receive an error when data doesn't match the criteria, you can enable strict validation mode:

db.use(RattusZodValidationPlugin({ strict: true }))

Or, you can activate strict mode for specific models:

db.use(RattusZodValidationPlugin({ strict: [User.entity] }))

In this case, the above warning will turn into an error message:

class User extends Model {
  public static entity = 'user'

  @NumberField(0)
  public id: number

  @StringField('')
  public name: string
}

db.getRepository(User).save({ id: 'asdasd', name: 'test' })
// RattusZodValidationError: Data validation failed (connection.user):
// 1. Invalid number: "asdasd" (user.id)

The RattusZodValidationError contains the original Zod errors, in case they are needed. For TypeScript, you can use a special type guard:

import { isRattusZodValidationError } from '@rattus-orm/plugin-zod-validate'

try {
  db.getRepository(User).save({ id: 'asdasd', name: 'test' })
} catch (e) {
  if (isRattusZodValidationError(e)) {
    console.log(e.originalZodErrors) // ZodError[]
  }
}