docs: add basic docs for koka-domain and koka-ddd

Author: Lucifier129

packages/koka-ddd/README.md

@@ -0,0 +1,158 @@
+# koka-ddd - Domain Modeling with Effects
+
+Koka DDD provides a domain modeling framework built on Koka's algebraic effects system, featuring:
+
+-   **Domain Modeling**: Type-safe domain definitions
+-   **Store Pattern**: Centralized state management
+-   **Command/Query Separation**: Clear distinction between writes and reads
+-   **Effect Integration**: Seamless Koka effects usage
+-   **Optics Support**: Composable data access patterns
+
+## Installation
+
+```bash
+npm install koka-ddd
+# or
+yarn add koka-ddd
+# or
+pnpm add koka-ddd
+```
+
+## Core Concepts
+
+### Domain Modeling
+
+Define your domain using the `Domain` base class:
+
+```typescript
+import { Domain } from 'koka-ddd'
+
+class TodoDomain extends Domain<Todo> {
+  text = new TextDomain(this.$prop('text'))
+  done = new BoolDomain(this.$prop('done'))
+
+  *updateText(newText: string) {
+    yield* this.text.updateText(newText)
+  }
+}
+```
+
+### Store Pattern
+
+Manage application state with the `Store` class:
+
+```typescript
+import { Store } from 'koka-ddd'
+
+const store = new Store({
+    state: {
+        todos: [],
+        filter: 'all',
+    },
+})
+```
+
+### Commands and Queries
+
+```typescript
+// Query example
+const todos = store.get(todoListDomain)
+
+// Command example
+store.runCommand(todoDomain.addTodo('New task'))
+```
+
+## Complete Todo App Example
+
+```typescript
+import { Domain, Store } from 'koka-ddd'
+
+// Define domains
+class TodoDomain extends Domain<Todo> {
+  text = new TextDomain(this.$prop('text'))
+  done = new BoolDomain(this.$prop('done'))
+
+  *toggle() {
+    yield* this.done.toggle()
+  }
+}
+
+class TodoListDomain extends Domain<Todo[]> {
+  *addTodo(text: string) {
+    const newTodo = { id: Date.now(), text, done: false }
+    yield* set(this, todos => [...todos, newTodo])
+  }
+
+  todo(id: number) {
+    return new TodoDomain(this.$find(todo => todo.id === id))
+  }
+}
+
+// Create store
+const store = new Store({
+  state: {
+    todos: []
+  }
+})
+
+// Usage
+store.runCommand(todoListDomain.addTodo('Learn Koka DDD'))
+store.runCommand(todoListDomain.todo(1).toggle())
+```
+
+## Advanced Patterns
+
+### Nested Domains
+
+```typescript
+class AppDomain extends Domain<AppState> {
+    todos = new TodoListDomain(this.$prop('todos'))
+    user = new UserDomain(this.$prop('user'))
+}
+```
+
+### Async Operations
+
+```typescript
+*loadTodos() {
+  const response = yield* Eff.await(fetch('/todos'))
+  const todos = yield* Eff.await(response.json())
+  yield* set(this, todos)
+}
+```
+
+## Testing
+
+Tests follow the same patterns as production code:
+
+```typescript
+test('should add todo', async () => {
+    await store.runCommand(todos.addTodo('Test'))
+    expect(store.getState().todos.length).toBe(1)
+})
+```
+
+## API Reference
+
+### Domain
+
+-   `$prop()`: Create property accessor
+-   `$find()`: Find item in collection
+-   `$filter()`: Filter collection
+-   `$map()`: Transform values
+
+### Store
+
+-   `get(domain)`: Query state
+-   `runCommand(command)`: Execute state mutation
+-   `subscribe(listener)`: React to changes
+
+## Contributing
+
+1. Ensure tests pass (`npm test`)
+2. Update documentation
+3. Follow existing patterns
+
+## License
+
+MIT

packages/koka-domain/README.md

