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](patterns/constructor-succeed-some-right.mdx)
• From sync code → [constructor-sync-async.mdx](patterns/constructor-sync-async.mdx)
• From promise → [constructor-try-trypromise.mdx](patterns/constructor-try-trypromise.mdx)
• From nullable → [constructor-from-nullable-option-either.mdx](patterns/constructor-from-nullable-option-either.mdx)
• Pre-resolved → [create-pre-resolved-effect.mdx](patterns/create-pre-resolved-effect.mdx)

Transform & Compose

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

Control Flow

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

Error Handling

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

Concurrency

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

Services & Dependency Injection

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

Resource Management

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

Streaming

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

Schema & Validation

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

Data Types

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

Pattern Matching

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

HTTP & Web

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

Testing

• Mocking dependencies → [mocking-dependencies-in-tests.mdx](patterns/mocking-dependencies-in-tests.mdx)
• Use Default layer → [use-default-layer-for-tests.mdx](patterns/use-default-layer-for-tests.mdx)
• Tests adapt to code → [write-tests-that-adapt-to-application-code.mdx](patterns/write-tests-that-adapt-to-application-code.mdx)

Observability

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

Runtime & Execution

• runPromise → [execute-with-runpromise.mdx](patterns/execute-with-runpromise.mdx)
• runSync → [execute-with-runsync.mdx](patterns/execute-with-runsync.mdx)
• runFork → [execute-long-running-apps-with-runfork.mdx](patterns/execute-long-running-apps-with-runfork.mdx)
• Reusable runtime → [create-reusable-runtime-from-layers.mdx](patterns/create-reusable-runtime-from-layers.mdx)

Configuration

• Access config → [access-config-in-context.mdx](patterns/access-config-in-context.mdx)
• Define schema → [define-config-schema.mdx](patterns/define-config-schema.mdx)
• Provide layer → [provide-config-layer.mdx](patterns/provide-config-layer.mdx)

Time & Scheduling

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

Project Setup

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

Advanced Concepts

• Structural equality → [comparing-data-by-value-with-structural-equality.mdx](patterns/comparing-data-by-value-with-structural-equality.mdx)
• Effect channels → [understand-effect-channels.mdx](patterns/understand-effect-channels.mdx)
• Effects are lazy → [effects-are-lazy.mdx](patterns/effects-are-lazy.mdx)
• Not found vs errors → [distinguish-not-found-from-errors.mdx](patterns/distinguish-not-found-from-errors.mdx)
• Promise problems → [solve-promise-problems-with-effect.mdx](patterns/solve-promise-problems-with-effect.mdx)
• Avoid long chains → [avoid-long-andthen-chains.mdx](patterns/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?"