Validation & constraints

prorm validates records before they hit the database. You attach validation
rules to a model's attributes, and the ORM runs them automatically on create,
and instance.update(). When a record fails, prorm throws a
ValidationError carrying a structured list of every failure. This guide
covers the built-in rule set, custom rules, the allowNull/unique
constraints, model-level validation, when validation fires, and the exact shape
of the error you get back.

Validation lives in src/validators/validator.ts. It is wired into models
through Model.create, instance.save, and instance.validate in
src/models/model.ts.

Field-level validators

Attach a validate object to any attribute. Each key is a rule name and each
value is the rule's argument. The value is

boolean | string | number | RegExp |
array

import { Prorm, INTEGER, STRING } from 'ts-prorm-orm';

const prorm = new Prorm({ dialect: 'sqlite', storage: ':memory:' });

const User = prorm.define('User', {
  id: { type: INTEGER, autoIncrement: true, primaryKey: true },
  username: {
    type: STRING(50),
    allowNull: false,
    validate: {
      notEmpty: true,     // rule enabled with `true`
      len: [3, 20],       // string length between 3 and 20
    },
  },
  email: {
    type: STRING(255),
    validate: { isEmail: true },
  },
  age: {
    type: INTEGER,
    validate: { isInt: true, min: 0, max: 150 },
  },
});

A boolean-style rule (isEmail, notEmpty, isInt, …) is turned on with
true. A parameterized rule takes its argument directly as the value: len
takes a number or a [min, max] tuple, min/max take a number, isIn/notIn
take an array, matches takes a RegExp.

Setting a rule value to false disables it, which is handy when overriding a
base configuration:

validate: { isEmail: false } // rule is skipped entirely

On a decorated model

The same rules, declared with @Validate:

import { Model, DataTypes, Table, Column, PrimaryKey, AutoIncrement,
         Validate, IsEmail, Len, Min, IsIn } from 'ts-prorm-orm';

@Table({ tableName: 'users' })
class User extends Model {
  @Column(DataTypes.INTEGER())
  @PrimaryKey
  @AutoIncrement
  declare id: number;

  @Column(DataTypes.STRING(50))
  @Validate({ notEmpty: true, len: [3, 20] })
  declare username: string;

  @Column(DataTypes.STRING(255))
  @IsEmail()
  declare email: string;

  @Column(DataTypes.INTEGER())
  @Min(0)
  declare age: number;
}

@Validate(rules) takes the same map as the validate option, and applying it
more than once merges — so rules can be split across lines, or added to a base
class's. Each shorthand is one rule: @IsEmail(), @IsUrl(), @IsIP(),
@IsAlpha(), @IsAlphanumeric(), @IsNumeric(), @IsInt(), @IsFloat(),
@IsDecimal(), @IsBoolean(), @IsDate(), @IsUUID(), @IsJSON(),
@NotEmpty(), @IsLowercase(), @IsUppercase(), @IsHexColor(),
@IsCreditCard() take an optional message; @Len(), @Min(), @Max(),
@Range(), @IsIn(), @NotIn(), @Matches(), @NotMatches(), @Equals()
and @NotEquals() take their argument.

class Post extends Model {
  @IsEmail('give a real address')     // rule + custom message
  declare contact: string;

  @Len([3, 20])                       // parameterised rule
  declare slug: string;

  @IsIn(['draft', 'live'])
  declare status: string;
}

Custom error messages

Pass a string instead of true to supply your own message. The rule still runs;
the string is only used as the failure message.

import { INTEGER, STRING } from 'ts-prorm-orm';

const Account = prorm.define('Account', {
  id: { type: INTEGER, autoIncrement: true, primaryKey: true },
  email: {
    type: STRING(255),
    validate: { isEmail: 'Please enter a valid email address' },
  },
});

Note that isIn and notIn treat a string value as data, not as a message —
always pass those an array.

The built-in validator set

Every rule below is implemented as a static method on the Validator class and
dispatched by name. Rules skip null, undefined, and empty-string values (use
notEmpty to require a value), so an optional field only validates when present.

Format and content:

isEmail — valid email address

isUrl — parseable URL

isIP — IPv4 or IPv6 address

isAlpha — letters only

isAlphanumeric — letters and digits only

isNumeric — digits only

isInt — integer

isFloat — floating-point number

isDecimal — decimal number (123.45)

