TSets

A types-only TypeScript library for mathematical set operations with compile-time type checking and disjoint unions. All operations are performed at the type level with zero runtime overhead.

Features

🔒 100% Type-level - No runtime code, pure TypeScript types
🧮 Mathematical notation - Work with sets using familiar mathematical concepts (∪, ∩, , ×, etc.)
🔀 Disjoint unions - Type-safe tagged unions and sum types
⚡ Zero runtime overhead - Everything happens at compile time
📦 as const compatible - Full support for const assertions
🎯 Type-safe pattern matching - Exhaustive matching for disjoint unions

Installation

# npm
npm install tsets

# pnpm  
pnpm add tsets

# yarn
yarn add tsets

Quick Start

import type { Union, Intersection, Difference, IsDisjoint } from 'tsets';

// Define sets using readonly tuples
type SetA = readonly ['apple', 'banana', 'cherry'];
type SetB = readonly ['banana', 'date', 'elderberry'];

// Mathematical operations at the type level
type UnionResult = Union<SetA, SetB>;
// Result: readonly ["apple", "banana", "cherry", "banana", "date", "elderberry"]

type IntersectionResult = Intersection<SetA, SetB>; 
// Result: Elements present in both sets

type DifferenceResult = Difference<SetA, SetB>;
// Result: Elements in A but not in B

// Compile-time validation
type AreDisjoint = IsDisjoint<readonly [1, 2], readonly ['a', 'b']>; // true

Core Set Operations

Basic Operations

All operations follow standard mathematical set theory:

import type { 
  Union,              // A ∪ B 
  Intersection,       // A ∩ B
  Difference,         // A \ B
  SymmetricDifference, // A △ B
  CartesianProduct,   // A × B
  PowerSet,           // 𝒫(A)
  SetComplement       // A^c
} from 'tsets';

// Union: A ∪ B
type Numbers = readonly [1, 2, 3];
type Letters = readonly ['a', 'b'];
type Combined = Union<Numbers, Letters>; // readonly [1, 2, 3, 'a', 'b']

// Cartesian Product: A × B  
type Pairs = CartesianProduct<Numbers, Letters>;
// readonly [readonly [1, 'a'], readonly [1, 'b'], ...]

// Set relationships
type IsSubset = Subset<readonly [1, 2], readonly [1, 2, 3]>; // true
type AreEqual = Equal<readonly ['a', 'b'], readonly ['b', 'a']>; // true

Set Properties

import type { Cardinality, IsEmpty, Subset, Equal } from 'tsets';

type MySet = readonly ['x', 'y', 'z'];
type Size = Cardinality<MySet>; // 3
type Empty = IsEmpty<readonly []>; // true

Disjoint Unions (Sum Types)

Perfect for modeling state machines, API responses, and error handling:

import type { DisjointUnion, Result, Option, PatternMatcher } from 'tsets';

// API Response States
const apiStates = {
  loading: [] as const,
  success: ['data'] as const,
  error: ['network_error', 'timeout', 'server_error'] as const,
} as const;

type ApiResponse = DisjointUnion<typeof apiStates>;
/*
Result:
  | { readonly tag: 'loading'; readonly value: never }
  | { readonly tag: 'success'; readonly value: 'data' }  
  | { readonly tag: 'error'; readonly value: 'network_error' | 'timeout' | 'server_error' }
*/

// Result type for error handling
type FetchResult = Result<User, 'network_error' | 'not_found'>;

// Option type for nullable values
type MaybeUser = Option<User>;

// Pattern matching
type Matcher = PatternMatcher<ApiResponse, string>;
// Creates exhaustive handler type

Real-World Examples

State Machine Modeling

import type { StateMachine, DisjointUnion } from 'tsets';

type AuthStates = {
  anonymous: readonly [];
  logging_in: readonly [string]; // username
  authenticated: readonly [User];
  session_expired: readonly [];
};

type AuthState = StateMachine<AuthStates>;
// Compile-time guarantee of exhaustive state handling

HTTP Status Code Validation

type SuccessCodes = readonly [200, 201, 204];
type ErrorCodes = readonly [400, 401, 403, 404, 500];

// Ensure codes don't overlap at compile time
type CodesAreDisjoint = IsDisjoint<SuccessCodes, ErrorCodes>; // true

type AllCodes = Union<SuccessCodes, ErrorCodes>;
type TotalCodes = Cardinality<AllCodes>; // 8

Form Validation States

const formStates = {
  pristine: [] as const,
  validating: ['field_name'] as const,
  valid: ['form_data'] as const,
  invalid: ['error_message', 'field_name'] as const,
} as const;

type FormState = DisjointUnion<typeof formStates>;
// Type-safe form state management

Mathematical Foundations

This library implements standard set theory operations:

Union (∪): A ∪ B = {x | x ∈ A or x ∈ B}
Intersection (∩): A ∩ B = {x | x ∈ A and x ∈ B}
Difference (\): A \ B = {x | x ∈ A and x ∉ B}
Symmetric Difference (△): A △ B = (A \ B) ∪ (B \ A)
Cartesian Product (×): A × B = {(a,b) | a ∈ A and b ∈ B}
Power Set (𝒫): 𝒫(A) = {S | S ⊆ A}
Subset (⊆): A ⊆ B if ∀x (x ∈ A → x ∈ B)
Disjoint: A ∩ B = ∅

API Reference

Core Types

SetLike<T> - Base set type using readonly arrays
Union<A, B> - Set union A ∪ B
Intersection<A, B> - Set intersection A ∩ B
Difference<A, B> - Set difference A \ B
IsDisjoint<A, B> - Check if sets are disjoint
Subset<A, B> - Check if A ⊆ B
Equal<A, B> - Check if A = B
Cardinality<A> - Get set size |A|
IsEmpty<A> - Check if set is empty ∅

Advanced Operations

CartesianProduct<A, B> - Cartesian product A × B
PowerSet<A> - Power set 𝒫(A)
SymmetricDifference<A, B> - Symmetric difference A △ B
SetComplement<U, A> - Set complement A^c

Disjoint Unions

DisjointUnion<T> - Create tagged union from sets
TaggedValue<Tag, Value> - Tagged value type
PatternMatcher<T, R> - Pattern matching function type
Result<S, E> - Success/Error result type
Option<T> - Optional value type
StateMachine<States> - State machine type

Development

# Install dependencies
pnpm install

# Run type tests
pnpm test

# Build library  
pnpm build

# Type checking
pnpm typecheck

# Linting
pnpm lint

# Release preparation
pnpm release:dry  # dry run
pnpm release      # actual release

TypeScript Configuration

This library requires TypeScript 5.0+ for optimal type inference. Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "strict": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true
  }
}

License

MIT - Use freely in commercial and open source projects.

TSets - Bringing mathematical rigor to TypeScript through compile-time set operations. Perfect for type-safe state management, API modeling, and functional programming patterns.