resources

name	resources
description	This skill should be used when the user asks about "Effect resources", "acquireRelease", "Scope", "finalizers", "resource cleanup", "Effect.addFinalizer", "Effect.ensuring", "scoped effects", "resource lifecycle", "bracket pattern", "safe resource handling", "database connections", "file handles", or needs to understand how Effect guarantees resource cleanup.
version	1.0.0

Resource Management in Effect

Overview

Effect provides structured resource management that guarantees cleanup even when errors occur or the effect is interrupted. This is essential for:

• Database connections
• File handles
• Network sockets
• Locks and semaphores
• Any resource requiring cleanup

Core Concept: Scope

A Scope is a context that tracks resources and ensures their cleanup:

Effect<A, E, R | Scope>;
//              ^^^^^ Indicates resource needs cleanup

Basic Resource Acquisition

Effect.acquireRelease

The fundamental pattern for safe resource management:

import { Effect } from "effect";

const managedFile = Effect.acquireRelease(
  Effect.sync(() => fs.openSync("file.txt", "r")),
  (fd) => Effect.sync(() => fs.closeSync(fd)),
);

Using the Resource

const program = Effect.gen(function* () {
  const fd = yield* managedFile;
  const content = yield* Effect.sync(() => fs.readFileSync(fd, "utf-8"));
  return content;
});

// Run with automatic scope management
const result = yield * Effect.scoped(program);

Effect.scoped

Converts a scoped effect into a regular effect by managing the scope:

const runnable = Effect.scoped(program);

The scope closes when the scoped block completes, triggering all finalizers.

acquireUseRelease Pattern

For simpler cases, combine acquire/use/release in one call:

const readFile = (path: string) =>
  Effect.acquireUseRelease(
    Effect.sync(() => fs.openSync(path, "r")),
    (fd) => Effect.sync(() => fs.readFileSync(fd, "utf-8")),
    (fd) => Effect.sync(() => fs.closeSync(fd)),
  );

Finalizers

Effect.addFinalizer

Add cleanup logic to the current scope:

const program = Effect.gen(function* () {
  yield* Effect.addFinalizer(() => Effect.log("Cleanup running!"));

  // ... do work ...

  return result;
});

Effect.ensuring

Run cleanup after effect completes (success or failure):

const withCleanup = someEffect.pipe(Effect.ensuring(Effect.log("Always runs after effect")));

Effect.onExit

Run different cleanup based on exit status:

const withExitHandler = someEffect.pipe(
  Effect.onExit((exit) => (Exit.isSuccess(exit) ? Effect.log("Succeeded!") : Effect.log("Failed or interrupted"))),
);

Multiple Resources

Sequential Acquisition

const program = Effect.gen(function* () {
  const db = yield* acquireDbConnection;
  const cache = yield* acquireRedisConnection;
});

const result = yield * Effect.scoped(program);

Parallel Acquisition

const program = Effect.gen(function* () {
  const [db, cache] = yield* Effect.all([acquireDbConnection, acquireRedisConnection]);
});

Resource Patterns

Database Connection Pool

const DbPool = Effect.acquireRelease(
  Effect.promise(() =>
    createPool({
      host: "localhost",
      database: "mydb",
      max: 10,
    }),
  ),
  (pool) => Effect.promise(() => pool.end()),
);

const query = (sql: string) =>
  Effect.gen(function* () {
    const pool = yield* DbPool;
    return yield* Effect.tryPromise(() => pool.query(sql));
  });

File Handle

const withFile = <A>(path: string, use: (handle: FileHandle) => Effect.Effect<A>) =>
  Effect.acquireUseRelease(
    Effect.promise(() => fs.promises.open(path)),
    use,
    (handle) => Effect.promise(() => handle.close()),
  );

Lock/Mutex

const withLock = <A>(lock: Lock, effect: Effect.Effect<A>) =>
  Effect.acquireUseRelease(
    lock.acquire,
    () => effect,
    () => lock.release,
  );

Layered Resources

Use Layer.scoped for service-level resources:

const DatabaseLive = Layer.scoped(
  Database,
  Effect.gen(function* () {
    const pool = yield* Effect.acquireRelease(createPool(), (pool) => Effect.promise(() => pool.end()));

    return {
      query: (sql) => Effect.tryPromise(() => pool.query(sql)),
    };
  }),
);

Error Handling in Cleanup

Finalizers should not fail, but if they do:

const safeRelease = (resource: Resource) =>
  Effect.sync(() => resource.close()).pipe(Effect.catchAll((error) => Effect.logError("Cleanup failed", error)));

const managed = Effect.acquireRelease(acquire, safeRelease);

Interruption Safety

Resources are cleaned up even on interruption:

const program = Effect.gen(function* () {
  const resource = yield* acquireResource;

  yield* Effect.sleep("1 hour");
});

const result = yield * program.pipe(Effect.scoped, Effect.timeout("1 second"));

Best Practices

1. Use acquireRelease for paired operations - Guarantees cleanup
2. Keep finalizers simple and infallible - Log errors instead of throwing
3. Use Effect.scoped at appropriate boundaries - Not too wide, not too narrow
4. Clean up in reverse acquisition order - Effect handles this automatically
5. Use Layer.scoped for service-level resources - Lifecycle tied to layer

Additional Resources

For comprehensive resource management documentation, consult ${CLAUDE_PLUGIN_ROOT}/references/llms-full.txt.

Search for these sections:

• "Introduction" (Resource Management) for core concepts
• "Scope" for detailed scope mechanics
• "Managing Layers" for Layer.scoped patterns