effect-usecase-patterns

Effect-TS Usecase Implementation Patterns and Best Practices

Import Patterns

Always Use Relative Paths for Internal Imports

• CRITICAL: Never use src/ aliases for internal imports
• Always use relative paths like ../../stores/blog/blog.store.js
• Use package imports only for external dependencies
• Store files follow pattern: store-name.store.ts

// ✅ CORRECT - Relative paths for internal imports
import { BlogStore } from '../../stores/blog/blog.store.js'
import { SearchStore } from '../../stores/search/search.store.js'

// ✅ CORRECT - Package imports for external dependencies
import { BlogPost, BlogPostId } from '@t6c/blog-domain'
import { Effect as E } from 'effect'

// ❌ WRONG - Never use src/ aliases
import { BlogStore } from 'src/stores/blog/blog.store.js'

MANDATORY Usecase Structure

Required Error Handling and Observability Pattern

EVERY usecase MUST follow this exact pattern:

export const myUsecase = (input: MyInput) =>
  E.gen(function* () {
    // Business logic implementation here...
    const result = yield* businessLogic(input)
    return result
  }).pipe(
    // 🔴 MANDATORY: Simple error logging - NO custom messages
    E.tapError(E.logError),
    // 🔴 MANDATORY: Use E.orDie for unexpected errors OR allow domain errors to bubble up
    E.orDie, // Use this for usecases that should only return success
    // 🔴 MANDATORY: Observability span with relevant attributes
    E.withSpan('my-usecase-name', { 
      attributes: { 
        // Only include primitive values, not entire objects
        userId: input.userId,
        page: input.page 
      } 
    }),
  )

Error Handling Strategy by Usecase Type

GET Usecases - Allow NotFoundError to Bubble Up

// ✅ CORRECT - Allow NotFoundError for client handling
export const getBlogByIdUsecase = (id: BlogPostId) =>
  E.gen(function* () {
    const blogStore = yield* BlogStore
    const userStore = yield* UserStore

    const blogPost = yield* blogStore.getById(id) // Can throw NotFoundError
    const author = yield* userStore.getAuthorById(blogPost.authorId)
    
    return BlogPostProfile.make({
      // ... transformation
    })
  }).pipe(
    E.tapError(E.logError), // ✅ Simple logging only
    // ❌ NO E.orDie - let NotFoundError bubble up
    E.withSpan('getBlogByIdUsecase', { 
      attributes: { blogPostId: id } 
    })
  )