https://github.com/0xspringtime/catsys
https://github.com/0xspringtime/catsys
category-theory functional-programming npm system-design typescript
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/0xspringtime/catsys
- Owner: 0xspringtime
- License: other
- Created: 2025-09-05T14:06:26.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-06T10:38:40.000Z (10 months ago)
- Last Synced: 2025-09-23T11:59:27.489Z (9 months ago)
- Topics: category-theory, functional-programming, npm, system-design, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/catsys
- Size: 146 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# CatSys: Category-Theoretic System Design Framework
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://www.npmjs.com/package/catsys)
[](https://www.typescriptlang.org/)
📦 [npm package](https://www.npmjs.com/package/catsys) |
🐙 [GitHub repository](https://github.com/0xspringtime/catsys)
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
```bash
npm install @catsys/core
```
```typescript
import { DomainSpec, createGenericService, adapters } from '@catsys/core';
// 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:
1. **Purity**: Domain logic is pure and deterministic
2. **Functoriality**: Implementation preserves composition
3. **Observability**: Metrics and traces compose correctly
4. **CQRS Commutativity**: Read models are consistent
5. **Outbox Pattern**: Reliable event publishing
6. **Push/Pull Equivalence**: UI state convergence
7. **Replay Determinism**: Event sourcing correctness
8. **Idempotence**: Safe command retries
9. **Causality**: Event ordering preservation
10. **Monoidal Aggregation**: Correct analytics
11. **Pullback Correctness**: Safe data joins
12. **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
```typescript
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:
```typescript
// 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](./GUIDE.md): In-depth explanation of concepts
- [Installation Guide](./INSTALLATION.md): Detailed setup instructions
- [Contributing Guide](./CONTRIBUTING.md): How to contribute
## Examples
See the [examples directory](./examples) 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](./LICENSE) for details.
## Support
- [GitHub Issues](https://github.com/catsys-org/catsys/issues)
- [Documentation](./GUIDE.md)
- [Contributing](./CONTRIBUTING.md)