Write Effect

import { Effect, Schema } from "effect";

class NotionFsError extends Schema.TaggedError<NotionFsError>("NotionFsError")({
  message: Schema.String,
  cause: Schema.optional(Schema.Defect),
}) {}

const program = Effect.fail(
  new NotionFsError({
    message: "Page not found",
    cause: new Error("Notion API returned 404"),
  }),
);

Store typed domain errors in src/errors.ts and export public ones from src/index.ts.

Writing Effects

• Prefer Effect.gen for multi-step composition.
• Use yield* to execute Effects.
• For conditional failures, use return yield* Effect.fail(...) for narrowing.
• Prefer Effect.fn("Service.method") for reusable Effect functions.
• Give spans meaningful names.
• Add context with Effect.annotateLogs and Effect.annotateCurrentSpan.

Example:

import { Effect } from "effect";

export const parseUser = Effect.fn("UserService.parseUser")((input: string) =>
  Effect.sync(() => JSON.parse(input)).pipe(
    Effect.annotateLogs("inputLength", input.length),
  ),
);

Avoid try/catch Inside Effects

• Use Effect.try for sync code that may throw.
• Use Effect.tryPromise for async code that may reject.

import { Effect } from "effect";

const fromDisk = Effect.try({
  try: () => Bun.file("data.json").text(),
  catch: (error: unknown) =>
    new Error(`Failed to read file: ${String(error)}`),
});

const fromApi = Effect.tryPromise({
  try: () => fetch("https://example.com/data"),
  catch: (error: unknown) =>
    new Error(`Request failed: ${String(error)}`),
});

Layer Provisioning Boundary

• Provide layers once at the application boundary.
• Avoid scattering Effect.provide(...) through domain modules.
• Keep domain code dependency-driven and runtime wiring centralized.

Verification

bun run typecheck
bun run lint

If test harness is configured:

bun run test
bun run test:coverage