{"id":31262741,"url":"https://github.com/0xspringtime/catsys","last_synced_at":"2026-05-14T12:36:12.861Z","repository":{"id":313364997,"uuid":"1051143831","full_name":"0xspringtime/catsys","owner":"0xspringtime","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-06T10:38:40.000Z","size":149,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-23T11:59:27.489Z","etag":null,"topics":["category-theory","functional-programming","npm","system-design","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/catsys","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xspringtime.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-05T14:06:26.000Z","updated_at":"2025-09-05T18:20:08.000Z","dependencies_parsed_at":"2025-09-05T16:44:30.159Z","dependency_job_id":null,"html_url":"https://github.com/0xspringtime/catsys","commit_stats":null,"previous_names":["0xspringtime/catsys"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/0xspringtime/catsys","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xspringtime%2Fcatsys","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xspringtime%2Fcatsys/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xspringtime%2Fcatsys/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xspringtime%2Fcatsys/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xspringtime","download_url":"https://codeload.github.com/0xspringtime/catsys/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xspringtime%2Fcatsys/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33025335,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["category-theory","functional-programming","npm","system-design","typescript"],"created_at":"2025-09-23T11:52:50.241Z","updated_at":"2026-05-14T12:36:12.666Z","avatar_url":"https://github.com/0xspringtime.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CatSys: Category-Theoretic System Design Framework\n\n[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![npm version](https://img.shields.io/npm/v/catsys.svg)](https://www.npmjs.com/package/catsys)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)\n\n📦 [npm package](https://www.npmjs.com/package/catsys) | \n🐙 [GitHub repository](https://github.com/0xspringtime/catsys)\n\nCatSys is a robust framework for building scalable, modular systems using category theory principles. It provides mathematical guarantees for system correctness through 12 foundational laws.\n\n## Key Features\n\n- **Mathematical Foundations**: Built on category theory principles ensuring system correctness\n- **Type-Safe**: Written in TypeScript with comprehensive type definitions\n- **Modular Architecture**: Clean separation of domain logic from infrastructure\n- **Event Sourcing \u0026 CQRS**: Built-in support with mathematical guarantees\n- **Property-Based Testing**: Automated verification of category theory laws\n- **Infrastructure Independence**: Swap implementations without changing business logic\n- **Observability**: Built-in metrics and tracing that compose correctly\n\n## Quick Start\n\n```bash\nnpm install @catsys/core\n```\n\n```typescript\nimport { DomainSpec, createGenericService, adapters } from '@catsys/core';\n\n// Define your domain\nclass CounterSpec extends DomainSpec {\n  constructor() {\n    super();\n    this.initialState = { count: 0 };\n  }\n\n  decide(state, command) {\n    if (command.kind === 'Increment') {\n      return [{ kind: 'Incremented', amount: command.amount }];\n    }\n    return [];\n  }\n\n  evolve(state, event) {\n    if (event.kind === 'Incremented') {\n      return { count: state.count + event.amount };\n    }\n    return state;\n  }\n}\n\n// Create service with in-memory adapters\nconst service = createGenericService(\n  new CounterSpec(),\n  { count: 0 },\n  {\n    sql: adapters.inMemorySql(),\n    bus: adapters.inMemoryBus()\n  }\n);\n\n// Use the service\nawait service.handle({ count: 0 }, { kind: 'Increment', amount: 5 });\n```\n\n## Core Concepts\n\n### Category Theory Laws\n\nCatSys enforces 12 mathematical laws that guarantee system correctness:\n\n1. **Purity**: Domain logic is pure and deterministic\n2. **Functoriality**: Implementation preserves composition\n3. **Observability**: Metrics and traces compose correctly\n4. **CQRS Commutativity**: Read models are consistent\n5. **Outbox Pattern**: Reliable event publishing\n6. **Push/Pull Equivalence**: UI state convergence\n7. **Replay Determinism**: Event sourcing correctness\n8. **Idempotence**: Safe command retries\n9. **Causality**: Event ordering preservation\n10. **Monoidal Aggregation**: Correct analytics\n11. **Pullback Correctness**: Safe data joins\n12. **Schema Evolution**: Safe upgrades\n\n### Architecture\n\nCatSys uses a ports and adapters architecture with:\n\n- **Domain Layer**: Pure business logic (Set category)\n- **Application Layer**: Infrastructure integration (Kleisli category)\n- **Infrastructure Layer**: Concrete implementations\n- **Composition Root**: Dependency injection point\n\n### Type System\n\n```typescript\ntype Command = { kind: string, ... }\ntype Event = { kind: string, ... }\ntype State = any\ntype View = any\ntype Raw = any\n\ninterface DomainSpec {\n  decide(state: State, command: Command): Event[]\n  evolve(state: State, event: Event): State\n  project(view: View, event: Event): View\n  // ... other methods\n}\n```\n\n## Testing\n\nCatSys includes comprehensive testing tools:\n\n```typescript\n// Property-based testing\nspec.verifyLaws();\n\n// Unit testing\ntest('increment', async () =\u003e {\n  const result = await service.handle(\n    { count: 0 },\n    { kind: 'Increment', amount: 1 }\n  );\n  expect(result).toEqual({ count: 1 });\n});\n```\n\n## Documentation\n\n- [Complete Guide](./GUIDE.md): In-depth explanation of concepts\n- [Installation Guide](./INSTALLATION.md): Detailed setup instructions\n- [Contributing Guide](./CONTRIBUTING.md): How to contribute\n\n## Examples\n\nSee the [examples directory](./examples) for:\n\n- Video streaming service\n- Document management system\n- Multi-tenant architecture\n- Blue/green deployments\n- Event sourcing patterns\n\n## Security\n\nCatSys takes security seriously:\n\n- No eval() or dynamic code execution\n- No sensitive data in logs/metrics\n- Secure by default adapters\n- Input validation at boundaries\n- Safe schema evolution\n\n## License\n\nGPL-3.0 - see [LICENSE](./LICENSE) for details.\n\n## Support\n\n- [GitHub Issues](https://github.com/catsys-org/catsys/issues)\n- [Documentation](./GUIDE.md)\n- [Contributing](./CONTRIBUTING.md)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xspringtime%2Fcatsys","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xspringtime%2Fcatsys","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xspringtime%2Fcatsys/lists"}