EffectPatterns copilot-instructions.md

Effect-Patterns AI Agent Instructions

Project Overview

Effect-Patterns is a community-driven knowledge base of practical patterns for building robust applications with Effect-TS. The project includes:

• A pattern server for serving API endpoints
• Documentation and examples of Effect-TS patterns
• Rules and guidelines for AI coding agents
• MCP server integration for context-aware coding assistance

Key Architectural Patterns

Service Pattern

All services must use the modern Effect.Service pattern:

export class UserService extends Effect.Service<UserService>()("UserService", {
  // Enable static accessor methods
  accessors: true,

  // Define implementation with dependencies
  effect: Effect.gen(function* () {
    // Get dependencies
    const logger = yield* LoggerService;
    const db = yield* DatabaseService;

    return {
      getUser: (id: string) =>
        Effect.gen(function* () {
          yield* logger.log(`Fetching user ${id}`);
          return yield* db.query(`SELECT * FROM users WHERE id = ${id}`);
        }),
    };
  }),

  // Declare dependencies
  dependencies: [LoggerService.Default, DatabaseService.Default],
}) {}

Dependency Injection

• Use Layer-based DI with Layer.merge
• Compose layers logically:

const mainLayer = Layer.merge(
  DatabaseService.Default,
  LoggerService.Default,
  NodeContext.layer
);

const program = Effect.gen(function* () {
  // Program logic
}).pipe(Effect.provide(mainLayer));

Error Handling

Define tagged errors for type-safety:

export class ServiceError extends Data.TaggedError("ServiceError")<{
  message: string;
  cause?: unknown;
}> {}

// Usage
Effect.gen(function* () {
  try {
    // Operation
  } catch (cause) {
    yield* Effect.fail(
      new ServiceError({
        message: "Operation failed",
        cause,
      })
    );
  }
});

HTTP Server

Build HTTP servers with @effect/platform:

const app = HttpRouter.empty.pipe(
  HttpRouter.get("/health", () =>
    Effect.succeed({ status: "ok" }).pipe(
      Effect.flatMap(HttpServerResponse.json)
    )
  )
);

const server = NodeHttpServer.layer(() => require("node:http").createServer(), {
  port: 3001,
});

const serverLayer = HttpServer.serve(app);