Resource Finalizer

Deterministic cleanup helpers for TypeScript/JavaScript based on ECMAScript Explicit Resource Management (using / await using) and DisposableStack.

The package provides two base classes:

• Destructor — synchronous cleanup
• AsyncDestructor — asynchronous cleanup

And two ready-to-use scope guards:

• ScopeGuard — run a callback on scope exit (sync)
• AsyncScopeGuard — run an async callback on scope exit (async)

When an instance is disposed, all destructors declared in the class inheritance chain are invoked automatically (from the most-derived class to the base class).

Features

• ✅ Works with using / await using (and manual Symbol.dispose / Symbol.asyncDispose calls)
• ✅ Automatic destructor chaining across inheritance (C -> B -> A)
• ✅ Built-in DisposableStack / AsyncDisposableStack (via the disposablestack polyfill)
• ✅ Scope guards for ad-hoc cleanup (ScopeGuard / AsyncScopeGuard)
• ✅ Small API surface, TypeScript-first typings

Install

npm install resource-finalizer

Requirements

• TypeScript: enable the disposable APIs in your tsconfig.json:

{
  "compilerOptions": {
    "lib": ["ES2022", "ESNext.Disposable"]
  }
}

• Runtime: this library imports disposablestack/auto internally to ensure DisposableStack / AsyncDisposableStack exist on globalThis.

using / await using are part of the Explicit Resource Management proposal and require TypeScript (or a runtime) that understands this syntax.

Quick start (sync)

import { Symbols, Destructor } from 'resource-finalizer';

class A extends Destructor {
  public constructor() {
    super();
    console.log('[A] constructor');
  }

  public [Symbols.destructor](): void {
    console.log('[A] destructor');
  }
}

class B extends A {
  public constructor() {
    super();
    console.log('[B] constructor');
  }

  public [Symbols.destructor](): void {
    console.log('[B] destructor');
  }
}

class C extends B {
  public constructor() {
    super();
    console.log('[C] constructor');
  }

  public [Symbols.destructor](): void {
    console.log('[C] destructor');
  }
}

{
  using instance = new C();
  console.log('End scope');
}

console.log('End code');

Expected order:

• constructors: A -> B -> C
• destructors (on scope exit): C -> B -> A

Quick start (async)

import { Symbols, AsyncDestructor } from 'resource-finalizer';

class A extends AsyncDestructor {
  public constructor() {
    super();
    console.log('[Async][A] constructor');
  }

  public async [Symbols.asyncDestructor](): Promise<void> {
    console.log('[Async][A] destructor');
  }
}

class B extends A {
  public constructor() {
    super();
    console.log('[Async][B] constructor');
  }

  public async [Symbols.asyncDestructor](): Promise<void> {
    console.log('[Async][B] destructor');
  }
}

class C extends B {
  public constructor() {
    super();
    console.log('[Async][C] constructor');
  }

  public async [Symbols.asyncDestructor](): Promise<void> {
    console.log('[Async][C] destructor');
  }
}

(async () => {
  {
    await using instance = new C();
    console.log('[Async] End scope');
  }

  console.log('[Async] End code');
})().catch(console.error);

Scope guards

If you only need “run this cleanup when the scope ends”, you don’t have to define a new class. Use ScopeGuard / AsyncScopeGuard — small wrappers around Destructor / AsyncDestructor that execute a user-provided finalizer when disposed.

Sync (ScopeGuard)

import { ScopeGuard } from 'resource-finalizer';

{
  using _ = new ScopeGuard(() => {
    console.log('cleanup runs on scope exit');
  });

  console.log('work');
}

console.log('after scope');

Async (AsyncScopeGuard)

import { AsyncScopeGuard } from 'resource-finalizer';
import { promises as fs } from 'node:fs';

async function demo() {
  const path = './tmp.txt';
  await fs.writeFile(path, 'hello');

  await using _ = new AsyncScopeGuard(async () => {
    await fs.rm(path, { force: true });
  });

  // use the file...
}

Without using / await using

import { ScopeGuard, AsyncScopeGuard } from 'resource-finalizer';

const g = new ScopeGuard(() => console.log('cleanup'));
try {
  // work...
} finally {
  g[Symbol.dispose]();
}

async function demoAsync() {
  const g = new AsyncScopeGuard(async () => console.log('async cleanup'));
  try {
    // work...
  } finally {
    await g[Symbol.asyncDispose]();
  }
}

Combine with DisposableStack

