effect-handler-patterns

Effect-TS Lambda Handler 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 { getBlogByIdUsecase } from './usecase.js'

// ✅ CORRECT - Package imports for external dependencies
import { BlogPostId } from '@t6c/domain-common'
import { okResponse, toHandler } from '@t6c/lib-api'
import { Effect as E } from 'effect'

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

Usecase Co-location Pattern

Usecases Must Be Co-located with Handlers

• MANDATORY: Place usecases in the same directory as their handlers
• MANDATORY: Place usecase tests in the same directory as the usecase
• This ensures clear ownership and easier maintenance

src/lambdas/
├── get-blog-by-id/
│   ├── handler.ts
│   ├── handler.test.ts
│   ├── get-blog-by-id.usecase.ts
│   └── get-blog-by-id.usecase.test.ts
└── create-blog-post/
    ├── handler.ts
    ├── handler.test.ts
    ├── create-blog-post.usecase.ts
    └── create-blog-post.usecase.test.ts

Usecase Import Pattern

// ✅ CORRECT - Co-located usecase import
import { getBlogByIdUsecase } from './get-blog-by-id.usecase.js'

// ❌ WRONG - Separate usecases directory
import { getBlogByIdUsecase } from '../../usecases/get-blog-by-id.usecase.js'

Handler Structure Pattern

Standard REST API Handler

/**
 * JSDoc description of the endpoint
 * HTTP_METHOD /api/path
 */
export const _handler = schemaInputMethod(InputSchema).pipe(
  E.flatMap(usecaseFunction),
  E.flatMap(responseFunction),
  E.tapError(E.logError),
  E.catchTags({
    ParseError: (error) => badRequestResponse(error.message),
    NotFoundError: () => notFoundResponse(),
    ConflictError: (error) => conflictResponse(error.message),
  }),
  E.orDie,
  E.withSpan('handler-name'),
)

export const handler = _handler.pipe(
  E.provide(RequiredStore.Default),
  E.withSpan('handler-name-full'),
  toHandler,
)