AkiVal

A schema validation library for Akinon applications. Wraps Yup with re-exports for convenient access to all validation utilities.

Installation

pnpm add @akinon/akival

Basic Usage

import { object, string, number, type InferType } from '@akinon/akival';

// Define a schema
const productSchema = object({
  name: string().required(),
  price: number().positive().required(),
  description: string().optional()
});

// Infer TypeScript type from schema
type Product = InferType<typeof productSchema>;

// Validate data
const validateProduct = async (data: unknown) => {
  try {
    const product = await productSchema.validate(data);
    return { success: true, data: product };
  } catch (error) {
    return { success: false, error };
  }
};

API Reference

Akival re-exports all Yup utilities. Below are the most commonly used exports.

Schema Builders

Export	Description
string()	String schema
number()	Number schema
boolean() / bool()	Boolean schema
date()	Date schema
array()	Array schema
object()	Object schema
mixed()	Mixed/any type schema
lazy()	Lazy evaluation schema
ref()	Reference to another field

Types

Export	Description
InferType<T>	Infer TypeScript type from schema
AnySchema	Any schema type
AnyObjectSchema	Any object schema type
ISchema	Schema interface
LocaleObject	Locale configuration type

Schema Classes

Export	Description
Schema	Base schema class
StringSchema	String schema class
NumberSchema	Number schema class
BooleanSchema	Boolean schema class
DateSchema	Date schema class
ArraySchema	Array schema class
ObjectSchema	Object schema class
MixedSchema	Mixed schema class

Utilities

Export	Description
setLocale()	Set global validation messages
akival	Full Yup namespace for advanced usage

---

Parsing and Transforms

Schemas can parse and transform input values. Use cast() to coerce values without validation:

import { number, object, string } from '@akinon/akival';

// Coerce string to number
const num = number().cast('1'); // 1

// Transform with object schema
const userSchema = object({
  firstName: string().lowercase().trim()
});

userSchema.cast({ firstName: '  JOHN  ' }); // { firstName: 'john' }

Custom Transforms

import { string } from '@akinon/akival';

const reversedString = string()
  .transform((currentValue) => currentValue.split('').reverse().join(''))
  .cast('dlrow olleh'); // "hello world"

---

Custom Tests

Create custom validation tests for complex logic:

import { string } from '@akinon/akival';

const skuSchema = string().test({
  name: 'is-valid-sku',
  skipAbsent: true,
  test(value, ctx) {
    if (!value.startsWith('s-')) {
      return ctx.createError({ message: 'SKU missing correct prefix' });
    }
    if (!value.endsWith('-42a')) {
      return ctx.createError({ message: 'SKU missing correct suffix' });
    }
    if (value.length < 10) {
      return ctx.createError({ message: 'SKU is not the right length' });
    }
    return true;
  }
});

---

Schema Immutability

Schemas are immutable. Each method call returns a new schema object:

import { string } from '@akinon/akival';

const optionalString = string().optional();
const definedString = optionalString.defined();

const value = undefined;
optionalString.isValid(value); // true
definedString.isValid(value); // false

This allows safe reuse and composition of schemas.

---

String Validation

import { string } from '@akinon/akival';

const schema = string()
  .required('Name is required')
  .min(2, 'Minimum 2 characters')
  .max(100, 'Maximum 100 characters')
  .email('Invalid email format')
  .url('Invalid URL')
  .matches(/^[a-z]+$/, 'Only lowercase letters');

Common String Methods

Method	Description
required(message?)	Field is required
min(limit, message?)	Minimum length
max(limit, message?)	Maximum length
email(message?)	Valid email format
url(message?)	Valid URL format
matches(regex, message?)	Match regex pattern
trim()	Trim whitespace
lowercase()	Transform to lowercase
uppercase()	Transform to uppercase
nullable()	Allow null
optional()	Field is optional

---

Number Validation

import { number } from '@akinon/akival';

const schema = number()
  .required('Price is required')
  .positive('Must be positive')
  .min(0, 'Minimum is 0')
  .max(1000000, 'Maximum is 1,000,000')
  .integer('Must be a whole number');

Common Number Methods

Method	Description
required(message?)	Field is required
min(limit, message?)	Minimum value
max(limit, message?)	Maximum value
positive(message?)	Must be positive
negative(message?)	Must be negative
integer(message?)	Must be an integer
moreThan(value, message?)	Greater than value
lessThan(value, message?)	Less than value

---

Object Validation

import { object, string, number, array } from '@akinon/akival';

const orderSchema = object({
  customer: object({
    name: string().required(),
    email: string().email().required()
  }),
  items: array().of(
    object({
      productId: number().required(),
      quantity: number().positive().integer().required()
    })
  ).min(1, 'At least one item required'),
  notes: string().optional()
});

