effect-patterns-hub（效果模式中心）

Effect Patterns Hub

Purpose: Provide quick access to 130+ curated Effect-TS patterns from the EffectPatterns repository. Use this skill to find specific implementation patterns, compare approaches, and reference best practices.

Triggers

• Looking for a specific Effect pattern or idiom
• Need real-world examples of Effect concepts
• Want to see multiple approaches to the same problem
• Comparing implementation strategies
• Learning new Effect features

Pattern Library Location

Local Patterns: .claude/skills/effect-patterns-hub/patterns/ Documentation: docs/effect-patterns/ Count: 130+ patterns in MDX format

Quick Decision Tree

I need to...

Create Effects

• From value → constructor-succeed-some-right.mdx
• From sync code → constructor-sync-async.mdx
• From promise → constructor-try-trypromise.mdx
• From nullable → constructor-from-nullable-option-either.mdx
• Pre-resolved → create-pre-resolved-effect.mdx

Transform & Compose

• Map values → combinator-map.mdx
• Chain effects → combinator-flatmap.mdx
• Sequence operations → combinator-sequencing.mdx
• Combine values → combinator-zip.mdx
• Filter → combinator-filter.mdx
• Conditional logic → combinator-conditional.mdx
• Process collections → combinator-foreach-all.mdx

Control Flow

• Sequential logic → write-sequential-code-with-gen.mdx
• Business logic → use-gen-for-business-logic.mdx
• Pipe composition → use-pipe-for-composition.mdx
• Branching workflows → conditionally-branching-workflows.mdx
• Combinators → control-flow-with-combinators.mdx
• Repetition → control-repetition-with-schedule.mdx

Error Handling

• Define errors → define-tagged-errors.mdx
• Catch specific errors → pattern-catchtag.mdx
• Handle all errors → handle-errors-with-catch.mdx
• Retry operations → retry-based-on-specific-errors.mdx
• Flaky operations → handle-flaky-operations-with-retry-timeout.mdx
• Map errors → mapping-errors-to-fit-your-domain.mdx
• Handle unexpected → handle-unexpected-errors-with-cause.mdx
• API errors → handle-api-errors.mdx

Concurrency

• Parallel execution → run-effects-in-parallel-with-all.mdx
• Background tasks → run-background-tasks-with-fork.mdx
• Process collections → process-collection-in-parallel-with-foreach.mdx
• Race effects → race-concurrent-effects.mdx
• Fibers explained → understand-fibers-as-lightweight-threads.mdx
• Decouple with queues → decouple-fibers-with-queue-pubsub.mdx
• Polling → poll-for-status-until-task-completes.mdx
• Graceful shutdown → implement-graceful-shutdown.mdx

Services & Dependency Injection

• Model dependencies → model-dependencies-as-services.mdx
• Understand layers → understand-layers-for-dependency-injection.mdx
• Scoped services → scoped-service-layer.mdx
• Composable modules → organize-layers-into-composable-modules.mdx
• Compose scoped layers → compose-scoped-layers.mdx
• Provide config → provide-config-layer.mdx
• Caching wrapper → add-caching-by-wrapping-a-layer.mdx

Resource Management

• Bracket pattern → safely-bracket-resource-usage.mdx
• Scope management → manage-resource-lifecycles-with-scope.mdx
• Manual scope → manual-scope-management.mdx
• Scoped resources runtime → create-managed-runtime-for-scoped-resources.mdx

Streaming

• Process streaming data → process-streaming-data-with-stream.mdx
• From iterable → stream-from-iterable.mdx
• From file → stream-from-file.mdx
• From paginated API → stream-from-paginated-api.mdx
• Concurrent processing → stream-process-concurrently.mdx
• Batch processing → stream-process-in-batches.mdx
• Collect results → stream-collect-results.mdx
• Run for effects → stream-run-for-effects.mdx
• Manage resources → stream-manage-resources.mdx
• Retry on failure → stream-retry-on-failure.mdx

Schema & Validation

• Define contracts → define-contracts-with-schema.mdx
• Parse/decode → parse-with-schema-decode.mdx
• Transform data → transform-data-with-schema.mdx
• Validate body → validate-request-body.mdx
• Brand types → brand-model-domain-type.mdx
• Brand validation → brand-validate-parse.mdx
• Config schema → define-config-schema.mdx

Data Types

