catsys

CatSys: Category-Theoretic System Design Framework

📦 npm package | 🐙 GitHub repository

CatSys is a robust framework for building scalable, modular systems using category theory principles. It provides mathematical guarantees for system correctness through 12 foundational laws.

Key Features

• Mathematical Foundations: Built on category theory principles ensuring system correctness
• Type-Safe: Written in TypeScript with comprehensive type definitions
• Modular Architecture: Clean separation of domain logic from infrastructure
• Event Sourcing & CQRS: Built-in support with mathematical guarantees
• Property-Based Testing: Automated verification of category theory laws
• Infrastructure Independence: Swap implementations without changing business logic
• Observability: Built-in metrics and tracing that compose correctly

Quick Start

npm install catsys

import { DomainSpec, createGenericService, adapters } from 'catsys';

// Define your domain
class CounterSpec extends DomainSpec {
  constructor() {
    super();
    this.initialState = { count: 0 };
  }

  decide(state, command) {
    if (command.kind === 'Increment') {
      return [{ kind: 'Incremented', amount: command.amount }];
    }
    return [];
  }

  evolve(state, event) {
    if (event.kind === 'Incremented') {
      return { count: state.count + event.amount };
    }
    return state;
  }
}

// Create service with in-memory adapters
const service = createGenericService(
  new CounterSpec(),
  { count: 0 },
  {
    sql: adapters.inMemorySql(),
    bus: adapters.inMemoryBus()
  }
);

// Use the service
await service.handle({ count: 0 }, { kind: 'Increment', amount: 5 });

Core Concepts

Category Theory Laws

CatSys enforces 12 mathematical laws that guarantee system correctness:

• Purity: Domain logic is pure and deterministic
• Functoriality: Implementation preserves composition
• Observability: Metrics and traces compose correctly
• CQRS Commutativity: Read models are consistent
• Outbox Pattern: Reliable event publishing
• Push/Pull Equivalence: UI state convergence
• Replay Determinism: Event sourcing correctness
• Idempotence: Safe command retries
• Causality: Event ordering preservation
• Monoidal Aggregation: Correct analytics
• Pullback Correctness: Safe data joins
• Schema Evolution: Safe upgrades

Architecture

CatSys uses a ports and adapters architecture with:

• Domain Layer: Pure business logic (Set category)
• Application Layer: Infrastructure integration (Kleisli category)
• Infrastructure Layer: Concrete implementations
• Composition Root: Dependency injection point

Type System

type Command = { kind: string, ... }
type Event = { kind: string, ... }
type State = any
type View = any
type Raw = any

interface DomainSpec {
  decide(state: State, command: Command): Event[]
  evolve(state: State, event: Event): State
  project(view: View, event: Event): View
  // ... other methods
}

Testing

CatSys includes comprehensive testing tools:

// Property-based testing
spec.verifyLaws();

// Unit testing
test('increment', async () => {
  const result = await service.handle(
    { count: 0 },
    { kind: 'Increment', amount: 1 }
  );
  expect(result).toEqual({ count: 1 });
});

Documentation

• Complete Guide: In-depth explanation of concepts
• Installation Guide: Detailed setup instructions
• Contributing Guide: How to contribute

Examples

See the examples directory for:

• Video streaming service
• Document management system
• Multi-tenant architecture
• Blue/green deployments
• Event sourcing patterns

Security

CatSys takes security seriously:

• No eval() or dynamic code execution
• No sensitive data in logs/metrics
• Secure by default adapters
• Input validation at boundaries
• Safe schema evolution

License

GPL-3.0 - see LICENSE for details.

Support

• GitHub Issues
• Documentation
• Contributing