---

Array Validation

import { array, string, number } from '@akinon/akival';

// Array of strings
const tagsSchema = array()
  .of(string().required())
  .min(1, 'At least one tag required')
  .max(10, 'Maximum 10 tags');

// Array of numbers
const scoresSchema = array()
  .of(number().min(0).max(100))
  .required();

---

Conditional Validation

import { object, string, number } from '@akinon/akival';

const paymentSchema = object({
  type: string().oneOf(['credit', 'debit', 'bank']).required(),
  cardNumber: string().when('type', {
    is: (type: string) => type === 'credit' || type === 'debit',
    then: (schema) => schema.required('Card number is required'),
    otherwise: (schema) => schema.optional()
  }),
  bankAccount: string().when('type', {
    is: 'bank',
    then: (schema) => schema.required('Bank account is required'),
    otherwise: (schema) => schema.optional()
  })
});

---

Cross-Field Validation

import { object, string, ref } from '@akinon/akival';

const passwordSchema = object({
  password: string()
    .min(8, 'Minimum 8 characters')
    .required('Password is required'),
  confirmPassword: string()
    .oneOf([ref('password')], 'Passwords must match')
    .required('Please confirm your password')
});

---

Custom Validation Messages

Per-Field Messages

import { string } from '@akinon/akival';

const schema = string()
  .required('This field cannot be empty')
  .min(3, 'Please enter at least 3 characters')
  .email('Please enter a valid email address');

Global Locale

import { setLocale } from '@akinon/akival';

setLocale({
  mixed: {
    required: 'This field is required',
    notType: 'Invalid value'
  },
  string: {
    min: 'Must be at least ${min} characters',
    max: 'Must be at most ${max} characters',
    email: 'Must be a valid email'
  },
  number: {
    min: 'Must be at least ${min}',
    max: 'Must be at most ${max}',
    positive: 'Must be a positive number'
  }
});

With i18n Integration

Use setLocale with your translation function for dynamic messages:

import { setLocale } from '@akinon/akival';

import { t } from './locale'; // Your Akilocale instance

setLocale({
  mixed: {
    required: ({ path }) => t('validation.required', { field: t(path) })
  },
  string: {
    min: ({ path, min }) => t('validation.minLength', { field: t(path), min })
  }
});

---

Integration with Akiform

Use Akival schemas with Akiform for form validation. The akivalResolver is exported from @akinon/akiform:

import { object, string, number } from '@akinon/akival';
import { Akiform, FormItem, useForm, akivalResolver } from '@akinon/akiform';
import { Input } from '@akinon/ui-input';
import { InputNumber } from '@akinon/ui-input-number';

const schema = object({
  name: string().required('Name is required'),
  price: number().positive('Must be positive').required('Price is required')
});

const ProductForm = () => {
  const form = useForm({
    resolver: akivalResolver(schema)
  });

  return (
    <Akiform form={form} onFinish={handleSubmit}>
      <FormItem name="name" label="Name">
        <Input />
      </FormItem>
      <FormItem name="price" label="Price">
        <InputNumber />
      </FormItem>
    </Akiform>
  );
};

---

Type Inference

import { object, string, number, array, type InferType } from '@akinon/akival';

const userSchema = object({
  id: number().required(),
  name: string().required(),
  email: string().email().required(),
  roles: array().of(string()).required()
});

// Automatically infer the type
type User = InferType<typeof userSchema>;
// Result: { id: number; name: string; email: string; roles: string[] }

---

Async Validation

import { string } from '@akinon/akival';

const usernameSchema = string()
  .required()
  .test('unique', 'Username is already taken', async (value) => {
    if (!value) return true;
    const response = await api.checkUsername(value);
    return response.available;
  });

---

Transform Values

import { string, number } from '@akinon/akival';

// Trim and lowercase
const emailSchema = string()
  .trim()
  .lowercase()
  .email();

// Parse string to number
const priceSchema = number()
  .transform((value, originalValue) => {
    return originalValue === '' ? undefined : value;
  })
  .positive();

---

Best Practices

1. Infer types from schemas - Use InferType to keep types in sync with validation

2. Use with Akiform - Combine with yupResolver for form validation

3. Set global locale - Configure setLocale for consistent error messages across the app

4. Keep schemas in separate files - Export schemas from dedicated files for reusability

5. Use conditional validation - Leverage .when() for dynamic field requirements

Related

• Akiform - Form library with validation support

• Akiform Builder - Schema-driven form builder

More Information

For complete Yup documentation, visit Yup GitHub.