git.iko.soy/rowtype-yoga/purescript-yoga-om
on main help sign in
rowtype-yoga/purescript-yoga-om/README.md
109 lines 2.7 kB history raw
1# yoga-om-core
3Core Om types and operations for writing applications with dependency injection and checked exceptions.
5This is the base package that provides the `Om` type and all core operations. It works in both browser and Node.js environments.
7## Installation
9```bash
10spago install yoga-om-core
11```
13## What's Included
15- **Om type**: The core monad transformer stack combining `ReaderT`, `ExceptV`, and `Aff`
16- **Error handling**: `throw`, `handleErrors`, `expand` for mix-and-match error types
17- **Dependency injection**: `ask`, `asks` for accessing context
18- **Parallel computations**: `race`, `inParallel` for concurrent operations
19- **Helpers**: `note`, `delay`, `unliftAff` and more
21## Basic Usage
23```purescript
24import Yoga.Om (Om)
25import Yoga.Om as Om
27myApp :: Om { dbUrl :: String } (dbError :: String) Unit
28myApp = do
29 { dbUrl } <- Om.ask
30 -- Your application logic here
31 pure unit
33main = myApp
34 # Om.launchOm_
35 { dbUrl: "postgresql://localhost" }
36 { exception: \e -> Console.error (show e)
37 , dbError: \err -> Console.error err
38 }
39```
41## Features
43### Context (Dependency Injection)
45```purescript
46getUser :: Om { db :: Database } _ User
47getUser = do
48 { db } <- Om.ask
49 -- Use db to fetch user
50```
52### Error Handling
54```purescript
55saveUser :: Om _ (dbError :: String, validationError :: String) Unit
56saveUser = do
57 -- Can throw either dbError or validationError
58 Om.throw { validationError: "Invalid email" }
59```
61### Parallel Operations
63```purescript
64fetchMultiple :: Om _ _ (Array User)
65fetchMultiple = Om.inParallel
66 [ fetchUser 1
67 , fetchUser 2
68 , fetchUser 3
69 ]
70```
72## Testing
74Tests are colocated with the implementation in the `test/` directory:
76```bash
77# Run tests
78cd packages/yoga-om-core && spago test
80# Or from workspace root
81bun test:core
82```
84See [test/Test/Om/Core.purs](./test/Test/Om/Core.purs) for comprehensive test examples.
86## Package Structure
88```
89yoga-om-core/
90├── src/
91│ └── Yoga/
92│ ├── Om.purs # Main Om implementation
93│ └── Om/
94│ ├── Error.purs # Error types and helpers
95│ └── Error.js # FFI for error handling
96└── test/ # Tests colocated here!
97 └── Test/
98 ├── Main.purs # Test runner
99 └── Om/
100 └── Core.purs # Core Om tests (20 tests)
101```
103## See Also
105- **[yoga-om-node](../yoga-om-node)** - Node.js-specific extensions
106- **[yoga-om-rom](../yoga-om-rom)** - Reactive Om: Bolson FRP integration (push-based)
107- **[yoga-om-strom](../yoga-om-strom)** - Stream Om: Pull-based streaming library
109For more examples, see the [main README](../../README.md) and [tests](./test/).