1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

// Comprehensive cleanup method design
 
/**
 * Represents a resource that must be explicitly cleaned up.
 * 
 * ## Ownership
 * The creator of this resource is responsible for disposing it.
 * If ownership is transferred, document the transfer clearly.
 * 
 * ## Thread Safety
 * Individual methods are NOT thread-safe. Synchronize external access.
 * dispose() may be called from any thread.
 * 
 * ## Cleanup Behavior
 * dispose() releases all resources immediately. After dispose():
 * - All methods throw DisposedError
 * - Calling dispose() again is safe (no-op)
 * - Underlying connection is closed
 * 
 * ## Error Handling
 * dispose() swallows errors and logs them. Use flush() before
 * dispose() if you need to detect cleanup errors.
 */
interface DatabaseConnection {
    /**
     * Executes a query against the database.
     * @throws DisposedError if connection has been disposed
     * @throws QueryError if query execution fails
     */
    query<T>(sql: string, params?: unknown[]): Promise<T>;
 
    /**
     * Flushes any pending operations to the database.
     * Call this before dispose() if you need to detect flush errors.
     * @throws DisposedError if connection has been disposed
     * @throws FlushError if flush fails
     */
    flush(): Promise<void>;
 
    /**
     * Releases all resources held by this connection.
     * 
     * This method is idempotent - calling multiple times is safe.
     * After disposal, all other methods will throw DisposedError.
     * 
     * Errors during cleanup are logged but not thrown - disposal
     * should always "succeed" in the sense that the object is
     * marked as disposed, even if underlying cleanup has issues.
     */
    dispose(): Promise<void>;
 
    /**
     * Returns true if dispose() has been called.
     * Useful for conditional logic without try/catch.
     */
    readonly isDisposed: boolean;
}
 
// Implementation
class PostgresConnection implements DatabaseConnection {
    private _connection: Connection | null;
    private _disposed: boolean = false;
 
    constructor(connection: Connection) {
        this._connection = connection;
    }
 
    get isDisposed(): boolean {
        return this._disposed;
    }
 
    async query<T>(sql: string, params: unknown[] = []): Promise<T> {
        this.throwIfDisposed();  // Guard clause at method start
        return this._connection!.execute<T>(sql, params);
    }
 
    async flush(): Promise<void> {
        this.throwIfDisposed();
        await this._connection!.flush();  // May throw FlushError
    }
 
    async dispose(): Promise<void> {
        // Idempotent - second call does nothing
        if (this._disposed) {
            return;
        }
 
        // Mark disposed FIRST - prevents concurrent operations
        this._disposed = true;
 
        // Clean up resources - swallow errors, log them
        if (this._connection) {
            try {
                await this._connection.close();
            } catch (error) {
                console.error("Error closing connection during dispose:", error);
                // Don't re-throw - dispose should "succeed"
            } finally {
                this._connection = null;  // Clear reference
            }
        }
    }
 
    private throwIfDisposed(): void {
        if (this._disposed) {
            throw new DisposedError("Cannot use disposed connection");
        }
    }
}
 
