# @kuckit/users-module

> ⚠️ **LEGACY MODULE**: This module is kept for demonstrating advanced patterns.
> For the **canonical reference implementation**, use [`items-module`](../create-kuckit-app/templates/base/packages/items-module/).

## Status

This module is **not the primary reference** for new module development. Use it only if you need to learn about:

- **Use case decorators** (caching, retry, logging)
- **Event publishing patterns**
- **Advanced DI patterns**

## Canonical Reference

For creating new modules, use the **items-module** template:

```bash
# Scaffolded projects include items-module by default
bunx create-kuckit-app my-app

# Or generate a new module based on the pattern
bunx kuckit generate module your-module
```

See [items-module documentation](../create-kuckit-app/templates/base/packages/items-module/README.md).

## Advanced Patterns Demonstrated

### Use Case Decorators

```typescript
// Caching decorator
useCase = withCaching(useCase, cacheStore, {
	keyFn: (input) => `user:${input.userId}`,
	ttlMs: 60000,
})

// Retry decorator
useCase = withRetry(useCase, {
	maxAttempts: 3,
	initialBackoffMs: 100,
})
```

### Event Publishing

```typescript
// Publish domain events after mutations
await eventPublisher.publish({
	type: 'user.profile.updated',
	payload: { userId, changes },
})
```

## Documentation

- [AGENTS.md](./AGENTS.md) - Detailed patterns and AI guidance
- [items-module](../create-kuckit-app/templates/base/packages/items-module/) - Canonical reference