---
title: L2 - Scalars
description: Scalar type definitions with State generic for compile-time tracking
icon: box
---

**Location:** `src/schema/scalars/`

## Why This Layer Exists

Scalars need to preserve type information as users chain modifiers:

```typescript
s.string()           // StringScalar<{type: "string"}>
  .nullable()        // StringScalar<{type: "string", nullable: true}>  
  .default("hello")  // StringScalar<{..., default: "hello"}>
```

Each modifier returns a **new instance** with updated types. TypeScript tracks this through the State generic, enabling fully typed queries without code generation.

## The State Generic Pattern

Every scalar carries its configuration as a type parameter:

```typescript
class StringScalar<S extends StringScalarState> {
  // S contains: type, nullable, optional, default, unique, id, etc.
}
```

When you call `.nullable()`, a new scalar is created:

```typescript
nullable(): StringScalar<S & { nullable: true }> {
  return new StringScalar({ ...this.state, nullable: true });
}
```

The key insight: **immutability enables type tracking**. If we mutated the scalar, TypeScript couldn't know the type changed.

## Available Scalar Types

| Factory | Database Type | TypeScript Type |
|---------|---------------|-----------------|
| `s.string()` | VARCHAR/TEXT | `string` |
| `s.int()` | INTEGER | `number` |
| `s.bigInt()` | BIGINT | `bigint` |
| `s.number()` | FLOAT/DOUBLE | `number` |
| `s.decimal({ precision, scale })` | `NUMERIC(p,s)` / `DECIMAL(p,s)` / scaled `INTEGER` | `Decimal` |
| `s.boolean()` | BOOLEAN | `boolean` |
| `s.dateTime()` | DATETIME/TIMESTAMP | `Date` |
| `s.date()` | DATE | `string` (ISO date) |
| `s.time()` | TIME | `string` (ISO time) |
| `s.json<T>()` | JSON/JSONB | `T` |
| `s.enum(values)` | ENUM/VARCHAR | `values[number]` |
| `s.blob()` | BLOB/BYTEA | `Uint8Array` |
| `s.point()` | provider GeoPoint representation | `{ longitude, latitude }` |
| `s.vector().dimension(n)` | VECTOR | `number[]` |

The validation codec declares the one structural decimal descriptor shape.
Each fixed-decimal scalar validates and freezes one instance in scalar state.
The field-aware codec uses that instance for canonical private text, provider
scalar/list conversion, and final public `Decimal` construction. Consumers do
not invent a parallel live descriptor owner.

## Common Modifiers

Modifiers work across scalar types where applicable:

| Modifier | Purpose |
|----------|---------|
| `.nullable()` | Allow NULL values |
| `.default(value)` | Set default value |
| `.id()` | Mark as primary key |
| `.unique()` | Add unique constraint |
| `.map(columnName)` | Map to different column name |
| `.uuid()` | Auto-generate UUIDs (string) |
| `.ulid()` | Auto-generate ULIDs (string) |

## Lazy Schema Building

Scalars don't build validation schemas immediately - that would be slow. Instead, schemas are built **on first access**:

```typescript
// Internal pattern
get ["~"]() {
  this._schemas ??= buildSchemas(this.state);  // Built once, cached
  return this._schemas;
}
```

This matters because VibORM creates many scalar instances during schema definition, but only builds validation schemas when actually needed for queries.

## Connection to Other Layers

- **L1 (Validation)**: Scalars use `v.*` primitives internally
- **L3 (Query Schemas)**: Query schemas compose scalar schemas for where/create/update  
- **L7 (Adapters)**: Scalar types determine SQL column types
- **L12 (Migrations)**: Scalar state drives DDL generation
