Explicit Resource Management

Concise, clear implementations inspired by the TC39 Explicit Resource Management proposal, providing DisposableStack, AsyncDisposableStack, and SuppressedError.

Installation

npm install @jsxtools/explicit-resource-management

Usage

import { AsyncDisposableStack, DisposableStack } from "@jsxtools/explicit-resource-management";

// Sync disposal
const stack = new DisposableStack();

const file = stack.use({
	[Symbol.dispose]() {
		console.log("Closed example.txt");
	},
});
stack.defer(() => console.log("Cleanup complete"));

// Resources are disposed in reverse order
stack.dispose();

// Async disposal
const asyncStack = new AsyncDisposableStack();

const connection = asyncStack.use({
	async [Symbol.asyncDispose]() {
		console.log("Closed connection");
	},
});
asyncStack.defer(async () => console.log("Async cleanup complete"));

await asyncStack.disposeAsync();

API

DisposableStack

A stack-based container for synchronous disposable resources.

Methods

• use<T>(value: T): T - Adds a disposable resource (with Symbol.dispose) to the stack
• adopt<T>(value: T, onDispose: (value: T) => void): T - Adds a non-disposable resource with a cleanup callback
• defer(onDispose: () => void): void - Adds a cleanup callback to be called on disposal
• move(): DisposableStack - Moves all resources to a new stack and marks this one as disposed
• dispose(): void - Disposes all resources in reverse order

Properties

• disposed: boolean - Whether the stack has been disposed

AsyncDisposableStack

A stack-based container for asynchronous disposable resources.

Methods

• use<T>(value: T): T - Adds a disposable resource (with Symbol.asyncDispose or Symbol.dispose)
• adopt<T>(value: T, onDisposeAsync: (value: T) => Promise<void>): T - Adds a resource with async cleanup
• defer(onDisposeAsync: () => Promise<void>): void - Adds an async cleanup callback
• move(): AsyncDisposableStack - Moves all resources to a new stack
• disposeAsync(): Promise<void> - Disposes all resources asynchronously in reverse order

Properties

• disposed: boolean - Whether the stack has been disposed

SuppressedError

An error type used to chain multiple errors that occur during resource disposal.

const error = new SuppressedError(new Error("disposal error"), new Error("suppressed error"), "optional message");

console.log(error.error); // Error: disposal error
console.log(error.suppressed); // Error: suppressed error

Features

• ✅ Implementations of DisposableStack and AsyncDisposableStack
• ✅ Proper error aggregation with SuppressedError
• ✅ TypeScript support with full type definitions
• ✅ Zero runtime dependencies
• ✅ Concise, readable implementation (~230 lines total)

Requirements

This package assumes Symbol.dispose and Symbol.asyncDispose are already available in your environment. If they are not, polyfill them first:

Symbol.dispose ??= Symbol("Symbol.dispose");
Symbol.asyncDispose ??= Symbol("Symbol.asyncDispose");

License

MIT-0