Because scope guards implement Disposable / AsyncDisposable, you can register them in a stack:

import { Symbols, Destructor, ScopeGuard } from 'resource-finalizer';

class Service extends Destructor {
  public constructor() {
    super();

    this[Symbols.disposableStack].use(
      new ScopeGuard(() => console.log('Service stopped'))
    );
  }

  public [Symbols.destructor](): void {
    // other cleanup...
  }
}

Without inheritance from Destructor / AsyncDestructor

import { Symbols, Destructible, createDisposableStack, callDestructorsChain } from 'resource-finalizer';

class SomeBaseClass {}

/**
 * We need to add destructor support to a class that is already a derived class.
 * To do this, you need to implement the following yourself
 *
 * - [Symbols.disposableStack]: DisposableStack;
 * - [Symbols.callDestructorsChain](): void;
 * - [Symbols.destructor](): void;
 * - [Symbol.dispose](): void;
 */
class A extends SomeBaseClass implements Destructible {
  public [Symbols.disposableStack] = createDisposableStack();

  public [Symbol.dispose](): void {
    this[Symbols.disposableStack].dispose();
  }

  public constructor() {
    super();

    this[Symbols.disposableStack].defer(() => {
      this[Symbols.callDestructorsChain]();
    });

    console.log('[A] constructor');
  }

  public [Symbols.callDestructorsChain](): void {
    callDestructorsChain(this);
  }

  public [Symbols.destructor](): void {
    console.log('[A] destructor');
  }
}

class B extends A {
  public constructor() {
    super();
    console.log('[B] constructor');
  }

  public [Symbols.destructor](): void {
    console.log('[B] destructor');
  }
}

class C extends B {
  public constructor() {
    super();
    console.log('[C] constructor');
  }

  public [Symbols.destructor](): void {
    console.log('[C] destructor');
  }
}

{
  using instance = new C();
  console.log('End scope');
}

console.log('End code');

Using the built-in stacks

Every Destructor instance owns a DisposableStack accessible via a symbol key:

import { Symbols, Destructor } from 'resource-finalizer';

class FileHandle extends Destructor {
  private fd: number;

  public constructor(fd: number) {
    super();
    this.fd = fd;

    // Register cleanup actions.
    this[Symbols.disposableStack].defer(() => {
      // close(fd)
    });
  }

  public [Symbols.destructor](): void {
    // Additional destructor logic (logging, metrics, invariants, etc.)
  }
}

For async cleanup, use AsyncDestructor and Symbols.asyncDisposableStack.

Important note about destructor chaining

The destructor chain is discovered by walking the prototype chain and calling destructors that are defined directly on each prototype.

That means:

• ✅ Define destructors as class methods: public [Symbols.destructor](){...}
• ❌ Don’t assign destructors as instance fields (e.g. this[Symbols.destructor] = () => {}), because they won’t be found by the chain walker.
• ❌ Don’t call super[Symbols.destructor]() manually — the base destructors are called automatically and you’d double-run them.

API

Symbols

A holder of unique symbols used as keys:

• Symbols.destructor
• Symbols.asyncDestructor
• Symbols.disposableStack
• Symbols.asyncDisposableStack
• Symbols.callDestructorsChain
• Symbols.asyncCallDestructorsChain

class Destructor

• Implements Disposable ([Symbol.dispose]())
• Provides an instance DisposableStack at this[Symbols.disposableStack]
• Requires you to implement public abstract [Symbols.destructor](): void

class AsyncDestructor

• Implements AsyncDisposable ([Symbol.asyncDispose]())
• Provides an instance AsyncDisposableStack at this[Symbols.asyncDisposableStack]
• Requires you to implement public abstract [Symbols.asyncDestructor](): Promise<void>

class ScopeGuard

• Extends Destructor
• Constructor: new ScopeGuard(() => void)
• Executes the finalizer on [Symbol.dispose]() / using scope exit

class AsyncScopeGuard

• Extends AsyncDestructor
• Constructor: new AsyncScopeGuard(() => Promise<void>)
• Executes the finalizer on [Symbol.asyncDispose]() / await using scope exit

Types

• Destructible
• AsyncDestructible

Stack re-exports

• DisposableStack
• AsyncDisposableStack

Utils

• createDisposableStack(): DisposableStack
• createAsyncDisposableStack(): AsyncDisposableStack
• callDestructorsChain(obj: object): void
• asyncCallDestructorsChain(obj: object): Promise<void>

License

MIT