@effect-migrate/preset-basic

Default Effect migration rules for detecting legacy patterns and enforcing architectural boundaries.

Installation

pnpm add -D @effect-migrate/preset-basic

Usage

Add the preset to your effect-migrate.config.ts:

import type { Config } from "@effect-migrate/core"

export default {
  version: 1,
  presets: ["@effect-migrate/preset-basic"],
  paths: {
    root: ".",
    include: ["src/**/*.ts"]
  }
} satisfies Config

The preset automatically loads all pattern and boundary rules, plus sensible config defaults.

What's Included

Pattern Rules (5 rules)

Pattern rules detect legacy code patterns that should be migrated to Effect equivalents.

no-async-await

Detects: async function declarations and arrow functions

Why: async/await cannot be interrupted, retried, or composed with Effects. Effect.gen provides all async/await benefits plus interruption, retry, and structured concurrency.

Example violation:

// ❌ Detected
async function fetchUser(id: string) {
  const response = await fetch(`/users/${id}`)
  return response.json()
}

Fix:

// ✅ Use Effect.gen
const fetchUser = (id: string) =>
  Effect.gen(function* () {
    const response = yield* Effect.tryPromise(() => fetch(`/users/${id}`))
    const data = yield* Effect.tryPromise(() => response.json())
    return data
  })

no-new-promise

Detects: new Promise<T>(...) constructor calls

Why: Raw Promises lack resource safety and composability. Effect provides better abstractions for async operations.

Example violation:

// ❌ Detected
function delay(ms: number) {
  return new Promise<void>((resolve) => setTimeout(resolve, ms))
}

Fix:

// ✅ Use Effect.sleep
const delay = (ms: number) => Effect.sleep(Duration.millis(ms))

// ✅ Or Effect.async for custom async operations
const delay = (ms: number) =>
  Effect.async<void>((resume) => {
    const id = setTimeout(() => resume(Effect.void), ms)
    return Effect.sync(() => clearTimeout(id))
  })

no-try-catch

Detects: try { ... } catch blocks

Why: try/catch doesn't compose well with Effects and loses type information. Effect.catchAll and Effect.catchTag provide typed error handling.

Example violation:

// ❌ Detected
function parseJSON(text: string) {
  try {
    return JSON.parse(text)
  } catch (error) {
    return null
  }
}

Fix:

// ✅ Use Effect.try
const parseJSON = (text: string) =>
  Effect.try({
    try: () => JSON.parse(text),
    catch: (error) => new ParseError({ message: String(error) })
  })

// ✅ Or handle specific error types
const program = Effect.gen(function* () {
  const data = yield* parseJSON(text).pipe(
    Effect.catchTag("ParseError", () => Effect.succeed(null))
  )
  return data
})

no-barrel-import-effect

Detects: import { ... } from "effect" (barrel imports)

Why: Barrel imports hurt tree-shaking and increase bundle size. Import from specific modules for better optimization.

Example violation:

// ❌ Detected
import { Effect, Console, pipe } from "effect"

Fix:

// ✅ Import from specific modules
import * as Effect from "effect/Effect"
import * as Console from "effect/Console"
import { pipe } from "effect/Function"

no-fs-promises

Detects: from "fs/promises" or from "node:fs/promises" imports

Why: Direct Node.js filesystem imports couple code to Node.js. Use @effect/platform FileSystem for cross-platform compatibility and resource safety.

Example violation:

// ❌ Detected
import { readFile } from "fs/promises"

async function loadConfig(path: string) {
  const content = await readFile(path, "utf-8")
  return JSON.parse(content)
}

Fix:

// ✅ Use @effect/platform FileSystem
import { FileSystem } from "@effect/platform"
import * as Effect from "effect/Effect"

const loadConfig = (path: string) =>
  Effect.gen(function* () {
    const fs = yield* FileSystem.FileSystem
    const content = yield* fs.readFileString(path)
    return JSON.parse(content)
  })

Boundary Rules (4 rules)

Boundary rules enforce architectural constraints to maintain clean separation between Effect and platform-specific code.

