https://github.com/unkn0wn-root/ts-validator
A lightweight, type-safe runtime validation library for TypeScript.
https://github.com/unkn0wn-root/ts-validator
deno nodejs typescript validation-library validator validator-node
Last synced: about 1 month ago
JSON representation
A lightweight, type-safe runtime validation library for TypeScript.
- Host: GitHub
- URL: https://github.com/unkn0wn-root/ts-validator
- Owner: unkn0wn-root
- License: mit
- Created: 2024-12-16T12:46:28.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2024-12-19T09:20:32.000Z (6 months ago)
- Last Synced: 2025-04-30T19:06:46.219Z (about 1 month ago)
- Topics: deno, nodejs, typescript, validation-library, validator, validator-node
- Language: TypeScript
- Homepage:
- Size: 73.2 KB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TypeScript Validator
A lightweight, type-safe runtime validation library for TypeScript.
## Features
- Full TypeScript support with type inference
- Runtime validation
- Composable schemas
- Automatic removal of unknown properties
- Zero dependencies
- Small bundle size
## Installation
```bash
npm install @unkn0wn-root/ts-validator
# or
yarn add @unkn0wn-root/ts-validator
```
## Usage
```typescript
import { validator } from '@unkn0wn-root/ts-validator';
enum Status {
Active = 'active',
Inactive = 'inactive',
Pending = 'pending'
}
// Define your schema
const userSchema = validator.object({
id: validator.number(),
username: validator.string().refine((s) => s.length >= 3, 'Username must be at least 3 characters'), // add custom validation
name: validator.string(),
email: validator.string().optional(),
status: validator.enum(Status),
metadata: validator.object({
lastLogin: validator.date().nullable(),
preferences: validator.object({
theme: validator.string()
}).optional()
})
});
// Type inference
type User = typeof userSchema._type;
// Parse data (throws on invalid data)
try {
const user = userSchema.parse({
id: 123,
username: "jobo"
name: "John",
email: "[email protected]",
status: Status.Active, // Must be one of "active", "inactive", or "pending"
metadata: {
lastLogin: new Date(),
preferences: {
theme: "dark"
}
}
});
console.log("Valid user:", user);
} catch (error) {
if (error instanceof validator.ValidationError) {
console.error("Validation errors:", error.issues);
}
}
// Safe parsing (returns result object)
const result = userSchema.safeParse(data);
if (result.success) {
console.log("Valid data:", result.data);
} else {
console.error("Validation errors:", result.error.issues);
}
```
## API Reference
### Basic Types
- `validator.string()`
- `validator.number()`
- `validator.boolean()`
- `validator.date()`
### Complex Types
- `validator.array(schema)`
- `validator.object(shape)`
- `validator.literal(value)`
- `validator.union(schemas)`
- `validator.enum(EnumType)`
### Modifiers
- `.optional()` - Makes a field optional
- `.nullable()` - Allows null values
- `.refine(check, message)` - Adds custom validation logic
## Error Handling
The library throws `ValidationError` instances which contain detailed information about validation failures:
```typescript
try {
const data = schema.parse(invalidData);
} catch (error) {
if (error instanceof validator.ValidationError) {
error.issues.forEach(issue => {
console.log(`Error at ${issue.path.join('.')}: ${issue.message}`);
});
}
}
```
## License
MIT