TypeScript Data Objects - v1.1.0

Documentation Status:

README.md

TS Data Objects

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

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.

If you like this library, don't hesitate to give this repository a star! 😊

readme/CHANGELOG.md

Changelog

1.1.0: Fix parseObject returning undefined on doNotThrow
1.0.1: Fix docs
1.0.0:
- Small finalizing touches to code documentation
- Introduced unit tests for assertions and core functions
- Declaring ts-data-objects/common as stable
- Declaring ts-data-objects/core as stable
- Declaring ts-data-objects/deep as experimental, but available
0.7.1: Fix exports
0.7.0: Finalize unit tests, core perf tests, add isObject guard helper
0.6.1: Update README
0.6.0: Fix optional defaultValues for generated data object contructor, added thorough README
0.5.1: Refined JSDocs for generated HTML documentation
0.5.0: Introduced defineObject, fixed bugs
0.4.0: Slightly improved doc generation
0.3.0: Draft of alternative deep validation implementation
0.2.0: Finalization of core implementation
0.1.0: First core implementation draft
0.0.1: Core init
0.0.0: Initialized Repository