isBoolean — boolean-ish value

isDate — parseable date

isTime — HH:MM or HH:MM:SS

isDateString — ISO 8601 date string

isUUID — UUID v1/v4/v5

isJSON — valid JSON value or string

isCreditCard — passes the Luhn check

isPostalCode — postal code (Validator.isPostalCode(value, locale), default US)

isMobilePhone — phone number (default locale en-US)

isHexColor — hex color such as #ff8800

isLowercase / isUppercase — case check

Presence, length, and range:

notEmpty — rejects null, undefined, empty string, empty array

isEmpty — the inverse

len — len: 8 for an exact length, len: [3, 20] for a range

min / max — numeric bounds

range — range: [1, 10]

Sets, equality, and patterns:

isIn: [...] — value must be one of the listed values

notIn: [...] — value must not be in the list

equals / notEquals — strict equality against the rule value

matches: /pattern/ — value matches the RegExp (string patterns are compiled)

notMatches: /pattern/ — value must not match

import { INTEGER, STRING } from 'ts-prorm-orm';

const Product = prorm.define('Product', {
  id: { type: INTEGER, autoIncrement: true, primaryKey: true },
  sku: {
    type: STRING(20),
    validate: {
      notEmpty: true,
      matches: /^[A-Z]{3}-\d{4}$/, // e.g. ABC-1234
    },
  },
  status: {
    type: STRING(20),
    validate: { isIn: ['active', 'inactive', 'archived'] },
  },
  quantity: {
    type: INTEGER,
    validate: { isInt: true, range: [0, 9999] },
  },
});

Where validation happens

Two distinct layers. Validators run in the process and never reach the
database — a ValidationError means no statement was sent. Constraints run in
the database and produce a different error. A uniqueness rule can only be
truly enforced by the second: between a validator's SELECT and the INSERT,
another writer can take the value.

Every failing rule is collected before anything is thrown, so one bad request
reports all of its problems at once:

await User.create({ username: 'ab', email: 'not-an-email', age: -5 });

ValidationError: Validation len on username failed, Validation isEmail on email failed, Validation min on age failed

Custom validators

For logic outside the built-in set, use matches with your own regular
expression, or run rules programmatically with the Validator class and the
standalone validate / validateField helpers. These are the same functions
the model uses internally. They are exported from the package root, and from
the ts-prorm-orm/validators subpath.

import { Validator, validate, validateField } from 'ts-prorm-orm';

// Call a single built-in method directly.
Validator.isEmail('user@example.com'); // true
Validator.len('abcd', [3, 20]);        // true
Validator.matches('ABC-1234', /^[A-Z]{3}-\d{4}$/); // true

// Validate a whole object against a rule config.
const result = validate(
  { email: 'nope', age: 200 },
  {
    email: { isEmail: true },
    age: { isInt: true, max: 150 },
  },
);
// result.valid === false
// result.errors -> one item per failed rule

// Validate a single value.
const one = validateField('ab', { len: [3, 20] });
// one.valid === false

To enforce rules that span several fields or need to run I/O, put the logic in a
beforeValidate (or beforeSave) hook and throw when it fails. A throw from the
hook aborts the write before it reaches the database:

import { INTEGER, STRING } from 'ts-prorm-orm';

const Booking = prorm.define('Booking', {
  id: { type: INTEGER, autoIncrement: true, primaryKey: true },
  startDate: { type: STRING(20) },
  endDate: { type: STRING(20) },
});

Booking.addHook('beforeValidate', (instance: any) => {
  if (instance.endDate < instance.startDate) {
    throw new Error('endDate must be on or after startDate');
  }
});

[!NOTE]
A throw from a hook is re-thrown as it is — a plain Error, not a
ValidationError — so a form handler that only looks for ValidationError
will not see it as a field problem. For cross-field rules that should read as
validation failures, use a model-level validator
instead: its message lands in err.errors like any other rule.

Uniqueness

There are two independent notions of "unique":

The unique attribute option is a database constraint applied when the
table is created or synced. It does not run during application-side validation.

import { INTEGER, STRING } from 'ts-prorm-orm';

const Member = prorm.define('Member', {
  id: { type: INTEGER, autoIncrement: true, primaryKey: true },
  email: { type: STRING(255), unique: true },
  // Named constraint, or an object form: { name, msg }
  slug: { type: STRING(60), unique: 'uq_member_slug' },
});

