Files
effect/.patterns/effect-library-development.md
T

14 KiB

Effect Library Development Patterns

🎯 OVERVIEW

Fundamental patterns for developing high-quality, type-safe code within the Effect library ecosystem. These patterns ensure consistency, reliability, and maintainability across the codebase.

🚨 CRITICAL FORBIDDEN PATTERNS

❌ NEVER: try-catch in Effect.gen

REASON: Effect generators handle errors through the Effect type system, not JavaScript exceptions.

// ❌ WRONG - This will cause runtime errors
Effect.gen(function*() {
  try {
    const result = yield* someEffect
    return result
  } catch (error) {
    // This will never be reached and breaks Effect semantics
    console.error(error)
  }
})

// ✅ CORRECT - Use Effect's built-in error handling
Effect.gen(function*() {
  const result = yield* Effect.result(someEffect)
  if (result._tag === "Failure") {
    // Handle error case properly
    console.error("Effect failed:", result.cause)
    return yield* Effect.fail("Handled error")
  }
  return result.value
})

❌ NEVER: Type Assertions

REASON: Type assertions hide real type errors and break TypeScript's safety guarantees.

// ❌ FORBIDDEN - These break type safety
const value = something as any
const value = something as never
const value = something as unknown

// ✅ CORRECT - Fix the underlying type issues
// Use proper generic type parameters
function processValue<T>(value: T): Effect.Effect<T, never, never> {
  return Effect.succeed(value)
}

// Use proper Effect constructors
const safeValue = Effect.try(() => JSON.parse(jsonString))

✅ MANDATORY PATTERNS

🔄 return yield* Pattern for Errors

CRITICAL: Always use return yield* when yielding terminal effects.

// ✅ CORRECT - Makes termination explicit
Effect.gen(function*() {
  if (invalidCondition) {
    return yield* Effect.fail("Validation failed")
  }

  if (shouldInterrupt) {
    return yield* Effect.interrupt
  }

  // Continue with normal flow
  const result = yield* someOtherEffect
  return result
})

// ❌ WRONG - Missing return keyword leads to unreachable code
Effect.gen(function*() {
  if (invalidCondition) {
    yield* Effect.fail("Validation failed") // Missing return!
    // Unreachable code after error!
  }
})

🏗️ CORE DEVELOPMENT PATTERNS

Effect.gen Composition Pattern

Use Effect.gen for sequential operations with proper error propagation:

import { Console, Effect } from "effect"

const processData = (input: string) =>
  Effect.gen(function*() {
    // Validate input
    if (input.length === 0) {
      return yield* Effect.fail("Input cannot be empty")
    }

    // Transform data
    const processed = yield* Effect.try({
      try: () => JSON.parse(input),
      catch: (error) => `Invalid JSON: ${error}`
    })

    // Log progress
    yield* Console.log(`Processed: ${JSON.stringify(processed)}`)

    return processed
  })

Effect.gen vs Effect.fn vs Effect.fnUntraced

Choose the right function constructor based on your use case:

Feature Effect.gen Effect.fn Effect.fnUntraced
Purpose One-off effect composition Reusable effectful functions Internal/performance-critical
Returns Effect<A, E, R> (...args) => Effect<A, E, R> (...args) => Effect<A, E, R>
Tracing Uses parent span Creates new span + stack trace No tracing overhead
Performance Standard Overhead for tracing Minimal overhead
Use case Inline composition Public API methods Library internals

Effect.gen - Inline Composition

Use for one-off effect composition that doesn't need to be reused as a function:

import { Effect } from "effect"

// One-off effect, no function wrapper needed
const program = Effect.gen(function*() {
  const user = yield* fetchUser(id)
  const posts = yield* fetchPosts(user.id)
  return { user, posts }
})

Effect.fn - Traced Reusable Functions (Public API)

Use for reusable effectful functions that benefit from tracing and stack traces:

import { Effect } from "effect"

// Creates a traced function with span + stack capture
const fetchUserPosts = Effect.fn("fetchUserPosts")(function*(userId: string) {
  yield* Effect.annotateCurrentSpan("userId", userId)
  const user = yield* fetchUser(userId)
  const posts = yield* fetchPosts(user.id)
  return { user, posts }
})

// Calling creates a span named "fetchUserPosts" with stack traces
await Effect.runPromise(fetchUserPosts("123"))

Effect.fn also supports piping transformations after the function body:

