Typedantic

Typedantic is a TypeScript-first schema validation library inspired by Pydantic. It enables developers to define strongly typed data models and perform strict runtime validation while maintaining full TypeScript type inference.

The package is designed for backend, frontend, and serverless JavaScript applications where data correctness, predictability, and maintainability are critical.

Features

• Validate objects, arrays, and primitive types (string, number, boolean)
• Optional, nullable, and default fields
• Required fields with constraints and custom messages
• Nested models with automatic path-based error reporting
• Array validation with schema support

Installation

npm install typedantic

Examples

// array.test.ts
import { Schema, string, number, object, array } from "typedantic";

const UserSchema = new Schema(
  array(
    object({
      name: string(),
      age: number().optional(),
      address: string().optional(),
      username: string().optional(),
      email: string().optional(),
    })
  )
);

const users = UserSchema.parse([
  { name: "Tariq", age: 30 },
  { name: "Ali" },
]);

console.log(users);

// Output:
/*
[
  { name: 'Tariq', age: 30 },
  { name: 'Ali' }
]
*/

Base Model

// base-model.test.ts
import { string, number, boolean, BaseModel } from "typedantic";


// Default User Model
export const UserModel = new BaseModel({
  name: string(),
  age: number().optional(),
  email: string().optional(),
  active: boolean().optional(),
});

const user = UserModel.parse({ name: "Tariq", age: 30 });

console.log(user);

// Output:
/*
{
  name: 'Tariq',
  age: 30
}
*/

Errors

// errors.test.ts
import { Schema, string, number, object, ValidationError } from "typedantic";


// ------------------------
// Test: Required field missing
// ------------------------
try {
  const schema1 = new Schema(
    object({
      name: string(),
      age: number(),
    })
  );

  schema1.parse({ age: 25 }); // Missing 'name'

} catch (err) {
  if (err instanceof ValidationError) {
    console.log("Test 1 Passed: Required field missing");
    console.log(err.issues); // Should show path '' and message about 'name'
  } else {
    console.error("Test 1 Failed", err);
  }
}

// ------------------------
// Test: Type mismatch
// ------------------------
try {
  const schema2 = new Schema(
    object({
      name: string(),
      age: number(),
    })
  );

  schema2.parse({ name: "Tariq", age: "25" }); // 'age' should be number
} catch (err) {
  if (err instanceof ValidationError) {
    console.log("Test 2 Passed: Type mismatch");
    console.log(err.issues); // Should show error about 'age'
  } else {
    console.error("Test 2 Failed", err);
  }
}

// ------------------------
// Test: Optional field present and valid
// ------------------------
try {
  const schema3 = new Schema(
    object({
      name: string(),
      email: string().optional(),
    })
  );

  const user = schema3.parse({ name: "Tariq", email: "[email protected]" });
  console.log("Test 3 Passed: Optional field valid");
  console.log(user);
} catch (err) {
  console.error("Test 3 Failed", err);
}

// ------------------------
// Test: Optional field missing
// ------------------------
try {
  const schema4 = new Schema(
    object({
      name: string(),
      email: string().optional(),
    })
  );

  const user = schema4.parse({ name: "Ali" });
  console.log("Test 4 Passed: Optional field missing is fine");
  console.log(user); // email should be undefined
} catch (err) {
  console.error("Test 4 Failed", err);
}

// ------------------------
// Test: Nested object error
// ------------------------
try {
  const schema5 = new Schema(
    object({
      user: object({
        name: string(),
        age: number(),
      }),
    })
  );

  schema5.parse({ user: { name: "Tariq", age: "30" } }); // age type mismatch
} catch (err) {
  if (err instanceof ValidationError) {
    console.log("Test 5 Passed: Nested object type error");
    console.log(err.issues);
  } else {
    console.error("Test 5 Failed", err);
  }
}

// Output:
/*
Test 1 Passed: Required field missing
[
  {
    "path": "",
    "message": "Required field missing"
  }
]
Test 2 Passed: Type mismatch
[
  {
    "path": "/age",
    "message": "Type mismatch"
  }
]
Test 3 Passed: Optional field valid
{
  name: 'Tariq',
  email: '[email protected]'
}
*/

Extended Base Model

// extend-base-model.test.ts
import { string, number, boolean, BaseModel } from "typedantic";


// ---------------- Nested Address model
const AddressModel = new BaseModel({
  street: string(),
  city: string(),
  zip: string().optional(),
});

// ---------------- User model with nested address
const UserModel = new BaseModel({
  name: string(),
  age: number().required({ min: 6, max: 15, integer: true }),
  email: string().default("[email protected]"),
  active: boolean().optional(),
  isAdmin: boolean().default(true),
  address: AddressModel, // Nested BaseModel
});

