inputshield

Lightweight, TypeScript-first input validation and security hardening library for Node.js applications.

inputshield provides strongly typed, composable validation schemas for user inputs with built-in prototype pollution defenses and fail-closed security guarantees.

Installation

npm install inputshield

Usage & Examples

1. Schema Factory Import

import { s, InputShieldError } from 'inputshield';

2. Primitive Validators

String Validation

const EmailSchema = s.string().trim().toLowerCase().email();
const UsernameSchema = s.string().min(3).max(20).regex(/^[a-z0-9_]+$/);

const res1 = EmailSchema.safeParse('  [email protected]  ');
// res1.success === true -> res1.data === '[email protected]'

const UrlSchema = s.string().url();
const res2 = UrlSchema.safeParse('https://example.com');
// res2.success === true

Number Validation

const AgeSchema = s.number().int().min(18).max(120);

const res = AgeSchema.safeParse(25);
// res.success === true -> res.data === 25

Date Validation

const EventDateSchema = s.date().coerce().min(new Date('2026-01-01'));

const res = EventDateSchema.safeParse('2026-08-14T00:00:00.000Z');
// res.success === true -> res.data is a Date instance

3. Object & Array Schemas

Object Validation (With Built-In Prototype Pollution Defense)

ObjectSchema validates key-value schemas while automatically rejecting dangerous object keys (__proto__, constructor, prototype) to prevent prototype contamination.

const UserProfileSchema = s.object({
  username: s.string().min(3),
  age: s.number().int().min(18),
  email: s.string().email().optional(),
});

// Safe parse
const result = UserProfileSchema.safeParse({
  username: 'alice',
  age: 25,
  email: '[email protected]',
});

if (result.success) {
  console.log('Validated User:', result.data.username);
} else {
  console.error('Validation Issues:', result.error.issues);
}

Array Validation

const TagsSchema = s.array(s.string().min(1)).min(1).max(5);

const res = TagsSchema.safeParse(['typescript', 'security']);
// res.success === true

4. Result Parsing Modes

Non-Throwing (safeParse)

Returns a discriminated union { success: true, data } | { success: false, error }.

const result = s.string().min(5).safeParse('hi');

if (!result.success) {
  console.log(result.error.issues); 
  // [{ code: 'TOO_SHORT', message: 'String must be at least 5 characters long', received: 'hi' }]
}

Exception-Based (parse)

Returns the validated data directly or throws an InputShieldError.

try {
  const data = s.string().min(5).parse('hi');
} catch (err) {
  if (err instanceof InputShieldError) {
    console.error(err.message);
    console.error(err.issues);
  }
}

License

MIT