• Option → data-option.mdx, model-optional-values-with-option.mdx
• Either → data-either.mdx, accumulate-multiple-errors-with-either.mdx
• Chunk → data-chunk.mdx, use-chunk-for-high-performance-collections.mdx
• Array → data-array.mdx
• HashSet → data-hashset.mdx
• Duration → data-duration.mdx, representing-time-spans-with-duration.mdx
• DateTime → data-datetime.mdx, beyond-the-date-type.mdx
• BigDecimal → data-bigdecimal.mdx
• Cause → data-cause.mdx
• Exit → data-exit.mdx
• Ref → data-ref.mdx, manage-shared-state-with-ref.mdx
• Redacted → data-redacted.mdx
• Case → data-case.mdx
• Class → data-class.mdx
• Struct → data-struct.mdx
• Tuple → data-tuple.mdx

Pattern Matching

• Match API → pattern-match.mdx
• Effectful match → pattern-matcheffect.mdx
• Tag matching → pattern-matchtag.mdx
• Option/Either checks → pattern-option-either-checks.mdx

HTTP & Web

• Basic HTTP server → build-a-basic-http-server.mdx
• Launch server → launch-http-server.mdx
• Handle GET → handle-get-request.mdx
• HTTP client request → make-http-client-request.mdx
• Testable HTTP client → create-a-testable-http-client-service.mdx
• JSON response → send-json-response.mdx
• Path parameters → extract-path-parameters.mdx
• Provide dependencies to routes → provide-dependencies-to-routes.mdx

Testing

• Mocking dependencies → mocking-dependencies-in-tests.mdx
• Use Default layer → use-default-layer-for-tests.mdx
• Tests adapt to code → write-tests-that-adapt-to-application-code.mdx

Observability

• Structured logging → leverage-structured-logging.mdx, observability-structured-logging.mdx
• Tracing spans → trace-operations-with-spans.mdx, observability-tracing-spans.mdx
• Custom metrics → add-custom-metrics.mdx, observability-custom-metrics.mdx
• OpenTelemetry → observability-opentelemetry.mdx
• Effect.fn instrumentation → observability-effect-fn.mdx

Runtime & Execution

• runPromise → execute-with-runpromise.mdx
• runSync → execute-with-runsync.mdx
• runFork → execute-long-running-apps-with-runfork.mdx
• Reusable runtime → create-reusable-runtime-from-layers.mdx

Configuration

• Access config → access-config-in-context.mdx
• Define schema → define-config-schema.mdx
• Provide layer → provide-config-layer.mdx

Time & Scheduling

• Current time → accessing-current-time-with-clock.mdx
• Duration → representing-time-spans-with-duration.mdx
• DateTime → beyond-the-date-type.mdx
• Schedule repetition → control-repetition-with-schedule.mdx

Project Setup

• New project → setup-new-project.mdx
• Editor LSP → supercharge-your-editor-with-the-effect-lsp.mdx
• AI agents MCP → teach-your-ai-agents-effect-with-the-mcp-server.mdx

Advanced Concepts

• Structural equality → comparing-data-by-value-with-structural-equality.mdx
• Effect channels → understand-effect-channels.mdx
• Effects are lazy → effects-are-lazy.mdx
• Not found vs errors → distinguish-not-found-from-errors.mdx
• Promise problems → solve-promise-problems-with-effect.mdx
• Avoid long chains → avoid-long-andthen-chains.mdx

Pattern Categories

By Skill Level

Beginner (Getting Started)

• Constructor patterns (succeed, fail, sync, async)
• Basic combinators (map, flatMap, tap)
• Simple error handling (catch, catchTag)
• Effect.gen basics
• runPromise/runSync

Intermediate (Building Applications)

• Services and layers
• Schema validation
• HTTP servers and clients
• Resource management
• Concurrency basics (Effect.all, fork)
• Testing with mocks

Advanced (Production Systems)

• Complex layer composition
• Custom runtimes
• Streaming pipelines
• Graceful shutdown
• OpenTelemetry integration
• Performance optimization (Chunk, Ref)

By Use Case

Domain Modeling

• Schema definitions
• Brand types
• Tagged errors
• Option/Either for optional/fallible values

API Development

• HTTP server setup
• Route handling
• Request validation
• Error handling
• Response formatting

Data Processing

• Stream processing
• Batch operations
• Parallel processing
• Resource-safe pipelines

Application Architecture

• Service layer design
• Dependency injection
• Module composition
• Configuration management

Testing

• Mock layers
• Test utilities
• Testable services

Observability

• Structured logging
• Distributed tracing
• Custom metrics
• Performance monitoring

Search Patterns

By Keyword

Use Grep to search patterns by keyword:

