EvoGuard

Production-grade, Defensive Runtime Validation for TypeScript.

Make unsafe developers write safe code by default.

EvoGuard protects your application from runtime crashes by enforcing strict schema validation at the boundaries of your system. It is designed to be fail-fast, zero-dependency, and impossible to ignore.

Why EvoGuard?

Runtime bugs often occur when external data (APIs, user input, JSON files) doesn't match what your TypeScript types expect.

The "Bad" Way (Anti-Pattern):

//  Dangerous: TypeScript trusts you, but runtime data might be wrong.
function processUser(data: any) {
  // CRASH: Cannot read properties of undefined (reading 'toUpperCase')
  return data.name.toUpperCase(); 
}

The EvoGuard Way:

//  Safe: Crash-proof by design.
const safeProcess = guard({ name: 'string' }, (data) => {
  return data.name.toUpperCase(); // Guaranteed to be a string
});

Installation

npm install evo-guard

Core API

1. guard(schema, fn)

Best for: API handlers, critical logic where invalid data should stop execution. Throws a typed EvoGuardError if validation fails.

import { guard } from 'evo-guard';

const createUser = guard(
  { 
    username: 'string', 
    age: 'number',
    role: ['enum', 'admin', 'user'], // Enum validation
    meta: { 
      source: 'string?', // Optional string
    } 
  },
  (user) => {
    // 'user' is fully typed here!
    console.log(`User: ${user.username}, Role: ${user.role}`);
  }
);

createUser({ username: 'Alice', age: 30, role: 'admin' }); // ✅
createUser({ username: 'Bob', age: '20' }); // ❌ Throws EvoGuardError

2. safeGuard(schema, fn)

Best for: Background jobs, high-availability services where you want to handle errors gracefully. Returns a Result object instead of throwing.

import { safeGuard } from 'evo-guard';

const processOrder = safeGuard({ amount: 'number' }, (order) => {
  return order.amount * 1.1; // Tax calc
});

const result = processOrder({ amount: 'invalid' });

if (result.ok) {
  console.log('Total:', result.data);
} else {
  console.error('Validation failed:', result.error.message); // Clean error log
}

Schema Reference

| Type | Syntax | Description | |------|--------|-------------| | String | 'string' | Matches non-empty strings | | Number | 'number' | Matches primitive numbers | | Boolean | 'boolean' | Matches true/false | | Any | 'any' | Bypasses validation | | Optional | 'type?' | e.g. 'string?', 'number?'. Allows null or undefined. | | Enum | ['enum', ...val] | e.g. ['enum', 'red', 'blue']. Matches specific values. | | Array | [Schema] | e.g. ['string']. Validates every item. | | Tuple | [S1, S2] | e.g. ['string', 'number']. Fixed length & types. | | Object | { key: Schema } | Recursive object validation. |

Flow

graph TD
    A[Input Data] --> B{guard / safeGuard}
    B -->|Schema Check| C{Valid?}
    C -->|No| D[Error Handling]
    D -->|guard| E[Throw EvoGuardError]
    D -->|safeGuard| F[Return { ok: false, error }]
    C -->|Yes| G[Execute Function]
    G --> H[Return Result]

Author

Daksha Dubey - Senior Software Architect

License

ISC