@asaidimu/utils-schema

A lightweight, performant, and type-safe schema validation library for TypeScript, inspired by Go's robust type system. It supports complex data modeling, recursive structures, and predicate-based constraints.

Features

• Strict, Partial, and Loose Validation Modes: Flexible validation levels for different use cases.
• Complex Types: Supports nested objects, arrays, sets, records, unions, and recursive structures.
• Predicate-based Constraints: Enforce custom business logic with a plugin-based predicate architecture.
• Meta-Schema Validation: The library is self-validating, ensuring schema integrity.
• Standard Schema V1 Compatible: Easily integrate with ecosystems like Hono, Formik, or any library supporting the Standard Schema specification.
• High Performance: Optimized for fast validation of both flat and deep data structures.

Installation

npm install @asaidimu/utils-schema
# or
bun add @asaidimu/utils-schema

Quick Start

import { DocumentValidator } from "@asaidimu/utils-schema";

const schema = {
  name: "User",
  version: "1.0.0",
  fields: {
    f1: { name: "id", type: "string", required: true },
    f2: { name: "username", type: "string", required: true },
    f3: { name: "age", type: "integer", required: false },
  },
};

const validator = await DocumentValidator.create(schema, {});
const issues = await validator.validate({
  id: "u1",
  username: "jdoe",
  age: 30,
});

if (issues.length === 0) {
  console.log("Validation successful");
}

Validating Schemas

import { SchemaValidator } from "@asaidimu/utils-schema";
import { expect } from "vitest";

const schema = {
  // missing name
  version: "1.0.0",
  fields: {
    f1: { name: "id", type: "string", required: true },
    f2: { name: "username", type: "string", required: true },
    f3: { name: "age", type: "integer", required: false },
  },
};

const issues = await SchemaValidator.validate(schema);

expect(issues).toContainEqual(
  expect.objectContaining({
    code: "REQUIRED_FIELD_MISSING",
  }),
);

Validation Modes

The DocumentValidator provides three modes to handle different validation needs:

1. Strict (validate): All fields present must be declared in the schema. Required fields must be present.
2. Partial Strict (validatePartial): Suppresses REQUIRED_FIELD_MISSING issues, but still checks for type mismatches and unexpected fields.
3. Loose (validateLoose): Suppresses REQUIRED_FIELD_MISSING and UNEXPECTED_FIELD issues. Only validates types for present fields.

Standard Schema V1 Interoperability

To use with libraries supporting Standard Schema, use the StandardDocumentValidator wrapper:

import { StandardDocumentValidator } from "@asaidimu/utils-schema";

const standardValidator = await StandardDocumentValidator.create(schema);
const result = await standardValidator["~standard"].validate(data);

if (result.issues) {
  console.error("Validation failed", result.issues);
} else {
  console.log("Valid data", result.value);
}