Get usage patterns and idiomatic examples #19

New issue

Open

opened 2026-01-05 21:15:20 +00:00 by mprihoda · 0 comments

mprihoda commented

2026-01-05 21:15:20 +00:00

(Migrated from github.com)

Problem

Javadoc shows method signatures but not idiomatic usage:

"How do I properly use Resource?" (just signatures doesn't tell you)
"What's the pattern for error handling with IO?"
"How do I combine these types in practice?"

Proposed Solution

New Tool: `get_usage_patterns`

{
  "name": "get_usage_patterns",
  "description": "Get idiomatic usage patterns for a class",
  "input": {
    "coordinates": "Maven/Coursier coordinates",
    "className": "Fully qualified class name",
    "scalaVersion": "optional"
  }
}

Example:

get_usage_patterns("org.typelevel::cats-effect:3.5.4", "cats.effect.Resource")

Returns:

## Usage Patterns: cats.effect.Resource

### Pattern 1: Basic Resource Management
\`\`\`scala
val fileResource: Resource[IO, BufferedReader] = 
  Resource.make(
    IO(new BufferedReader(new FileReader("file.txt")))
  )(reader => IO(reader.close()))

// Use with .use - guarantees cleanup
fileResource.use { reader =>
  IO(reader.readLine())
}
\`\`\`

### Pattern 2: Combining Resources
\`\`\`scala
val combined = for {
  config <- configResource
  db     <- databaseResource(config)
  http   <- httpClientResource
} yield AppResources(config, db, http)
\`\`\`

### Pattern 3: From AutoCloseable
\`\`\`scala
Resource.fromAutoCloseable(IO(new FileInputStream("file")))
\`\`\`

### Anti-patterns to Avoid
- ❌ Don't call `.allocated` unless you manage cleanup yourself
- ❌ Don't nest `.use` calls - compose with flatMap instead
- ❌ Don't ignore the release action

### Integration Notes
- Works with any `F[_]: MonadCancel`
- Composes naturally with `IO` for-comprehensions
- For HTTP: prefer `Resource[IO, Client[IO]]` over raw client
\`\`\`

## Implementation Sources

1. **Library test suites** - Often contain good examples
2. **README/docs site** - Official guidance
3. **Curated knowledge base** - Hand-written patterns
4. **AI synthesis** - Generate from method signatures + context

## Value for Agent

- Knows HOW to use, not just WHAT methods exist
- Avoids common mistakes (anti-patterns)
- Understands integration with other types

## Acceptance Criteria

- [ ] Provide at least 2-3 patterns per major type
- [ ] Include code examples
- [ ] Mention anti-patterns where applicable
- [ ] Note integration with related types

## Problem Javadoc shows method signatures but not idiomatic usage: - "How do I properly use `Resource`?" (just signatures doesn't tell you) - "What's the pattern for error handling with `IO`?" - "How do I combine these types in practice?" ## Proposed Solution ### New Tool: `get_usage_patterns` ```json { "name": "get_usage_patterns", "description": "Get idiomatic usage patterns for a class", "input": { "coordinates": "Maven/Coursier coordinates", "className": "Fully qualified class name", "scalaVersion": "optional" } } ``` **Example:** ``` get_usage_patterns("org.typelevel::cats-effect:3.5.4", "cats.effect.Resource") ``` **Returns:** ```markdown ## Usage Patterns: cats.effect.Resource ### Pattern 1: Basic Resource Management \`\`\`scala val fileResource: Resource[IO, BufferedReader] = Resource.make( IO(new BufferedReader(new FileReader("file.txt"))) )(reader => IO(reader.close())) // Use with .use - guarantees cleanup fileResource.use { reader => IO(reader.readLine()) } \`\`\` ### Pattern 2: Combining Resources \`\`\`scala val combined = for { config <- configResource db <- databaseResource(config) http <- httpClientResource } yield AppResources(config, db, http) \`\`\` ### Pattern 3: From AutoCloseable \`\`\`scala Resource.fromAutoCloseable(IO(new FileInputStream("file"))) \`\`\` ### Anti-patterns to Avoid - ❌ Don't call `.allocated` unless you manage cleanup yourself - ❌ Don't nest `.use` calls - compose with flatMap instead - ❌ Don't ignore the release action ### Integration Notes - Works with any `F[_]: MonadCancel` - Composes naturally with `IO` for-comprehensions - For HTTP: prefer `Resource[IO, Client[IO]]` over raw client \`\`\` ## Implementation Sources 1. **Library test suites** - Often contain good examples 2. **README/docs site** - Official guidance 3. **Curated knowledge base** - Hand-written patterns 4. **AI synthesis** - Generate from method signatures + context ## Value for Agent - Knows HOW to use, not just WHAT methods exist - Avoids common mistakes (anti-patterns) - Understands integration with other types ## Acceptance Criteria - [ ] Provide at least 2-3 patterns per major type - [ ] Include code examples - [ ] Mention anti-patterns where applicable - [ ] Note integration with related types