Simple, lightweight, and flexible TypeScript library for creating type-safe data objects with validation.

Implementation documentation can be found on https://salmon42.github.io/ts-data-objects.

Changelog can be found here

Table of Contents

• Introduction
• Installation
• Usage
  • Basic Object Definition
  • Using Individual Components
• Why ts-data-objects?
• When to choose ts-data-objects
• License

Introduction

ts-data-objects provides a lightweight way to create, validate, and parse TypeScript objects with user-defined runtime type checking. Unlike more complex validation libraries, it focuses on the essential task of ensuring data matches your TypeScript types - particularly useful when working with API responses or JSON data.

The library provides a compromise in balance between type safety and simplicity, allowing you to use as much or as little of its functionality as you need - from simple object construction with defaults to complete type-safe parsing and validation.

Installation

You can install this package from NPM registry https://www.npmjs.com/package/ts-data-objects.

npm install ts-data-objects

Usage

The library is exported with multiple entry points to allow granular usage of the available functionality.

// Importing everything from single entry point
import { ... } from 'ts-data-objects'

// Importing only partial functionality
import { ... } from 'ts-data-objects/common'
import { ... } from 'ts-data-objects/core'
import { ... } from 'ts-data-objects/deep' // Currently only experimental

Basic Object Definition

import { defineObject, isStr, isNum } from 'ts-data-objects'

// Define your TypeScript type. It may clash with generated constructor
type User = {
  name: string
  age: number
  verified?: boolean
}

// Create a complete object definition with validation
const { User, isUser, parseUser } = defineObject<User>('User', {
  // Default values
  defaultValues: {
    verified: false
  },
  // Type validation predicate
  predicate: o => (
    isStr(o?.name) &&
    isNum(o?.age)
  ),
  // doNotThrow: true // -> if this is set to true, you don't need to catch any error, it will only log console.error by itself
})

// Create a new user with defaults. Must provide both name and age accorting to TS type/interface
const user1 = User({ name: 'John', age: 20 })
// Result: { name: 'John', age: 20, verified: false }

// Validate unknown data
if (isUser(someData)) {
  // TS now knows that someData is User
  console.log(someData.name, someData.age)
}

// Safely parse unknown data (throws on invalid data)
// Throwing behavior may be changed with doNotThrow param in defineObject
try {
  const user2 = parseUser(apiResponse)
  console.log(user2.name)
}
catch (e: any) {
  console.error(e)
}

Using Individual Components

The library can be used modularly - you don't need to use all features:

import { dataObject, dataGuard } from 'ts-data-objects/core'
import { isStr, isNum } from 'ts-data-objects/common'

type User = {
  name: string
  age: number
  verified?: boolean
}

// Just create objects with defaults
const User = dataObject<User>({
  verified: false,
  // Here you an provide any default-like values to fill
  // if you don't get them from API response or want them
  // to be created automatically.
})

// Only guard function
const isUser = dataGuard<User>(o => (
  isStr(o?.name) &&
  isNum(o?.age)
  // You can use either helping typechecking functions
  // from 'ts-data-objects/common'
  // or use your own validation logic.
))

Why ts-data-objects?

This library is not at all something new in the web development environment. We already have well known and battle-tested libraries like Zod and Yup. While these libraries are excellent for comprehensive schema validation, ts-data-objects takes a different approach:

✅ 1. Simplicity first

• ts-data-objects focuses purely on TypeScript type validation
• No complex schema definition language to learn
• Uses standard TypeScript types and JavaScript type checks
• Smaller learning curve

💪 2. Flexible

• Availability of modular design - use only what you need
• No lock-in to a specific validation paradigm
• Works well as just a typed constructor utility

🔄 3. Type-System Aligned

• Works with your existing TypeScript interfaces
• No need to maintain or create separate schema definitions

☁ 4. Lightweight

• Easy to integrate into existing project
• No dependencies, small bundle size

When to choose ts-data-objects

ts-data-objects is ideal for projects that need straightforward type validation without the complexity of full schema validation libraries. It's particularly well-suited for API integration layers and internal data management where TypeScript types are the source of truth.

✅ Choose ts-data-objects when you:

• Need simple type validation for API responses
• Want to ensure data matches TypeScript types at runtime
• Need object construction with defaults
• Prefer using standard TypeScript types instead of reconstructing them with 3rd party library schemas
• Want a minimal, lightweight solution

❌ Consider Zod or Yup when you need:

• Complex validation rules (email formats, regex, etc.) out of the box
• Value transformations and coercion
• Advanced string/number constraints

License

This library is released under MIT license, which means that you can reuse any part of code here for your convenience.

Copyright (C) 2025-present, Andrej Hučko

• ~