A lightweight, zero-dependency, runtime validation library powered by code generation. Define your data shapes in a simple JSON file and AssertScript generates highly-optimized validation and sanitization functions, plus TypeScript definitions automatically.
AssertScript solves the problem of wanting type-safety in JavaScript without the overhead of a full TypeScript compilation step. It provides runtime guarantees that your data structures are correct, which is essential for validating API responses, form data, and function arguments.
The core workflow is simple:
- Define: You declare all your data shapes and rules in a single
types.json
file. - Generate: Run the AssertScript Node.js script to automatically generate
validators.js
andvalidators.d.ts
files. - Assert or Validate: Import the generated functions into your application to perform fast, precise, and descriptive runtime validation.
- Zero Production Dependencies: The generated validation code is pure, vanilla JavaScript.
- Dual-Mode Operation: Functions can fail-fast by throwing errors (assertion) or return a detailed result object (verbose validation).
- Data Sanitization: Automatically cleans and transforms data (e.g., trims whitespace, converts strings to numbers) based on schema rules.
- Rich Validation Rules: Go beyond simple
typeof
checks with powerful content-based rules. - TypeScript Declaration Generation: Get full autocompletion and type-checking in your editor (like VS Code) for free, even in a
.js
project. - Watch Mode: Automatically regenerates validators and types whenever your schema changes.
- Robust CLI: A professional command-line interface for easy use.
-
Install dependencies: This project uses a few development dependencies for code generation and testing.
npm install
-
Define Your Types: Edit the
types.json
file to define your data structures according to the guide below. -
Generate Validators: Run one of the following commands:
# Generate validators once npm run generate # Generate validators and the .d.ts file for type-safety npm run generate:dts # Start watch mode for automatic regeneration on save npm run watch
Each validator can be used in two modes, chosen at runtime.
Ideal for backend services or critical paths where you want to fail fast. It throws a descriptive error on the first validation failure.
import { validateUser } from './validators.js'
const badUserData = { id: 1, username: 'a' } // Username is too short
try {
validateUser(badUserData)
// This line will not be reached
} catch (error) {
console.error(error.message)
// Output: "Validation failed for User.username: must be at least 3 characters long."
}
Pass { verbose: true }
as the second argument. This mode never throws. It's perfect for UI form validation where you want to collect all errors at once.
The function returns an object: { isValid: boolean, errors: Array, value: object }
.
import { validateUser } from './validators.js'
const formInput = { id: 1, username: 'a', email: 'bad-email' }
const result = validateUser(formInput, { verbose: true })
if (!result.isValid) {
console.log('Please fix the following errors:')
for (const err of result.errors) {
// err is an object: { property: 'username', rule: 'minLength', message: '...' }
console.log(`- ${err.property}: ${err.message}`)
}
} else {
// The 'value' property contains the cleaned and sanitized data
const sanitizedUser = result.value
// ... do something with the safe data
}
This is the API for defining your data shapes.
By default, all properties are required. Add a ?
to a property name to make it optional.
"MyType": {
"id": { "type": "number" },
"name": { "type": "string" },
"isActive": { "type": "boolean" },
"notes?": { "type": "string" }
}
Reference another type by using its name as the type
.
"Product": {
"productId": { "type": "string" },
"seller": { "type": "Seller" }
}
Rule | Type | Description |
---|---|---|
minLength |
string |
The minimum number of characters. |
maxLength |
string |
The maximum number of characters. |
pattern |
string |
A regular expression string the value must match. |
min |
number |
The minimum numeric value. |
max |
number |
The maximum numeric value. |
enum |
string |
An array of specific string values that are allowed. |
isInteger |
number |
Value must be a whole number. |
startsWith |
string |
Value must start with the given substring. |
You can specify rules for the array itself (minLength
) and for the items
within it.
"Product": {
"tags": {
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"minLength": 2
}
}
}
Use the transform
array to clean and process data before it's validated.
Transform | Description |
---|---|
trim |
Removes leading/trailing whitespace. |
toLowerCase |
Converts the string to lowercase. |
toUpperCase |
Converts the string to uppercase. |
toInt |
Parses the value into an integer. |
Example:
"User": {
"username": {
"type": "string",
"minLength": 3,
"transform": ["trim", "toLowerCase"]
},
"id_from_url": {
"type": "string",
"transform": ["toInt"]
}
}
This project is licensed under the MIT License.