tessl/npm-ts-interface-checker

Runtime library to validate data against TypeScript interfaces

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

ts-interface-checker

Name: tessl/npm-ts-interface-checker
Author: tessl

ts-interface-checker is a TypeScript runtime validation library that validates data against TypeScript interfaces. It works with ts-interface-builder to generate runtime checkers from TypeScript interface definitions, enabling robust runtime type checking for JavaScript and TypeScript applications.

Package Information

Package Name: ts-interface-checker
Package Type: npm
Language: TypeScript
Installation: npm install ts-interface-checker

Core Imports

// Main validation functionality
import { createCheckers, Checker, CheckerT } from "ts-interface-checker";

// Error handling
import { VError, IErrorDetail } from "ts-interface-checker";

// Type definition system
import { 
  TType, TName, TLiteral, TArray, TTuple, TUnion, TIntersection,
  TIface, TFunc, TOptional, TParam, TParamList, TProp,
  TEnumType, TEnumLiteral, RestType,
  name, lit, array, tuple, union, intersection,
  iface, func, opt, param, rest,
  enumtype, enumlit, indexKey,
  BasicType, ITypeSuite
} from "ts-interface-checker";

// Context system (advanced usage)
import { IContext, NoopContext, DetailContext } from "ts-interface-checker";

For CommonJS:

// Main validation functionality
const { createCheckers, Checker, CheckerT } = require("ts-interface-checker");

// Complete import (all exports)
const {
  createCheckers, Checker, CheckerT,
  VError, IErrorDetail,
  TType, TName, TLiteral, TArray, TTuple, TUnion, TIntersection,
  TIface, TFunc, TOptional, TParam, TParamList, TProp,
  TEnumType, TEnumLiteral, RestType,
  name, lit, array, tuple, union, intersection,
  iface, func, opt, param, rest,
  enumtype, enumlit, indexKey,
  BasicType, ITypeSuite,
  IContext, NoopContext, DetailContext
} = require("ts-interface-checker");

Basic Usage

import { createCheckers } from "ts-interface-checker";
import myInterfaceTI from "./my-interface-ti"; // Generated by ts-interface-builder

// Create checkers from generated type suite
const { MyInterface } = createCheckers(myInterfaceTI);

// Validate data
MyInterface.check({ name: "Alice", age: 30 }); // OK
MyInterface.check({ name: "Bob" }); // Throws: "value.age is missing"

// Fast boolean check
if (MyInterface.test(someData)) {
  // Data is valid
  console.log("Valid data");
}

// Get detailed validation errors
const errors = MyInterface.validate(invalidData);
if (errors) {
  console.log("Validation errors:", errors);
}

Architecture

ts-interface-checker is built around several key components:

Type Suite System: Collections of type definitions that can be combined and cross-referenced
Checker Factory: createCheckers() function that converts type suites into validation instances
Validation Engine: Core checking logic with strict and non-strict modes
Error Reporting: Detailed error messages with path information for debugging
Type Definition DSL: Rich set of type builders for creating complex validation rules

Capabilities

Checker Creation and Management

Create checker instances from type suites generated by ts-interface-builder. Supports combining multiple type suites and cross-referencing between types.

function createCheckers(...typeSuite: ITypeSuite[]): ICheckerSuite;

interface ICheckerSuite {
  [name: string]: Checker;
}

interface ITypeSuite {
  [name: string]: TType;
}

Checker Creation

Data Validation

Core validation functionality with multiple validation modes, detailed error reporting, and TypeScript type guard support.

class Checker {
  check(value: any): void;
  test(value: any): boolean;
  validate(value: any): IErrorDetail[] | null;
  strictCheck(value: any): void;
  strictTest(value: any): boolean;
  strictValidate(value: any): IErrorDetail[] | null;
  setReportedPath(path: string): void;
  getType(): TType;
}

interface CheckerT<T> extends Checker {
  test(value: any): value is T;
  strictTest(value: any): value is T;
}

Data Validation

Interface and Method Validation

Specialized validation for interface properties and method calls, including argument and return value validation.

class Checker {
  getProp(prop: string): Checker;
  methodArgs(methodName: string): Checker;
  methodResult(methodName: string): Checker;
  getArgs(): Checker;
  getResult(): Checker;
}

Interface and Method Validation

Type Definition System

Comprehensive type definition DSL for creating complex type structures including interfaces, unions, arrays, functions, and enums.

// Basic types
function name(value: string): TName;
function lit(value: any): TLiteral;
function array(typeSpec: TypeSpec): TArray;
function tuple(...typeSpec: TypeSpec[]): TTuple;
function union(...typeSpec: TypeSpec[]): TUnion;
function intersection(...typeSpec: TypeSpec[]): TIntersection;

// Interface and function types
function iface(bases: string[], props: {[name: string]: TOptional|TypeSpec}): TIface;
function func(resultSpec: TypeSpec, ...params: TParam[]): TFunc;
function opt(typeSpec: TypeSpec): TOptional;
function param(name: string, typeSpec: TypeSpec, isOpt?: boolean): TParam;

// Enum types
function enumtype(values: {[name: string]: string|number}): TEnumType;
function enumlit(name: string, prop: string): TEnumLiteral;

Type Definition System

Error Handling

Comprehensive error reporting with path information, nested error details, and custom error types for validation failures.

class VError extends Error {
  constructor(public path: string, message: string);
}

interface IErrorDetail {
  path: string;
  message: string;
  nested?: IErrorDetail[];
}

Error Handling

Types

// Core type specification
type TypeSpec = TType | string;

// Checker function type
type CheckerFunc = (value: any, ctx: IContext) => boolean;

// Abstract base for all type definitions
abstract class TType {
  abstract getChecker(suite: ITypeSuite, strict: boolean, allowedProps?: Set<string>): CheckerFunc;
}

// Special symbol for index signatures
const indexKey: unique symbol;