VibORM Internals

This section documents VibORM's internal architecture for contributors and advanced users who want to understand how the ORM works under the hood.

What You'll Learn

• Architecture - High-level system design and component relationships
• Schema System - How models, fields, and relations are defined
• Type System - TypeScript type inference and derivation
• Runtime Schemas - ArkType schema builders for validation
• Normalization - Input transformation pipeline
• Contract - Guarantees between types and runtime

Design Principles

1. Type-First Design

VibORM is built with TypeScript types as the source of truth. Rather than generating types from a schema file (like Prisma), types are inferred directly from the schema definition at compile time.

// Types are inferred, not generated
const user = s.model({
  id: s.string().id().ulid(),
  name: s.string(),
  email: s.string().unique(),
});

// TypeScript knows the exact shape
type UserFields = (typeof user)["~"]["fields"];
// { id: StringField<...>, name: StringField<...>, email: StringField<...> }

2. Dual Validation

Every operation is validated twice:

1. Compile-time - TypeScript catches type errors
2. Runtime - ArkType schemas validate actual data

3. Normalization Pipeline

User-friendly shorthand syntax is normalized to canonical forms before reaching the query engine, simplifying SQL generation.

4. Separation of Concerns

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Schema Layer   │────▶│  Client Layer   │────▶│  Query Engine   │
│  (Definition)   │     │  (Operations)   │     │  (Execution)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        ▼                       ▼                       ▼
   Type System            Type Guards           SQL Generation
   ArkType Schemas        Validation            Database Adapters

Quick Architecture Overview

Key Components

Next Steps

Start with Architecture for a comprehensive system overview, or jump directly to the component you're interested in.