When the database rejects a duplicate, the dialect throws a
UniqueConstraintError (a ValidationError subclass, code
UNIQUE_CONSTRAINT_ERROR) whose fields names the colliding columns, with the
driver's error on .parent and the statement on .sql. Turn it into the same
shape as a validation failure, so the client sees one kind of error per field:

import { UniqueConstraintError } from 'ts-prorm-orm';

async function register(email: string) {
  try {
    return { member: await Member.create({ email }) };
  } catch (err) {
    if (err instanceof UniqueConstraintError) {
      return { errors: Object.fromEntries((err.fields ?? ['email']).map((f) => [f, ['Already registered']])) };
    }
    throw err;
  }
}

Before 4.9.2 the duplicate arrived as a plain Error carrying the driver's
text (Query error: SqliteError: UNIQUE constraint failed: …), and had to be
matched by message.

For an application-level uniqueness check that queries the database, use the
isUnique validation rule. Because it needs an async lookup, it only runs when
validation is executed asynchronously — which is exactly what create, save,
and the instance validate() method do. The synchronous entry points
(validate, validateField, isValid, validateSync) cannot query the
database and always pass isUnique, logging a warning instead.

isUnique resolves its target model either from a model registered with
registerValidatorModel(name, model) or from a live model reference passed as
options.model. When validation runs on an update, prorm automatically excludes
the current record (by primary key) so a row does not conflict with itself.

Model-level validation

The model's validate map holds two different things, told apart by what the
value is.

A function is a validator run against the whole instance — the place for a
rule that spans columns, which no per-column rule can express. It is called
with this bound to the instance and reports by throwing; it may be async.

import { INTEGER, DATE } from 'ts-prorm-orm';

const Event = prorm.define(
  'Event',
  {
    id: { type: INTEGER, autoIncrement: true, primaryKey: true },
    startsAt: { type: DATE },
    endsAt: { type: DATE },
  },
  {
    validate: {
      endsAfterStart(this: { endsAt: Date; startsAt: Date }) {
        if (this.endsAt <= this.startsAt) throw new Error('endsAt must be after startsAt');
      },
    },
  },
);

A model-level failure is reported under the validator's name, not a column:

{ "field": "endsAfterStart", "message": "endsAt must be after startsAt", "type": "endsAfterStart", "path": "endsAfterStart" }

On a decorated model that is a class-level @Validate:

@Table({ tableName: 'events' })
@Validate({
  endsAfterStart() {
    if (this.endsAt <= this.startsAt) throw new Error('endsAt must be after startsAt');
  },
})
class Event extends Model { /* … */ }

An object keyed by a column name attaches extra rules to that column, under
a validators key, composing with the attribute's own validate.

import { INTEGER, STRING } from 'ts-prorm-orm';

const Signup = prorm.define(
  'Signup',
  {
    id: { type: INTEGER, autoIncrement: true, primaryKey: true },
    email: { type: STRING(255), validate: { isEmail: true } },
    referralCode: { type: STRING(20) },
  },
  {
    validate: {
      referralCode: {
        validators: { len: [6, 6], isAlphanumeric: true },
      },
    },
  },
);

When validation runs

Validation runs on every write path that takes values from you, except a
plain bulkCreate. Measured on a prorm.define() model with an isEmail
rule, writing 'bad' (SQLite):

Call	Validated?
`Model.create(values)`	yes
`instance.update(values)`	yes
`instance.save()` on a new instance (`Model.build(…)`)	yes
`instance.save()` on a loaded, changed instance	yes: the changed columns and the model validators
`Model.update(values, { where })` (static)	yes: the values written; SQL expressions such as `literal()` are skipped
`Model.bulkCreate(rows, { validate: true })`	yes: every row is checked before any `INSERT`, and the error names the row (`row 1: …`)
`Model.bulkCreate(rows, { individualHooks: true })`	yes, per row
`Model.bulkCreate(rows)`	no: the `INSERT` is sent as is
`Model.create(values, { validate: false })`, `Model.update(values, { where, validate: false })`	no: validation (and its hooks) is skipped on purpose

[!NOTE]
Before 4.9.2, save() on a loaded row, the static Model.update() and
bulkCreate({ validate: true }) sent the write without validating, and
create(values, { validate: false }) validated anyway. Code that relied on
those writes getting through with invalid values now gets a
ValidationError; pass validate: false where that is intended.