@@ -0,0 +1,155 @@
+# koka-domain - Type-Safe Data Accessors
+
+koka-domain provides composable, type-safe data access patterns built on algebraic effects. It enables:
+
+-   **Bidirectional transformations**: Get and set values with type safety
+-   **Optics patterns**: Lenses, prisms, and traversals for structured data
+-   **Domain modeling**: Structured data access patterns
+-   **Effect integration**: Works seamlessly with Koka effects
+
+## Installation
+
+```bash
+npm install koka-domain
+# or
+yarn add koka-domain
+# or
+pnpm add koka-domain
+```
+
+## Core Concepts
+
+### Root Domain
+
+```typescript
+import { Domain } from 'koka-domain'
+
+// Create root domain for a type
+const numberDomain = Domain.root<number>()
+
+// Get value
+const result = Eff.runResult(numberDomain.get(42))
+// { type: 'ok', value: 42 }
+
+// Set value
+const setter = numberDomain.set(function* (n) {
+    return n + 1
+})
+Eff.runResult(setter(42)) // 43
+```
+
+### Property Access
+
+```typescript
+const userDomain = Domain.root<{ name: string }>().$prop('name')
+
+// Get property
+Eff.runResult(userDomain.get({ name: 'Alice' })) // 'Alice'
+
+// Set property
+const setName = userDomain.set(function* () {
+    return 'Bob'
+})
+Eff.runResult(setName({ name: 'Alice' })) // { name: 'Bob' }
+```
+
+### Array Operations
+
+```typescript
+const todosDomain = Domain.root<Todo[]>()
+
+// Access by index
+const firstTodo = todosDomain.$index(0)
+
+// Find item
+const importantTodo = todosDomain.$find((todo) => todo.priority === 'high')
+
+// Filter items
+const completedTodos = todosDomain.$filter((todo) => todo.completed)
+
+// Map items
+const todoTitles = todosDomain.$map((todo) => todo.title)
+```
+
+### Type Refinement
+
+```typescript
+const numberDomain = Domain.root<string | number>().$match((v): v is number => typeof v === 'number')
+
+Eff.runResult(numberDomain.get(42)) // 42
+Eff.runResult(numberDomain.get('test')) // Error
+```
+
+### Object Composition
+
+```typescript
+const userDomain = Domain.object({
+    name: Domain.root<{ name: string }>().$prop('name'),
+    age: Domain.root<{ age: number }>().$prop('age'),
+})
+
+Eff.runResult(userDomain.get({ name: 'Alice', age: 30 }))
+// { name: 'Alice', age: 30 }
+```
+
+## Advanced Usage
+
+### Complex Transformations
+
+```typescript
+const complexDomain = Domain.root<{ users: User[] }>()
+    .$prop('users')
+    .$filter((user) => user.active)
+    .$map({
+        get: (user) => ({
+            ...user,
+            name: user.name.toUpperCase(),
+        }),
+        set: (user) => ({
+            ...user,
+            name: user.name.toLowerCase(),
+        }),
+    })
+
+const result = Eff.runResult(
+    complexDomain.get({
+        users: [
+            { name: 'Alice', active: true },
+            { name: 'Bob', active: false },
+        ],
+    }),
+)
+// [{ name: 'ALICE', active: true }]
+```
+
+## API Reference
+
+### Core Methods
+
+-   `Domain.root<T>()`: Create root domain for type T
+-   `$prop(key)`: Access object property
+-   `$index(n)`: Access array index
+-   `$find(predicate)`: Find array item
+-   `$filter(predicate)`: Filter array
+-   `$map(transform)`: Transform values
+-   `$match(predicate)`: Type refinement
+-   `$refine(predicate)`: Value validation
+-   `Domain.object(fields)`: Compose object domains
+-   `Domain.optional(domain)`: Handle optional values
+
+## Best Practices
+
+1. **Compose domains** for complex data structures
+2. **Combine with Koka effects** for async operations
+3. **Leverage type system** for safety
+
+## Contributing
+
+1. Write tests for new features
+2. Maintain type safety
+3. Document changes
+4. Follow existing patterns
+
+## License
+
+MIT