🔮 Warlock Seal

> Cast validation seals on your schemas to protect your data

A powerful, type-safe validation library for TypeScript with an intuitive API and framework-agnostic design.

📦 Installation

``bash
npm install @warlock.js/seal
`

`bash
yarn add @warlock.js/seal
`

`bash
pnpm add @warlock.js/seal
`

🚀 Quick Start

`typescript
import { v, type Infer } from "@warlock.js/seal";

// Define your validation schema (cast a seal)
const userSeal = v.object({
name: v.string().required().min(3),
email: v.string().email().required(),
age: v.int().min(18),
status: v.string().in(["active", "inactive"]),
});

// Extract TypeScript type automatically
type User = Infer;
// Result: { name: string; email: string; age: number; status: string }

// Validate data
const result = await v.validate(userSeal, userData);

if (result.isValid) {
console.log("Data is sealed! ✅", result.data);
} else {
console.log("Seal broken! ❌", result.errors);
// [
// { error: "The name must be at least 3 characters", path: "name" },
// { error: "The email must be a valid email address", path: "email" }
// ]
}
`

🎯 Core Concepts

$3

Seal uses a unique three-layer architecture that separates concerns:

`
Input Data
↓
🔧 MUTATORS (Prep for Validation)
- Normalize data before validation
- Examples: trim(), lowercase(), toStartOfDay()
- Run BEFORE validation rules
↓
✅ VALIDATORS (Check Constraints)
- Validate against rules
- Examples: email(), min(), after()
- Return errors if validation fails
↓
🎨 TRANSFORMERS (Format Output)
- Format validated data for output
- Examples: toISOString(), toFormat()
- Run AFTER validation passes
↓
Output Data
`

$3

`typescript
const schema = v
.date()
.toStartOfDay() // 🔧 Mutator: normalize to 00:00:00
.after("2024-01-01") // ✅ Validator: check Date object
.toISOString(); // 🎨 Transformer: output as ISO string

const result = await v.validate(schema, "2024-06-15 14:30:00");
// result.data = "2024-06-15T00:00:00.000Z"
`

Why this matters:

- Mutators prepare data for validation (no more string comparison issues!)
- Validators check constraints on normalized data
- Transformers format output without affecting validation

---

🌟 Key Features

$3

Automatically extract TypeScript types from your schemas:

`typescript
const schema = v.object({
name: v.string().required(),
age: v.int(),
tags: v.array(v.string()),
});

type User = Infer;
// { name: string; age: number; tags: string[] }
`

$3

Readable, chainable methods:

`typescript
v.string().required().email().min(5).max(100);

v.int().min(0).max(100).positive();

v.array(v.string()).minLength(1).unique();
`

$3

Apply different validators based on other field values:

`typescript
const schema = v.object({
type: v.string().required().in(["admin", "user"]),
role: v.string().when("type", {
is: {
admin: v.string().required().in(["super", "moderator"]),
user: v.string().required().in(["member", "guest"]),
},
}),
});

// If type is "admin", role must be "super" or "moderator"
// If type is "user", role must be "member" or "guest"
`

$3

Compare fields against each other (global or sibling scope):

`typescript
const schema = v.object({
password: v.string().required().min(8),
confirmPassword: v.string().required().sameAs("password"), // Compare with password field

startDate: v.date().required(),
endDate: v.date().required().after("startDate"), // Compare with startDate field
});
`

$3

Add your own validation logic:

`typescript
v.string().refine(async value => {
const exists = await checkUsername(value);
if (exists) return "Username already taken";
});
`

$3

Normalize input and format output:

`typescript
// String mutators
v.string()
.trim() // Remove whitespace
.lowercase() // Convert to lowercase
.email() // Validate email
.toJSON(); // Transform to JSON string