const fetchWithTimeout = Effect.fn("fetchWithTimeout")(
  function*(url: string) {
    return yield* Effect.tryPromise(() => fetch(url))
  },
  Effect.timeout("5 seconds"),
  Effect.retry({ times: 3 })
)

Effect.fnUntraced - Untraced Functions (Library Internals)

Use for internal implementations where tracing overhead is unacceptable:

import { Effect, Scope } from "effect"

// No tracing overhead - used in Stream, Channel, Sink internals
const internalTransform = Effect.fnUntraced(function*(pull, scope) {
  const reader = options.evaluate().getReader()
  yield* Scope.addFinalizer(scope, Effect.sync(() => reader.releaseLock()))
  // ... internal implementation
})

When to Use What

Use Effect.gen when:

  • Writing inline effect composition
  • One-off operations that don't need to be reused
  • Inside other functions already being traced

Use Effect.fn when:

  • Creating reusable effectful functions
  • Building public API methods
  • You want automatic tracing/spans for debugging
  • Error stack traces matter for users

Use Effect.fnUntraced when:

  • Building internal library implementations
  • Performance is critical (hot paths)
  • Function is called many times per operation
  • Tracing overhead is unacceptable

Error Handling with Data.TaggedError

Create structured, typed errors using Data.TaggedError:

import { Data, Effect } from "effect"

// Define custom error types
class ValidationError extends Data.TaggedError("ValidationError")<{
  field: string
  message: string
}> {}

class NetworkError extends Data.TaggedError("NetworkError")<{
  status: number
  url: string
}> {}

// Use in operations
const validateAndFetch = Effect.fn(function*(url: string) {
  if (!url.startsWith("https://")) {
    return yield* Effect.fail(
      new ValidationError({
        field: "url",
        message: "URL must use HTTPS"
      })
    )
  }

  const response = yield* Effect.tryPromise({
    try: () => fetch(url),
    catch: () => new NetworkError({ status: 0, url })
  })

  if (!response.ok) {
    return yield* Effect.fail(
      new NetworkError({
        status: response.status,
        url
      })
    )
  }

  return response
})

Resource Management Pattern

Use Effect.acquireUseRelease for automatic resource cleanup:

import { Console, Effect } from "effect"

// Resource acquisition pattern
const withDatabase = Effect.fn(<A, E>(
  operation: (db: Database) => Effect.Effect<A, E, never>
): Effect.Effect<A, E | DatabaseError, never> =>
  Effect.acquireUseRelease(
    // Acquire
    Effect.tryPromise({
      try: () => createDatabaseConnection(),
      catch: (error) => new DatabaseError({ cause: error })
    }),
    // Use
    operation,
    // Release
    (db) => Effect.promise(() => db.close())
  ))

