git.iko.soy/rowtype-yoga/purescript-yoga-backend-stack
on main help sign in
rowtype-yoga/purescript-yoga-backend-stack/README.md
146 lines 5.0 kB history raw
1# PureScript Yoga Backend Stack
3The complete backend stack for PureScript - high-quality, type-safe FFI bindings for databases, messaging, HTTP frameworks, and observability tools.
5## 📦 Packages
7### Foundation
8- **yoga-sql-types** - Common SQL types and utilities for type-safe queries
10### Databases (15 packages)
11- **yoga-redis** / **yoga-redis-om** - Redis client with Om observability
12- **yoga-postgres** / **yoga-postgres-om** - PostgreSQL client with Om observability
13- **yoga-scylladb** / **yoga-scylladb-om** - ScyllaDB client with Om observability
14- **yoga-sqlite** / **yoga-sqlite-om** - SQLite bindings with Om observability
15- **yoga-bun-sqlite** - Bun's native SQLite bindings
16- **yoga-node-sqlite** - Node SQLite bindings
17- **yoga-dynamodb** - AWS DynamoDB client
18- **yoga-elasticsearch** - Elasticsearch client
20### Messaging
21- **yoga-kafka** - Apache Kafka client (Producer, Consumer, Admin)
23### HTTP Frameworks (4 packages)
24- **yoga-fastify** / **yoga-fastify-om** - Fastify web framework with Om observability
25- **yoga-bun-yoga** / **yoga-bun-yoga-om** - Bun HTTP server with Yoga integration and Om observability
27### Observability (6 packages)
28- **yoga-opentelemetry** / **yoga-opentelemetry-om** - OpenTelemetry SDK with Om observability
29- **yoga-jaeger** - Jaeger distributed tracing
30- **yoga-pino** / **yoga-pino-om** - Pino logger with Om observability
32### Utilities
33- **yoga-docker-compose** - Docker Compose integration for tests and development
35## 🚀 Quick Start
37```bash
38# Install dependencies
39bun install
41# Build all packages
42bunx spago build
44# Build a specific package
45bunx spago build -p yoga-redis
47# Run tests for a specific package
48cd packages/yoga-redis && bunx spago test
49```
51## 🧪 Testing
53Run tests for individual packages:
55```bash
56cd packages/yoga-redis && bunx spago test
57cd packages/yoga-postgres && bunx spago test
58cd packages/yoga-fastify-om && bunx spago test
59```
61Some packages with integration tests use Docker for test infrastructure (Redis, Postgres, ScyllaDB). The `yoga-test-docker` package provides utilities for managing Docker Compose services within tests.
63## 📚 Documentation
65Comprehensive documentation is available for key packages:
66- **yoga-redis** / **yoga-redis-om** - Full API reference and examples
67- **yoga-sql-types** - SQL type system documentation
68- **yoga-test-docker** - Docker integration testing guide
69- **yoga-postgres** / **yoga-postgres-om** - PostgreSQL usage
70- **yoga-sqlite-om** - SQLite with Om
72Additional documentation:
73- `docs/ENDPOINT2_RECORD_API.md` - Tapir-style endpoint specification for Fastify
74- `docs/FIELD_OMISSION.md` - Union constraint and field omission patterns
76## 🏗️ Monorepo Structure
78```
79purescript-yoga-backend-stack/
80├── packages/
81│ ├── yoga-sql-types/ # Foundation package
82│ ├── yoga-redis/ # Redis base package
83│ │ ├── src/
84│ │ ├── test/ # Package-specific tests
85│ │ ├── spago.yaml
86│ │ └── package.json
87│ ├── yoga-redis-om/ # Redis with Om observability
88│ ├── yoga-postgres/
89│ ├── yoga-postgres-om/
90│ ├── yoga-fastify-om/ # Fastify web framework with Om
91│ └── ... # Additional packages
92├── docs/ # Documentation
93├── spago.yaml # Workspace configuration
94├── package.json # Root package.json
95└── README.md
96```
98## 🔧 Development
100### Adding a New Package
1021. Create package directory in `packages/`
1032. Add `spago.yaml`, `package.json`, and `README.md`
1043. Implement FFI bindings following the pattern in existing packages
1054. Add test suite in `test/Main.purs`
1065. Update root scripts if needed
108### Module Naming Convention
110All modules use the `Yoga.*` namespace:
111- `Yoga.Redis` - Base Redis module
112- `Yoga.Postgres.TypedQuery` - PostgreSQL typed queries
113- `Yoga.Bun.HTTP` - Bun HTTP server
114- etc.
116### Om Packages
118Packages with `-om` suffix provide Observable Monitoring integration:
119- Automatically instrument database queries
120- Add tracing and metrics
121- Integrate with OpenTelemetry
122- Provide layer-based composition
124## 📝 License
126MIT License - see LICENSE file for details
128## 🤝 Contributing
130Contributions are welcome! Please ensure:
131- All new bindings follow the FFI patterns from existing packages
132- Tests are included for new functionality
133- Documentation is updated
134- Code passes linting (`bunx spago build`)
136## ⚙️ Requirements
138- **PureScript** 0.15.15+
139- **Spago** 0.93.45+ (Spago Next)
140- **Bun** (recommended) or Node.js 18+
141- **Docker** (for integration tests)
143## 🔗 Related Projects
145- [purescript-yoga-om](https://github.com/rowtype-yoga/purescript-yoga-om) - Observable Monitoring effect system
146- [purescript-yoga-json](https://github.com/rowtype-yoga/purescript-yoga-json) - High-performance JSON codecs