valdex

Runtime type validation with TypeScript type inference

Validate unknown data at runtime and get automatic TypeScript type narrowing—without separate schema objects or class instances.

Why valdex?

Runtime validation libraries typically require you to define schemas separately and instantiate them before use. This creates distance between where you validate and where you consume the data.

Valdex takes a different approach: validate inline, exactly where you need it. No jumping between schema definitions and usage points. No maintaining separate DTO classes or validator instances.

// Traditional approach - schema defined elsewhere
const userSchema = z.object({ name: z.string(), age: z.number() });
const user = userSchema.parse(data);

// valdex - validate at point of use
validate(data, { name: String, age: Number });
// data is now typed as { name: string, age: number }

This is particularly useful when working with:

• Database query results (mysql2, pg, etc.)
• External API responses (axios, fetch)
• Message queue payloads
• Any unknown or any typed data that needs runtime verification

Philosophy

Valdex is intentionally small. It validates unknown data at the boundary and narrows its TypeScript type where the data is used. It is not a hidden control-flow engine.

Valdex avoids complex conditional schemas, branching rules, and transformation pipelines. If validation needs many branches, the payload is probably doing too much. For example, in an internal event system, that is often a sign that one event should be split into smaller, clearer events.

For internal payloads and repository responses, complexity should stay in explicit application code—or be removed by designing a simpler contract.

Valdex does not make complex payloads look simple. It encourages payloads to actually be simple.

The goal is clear validation, visible control flow, and lightweight type safety.

Installation

npm install valdex

Features

• Zero dependencies: No external dependencies
• Type inference: Automatic TypeScript type narrowing after validation
• Inline validation: Validate where you use, not where you define
• Nested structures: Full support for nested objects and arrays
• Optional/Nullable: Flexible handling of optional and nullable fields

Usage

Basic Validation

import { validate } from 'valdex';

const data: unknown = await fetchData();

validate(data, {
  name: String,
  age: Number,
  active: Boolean
});

// TypeScript now knows the exact type of data
data.name   // string
data.age    // number
data.active // boolean

Nested Objects

validate(data, {
  user: {
    id: Number,
    profile: {
      name: String,
      email: String
    }
  }
});

data.user.profile.name // string

Arrays

validate(data, {
  tags: [String],  // string[]
  items: [{        // { id: number, name: string }[]
    id: Number,
    name: String
  }]
});

data.tags[0]       // string
data.items[0].id   // number

Optional Fields

Use Optional() to allow undefined values:

import { validate, Optional } from 'valdex';

validate(data, {
  required: String,
  optional: Optional(String),  // string | undefined
  optionalObject: Optional({   // { id: number } | undefined
    id: Number
  }),
  optionalArray: Optional([Number]) // number[] | undefined
});

Nullable Fields

Use Nullable() to allow null values:

import { validate, Nullable } from 'valdex';

validate(data, {
  required: String,
  nullable: Nullable(String),  // string | null
  nullableObject: Nullable({   // { id: number } | null
    id: Number
  })
});

Combining Optional and Nullable

import { validate, Optional, Nullable } from 'valdex';

validate(data, {
  field: Optional(Nullable(String)) // string | undefined | null
});

Supported Types

Constructor	TypeScript Type
String	string
Number	number
Boolean	boolean
Array	any[]
Object	object
Date	Date

Error Handling

When validation fails, a RuntimeTypeError is thrown:

import { validate, RuntimeTypeError } from 'valdex';

try {
  validate(data, { count: Number });
} catch (error) {
  if (error instanceof RuntimeTypeError) {
    console.error(error.message);
    // "count must be Number, but got String. Actual value: hello"
  }
}

How It Works

• Fields not declared in the schema but present in data are ignored
• All declared fields are required by default (no undefined or null)
• Use Optional() to allow undefined
• Use Nullable() to allow null
• NaN is not considered a valid Number

License

MIT