AGENTS.md

Agent Instructions

This is the Effect App library itory, focusing on functional programming patterns and effect systems in TypeScript, wrapping and extending the Effect library.

Development Workflow

• The git base branch is main
• Use pnpm as the package manager

Core Principles

• Zero Tolerance for Errors: All automated checks must pass
• No as any / as unknown casts: These are never acceptable fixes. Understand the actual types and fix the root cause. If a type mismatch exists, find the correct v4 API, update the type signatures, or restructure the code.
• Clarity over Cleverness: Choose clear, maintainable solutions
• Conciseness: Keep code and any wording concise and to the point. Sacrifice grammar for the sake of concision.
• Reduce comments: Avoid comments unless absolutely required to explain unusual or complex logic. Comments in jsdocs are acceptable.
• Look for effect sources inside repos/effect-v4
• Never import local repos files: Always use the latest online (pre-release) versions of packages instead. repos is just for reference, also includes examples, tests, and migration documentation.
• Never webfetch from the effect-v3 and effect-v4 repos: just use the locally included under repos

Mandatory Validation Steps

New Features

• Run pnpm lint-fix (available inside each package) after editing files

• Run type checking: pnpm check (available inside each package
  • If type checking continues to fail, run pnpm clean to clear caches, then re-run pnpm check

Migrations

• Run pnpm eslint fix ./src/<file.ts> inside the package root after editing files
• Run type checking: pnpm check inside the package root after editing files
  • If type checking continues to fail, run pnpm clean to clear caches, then re-run pnpm tsc ./src/<file.ts>

Code Style Guidelines

Always look at existing code in the repository to learn and follow established patterns before writing new code.

Do not worry about getting code formatting perfect while writing. Use pnpm lint-fix to automatically format code according to the project's style guidelines.

Prefer Effect.fnUntraced over functions that return Effect.gen

Instead of writing:

const fn = (param: string) =>
  Effect.gen(function*() {
    // ...
  })

Prefer:

const fn = Effect.fnUntraced(function*(param: string) {
  // ...
})

Using Context.Service

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

import { Context } from "effect-app"

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

Checking Array is not empty

Avoid .length > 0 or .length === 0 or !.length or !!.length checks, use Array.isArrayNonEmpty for type narrowing by default.

Changesets

All pull requests must include a changeset. You can create changesets in the .changeset/ directory.

The have the following format:

---
"package-name": patch | minor | major
---

A description of the change.