// Date mutators & transformers
v.date()
.toStartOfDay() // Normalize to midnight
.after("2024-01-01")
.toISOString(); // Output as ISO string
`

---

📚 Documentation

For complete documentation, visit: https://warlock.js.org/seal

$3

| Validator | Purpose | Example |
| ------------- | ------------------ | -------------------------------- |
| v.string() | String validation | v.string().email().min(3) |
| v.int() | Integer validation | v.int().min(0).max(100) |
| v.float() | Float validation | v.float().positive() |
| v.number() | Number validation | v.number().min(0) |
| v.boolean() | Boolean validation | v.boolean().accepted() |
| v.date() | Date validation | v.date().after(new Date()) |
| v.array() | Array validation | v.array(v.string()).min(1) |
| v.object() | Object validation | v.object({ name: v.string() }) |
| v.scalar() | Scalar values | v.scalar().in([1, "2", true]) |

$3

Available on all validators:

| Method | Purpose |
| -------------------------- | -------------------------------- |
| .required() | Value must be present |
| .optional() | Value is optional |
| .forbidden() | Value must not be present |
| .equals(value) | Must equal specific value |
| .default(value) | Set default value |
| .allowsEmpty() | Skip validation if empty |
| .when(field, conditions) | Conditional validation |
| .omit() | Validate but exclude from output |
| .refine(callback) | Custom validation logic |

---

💡 Examples

$3

`typescript
const registerSchema = v.object({
email: v.string().required().email(),
password: v.string().required().min(8).strongPassword(),
confirmPassword: v.string().required().sameAs("password"),
age: v.int().required().min(18).max(120),
terms: v.boolean().required().accepted(),
});
`

$3

`typescript
const formSchema = v.object({
accountType: v.string().required().in(["personal", "business"]),

// Required only if accountType is "business"
companyName: v.string().requiredIf("accountType", { is: "business" }),

// Conditional validation
taxId: v.string().when("accountType", {
is: {
business: v
.string()
.required()
.pattern(/^[0-9]{9}$/),
personal: v.string().forbidden(),
},
}),
});
`

$3

`typescript
const bookingSchema = v.object({
checkIn: v.date().required().afterToday(),

checkOut: v
.date()
.required()
.after("checkIn") // Compare with checkIn field
.withinDays(30), // Max 30 days from checkIn
});
`

$3

`typescript
const tagsSchema = v
.array(v.string())
.required()
.minLength(1)
.maxLength(10)
.unique();

const usersSchema = v
.array(
v.object({
name: v.string().required(),
email: v.string().email(),
})
)
.minLength(1);
`

---

🔧 Framework Extensions

For Warlock.js projects, framework-specific validators are available:

`typescript
import { v } from "@warlock.js/core/v";

const schema = v.object({
email: v.string().email().unique(User), // Database validation
avatar: v.file().image().maxSize(5000000), // File upload validation
uploadId: v.string().uploadable(), // Upload hash validation
});
`

---

🎨 Why "Seal"?

🔮 Magical Context
Warlocks use seals to protect and verify. Your validation schemas are seals that protect your data integrity.

💻 Programming Context
A "seal of approval" - data that passes validation is sealed and verified.

✨ Developer Experience
Clean, intuitive API that feels natural:

`typescript
const seal = v.object({ ... }); // Cast a seal
await v.validate(seal, data); // Verify with the seal
``

---

🤝 Philosophy

Seal is designed around three principles:

1. Type Safety First - TypeScript support is not an afterthought
2. Framework Agnostic - Works anywhere JavaScript runs
3. Intuitive API - If it feels right, it probably works

---

📖 Full Documentation

For complete documentation, visit: https://warlock.js.org/seal

The documentation includes:

- 📘 Getting Started Guide
- 🎯 Core Concepts
- 📝 Validator Reference
- 🔍 All Validation Rules
- 🔌 Plugin System
- 🎨 Custom Rules

---

📄 License

MIT

---

🤝 Contributing

See main Warlock.js repository

---

Cast your seals and protect your data! 🔮✨