# Find patterns about error handling
grep -l "error" patterns/*.mdx

# Find patterns about concurrency
grep -l "concurrent\|parallel\|fiber" patterns/*.mdx

# Find patterns about HTTP
grep -l "http\|server\|client" patterns/*.mdx

# Find patterns about testing
grep -l "test\|mock" patterns/*.mdx

By Frontmatter Tags

All patterns include metadata:

• title: Human-readable name
• id: Unique identifier (filename without extension)
• skillLevel: beginner, intermediate, advanced
• useCase: domain-modeling, error-handling, concurrency, etc.
• summary: Brief description
• tags: Keywords for searching
• related: Links to related patterns

Common Searches

"How do I create an Effect from..."

• → Search constructor patterns: grep -l "constructor" patterns/*.mdx
• → Check constructor-*.mdx files

"How do I handle errors when..."

• → Search error handling: grep -l "error\|catch\|retry" patterns/*.mdx
• → Check handle-*.mdx and pattern-catchtag.mdx

"How do I run multiple things concurrently?"

• → Search concurrency: grep -l "concurrent\|parallel\|all\|fork" patterns/*.mdx
• → Check run-effects-in-parallel-with-all.mdx

"How do I work with services?"

• → Search services: grep -l "service\|layer\|dependency" patterns/*.mdx
• → Check model-dependencies-as-services.mdx, understand-layers-for-dependency-injection.mdx

"How do I validate data?"

• → Search schema: grep -l "schema\|validate\|parse" patterns/*.mdx
• → Check define-contracts-with-schema.mdx, parse-with-schema-decode.mdx

Integration with Other Skills

Foundations → Patterns Hub

When you need concrete examples for foundation concepts, check patterns:

• effect-foundations teaches concepts → patterns show implementation

Architect → Patterns Hub

When designing systems, reference architectural patterns:

• Layer composition → organize-layers-into-composable-modules.mdx
• Service design → model-dependencies-as-services.mdx
• Scoped resources → scoped-service-layer.mdx

Engineer → Patterns Hub

When implementing features, find relevant patterns:

• HTTP endpoints → handle-get-request.mdx, validate-request-body.mdx
• Error handling → retry-based-on-specific-errors.mdx
• Concurrency → run-effects-in-parallel-with-all.mdx

Tester → Patterns Hub

When writing tests, reference testing patterns:

• Mock services → mocking-dependencies-in-tests.mdx
• Test layers → use-default-layer-for-tests.mdx
• Testable design → write-tests-that-adapt-to-application-code.mdx

Usage Workflow

1. Identify Need: "I need to [do something] with Effect"
2. Check Decision Tree: Find relevant section above
3. Read Pattern: Use Read tool on the pattern file
4. Adapt to Context: Apply pattern to your specific use case
5. Check Related: Follow related links in pattern frontmatter
6. Consult Agent: If unclear, use @effect-engineer or @effect-architect

Anti-Pattern Detection

If you find yourself:

• Using imperative loops → Check process-collection-in-parallel-with-foreach.mdx
• Mixing promises and Effects → Check constructor-try-trypromise.mdx, solve-promise-problems-with-effect.mdx
• Long andThen chains → Check avoid-long-andthen-chains.mdx, use-gen-for-business-logic.mdx
• Leaking requirements → Check model-dependencies-as-services.mdx
• Manual resource cleanup → Check safely-bracket-resource-usage.mdx

Pattern File Structure

Each pattern file follows this structure:

---
title: Human-readable title
id: kebab-case-id
skillLevel: beginner | intermediate | advanced
useCase: primary-use-case
summary: Brief description
tags:
  - keyword1
  - keyword2
related:
  - related-pattern-id-1
  - related-pattern-id-2
author: Author name
---

# Title

## Guideline
What to do

## Rationale
Why do it this way

## Good Example
✅ Recommended approach

## Bad Example
❌ What to avoid

## Related Patterns
Links to related patterns

Maintenance

Patterns are synced from EffectPatterns repository.

To update patterns:

cd /tmp
git clone --depth=1 https://github.com/PaulJPhilp/EffectPatterns.git
cp -r EffectPatterns/content/published/* /Users/pooks/Dev/crate/.claude/skills/effect-patterns-hub/patterns/
cp -r EffectPatterns/content/published/* /Users/pooks/Dev/crate/docs/effect-patterns/

Summary

• 130+ patterns covering all Effect-TS concepts
• Decision tree for quick pattern lookup
• Integration with existing skills and agents
• Searchable by keyword, use case, skill level
• Examples showing good and bad practices
• Related patterns for deeper exploration

Use this skill as your go-to reference for "How do I... with Effect?"