// Custom error for disposed state
class DisposedError extends Error {
    constructor(message: string) {
        super(message);
        this.name = "DisposedError";
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

// The complete Dispose pattern with all components
 
public class CompositeResource : IDisposable
{
    // Resources this object owns
    private FileStream? _file;           // Managed disposable resource
    private IntPtr _nativeHandle;         // Unmanaged/native resource
    private SqlConnection? _database;     // Another managed disposable
    
    // Disposal state tracking
    private bool _disposed = false;
    
    // Thread safety for disposal
    private readonly object _disposeLock = new object();
    
    #if DEBUG
    // For leak detection in debug builds
    private readonly StackTrace _allocationStack;
    #endif
 
    public CompositeResource(string filePath, string connectionString, IntPtr handle)
    {
        #if DEBUG
        _allocationStack = new StackTrace(true);
        #endif
        
        // Acquire resources - if any fails, cleanup already-acquired ones
        try
        {
            _file = new FileStream(filePath, FileMode.OpenOrCreate);
            _nativeHandle = handle;
            _database = new SqlConnection(connectionString);
            _database.Open();
        }
        catch
        {
            // Cleanup any successfully acquired resources
            _file?.Dispose();
            if (_nativeHandle != IntPtr.Zero)
            {
                NativeRelease(_nativeHandle);
            }
            _database?.Dispose();
            throw;  // Re-throw - object creation failed
        }
    }
 
    // Public dispose method - what callers use
    public void Dispose()
    {
        Dispose(disposing: true);
        GC.SuppressFinalize(this);  // No need for finalizer now
    }
 
    // Protected dispose with disposing parameter
    // disposing = true: called from Dispose(), safe to touch managed objects
    // disposing = false: called from finalizer, managed objects may be already finalized
    protected virtual void Dispose(bool disposing)
    {
        // Thread-safe disposal check
        lock (_disposeLock)
        {
            if (_disposed)
            {
                return;  // Already disposed - idempotent
            }
            
            _disposed = true;
        }
 
        if (disposing)
        {
            // MANAGED RESOURCES - only touch these when disposing = true
            // These objects might already be finalized if we're in our finalizer
            
            SafeDispose(_file, "file stream");
            _file = null;
            
            SafeDispose(_database, "database connection");
            _database = null;
        }
 
        // UNMANAGED RESOURCES - always release these
        // Safe to do whether called from Dispose() or finalizer
        if (_nativeHandle != IntPtr.Zero)
        {
            try
            {
                NativeRelease(_nativeHandle);
            }
            catch (Exception ex)
            {
                Console.Error.WriteLine($"Error releasing native handle: {ex.Message}");
            }
            _nativeHandle = IntPtr.Zero;
        }
    }
 
    // Finalizer - safety net only, should never run in correct code
    ~CompositeResource()
    {
        // Log leak warning
        Console.Error.WriteLine("⚠️ RESOURCE LEAK: CompositeResource was not disposed!");
        
        #if DEBUG
        Console.Error.WriteLine($"Allocated at:\n{_allocationStack}");
        #endif
        
        // Best-effort cleanup - can only touch unmanaged resources
        Dispose(disposing: false);
    }
 
    // Helper method for safe disposal of managed resources
    private static void SafeDispose(IDisposable? resource, string resourceName)
    {
        if (resource == null) return;
        
        try
        {
            resource.Dispose();
        }
        catch (Exception ex)
        {
            Console.Error.WriteLine($"Error disposing {resourceName}: {ex.Message}");
            // Don't throw - continue disposing other resources
        }
    }
 
    // Methods that use resources guard against disposed state
    public void WriteData(byte[] data)
    {
        ThrowIfDisposed();
        _file!.Write(data, 0, data.Length);
    }
 
    public DataTable QueryDatabase(string sql)
    {
        ThrowIfDisposed();
        using var command = new SqlCommand(sql, _database);
        var adapter = new SqlDataAdapter(command);
        var result = new DataTable();
        adapter.Fill(result);
        return result;
    }
 
    private void ThrowIfDisposed()
    {
        if (_disposed)
        {
            throw new ObjectDisposedException(GetType().Name);
        }
    }
 
    // External native method (platform invoke)
    [DllImport("native.dll")]
    private static extern void NativeRelease(IntPtr handle);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

// Two-layer cleanup: fallible flush + infallible dispose
 
class BufferedFileWriter {
    private file: FileHandle | null;
    private buffer: Buffer[] = [];
    private disposed = false;
 
    constructor(path: string) {
        this.file = openFileSync(path, "w");
    }
 
    write(data: Buffer): void {
        this.throwIfDisposed();
        this.buffer.push(data);
    }
 
    /**
     * LAYER 1: Flush - fallible, caller handles errors
     * 
     * Call this when you need to ensure data is written
     * and want to handle write errors explicitly.
     */
    async flush(): Promise<void> {
        this.throwIfDisposed();
        
        if (this.buffer.length === 0) return;
        
        const data = Buffer.concat(this.buffer);
        
        // This can throw: disk full, permission error, etc.
        await this.file!.write(data);
        this.buffer = [];
    }
 
    /**
     * LAYER 2: Dispose - infallible, always completes
     * 
     * Releases all resources. Will attempt to flush
     * remaining buffer but won't fail if flush fails.
     */
    async dispose(): Promise<void> {
        if (this.disposed) return;
        this.disposed = true;
 
        // Best-effort flush - swallow errors
        if (this.buffer.length > 0 && this.file) {
            try {
                await this.file.write(Buffer.concat(this.buffer));
            } catch (error) {
                // Log but don't throw
                console.warn("Failed to flush buffer during dispose:", error);
            }
        }
        this.buffer = [];
 
        // Release file handle - swallow errors
        if (this.file) {
            try {
                await this.file.close();
            } catch (error) {
                console.warn("Failed to close file during dispose:", error);
            }
            this.file = null;
        }
    }
 
    private throwIfDisposed(): void {
        if (this.disposed) {
            throw new Error("Writer has been disposed");
        }
    }
}
 
// Usage patterns:
 
// Pattern A: Fire-and-forget - flush errors are ignored
async function writeAndForget(data: Buffer): Promise<void> {
    const writer = new BufferedFileWriter("/tmp/log.txt");
    try {
        writer.write(data);
        // No explicit flush - dispose will try to flush
    } finally {
        await writer.dispose();  // Always runs, might lose data silently
    }
}
 
// Pattern B: Careful write - flush errors are handled
async function writeCarefully(data: Buffer): Promise<void> {
    const writer = new BufferedFileWriter("/tmp/critical.txt");
    try {
        writer.write(data);
        await writer.flush();  // Throws if write fails - caller notified
    } catch (error) {
        console.error("Failed to write critical data:", error);
        throw error;  // Propagate to caller
    } finally {
        await writer.dispose();  // Still release resources
    }
}
 
// Pattern C: Different error handling for flush vs dispose
async function writeWithRetry(data: Buffer): Promise<void> {
    const writer = new BufferedFileWriter("/tmp/data.txt");
    let flushSucceeded = false;
    
    try {
        writer.write(data);
        
        // Retry flush failures
        for (let attempt = 0; attempt < 3; attempt++) {
            try {
                await writer.flush();
                flushSucceeded = true;
                break;
            } catch (error) {
                console.warn(`Flush attempt ${attempt + 1} failed:`, error);
                await sleep(100 * (attempt + 1));  // Backoff
            }
        }
        
        if (!flushSucceeded) {
            throw new Error("All flush attempts failed");
        }
    } finally {
        // Dispose doesn't retry - just release resources
        await writer.dispose();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

// Composite disposal with error aggregation
 
class DataProcessor {
    // Resources this object OWNS (created internally)
    private readonly tempFile: TempFile;
    private readonly cache: Cache;
    private readonly metrics: MetricsCollector;
    
    // Resource this object BORROWS (passed in, not owned)
    private readonly database: DatabaseConnection;
    
    private disposed = false;
 
    constructor(database: DatabaseConnection /* borrowed */) {
        // We don't own the database - caller is responsible for it
        this.database = database;
        
        // We own these - we create them, we dispose them
        this.tempFile = TempFile.create();
        this.cache = new Cache(1000);
        this.metrics = new MetricsCollector("processor");
    }
 
    async process(data: InputData): Promise<OutputData> {
        this.throwIfDisposed();
        
        // Use all resources
        const cached = await this.cache.get(data.id);
        if (cached) {
            this.metrics.increment("cache_hit");
            return cached;
        }
        
        const dbResult = await this.database.query(`SELECT * FROM ... WHERE id = ${data.id}`);
        await this.tempFile.write(dbResult);
        
        // ... processing ...
        
        const result = { /* ... */ } as OutputData;
        await this.cache.set(data.id, result);
        this.metrics.increment("processed");
        
        return result;
    }
 
    async dispose(): Promise<void> {
        if (this.disposed) return;
        this.disposed = true;
 
        const errors: Error[] = [];
 
        // Dispose OWNED resources in reverse order of acquisition
        
        // 3. Metrics (last acquired, first disposed)
        try {
            await this.metrics.shutdown();
        } catch (error) {
            errors.push(new Error(`Metrics disposal failed: ${(error as Error).message}`));
        }
 
        // 2. Cache
        try {
            await this.cache.clear();
        } catch (error) {
            errors.push(new Error(`Cache disposal failed: ${(error as Error).message}`));
        }
 
        // 1. Temp file (first acquired, last disposed)
        try {
            await this.tempFile.delete();
        } catch (error) {
            errors.push(new Error(`TempFile disposal failed: ${(error as Error).message}`));
        }
 
        // Note: We do NOT dispose this.database - we don't own it!
        // The caller is responsible for disposing the database connection.
 
        // Report aggregated errors
        if (errors.length > 0) {
            console.error(`DataProcessor disposal completed with ${errors.length} errors:`);
            errors.forEach(e => console.error(`  - ${e.message}`));
        }
    }
 
    private throwIfDisposed(): void {
        if (this.disposed) {
            throw new Error("DataProcessor has been disposed");
        }
    }
}
 
// Clear ownership at call site
async function processInBatch(items: InputData[]): Promise<OutputData[]> {
    // WE create and own the database connection
    const database = await DatabaseConnection.create("postgresql://...");
    
    try {
        // We pass it to processor, but we still own it
        const processor = new DataProcessor(database);
        
        try {
            const results: OutputData[] = [];
            for (const item of items) {
                results.push(await processor.process(item));
            }
            return results;
        } finally {
            // Processor is done, dispose it (doesn't touch database)
            await processor.dispose();
        }
    } finally {
        // WE dispose the database - we created it, we own it
        await database.dispose();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

// Comprehensive cleanup tests
 
describe("ConnectionPool", () => {
    let pool: ConnectionPool;
 
    afterEach(async () => {
        // Cleanup after each test
        if (pool) {
            await pool.dispose();
        }
    });
 
    // Test 1: Dispose releases all connections
    test("dispose releases all connections", async () => {
        pool = new ConnectionPool({ maxSize: 5 });
        
        // Acquire some connections
        const conn1 = await pool.acquire();
        const conn2 = await pool.acquire();
        await pool.release(conn1);
        await pool.release(conn2);
        
        // Get internal state before dispose
        expect(pool.activeConnections).toBe(0);
        expect(pool.pooledConnections).toBe(2);
        
        // Dispose
        await pool.dispose();
        
        // Verify all cleaned up
        expect(pool.activeConnections).toBe(0);
        expect(pool.pooledConnections).toBe(0);
        expect(pool.isDisposed).toBe(true);
    });
 
    // Test 2: Dispose is idempotent
    test("dispose can be called multiple times safely", async () => {
        pool = new ConnectionPool({ maxSize: 5 });
        
        // Call dispose multiple times
        await pool.dispose();
        await pool.dispose();  // Should not throw
        await pool.dispose();  // Should not throw
        
        expect(pool.isDisposed).toBe(true);
    });
 
    // Test 3: Operations throw after dispose
    test("operations throw after dispose", async () => {
        pool = new ConnectionPool({ maxSize: 5 });
        await pool.dispose();
        
        await expect(pool.acquire()).rejects.toThrow("disposed");
    });
 
    // Test 4: Dispose completes even with errors
    test("dispose completes even if individual releases fail", async () => {
        pool = new ConnectionPool({ maxSize: 5 });
        
        // Create a connection that will fail to close
        const badConn = {
            close: () => { throw new Error("Close failed!"); }
        };
        
        // Inject it into the pool (test helper method)
        pool._injectForTesting(badConn);
        
        // Dispose should complete (not throw)
        await expect(pool.dispose()).resolves.toBeUndefined();
        
        // Pool should be marked as disposed
        expect(pool.isDisposed).toBe(true);
    });
 
    // Test 5: Dispose with active connections
    test("dispose waits for or cancels active connections", async () => {
        pool = new ConnectionPool({ maxSize: 5, disposeTimeout: 1000 });
        
        const conn = await pool.acquire();
        // Connection is still 'active' (not released)
        
        // Dispose should handle this gracefully
        const disposePromise = pool.dispose();
        
        // Depending on implementation:
        // Option A: Dispose waits for release
        // Option B: Dispose force-closes after timeout
        // Option C: Dispose throws error
        
        await expect(disposePromise).resolves.toBeUndefined();
    });
 
    // Test 6: Resource leak detection
    test("detects resource leaks in debug mode", async () => {
        const consoleSpy = jest.spyOn(console, "error").mockImplementation();
        
        // Create resource without disposing
        const resource = new TrackedResource();
        
        // Simulate finalization (in test environment)
        (resource as any)._simulateFinalizer();
        
        // Should have logged a leak warning
        expect(consoleSpy).toHaveBeenCalledWith(
            expect.stringContaining("RESOURCE LEAK")
        );
        
        consoleSpy.mockRestore();
    });
});
 
// Test helper: Track created resources to detect leaks
class ResourceTracker {
    private static created = new Set<Disposable>();
    private static disposed = new Set<Disposable>();
 
    static track(resource: Disposable): void {
        this.created.add(resource);
    }
 
    static markDisposed(resource: Disposable): void {
        this.disposed.add(resource);
    }
 
    static checkForLeaks(): string[] {
        const leaks: string[] = [];
        for (const resource of this.created) {
            if (!this.disposed.has(resource)) {
                leaks.push(resource.constructor.name);
            }
        }
        return leaks;
    }
 
    static reset(): void {
        this.created.clear();
        this.disposed.clear();
    }
}
 
// Use in tests
afterEach(() => {
    const leaks = ResourceTracker.checkForLeaks();
    if (leaks.length > 0) {
        console.error("Resource leaks detected:", leaks);
    }
    ResourceTracker.reset();
});