https://github.com/asheswook/valdex
Runtime type validation with TypeScript type inference
https://github.com/asheswook/valdex
typescript
Last synced: 6 months ago
JSON representation
Runtime type validation with TypeScript type inference
- Host: GitHub
- URL: https://github.com/asheswook/valdex
- Owner: asheswook
- License: mit
- Created: 2025-10-30T02:40:23.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-12-30T05:37:25.000Z (6 months ago)
- Last Synced: 2026-01-13T02:50:07.378Z (6 months ago)
- Topics: typescript
- Language: TypeScript
- Homepage:
- Size: 170 KB
- Stars: 9
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
### Basic Validation
```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
```
### Nested Objects
```typescript
validate(data, {
user: {
id: Number,
profile: {
name: String,
email: String
}
}
});
data.user.profile.name // string
```
### Arrays
```typescript
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:
```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
});
```
### Nullable Fields
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
})
});
```
### Combining Optional and Nullable
```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