effect-service-architecture

Effect-TS Service Architecture Patterns and Best Practices

1. 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

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

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

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

2. Store Layer (Data Access)

Service Class Structure

export class BlogStore extends E.Service<BlogStore>()('BlogStore', {
  dependencies: [DynamoDBService, ConfigService],
  effect: E.gen(function* () {
    const dynamodb = yield* DynamoDBService
    const config = yield* ConfigService
    
    return {
      create: (blogPost: BlogPost) => E.gen(function* () {
        // Implementation
      }),
      getById: (id: BlogPostId) => E.gen(function* () {
        // Implementation  
      }),
    }
  }),
}) {}

Store Responsibilities

• ✅ Data persistence and retrieval only
• ✅ Schema encoding/decoding
• ✅ External service integration (DynamoDB, Algolia, S3)
• ✅ Return raw data without business logic processing
• ❌ No pagination calculations or business logic

3. Usecase Layer (Business Logic)

Usecase Structure with Observability

/**
 * Creates a new blog post with default values
 * @param input - Blog post creation input
 * @returns Created blog post with generated ID and timestamps
 */
export const createBlogPostUsecase = (input: CreateBlogPostInput) =>
  E.gen(function* () {
    // Start logging - concise format
    yield* E.logInfo('createBlogPostUsecase started', JSON.stringify(input))
    
    const blogStore = yield* BlogStore
    
    // Annotate key data points for tracing
    const blogPostData = BlogPost.make({
      id: BlogPostId.make(randomUUID()),
      ...input,
      // ... other fields
    })
    yield* E.annotateCurrentSpan('blogPostData', JSON.stringify(blogPostData))
    
    const createdBlogPost = yield* blogStore.create(blogPostData)
    yield* E.annotateCurrentSpan('createdBlogPost', JSON.stringify(createdBlogPost))
    
    // Completion logging - concise format
    yield* E.logInfo('createBlogPostUsecase completed successfully', JSON.stringify(createdBlogPost))
    
    return createdBlogPost
  }).pipe(
    E.tapError((error) =>
      E.logError('createBlogPostUsecase failed', JSON.stringify({ error, input }))
    ),
    E.withSpan('createBlogPostUsecase', { attributes: { input } })
  )