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.

``typescript
// 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

Installation

`bash
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

$3

`typescript
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
`

$3

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

data.user.profile.name // string
`

$3

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

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

$3

Use Optional() to allow undefined values:

`typescript
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
});
`

$3

Use Nullable() to allow null values:

`typescript
import { validate, Nullable } from 'valdex';

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

$3

`typescript
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:

`typescript
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