// Usage
const queryUser = Effect.fn((id: string) =>
  withDatabase(Effect.fnUntraced(function*(db) {
    const user = yield* Effect.tryPromise({
      try: () => db.query("SELECT * FROM users WHERE id = ?", [id]),
      catch: (error) => new QueryError({ query: "users", cause: error })
    })

    yield* Console.log(`Found user: ${user.name}`)
    return user
  }))

Layer Composition Pattern

Prefer the class syntax when working with Context.Service. For example:

import { Context } from "effect"

class MyService extends Context.Service<MyService, {
  readonly doSomething: (input: string) => number
}>()("MyService") {}

Build applications using layered architecture:

import { Context, Effect, Layer } from "effect"

// Define service interfaces
class DatabaseService extends Context.Service("DatabaseService")<
  DatabaseService,
  {
    readonly query: (sql: string) => Effect.Effect<unknown[], DatabaseError, never>
  }
>() {}

class UserService extends Context.Service("UserService")<
  UserService,
  {
    readonly getUser: (id: string) => Effect.Effect<User, UserError, never>
  }
>() {}

// Implement services as layers
const DatabaseServiceLive = Layer.succeed(
  DatabaseService,
  DatabaseService.of({
    query: (sql) =>
      Effect.tryPromise({
        try: () => database.execute(sql),
        catch: (error) => new DatabaseError({ cause: error })
      })
  })
)

const UserServiceLive = Layer.effect(
  UserService,
  Effect.gen(function*() {
    const db = yield* DatabaseService

    return UserService.of({
      getUser: (id) =>
        Effect.gen(function*() {
          const rows = yield* db.query(`SELECT * FROM users WHERE id = '${id}'`)
          if (rows.length === 0) {
            return yield* Effect.fail(new UserError({ message: "User not found" }))
          }
          return rows[0] as User
        })
    })
  })
)

// Compose layers
const AppLayer = UserServiceLive.pipe(
  Layer.provide(DatabaseServiceLive)
)

🔧 DEVELOPMENT WORKFLOW PATTERNS

Immediate Linting Pattern

MANDATORY: Always lint TypeScript files immediately after editing:

# After editing any TypeScript file
pnpm lint --fix packages/effect/src/ModifiedFile.ts

# This ensures:
# - Consistent code formatting
# - Early detection of style issues
# - Compliance with project standards

Validation Checkpoint Pattern

Run comprehensive validation after implementation:

# 1. Lint all modified files
pnpm lint --fix packages/effect/src/*.ts

# 2. Validate JSDoc examples compile
pnpm docgen

# 3. Check types
pnpm check

# 4. Run tests
pnpm test packages/effect/test/ModifiedTest.ts

# 5. Build project
pnpm build

Progressive Implementation Pattern

Break complex features into validated increments:

// Step 1: Basic structure with types
interface FeatureConfig {
  readonly option1: string
  readonly option2: number
}

// Step 2: Core implementation
const createFeature = Effect.fn(function*(config: FeatureConfig) {
  // Basic implementation
  yield* Console.log("Feature created")
  return { config }
})

// Step 3: Add error handling
const createFeatureWithValidation = Effect.fn(function*(config: FeatureConfig) {
  if (config.option2 < 0) {
    return yield* Effect.fail("Option2 must be positive")
  }

  const feature = yield* createFeature(config)
  return feature
})
// Step 4: Add comprehensive functionality
// ... continue building incrementally

📚 INTEGRATION PATTERNS

Module Export Pattern

Structure module exports for clarity and discoverability:

// ModuleName.ts
/**
 * @since 1.0.0
 */

// Internal implementations
const internal = {
  // Private helper functions
}

// Public API exports

/**
 * Creates a new instance with the given configuration.
 *
 * @example
 * ```ts
 * import { ModuleName } from "effect"
 *
 * const instance = ModuleName.create({ value: 42 })
 * ```
 *
 * @since 1.0.0
 * @category constructors
 */
export const create: <A>(config: Config<A>) => Effect.Effect<Instance<A>, never, never> = (config) =>
  Effect.succeed({ config })

/**
 * Transforms an instance using the provided function.
 *
 * @example
 * ```ts
 * import { ModuleName, Effect } from "effect"
 *
 * const program = Effect.gen(function*() {
 *   const instance = yield* ModuleName.create({ value: 42 })
 *   const transformed = yield* ModuleName.map(instance, x => x * 2)
 *   return transformed
 * })
 * ```
 *
 * @since 1.0.0
 * @category combinators
 */
export const map: <A, B>(instance: Instance<A>, f: (a: A) => B) => Effect.Effect<Instance<B>, never, never> = (
  instance,
  f
) => Effect.succeed({ config: f(instance.config) })

Testing Integration Pattern

Structure tests to validate all aspects of functionality:

import { assert, describe, it } from "@effect/vitest"
import { Duration, Effect, TestClock } from "effect"
import * as ModuleName from "../src/ModuleName.js"

describe("ModuleName", () => {
  describe("constructors", () => {
    it.effect("create should initialize with config", () =>
      Effect.gen(function*() {
        const config = { value: 42 }
        const instance = yield* ModuleName.create(config)

        assert.deepStrictEqual(instance.config, config)
      }))
  })

  describe("combinators", () => {
    it.effect("map should transform instance", () =>
      Effect.gen(function*() {
        const instance = yield* ModuleName.create({ value: 10 })
        const transformed = yield* ModuleName.map(instance, (x) => x * 2)

        assert.strictEqual(transformed.config.value, 20)
      }))
  })

  describe("time-dependent operations", () => {
    it.effect("should handle delays properly", () =>
      Effect.gen(function*() {
        const fiber = yield* Effect.fork(
          ModuleName.delayedOperation(Duration.seconds(5))
        )

        // Use TestClock to advance time
        yield* TestClock.advance(Duration.seconds(5))

        const result = yield* Effect.join(fiber)
        assert.strictEqual(result, "completed")
      }))
  })
})