Koka - Lightweight TypeScript Effect Management Library Based on Algebraic Effects

Warning: This library is in early development and may undergo significant changes. Do not use in production environments.

Koka is a lightweight TypeScript effect management library based on algebraic effects, providing structured error handling, context management, and asynchronous operations with composability and type safety.

📚 Documentation Navigation

中文文档

• Documentation Home - Complete documentation navigation
• Tutorials - Learn Koka from scratch
• How-to Guides - Step-by-step solutions to specific problems
• API Reference - Complete API documentation
• Concept Explanations - Deep understanding of Koka's design philosophy

📋 Quick Navigation

• 🚀 Quick Start
• ✨ Core Features
• 🔄 Comparison with Effect-TS
• 📖 Documentation Structure
• 🤝 Contributing

🚀 Quick Start

Installation

npm install koka
# or
yarn add koka
# or
pnpm add koka

Basic Usage

import { Eff } from 'koka'

// Error handling
class ValidationError extends Eff.Err('ValidationError')<string> {}

function* getUser(id: string) {
    if (!id) {
        yield* Eff.throw(new ValidationError('ID is required'))
    }
    return { id, name: 'John Doe' }
}

// Context management
class Discount extends Eff.Ctx('Discount')<number> {}

function* calculateTotal() {
    const discount = yield* Eff.get(Discount)
    return 100 * (1 - discount)
}

// Async operations
async function* fetchData() {
    const response = yield* Eff.await(fetch('/api/data'))
    return response.json()
}

// Run effects
const result = await Eff.run(
    Eff.try(getUser('123')).handle({
        ValidationError: (error) => ({ error }),
    }),
)

✨ Core Features

• Type Safe - Full TypeScript support
• Lightweight - Only ~3kB gzipped
• Composable - Effects naturally compose
• Async Ready - Seamless Promise integration
• Design First - Support for predefined effect types

🔄 Comparison with Effect-TS

Feature	Koka	Effect-TS
Error Effects	✅	✅
Context Effects	✅	✅
Async Effects	✅	✅
Composability	✅	✅
Type Safety	✅	✅
Minimal API	✅	❌
Full Ecosystem	❌	✅
Learning Curve	Low	High
Package Size	~3kB	~50kB

Koka is a lightweight alternative to Effect-TS, focusing on providing core effect management functionality without the complete ecosystem.

📖 Documentation Structure

Tutorials

• Getting Started - Create your first Koka program
• Error Handling Basics - Learn how to handle error effects
• Context Management - Understand how to use context effects
• Async Programming - Master async effect handling

How-to Guides

• Handle Specific Error Types
• Combine Multiple Effects
• Use Design-First Approach
• Message Passing
• Stream Processing

Reference

• Eff API - Complete Eff class API
• Effect Types - Definitions of all effect types
• Utility Functions - Helper functions and types

Explanations

• Algebraic Effects - Concepts of algebraic effects
• Effect System Design - Koka's design philosophy
• Detailed Comparison with Effect-TS

🤝 Contributing

PRs are welcome! Please ensure tests pass and new features include appropriate test coverage.

📄 License

MIT