manage-hierarchical-resources

description: Use nested Scopes to manage resources with parent-child dependencies. globs: "**/*.ts" alwaysApply: true

Manage Hierarchical Resources

Rule: Use nested Scopes to manage resources with parent-child dependencies.

Example

import { Effect, Scope, Exit } from "effect"

// ============================================
// 1. Define hierarchical resources
// ============================================

interface Database {
  readonly name: string
  readonly createConnection: () => Effect.Effect<Connection, never, Scope.Scope>
}

interface Connection {
  readonly id: string
  readonly database: string
  readonly beginTransaction: () => Effect.Effect<Transaction, never, Scope.Scope>
}

interface Transaction {
  readonly id: string
  readonly connectionId: string
  readonly execute: (sql: string) => Effect.Effect<void>
}

// ============================================
// 2. Create resources with proper lifecycle
// ============================================

const makeDatabase = (name: string): Effect.Effect<Database, never, Scope.Scope> =>
  Effect.acquireRelease(
    Effect.gen(function* () {
      yield* Effect.log(`Opening database: ${name}`)
      
      const db: Database = {
        name,
        createConnection: () => makeConnection(name),
      }
      
      return db
    }),
    (db) => Effect.log(`Closing database: ${db.name}`)
  )

const makeConnection = (dbName: string): Effect.Effect<Connection, never, Scope.Scope> =>
  Effect.acquireRelease(
    Effect.gen(function* () {
      const id = `conn-${crypto.randomUUID().slice(0, 8)}`
      yield* Effect.log(`  Opening connection: ${id} to ${dbName}`)
      
      const conn: Connection = {
        id,
        database: dbName,
        beginTransaction: () => makeTransaction(id),
      }
      
      return conn
    }),
    (conn) => Effect.log(`  Closing connection: ${conn.id}`)
  )

const makeTransaction = (connId: string): Effect.Effect<Transaction, never, Scope.Scope> =>
  Effect.acquireRelease(
    Effect.gen(function* () {
      const id = `tx-${crypto.randomUUID().slice(0, 8)}`
      yield* Effect.log(`    Beginning transaction: ${id}`)
      
      const tx: Transaction = {
        id,
        connectionId: connId,
        execute: (sql) => Effect.log(`      [${id}] ${sql}`),
      }
      
      return tx
    }),
    (tx) => Effect.log(`    Committing transaction: ${tx.id}`)
  )

// ============================================
// 3. Use hierarchical resources
// ============================================

const program = Effect.scoped(
  Effect.gen(function* () {
    yield* Effect.log("=== Starting hierarchical resource demo ===\n")
    
    // Level 1: Database
    const db = yield* makeDatabase("myapp")
    
    // Level 2: Connection (child of database)
    const conn = yield* db.createConnection()
    
    // Level 3: Transaction (child of connection)
    const tx = yield* conn.beginTransaction()
    
    // Use the transaction
    yield* tx.execute("INSERT INTO users (name) VALUES ('Alice')")
    yield* tx.execute("INSERT INTO users (name) VALUES ('Bob')")
    
    yield* Effect.log("\n=== Work complete, releasing resources ===\n")
    
    // Resources released in reverse order:
    // 1. Transaction committed
    // 2. Connection closed
    // 3. Database closed
  })
)

Effect.runPromise(program)

// ============================================
// 4. Multiple children at same level
// ============================================

const multipleConnections = Effect.scoped(
  Effect.gen(function* () {
    const db = yield* makeDatabase("myapp")
    
    // Create multiple connections
    const conn1 = yield* db.createConnection()
    const conn2 = yield* db.createConnection()
    
    // Each connection can have transactions
    const tx1 = yield* conn1.beginTransaction()
    const tx2 = yield* conn2.beginTransaction()
    
    // Use both transactions
    yield* Effect.all([
      tx1.execute("UPDATE table1 SET x = 1"),
      tx2.execute("UPDATE table2 SET y = 2"),
    ])
    
    // All released in proper order
  })
)