resources

What this skill does

# 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:

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

## Basic Resource Acquisition

### Effect.acquireRelease

The fundamental pattern for safe resource management:

```typescript
import { Effect } from "effect";

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

### Using the Resource

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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):

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

### Effect.onExit

Run different cleanup based on exit status:

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

## Multiple Resources

### Sequential Acquisition

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

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

### Parallel Acquisition

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

## Resource Patterns

### Database Connection Pool

```typescript
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

```typescript
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

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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