// ---------------- Extend user with extra fields
const ExtendedUserModel = UserModel.extend({
  username: string().optional(),
  role: string().optional(),
  password: string().required({
    message: "Password is required",
  }),
});

try {
  const user = ExtendedUserModel.parse({
    name: "Tariq",
    email: "[email protected]",
    username: "tariq123",
    address: { street: "Main St", city: "Karachi" },
    password: "",  // <-- empty string triggers required
    age: 8,
  });
} catch (err: any) {
  console.error("Validation Error:");
  err.issues.forEach((issue: any) => console.error(`- ${issue.path}: ${issue.message}`));
}

// Output:
/*
Validation Error:
- /password: Password is required
- /age: Minimum age is 6
- /age: Maximum age is 15
- /age: Age must be an integer
*/

Schema

// schema.test.ts
import { Schema, string, number, object } from "typedantic";


const UserSchema = new Schema(
  object({
    name: string(),
    age: number().optional(),
    address: string().optional(),
    username: string().optional(),
    email: string().optional(),
  })
);

const user = UserSchema.parse({ name: "Tariq", age: 30 });
console.log(user);

// Output:
/*
{
  name: 'Tariq',
  age: 30
}
*/

Validation

// validation.test.ts
import { Schema, string, number, boolean, object, array } from "typedantic";


// ------------------------
// Test 1: Basic object validation
// ------------------------
const UserSchema = new Schema(
  object({
    name: string(),
    age: number(),
  })
);

const user1 = UserSchema.parse({ name: "Tariq", age: 30 });
console.log("Test 1 Passed:", user1);

// ------------------------
// Test 2: Optional fields
// ------------------------
const UserOptionalSchema = new Schema(
  object({
    name: string(),
    age: number().optional(),
    email: string().optional(),
  })
);

const user2a = UserOptionalSchema.parse({ name: "Ali" });
console.log("Test 2a Passed:", user2a);

const user2b = UserOptionalSchema.parse({ name: "Ali", age: 25, email: "[email protected]" });
console.log("Test 2b Passed:", user2b);

// ------------------------
// Test 3: Nullable number
// ------------------------
const ScoreSchema = new Schema(
  object({
    name: string(),
    score: number().nullable(),
  })
);

const score1 = ScoreSchema.parse({ name: "Tariq", score: null });
console.log("Test 3a Passed:", score1);

const score2 = ScoreSchema.parse({ name: "Ali", score: 100 });
console.log("Test 3b Passed:", score2);

// ------------------------
// Test 4: Nested object
// ------------------------
const NestedSchema = new Schema(
  object({
    user: object({
      name: string(),
      age: number().optional(),
    }),
  })
);

const nested1 = NestedSchema.parse({ user: { name: "Tariq" } });
console.log("Test 4a Passed:", nested1);

const nested2 = NestedSchema.parse({ user: { name: "Ali", age: 25 } });
console.log("Test 4b Passed:", nested2);

// ------------------------
// Test 5: Array of objects
// ------------------------
const UsersArraySchema = new Schema(
  array(
    object({
      name: string(),
      age: number().optional(),
    })
  )
);

const usersArray = UsersArraySchema.parse([
  { name: "Tariq", age: 30 },
  { name: "Ali" },
]);
console.log("Test 5 Passed:", usersArray);

// ------------------------
// Test 6: Boolean field
// ------------------------
const BoolSchema = new Schema(
  object({
    active: boolean(),
    verified: boolean().optional(),
  })
);

const bool1 = BoolSchema.parse({ active: true });
console.log("Test 6a Passed:", bool1);

const bool2 = BoolSchema.parse({ active: false, verified: true });
console.log("Test 6b Passed:", bool2);

// Output:
/*
Test 1 Passed: { name: 'Tariq', age: 30 }
Test 2a Passed: { name: 'Ali', age: undefined, email: undefined }
Test 2b Passed: { name: 'Ali', age: 25, email: '[email protected]' }
Test 3a Passed: { name: 'Tariq', score: null }
Test 3b Passed: { name: 'Ali', score: 100 }
Test 4a Passed: { user: { name: 'Tariq', age: undefined } }
Test 4b Passed: { user: { name: 'Ali', age: 25 } }
Test 5 Passed: [ { name: 'Tariq', age: 30 }, { name: 'Ali', age: undefined } ]
Test 6a Passed: { active: true, verified: undefined }
Test 6b Passed: { active: false, verified: true }
*/

MIT License

Copyright (c) 2026 Tariq Mehmood