For a bulk import, pass validate: true: one bad row stops the whole batch
before anything is written.

The switches:

Per model: validateOnInsert: false skips validation on inserts,
validateOnUpdate: false skips it on updates.

Globally for the model: skipValidations: true turns off all validation.

Per call: { validate: false } on create() and the static update()
skips validation for that call.

// Turn validation off for a whole model.
const Audit = prorm.define('Audit', { /* ... */ }, { skipValidations: true });

You can also validate on demand without writing:

// Async: runs every rule, including isUnique. Returns { valid, errors }.
const result = await user.validateRules();
if (!result.valid) console.log(result.errors);

// Validate only some fields.
await user.validateRules(['email', 'username']);

// Run beforeValidate / afterValidate hooks as part of the check.
await user.validateRules({ hooks: true });

// Synchronous checks (isUnique is skipped). Throws a ValidationError
// listing every failure when the instance is invalid.
user.validateSync();
user.isValid();                 // boolean, cached
await user.getValidationErrors(); // ValidationErrorItem[]

// Static: validate stored rows matching a query.
const errors = await User.validate({ where: { active: true } });

validate() on an instance is the password check. It was the rules form
until the name went to the thing people call far more often:
await user.validate(submittedPassword) answers true or false against a
@Secure field. The rules are validateRules(), with the
same arguments and the same result as before. The static User.validate()
above is unrelated and unchanged.

The ValidationError shape

When an automatic write fails validation, prorm throws a ValidationError
(exported from the package root, so err instanceof ValidationError works).
Its message joins every failure's message with , , and its errors
property is the full list.

import { ValidationError } from 'ts-prorm-orm';

try {
  await User.create({ username: 'ab', email: 'not-an-email', age: -5 });
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.name);    // 'ValidationError'
    console.log(err.errors);  // one item per failed rule
  }
}

The errors from that call, verbatim:

[
  { "field": "username", "message": "Validation len on username failed", "type": "len", "path": "username", "value": "ab" },
  { "field": "email", "message": "Please enter a valid email address", "type": "isEmail", "path": "email", "value": "not-an-email" },
  { "field": "age", "message": "Validation min on age failed", "type": "min", "path": "age", "value": -5 }
]

type is the rule that failed (notNull for a missing allowNull: false
value, whose message is username cannot be null), path is the field, and
message is your custom message when you gave one. The on-demand
validateRules() result uses the older item shape — type is always
'Validation error' and there is no field:

interface ValidationErrorItem {
  message: string; // human-readable failure message
  type: string;    // 'Validation error'
  path: string;    // the field name that failed
  value: any;      // the value that was rejected
}

The exported ValidationError class (used by the standalone helpers via
createValidationError) offers a few conveniences on top of a plain error:

import { ValidationError } from 'ts-prorm-orm';

const err = new ValidationError('Validation error', [
  { message: 'Bad email', type: 'Validation error', path: 'email', value: 'x' },
]);
err.errors;                    // the ValidationErrorItem[] it was built with
err.getMessages();             // ['Bad email']
err.getFieldErrors('email');   // items whose path === 'email'

Turning that into a 422 for an HTTP API — the usual end of the pipeline:

import express from 'express';
import { ValidationError } from 'ts-prorm-orm';
// `User` is the model from your db module — see Defining models.

export const userRoutes = express.Router();

userRoutes.post('/users', async (req, res, next) => {
  try {
    const user = await User.create(req.body);
    res.status(201).json(user);
  } catch (err) {
    if (err instanceof ValidationError) {
      const fields: Record<string, string[]> = {};
      for (const e of err.errors) (fields[e.path ?? '_model'] ??= []).push(e.message);
      return res.status(422).json({ error: 'validation_failed', fields });
    }
    next(err);
  }
});

{
  "error": "validation_failed",
  "fields": {
    "username": ["Validation len on username failed"],
    "email": ["Please enter a valid email address"],
    "age": ["Validation min on age failed"]
  }
}

Next: Hooks — running your own logic around the lifecycle.

Hooks — logic around the lifecycle, once values are valid

Error handling — what a validation failure looks like when it throws

Validation & constraints

Field-level validators#

On a decorated model#

Custom error messages#

The built-in validator set#

Where validation happens#

Custom validators#

Uniqueness#

Model-level validation#

When validation runs#

The ValidationError shape#

Related reading#