effect-patterns-project-setup--execution

name	effect-patterns-project-setup--execution
description	Effect-TS patterns for Project Setup Execution. Use when working with project setup execution in Effect-TS applications.

Effect-TS Patterns: Project Setup Execution

This skill provides 4 curated Effect-TS patterns for project setup execution. Use this skill when working on tasks related to:

• project setup execution
• Best practices in Effect-TS applications
• Real-world patterns and solutions

---

🟢 Beginner Patterns

Execute Synchronous Effects with Effect.runSync

Rule: Execute synchronous effects with Effect.runSync.

Good Example:

import { Effect } from "effect";

// Simple synchronous program
const program1 = Effect.gen(function* () {
  const n = 10;
  const result = n * 2;
  yield* Effect.log(`Simple program result: ${result}`);
  return result;
});

// Run simple program
Effect.runSync(program1);

// Program with logging
const program2 = Effect.gen(function* () {
  yield* Effect.logInfo("Starting calculation...");
  const n = yield* Effect.sync(() => 10);
  yield* Effect.logInfo(`Got number: ${n}`);
  const result = yield* Effect.sync(() => n * 2);
  yield* Effect.logInfo(`Result: ${result}`);
  return result;
});

// Run with logging
Effect.runSync(program2);

// Program with error handling
const program3 = Effect.gen(function* () {
  yield* Effect.logInfo("Starting division...");
  const n = yield* Effect.sync(() => 10);
  const divisor = yield* Effect.sync(() => 0);

  yield* Effect.logInfo(`Attempting to divide ${n} by ${divisor}...`);
  return yield* Effect.try({
    try: () => {
      if (divisor === 0) throw new Error("Cannot divide by zero");
      return n / divisor;
    },
    catch: (error) => {
      if (error instanceof Error) {
        return error;
      }
      return new Error("Unknown error occurred");
    },
  });
}).pipe(
  Effect.catchAll((error) => Effect.logInfo(`Error occurred: ${error.message}`))
);

// Run with error handling
Effect.runSync(program3);

Explanation:
Use runSync only for Effects that are fully synchronous. If the Effect contains async code, use runPromise instead.

Anti-Pattern:

Do not use runSync on an Effect that contains asynchronous operations like Effect.delay or Effect.promise. This will result in a runtime error.

Rationale:

To execute an Effect that is guaranteed to be synchronous, use Effect.runSync. This will return the success value directly or throw the error.

Effect.runSync is an optimized runner for Effects that don't involve any asynchronous operations. If the Effect contains any async operations, runSync will throw an error.

---

Execute Asynchronous Effects with Effect.runPromise

Rule: Execute asynchronous effects with Effect.runPromise.

Good Example:

import { Effect } from "effect";

const program = Effect.succeed("Hello, World!").pipe(Effect.delay("1 second"));

const promise = Effect.runPromise(program);

const programWithLogging = Effect.gen(function* () {
  const result = yield* program;
  yield* Effect.log(result); // Logs "Hello, World!" after 1 second.
  return result;
});

Effect.runPromise(programWithLogging);

Explanation:
Effect.runPromise executes your effect and returns a Promise, making it easy to integrate with existing JavaScript async workflows.

Anti-Pattern:

Never call runPromise inside another Effect composition. Effects are meant to be composed together before being run once at the end.

Rationale:

To execute an Effect that may be asynchronous and retrieve its result, use Effect.runPromise. This should only be done at the outermost layer of your application.

Effect.runPromise is the bridge from the Effect world to the Promise-based world of Node.js and browsers. If the Effect succeeds, the Promise resolves; if it fails, the Promise rejects.

---

Set Up a New Effect Project

Rule: Set up a new Effect project.

Good Example:

// 1. Init project (e.g., `npm init -y`)
// 2. Install deps (e.g., `npm install effect`, `npm install -D typescript tsx`)
// 3. Create tsconfig.json with `"strict": true`
// 4. Create src/index.ts
import { Effect } from "effect";

const program = Effect.log("Hello, World!");

Effect.runSync(program);

// 5. Run the program (e.g., `npx tsx src/index.ts`)

Explanation:
This setup ensures you have TypeScript and Effect ready to go, with strict type-checking for maximum safety and correctness.

Anti-Pattern:

Avoid disabling strict mode in your tsconfig.json. Running with "strict": false will cause you to lose many of the type-safety guarantees that make Effect so powerful.

Rationale:

To start a new Effect project, initialize a standard Node.js project, add effect and typescript as dependencies, and create a tsconfig.json file with strict mode enabled.

A proper setup is crucial for leveraging Effect's powerful type-safety features. Using TypeScript's strict mode is non-negotiable.

---

🟠 Advanced Patterns

Create a Reusable Runtime from Layers

Rule: Create a reusable runtime from layers.

Good Example:

import { Effect, Layer, Runtime } from "effect";

class GreeterService extends Effect.Service<GreeterService>()("Greeter", {
  sync: () => ({
    greet: (name: string) => Effect.sync(() => `Hello ${name}`),
  }),
}) {}

const runtime = Effect.runSync(
  Layer.toRuntime(GreeterService.Default).pipe(Effect.scoped)
);

// In a server, you would reuse `run` for every request.
Runtime.runPromise(runtime)(Effect.log("Hello"));

Explanation:
By compiling your layers into a Runtime once, you avoid rebuilding the dependency graph for every effect execution.

Anti-Pattern:

For a long-running application, avoid providing layers and running an effect in a single operation. This forces Effect to rebuild the dependency graph on every execution.

Rationale:

For applications that need to run multiple effects (e.g., a web server), use Layer.toRuntime(appLayer) to compile your dependency graph into a single, reusable Runtime object.

Building the dependency graph from layers has a one-time cost. Creating a Runtime once when your application starts is highly efficient for long-running applications.

---