Lifecycle

Teardown hooks are the only lifecycle hook in rvx. They can be used to run logic when the lifecycle context they have been registered in is disposed.

teardown

Register a hook to be called when the current lifecycle is disposed:

JSXNo Build

import { teardown } from "rvx";

const handle = setInterval(() => console.log("ping"), 1000);

teardown(() => {
    clearInterval(handle);
});

import { teardown } from "./rvx.js";

const handle = setInterval(() => console.log("ping"), 1000);

teardown(() => {
    clearInterval(handle);
});

Calling teardown outside of any functions listed below has no effect and "leaks" the teardown hook. When running tests, this behavior can be configured to log leaks or to throw an error.

capture

Capture teardown hooks during a function call:

JSXNo Build

import { capture, teardown } from "rvx";

const dispose = capture(() => {
    teardown(() => { ... });
});

dispose();

import { capture, teardown } from "./rvx.js";

const dispose = capture(() => {
    teardown(() => { ... });
});

dispose();

Teardown hooks are called in reverse registration order when the returned dispose function is called.

If the specified function throws an error, teardown hooks are called in reverse registration order and the error is re-thrown.

captureSelf

This is almost the same as capture and is meant for things that need to dispose themselves.

JSXNo Build

import { captureSelf, teardown } from "rvx";

captureSelf(dispose => {
    teardown(() => { ... });

    dispose();
});

import { captureSelf, teardown } from "./rvx.js";

captureSelf(dispose => {
    teardown(() => { ... });

    dispose();
});

Teardown hooks are called in reverse registration order when the dispose function is called.

When dispose is called while the callback is still running, it has no effect and will call teardown hooks immediately after the callback completes instead.

If the specified function throws an error, teardown hooks are called in reverse registration order and the error is re-thrown.

uncapture

To explicitly leak teardown hooks, the uncapture function can be used. Code running during the call has an infinitly long lifecycle.

JSXNo Build

import { uncapture } from "rvx";

uncapture(() => {
    // This has no effect here:
    teardown(() => { ... });
});

import { uncapture } from "./rvx.js";

uncapture(() => {
    // This has no effect here:
    teardown(() => { ... });
});

nocapture

There are some places where registering teardown hooks is very likely a mistake. E.g. inside of expressions. Trying to register teardown hooks during an nocapture call will throw an error:

JSXNo Build

import { nocapture } from "rvx";

nocapture(() => {
    // This will throw an error:
    teardown(() => { ... });
});

import { nocapture } from "./rvx.js";

nocapture(() => {
    // This will throw an error:
    teardown(() => { ... });
});

isolate

Run a function within an error isolation boundary.

• If an error is thrown, teardown hooks are immediately called in reverse registration order and the error is re-thrown.
• If no error is thrown, this behaves as if teardown hooks were registered in the outer context.

JSXNo Build

import { isolate } from "rvx";

isolate(() => {
    teardown(() => doSomeCleanup());
    throw new Error("something went wrong");
});

import { isolate } from "./rvx.js";

isolate(() => {
    teardown(() => doSomeCleanup());
    throw new Error("something went wrong");
});

Nesting

Calls to capture, captureSelf, uncapture, nocapture and isolate can be arbitrarily nested:

JSXNo Build

import { capture, captureSelf, uncapture, nocapture } from "rvx";

nocapture(() => {
    const dispose = capture(() => {
        // This works:
        teardown(() => { ... });
        uncapture(() => {
            // This is ignored:
            teardown(() => { ... });
        });
    });

    dispose();

    // This will fail:
    teardown({ ... });
});

import { capture, captureSelf, uncapture, nocapture } from "./rvx.js";

nocapture(() => {
    const dispose = capture(() => {
        // This works:
        teardown(() => { ... });
        uncapture(() => {
            // This is ignored:
            teardown(() => { ... });
        });
    });

    dispose();

    // This will fail:
    teardown({ ... });
});

Repetitive Disposal

By default, lifecycle hooks can be called multiple times and primitives like capture and captureSelf don't provide any logic for preventing multiple calls.

const dispose = capture(() => {
    teardown(() => {
        console.log("teardown");
    });
});

// This will call all registered hooks twice:
dispose();
dispose();

In general, teardown hooks should never cause any unintended behavior just because they are called multiple times. Preventing something from being called multiple times must be implemented manually.

Async Code

Capturing teardown hooks relies on the synchronous call stack and therefore only works partially with async code:

const dispose = capture(async () => {
    // This will be captured:
    teardown(() => { ... });

    await something;

    // This will be leaked:
    teardown(() => { ... });
});

In a test or development environment, you can configure how leaked teardown hooks behave.

To dispose things that are initialized later, you manually need to capture it's teardown hooks:

const dispose = capture(async () => {
    let disposed = false;
    let disposeLater: TeardownHook | undefined;

    teardown(() => {
        disposed = true;
        disposeLater?.();
    });

    await something;

    if (!disposed) {
        disposeLater = capture(() => {
            // Register some teardown hooks here...
        });
    }
});