no-node-in-services

Severity: Error

Enforces: Service layer (src/services/**/*.ts) cannot import Node.js built-ins (node:*)

Why: Services should be platform-agnostic for testability and reusability.

Example violation:

// ❌ src/services/ConfigService.ts
import { readFileSync } from "node:fs"

Fix:

// ✅ Use @effect/platform abstraction
import { FileSystem } from "@effect/platform"

Docs: https://effect.website/docs/guides/platform/overview

no-platform-node-in-core

Severity: Error

Enforces: Core logic (src/core/**/*.ts) cannot import @effect/platform-node

Why: Core modules should depend on platform-agnostic abstractions only.

Example violation:

// ❌ src/core/parser.ts
import { FileSystem } from "@effect/platform-node"

Fix:

// ✅ Import from platform-agnostic package
import { FileSystem } from "@effect/platform"

Docs: https://effect.website/docs/guides/platform/platform-specific

no-fs-promises (boundary)

Severity: Warning

Enforces: Source files (src/**/*.ts) should not import fs/promises, node:fs/promises, or node:fs

Why: Direct filesystem imports couple code to Node.js. Use @effect/platform FileSystem service.

Fix: Use FileSystem from @effect/platform (see pattern rule example above)

Docs: https://effect.website/docs/guides/platform/file-system

no-node-path

Severity: Warning

Enforces: Source files (src/**/*.ts) should not import path or node:path

Why: Direct path imports couple code to Node.js. Use @effect/platform Path service for cross-platform path handling.

Example violation:

// ❌ Detected
import path from "path"

const joined = path.join("src", "index.ts")

Fix:

// ✅ Use @effect/platform Path
import { Path } from "@effect/platform"
import * as Effect from "effect/Effect"

const program = Effect.gen(function* () {
  const path = yield* Path.Path
  const joined = path.join("src", "index.ts")
  return joined
})

Docs: https://effect.website/docs/guides/platform/path

Config Defaults

The preset provides sensible defaults that are merged with your config:

{
  paths: {
    exclude: ["node_modules/**", "dist/**", ".next/**", "coverage/**", ".git/**", "build/**"]
  }
}

You can override or extend these:

export default {
  version: 1,
  presets: ["@effect-migrate/preset-basic"],
  paths: {
    exclude: ["vendor/**"] // Extends preset excludes
  }
} satisfies Config

Rule Summary

| Rule ID | Type | Severity | Detects | | --------------------------- | -------- | -------- | ------------------------------- | | no-async-await | pattern | warning | async functions | | no-new-promise | pattern | warning | new Promise() constructor | | no-try-catch | pattern | warning | try/catch blocks | | no-barrel-import-effect | pattern | warning | import from "effect" | | no-fs-promises | pattern | warning | import from "fs/promises" | | no-node-in-services | boundary | error | node:* in src/services/**/* | | no-platform-node-in-core | boundary | error | @effect/platform-node in core | | no-fs-promises (boundary) | boundary | warning | fs/promises in src/**/* | | no-node-path | boundary | warning | node:path in src/**/* |

Disabling Rules

To disable specific preset rules, filter them out after loading:

import { presetBasic } from "@effect-migrate/preset-basic"

export default {
  version: 1,
  presets: [], // Don't use preset field
  // Manually load and filter
  patterns: presetBasic.rules
    .filter((rule) => rule.kind === "pattern" && rule.id !== "no-barrel-import-effect")
    .map((rule) => ({
      id: rule.id
      // ... convert to config format
    }))
} satisfies Config

Or use @effect-migrate-ignore comments in your code to suppress specific violations:

// @effect-migrate-ignore
async function legacyFunction() {
  // This won't trigger no-async-await
}

Creating Custom Presets

To create your own preset, export an object matching the Preset interface:

import type { Preset } from "@effect-migrate/core"

export const myPreset: Preset = {
  rules: [
    // Your custom rules
  ],
  defaults: {
    paths: {
      exclude: ["vendor/**"]
    }
  }
}

export default myPreset

License

MIT