DEV Community: typescript-guy

Catch the Silent Failures Your Vitest Suite is Missing

typescript-guy — Mon, 17 Aug 2026 23:24:59 +0000

Imagine a tax calculator that returns the correct final number, but silently skips the mandatory high-income audit step. Your standard black-box test passes with flying colors, but you now have a compliance violation.

Modern JavaScript testing rightly focuses on public outputs over line-by-line coverage. But for critical logic, verifying the final value isn't always enough. You need to verify the work performed to get there.

That’s the gap this article closes. We'll combine Vitest with fn-monitor to upgrade our tests from simple output assertions to deep internal behavior checks, ensuring the right code actually ran.

The project

Let's see this in action. The setup is deliberately minimal: two dependencies, one source file, one test file, and a handful of config lines. Create a folder (we'll call it vitest-with-monitor) with this structure:

vitest-with-monitor/
├── src/
│   └── index.ts
├── tests/
│   └── index.test.ts
├── .gitignore
├── vitest.config.ts
└── package.json

Setup

Install the two dependencies:

npm add -D vitest
npm add -D @typescript-guy/fn-monitor

Add node_modules to your .gitignore and write a minimal config:

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
    test: {
        include: ['tests/**/*.test.ts'],
    },
});

Add this script to your package.json:

"scripts": {
    "test": "vitest run"
}

Setup is done. In the next section, we'll write the code under test.

The Code Under Test

We're going to test a progressive tax calculator. It applies different rates across income brackets, but there's a compliance requirement: high-income earners must trigger an audit.

You don't have to stress about the details. For this article, all you need to know is that it must calculate the tax and satisfy the compliance requirement:

// src/index.ts

export function calculateTax(income: number): number {
    const lowThreshold = 1_000;
    const highThreshold = 5_000;

    const lowRate = 0.1;
    const averageRate = 0.2;
    const highRate = 0.3;


    const baseTax = 100; 
    const midBracketTax = 800; 

    let tax = 0;

    if (income <= lowThreshold) {
        tax = income * lowRate;
    } else if (income <= highThreshold) {
        tax = baseTax + (income - lowThreshold) * averageRate;
    } else {
        tax = baseTax + midBracketTax + (income - highThreshold) * highRate;
        triggerHighIncomeAudit(); 
    }
    return tax;
}
function triggerHighIncomeAudit(): void {
    console.log('High income audit triggered');
}

The Tests

The Black-box Test (The Blind Spot)

Let's write the test that we usually write when we want to assert that a function behaves correctly — a standard black-box test. Although it looks perfectly fine and passes with the correct code, it only asserts that the calculation is correct:

// tests/index.test.ts

import { test, expect } from 'vitest';
import { calculateTax } from '../src/index';

test('calculates correct tax for high income', () => {
    const income = 10_000;
    const expectedTax = 2_400;

    expect(calculateTax(income)).toBe(expectedTax);
});

The Upgraded Test

Next, we write another test using the same assertion as the black-box one but we will also inspect its AST using fn-monitor. It will assert that triggerHighIncomeAudit was actually called during execution.

For an overview, fn-monitor works by running functions through a JS-in-JS interpreter where it has full control of its execution. We import monitor, pass it our target function through an object, and get a new function that runs through the interpreter. The new function retains the call signature of the target.

Because the new function runs in a simulated environment, it will lose access to its lexical scope upon wrapping. The captures property gives the interpreter a function reference to bind to the triggerHighIncomeAudit identifier so it can execute without throwing a ReferenceError.

Together with our target function, we can also pass an inspector which is a first-class hook that can observe and control the AST mid-execution. For this test, we will use it to observe CallExpression nodes:

// tests/index.test.ts

//...Our other imports
//...Our black-box test

import { monitor } from '@typescript-guy/fn-monitor';

test('triggers compliance audit for high income', () => {
    const calls = new Set();
    const mockAudit = () => {};

    const monitoredCalculateTax = monitor({
        main: { 
            ref: calculateTax, // the function that we want to monitor
            captures: {
                triggerHighIncomeAudit: mockAudit
            }
        },
        inspector: (visit) => {
            visit.is('CallExpression', event => {
                const callee = event.node.callee;
                const scope = event.scope;

                if (callee.type !== "Identifier") return;

                const func = scope.variables.search(callee.name);
                calls.add(func);
            });
        }
    });
    // Output assertion
    expect(monitoredCalculateTax(10_000)).toBe(2_400);

    // Internal behavior assertion (The upgrade!)
    expect(calls).toContain(mockAudit);
});

If we run the tests now, both will pass.

Output

 ✓ tests/index.test.ts (2 tests) 63ms
   ✓ calculates correct tax for high income 12ms
   ✓ triggers compliance audit for high income 45ms

 Test Files  1 passed (1)
      Tests  2 passed (2)

💡 The loss of lexical access uncovers a hidden advantage of using fn-monitor for this test: triggerHighIncomeAudit does not need to be exported.

Traditional spies can't reach a private function without restructuring the code. With fn-monitor, you just pass a dummy function into captures — the interpreter only needs some binding for that name, as long as it respects the signature the code under test expects.

The "Gotcha" Moment (Breaking the Code)

Six months later, a well-meaning developer refactors calculateTax to clean up the math. They accidentally delete the audit call. The tax calculation function still returns the correct number but now you have a compliance violation.

export function calculateTax(income: number): number {
     // ... math ...
    } else {
        tax = baseTax + midBracketTax + (income - highThreshold) * highRate;
        // triggerHighIncomeAudit();
    }
    return tax;
}

When we run the tests, we will see that it is only the second test that catches the regression and fails:

Output

 ❯ tests/index.test.ts (2 tests | 1 failed) 51ms
   ✓ calculates correct tax for high income 6ms
   × triggers compliance audit for high income 40ms

FAIL  tests/index.test.ts > triggers compliance audit for high income
AssertionError: expected [] to include [Function mockAudit]
 ❯ tests/index.test.ts:46:19
     44|
     45|     // Internal behavior assertion (The upgrade!)
     46|     expect(calls).toContain(mockAudit);
       |                   ^
     47| });

When to Use This

The upgraded test caught a compliance violation that the first one missed — but we paid for it with extra code and execution overhead. That's the tradeoff for internal behavior assertions, but they catch a different class of bugs.

Use them when:

Silent failures are unacceptable — compliance rules, financial calculations, security checks
Side effects matter — logging, analytics, cache invalidation, audit trails
Output alone doesn't tell the whole story — the same return value could come from correct or incorrect internal work

For most tests, output assertions are enough. They're fast, they survive refactors, and they catch the majority of regressions. But for the 5% of your code where a green test on the wrong behavior is a real problem, fn-monitor gives you the observability to assert on the work, not just the output.

Next Steps

The code for this article is available in the vitest-with-monitor repository. Clone it, run npm install and npm test, and see the difference between the black-box and upgraded tests yourself.

If you had any trouble following along, spotted a typo, or just want to show off a unique use case you built with fn-monitor, feel free to open a discussion on GitHub.

And if you're interested in using fn-monitor in your own projects, check out the main repository for the full documentation.

Stop a Function Call From Hanging the Main Thread Without Using Web Workers

typescript-guy — Fri, 07 Aug 2026 11:17:22 +0000

In JavaScript, non-blocking execution is the de facto standard to stop a function call from hanging the main thread. It is typically achieved by offloading heavy work to a Web Worker or breaking the task into smaller chunks using setTimeout, queueMicrotask or a generator.

While these solutions work, they usually require you to change how you call or implement your functions. Today, we will address these limitations by approaching the problem differently using @typescript-guy/fn-monitor.

Before we start this article, let us get a quick overview of the package:

It is an instrumentation layer over a JS-in-JS interpreter that lets you monitor a function's execution at the AST level
It allows you to plug in hooks to observe and mutate a function's behavior at runtime while remaining on the same thread
It works for both synchronous and asynchronous functions.

If you ever want to dive deeper into its fundamentals, you can read the first article

To try this out locally, you can install the package from npm:

npm install @typescript-guy/fn-monitor

Making our timeout function

To begin, let us first write out our imports and custom types:

import { monitor, type Metadata } from "@typescript-guy/fn-monitor";

type milliseconds = number;
type Fn = (...args:any[])=>any

As a quick introduction to the package's API, its main export is a function called monitor, which takes a function through an object and returns a new function that runs in the custom interpreter while preserving the original function's call signature.

Let's define our timeout function and name it timeFn. It is quite long, but all you need to know is that it takes in a function along with its budget, and uses monitor() to create a new function injected with hooks to check against the budget as it executes:

function timeFn<T extends Fn>(fn:T,budget:milliseconds):T {
    //We create a grace period to account for floating point errors in performance.now()
    const graceTime = 0.5 as milliseconds;

    //A snapshot of roughly the exact millisecond the function was called
    let startTime = 0 as milliseconds;

    //A volatile variable that continuously tracks how much time the function has used
    let usedTime = 0 as milliseconds;

    //A buffer to prevent us from checking performance.now() for every single interpreted step which will hurt its performance
    let step = 0;

    //This is a function that implements our budget tracking
    const checkBudget = ()=>{
        //UsedTime is calculated as the difference between the currentTime and the time as when the function was called
        const currentTime = performance.now();
        usedTime = (currentTime - startTime);

        const timeIsUp = usedTime > (budget + graceTime)
        if (timeIsUp) {
            throw new Error(`The monitored function used ${usedTime.toFixed(3)}ms when only given a budget of ${budget.toFixed(3)}ms.`);
        };
    };

    //The monitored function that we will return to the caller
    const monitoredFn = monitor({
        main:{
            ref:fn,
        },

        //From the name, this will run before each call to our monitored function
        beforeEachCall: () => {
            startTime = performance.now()
            usedTime = 0;
            step = 0;
        },

        onStep:() => {
            step += 1;

            //Only check the budget every 1024 steps since performance.now is heavy
            //we use a bitwise operator here to be fast
            const shouldCheckBudget = (step & 1023) === 0;
            if (shouldCheckBudget) checkBudget();
        },

        //From the name, this will run after each call to our monitored function
        afterEachCall:(result)=>{

            //if the result is an error, we let the interpreter bubble it up rather than checking the budget
            if (!(result instanceof Error)) {
                //in case the function doesn't use up to the number of steps required to check the budget, we check the budget here to be accurate and safe
                checkBudget();
            }
        }
    });
    return monitoredFn
};

Our custom timeout uses the onStep hook instead of the inspector. You can learn more about the inspector later in the first article.

Although they are similar, they have their differences:

The onStep hook is fired before each interpreted step, while the inspector hook is fired as the interpreter walks the AST.
Unlike the inspector hook, it does not get the rich visit object which is used to observe and mutate AST nodes as the function executes.

The onStep hook is exactly what our timeout needs, and the monitored function will run much faster because it prevents the interpreter from making the extra allocations that the inspector hook would have required.

With that clarified, we can use timeFn on a function that gets the price of an item. But when the item is undefined, it will lag forever trying to fetch the price:

function getPrice(item?:string):number {
    if (!item) {
        while (true) {
            console.log('Lag');
        }
    }
    return 10; // we just return a constant number to keep it simple
}

Calling the bare getPrice function will hang our thread as expected:

getPrice();

Output

Lag
Lag
Lag
Lag
....

But if we call a timed version, it should throw an error.

const timedGetPrice = timeFn(getPrice,50);
timedGetPrice()

Output

Lag
Lag
Lag
Lag
Error: The monitored function used 53.961ms when only given a budget of 50.000ms.
...

Because we only check the budget every now and then, and because the interpreter steps off while the native JS engine executes the logs, the timeout isn't 100% accurate. And the exact millisecond it will halt is not deterministic.

But if we are being pragmatic, it is far better to lose a few milliseconds than to hang our main thread.

Our custom timeout works great for simple cases, but real-world functions rarely exist in isolation. If that function uses external variables, you have to ensure that you capture them as stated in the README.

We'll address this in a scenario where a timed function needs to call another function.

Capturing vs Embedding Functions

Assuming that we have a function that calls another function:

function getDetails(item?:string):{id?:string,price:number} {
    return {
        id:'id_' + item,
        price:getPrice(item)
    }
}

If we proceed to create a timed version and attempt to call it, it will crash and we will get a ReferenceError:

const timedGetDetails = timeFn(getDetails,50);
timedGetDetails()

Output

ReferenceError: 
getPrice is not defined

-Monitored functions cannot access variables from the outside.
-They must either be passed as an argument on each call or captured/embedded upon creation.

To solve this, we will have to extend timeFn to accept a captures object and include it in the interpreter's context:

function timeFn<T extends Fn>(fn:T,budget:milliseconds,captures?:Record<string,any>):T {
    //...Variable declarations and checkBudget implementation

    const monitoredFn = monitor({
        main:{
            ref:fn,
            captures
        },
        //...Other properties
    });
    return monitoredFn
}

If we now setup the timedGetDetails function with its captures and call it, we will bypass the error but we will run into another problem:

const timedGetDetails = timeFn(getDetails,50,{
    getPrice
});
timedGetDetails()

Because it is captured, calling it will make it run in the native JS engine and hang our main thread.

Output

Lag
Lag
Lag
Lag
....

One way to solve this is to force it to use the timedGetPrice function by using it in the captures:

const timedGetDetails = timeFn(getDetails,50,{
    getPrice:timedGetPrice
});
timedGetDetails()

When we run it, we expect timeFn to work as usual and halt it.

Output

Lag
Lag
Lag
Lag
Error: The monitored function used 58.440ms when only given a budget of 50.000ms.
...

This solves our immediate problem because not only does it allow the timedGetDetails function to call an external function without having to change its original source code, but it also allows us to put it under a strict budget.

The problem with this approach, though, is that it forces us to time every single function that our timed function will call and it makes the timer fragmented — one for the outer function and one for the captured one. We can solve these problems with a more streamlined solution.

What is Embedding?

In contrast to capturing, which works for all data types and simply gives the interpreter direct references/values, embedding is exclusive to function references and it tells the interpreter to copy its source code into the same context as our monitored function and parse it together.

This allows the onStep hook for the timedGetDetails function alone to contain the entire execution under a strict budget.

This will require us to extend timeFn. We will pack both the captures and embed configurations into a single object to make it neat.


interface ExternalData {
    captures?:Record<string,any>,
    embed?:Record<string,Metadata<Fn>>
};

function timeFn<T extends Fn>(fn:T,budget:milliseconds,external?:ExternalData):T {
    //...Variable declarations and checkBudget implementation

    const monitoredFn = monitor({
        main:{
            ref:fn,
            captures:external?.captures
        },
        embed:external?.embed,
        //...Other properties
    })
    return monitoredFn
}

Then we can time our function like this:

const timedGetDetails = timeFn(getDetails,50,{
    //The embed property has the same configuration structure as 'main' in the object passed to monitor()
    embed:{
        getPrice:{
            ref:getPrice
        }
    }
});

Then when we call it, it runs under our budget:

timedGetDetails()

Output

Lag
Lag
Lag
Lag
Error: The monitored function used 58.161ms when only given a budget of 50.000ms.
...

Peeking at the generated code (only when you need it)

So far, how the values are captured or embedded has been treated as a black box.

But if a captured or embedded function ever behaves unexpectedly, you don't have to guess — you can
read the exact code the interpreter runs by passing an object to the sourceOut property when calling monitor.

Let us quickly add that to timeFn and extend our interface:

interface ExternalData {
    //...Other properties
    sourceOut?:{value:string}//Add this to the interface
};

function timeFn<T extends Fn>(fn:T,budget:milliseconds,external?:ExternalData):T {
    //...Variable declarations and checkBudget implementation
    const monitoredFn = monitor({
       sourceOut:external?.sourceOut,
       //...Other properties
    })
    return monitoredFn
}

Then in the timedGetDetails function:

const generatedCode = { value: "" };

const timedGetDetails = timeFn(getDetails,50,{
    embed:{
        getPrice:{
            ref:getPrice
        }
    },
    sourceOut:generatedCode
});

The package overwrites the value property with the code executed by the interpreter.

The resulting code is crafted by a code generator that stitches together the injected captures and the source code of the embedded functions into a single string. The result isn't that pretty because it uses hashes to guarantee that the generated variables are collision-free.

The package ensures that the inspector and onStep hooks are only fired when executing
the actual logic of your functions and not the generated boilerplate.

When we run this, we will be able to see the generated code. We don't call timedGetDetails so that its output doesn't cut off the generated code from the logs:

console.log(generatedCode.value);
// timedGetDetails()

Output

Click to expand

'use strict'

const getDetails = (() => {

    const intermediateFn_generated_1de912009fe409ac0c51bb82c6c939ecad3227fe8d36ede3aae906089a513ade =
        function getDetails(item) {
            return {
                id:'id_' + item,
                price: getPrice(item)
            };
        };
    return intermediateFn_generated_1de912009fe409ac0c51bb82c6c939ecad3227fe8d36ede3aae906089a513ade;
})();

var getPrice;
getPrice = (() => {

    const getPrice = (() => {

        const intermediateFn_generated_8ce88bfc0fe7f0c48f18013aa0d9b67fdf80fbd257ce4526aaa8d0c33afbeb5c =
            function getPrice(item) {
                if (!item) {
                    while (true) {
                        console.log('Lag');
                    }
                }
                return 10;// we just return a constant number to keep it simple
            };
        return intermediateFn_generated_8ce88bfc0fe7f0c48f18013aa0d9b67fdf80fbd257ce4526aaa8d0c33afbeb5c;
    })();
    return getPrice;
})();

//This is the code that is ran each time the monitored function is called and the result is returned through the exports variable.

exports.generated_f6a214f7a5fcda0c2cee9660b7fc29f5649e3c68aad48e20e950137c98913a68 = getDetails(...generated_090772cf4068973daad3f715eb788d39fe2c02be42efd86de81f0e59198d6237);

💡 The exact format of the generated code may change between versions but the package ensures that it will not affect the behavior of your functions.

Conclusion

Because JavaScript is single-threaded, any code running on the main thread must finish completely before your browser can update the UI or before your server can respond to user requests, meaning that there is no seamless, single-thread solution to stop a function call from hanging the application.

This package, although providing a single-threaded solution, is not free in terms of performance. But if guaranteeing a function halts outweighs any performance overhead or if you're working in an environment that can't spawn workers — then this package is worth considering.

If you had any trouble following along, spotted a typo, or just want to show off a unique use case you built with fn-monitor, feel free to open a discussion on GitHub.

And if you're interested in using fn-monitor in your own projects, check out the main repository for the full documentation.

Rewrite JavaScript Behavior at Runtime with AST Mutation, From the Same Thread

typescript-guy — Mon, 03 Aug 2026 19:49:03 +0000

I've spent the last few months building an open-source package called @typescript-guy/fn-monitor.

This post walks through the package and how to rewrite a function's behavior at runtime, from the same thread — no build step, no workers, no message serialization.

In JavaScript, functions are fixed units. You define one, call it, and the code inside runs exactly as written. You can wrap it, monkey-patch dependencies, or use proxies around objects, but actually changing what happens inside the function usually requires one of these:

rewriting the source code
using a build-time transformation
running code in a worker or sandbox
manually patching every internal call site

fn-monitor offers a different approach.

It lets you execute a function through a JS-in-JS interpreter, and gives you hooks into the function’s AST while it executes.

That means you can do things like:

intercept specific AST nodes
inspect evaluated values
mutate operators
change returned results

To try this out locally, you can install the package from npm:

npm install @typescript-guy/fn-monitor

How to Wrap a Function in an Interpreter Context

We will start by writing our import:

import { monitor } from "@typescript-guy/fn-monitor";

The core export is monitor.

You give it a function through an object, and it returns a new function with the same call signature that runs through the custom interpretation layer when called.

Wrapping a function is straightforward. You create and pass an object with the key, main, which is the config of the function that we want to wrap. We then pass the reference through the ref property under main:

const originalFn = ()=>{
    return 'Hello World'
}

const monitoredFn = monitor({
    main: {
        ref: originalFn
    }
})

We can call the monitoredFn and log the result:

console.log(monitoredFn());

Output

Hello World

To the caller, the raw function and the monitored version are structurally the same.

But under the hood, the wrapper:

reads the function's source code through the .toString() method
parses it
spins up an interpreter for it
and tells the interpreter to run the parsed code

Whenever you call it, it asks the interpreter to import your arguments, use them in a virtual function call, and return the result.

Simply running a function in an interpreter isn't the main benefit. Instead, we will see what we can do by attaching hooks such as:

beforeEachCall
afterEachCall
inspector

Mutating an Assignment Operator at Runtime

Let's build an example to demonstrate three important ideas and gradually extend it as we go:

intercepting AST nodes during execution
mutating execution behavior without changing the original source
capturing external variables into the interpreter context

First, let's define the function we want to wrap. It will take an array of numbers, sum all the elements and return the result:

const sumUp = (nums: number[]) => {
    let sum: number = 0;
    for (const num of nums) {
        sum += num;
    }
    return sum;
}

When we call this function as it is, we expect to get our result as usual:

console.log('Result: ',sumUp([1,2,3,4,5]));

Output

Result:  15

Now let's wrap it with monitor and use the inspector hook:

The inspector hook is fired as the interpreter walks the AST. The interpreter passes it a visit object that contains four methods but we will only use two for this example — visit.execute and visit.is .

Let's start with visit.is:

const monitoredSumUp = monitor({
    main: {
        ref: sumUp,
    },
    inspector: (visit) => {
        visit.is('AssignmentExpression', event => {
            event.node.operator = "-="; // silently change the operator
        });
    }
});

When we call it, we get a different result from sumUp

console.log('Result: ',monitoredSumUp([1,2,3,4,5]));

Output

Result:  -15

When we run it, we get -15 because our inspector used visit.is to query for an AssignmentExpression. When it matched, the interpreter fired the callback passed alongside the query with an event object. The object contains the matching AST node under its node property.

Originally in the source code, the assignment expression was this:

sum += num;

But when we ran the following line, we told it to change the operator right before it could execute the node.

event.node.operator = "-=";

We can extend our inspector to log each intermediate result by using visit.execute. It explicitly tells the interpreter to execute the node right now and return the result.

const monitoredSumUp = monitor({
    main: {
        ref: sumUp,
    },
    inspector: (visit) => {
        visit.is('AssignmentExpression', event => {
            event.node.operator = "-="; // silently change the operator
            console.log('intermediate result: ',visit.execute());
        });
    }
});

So when we call it with our arguments, we can see the logs:

console.log('Result: ',monitoredSumUp([1,2,3,4,5]));

Output

intermediate result:  -1
intermediate result:  -3
intermediate result:  -6
intermediate result:  -10
intermediate result:  -15
Result:  -15

Calling visit.execute within the inspector is optional. If omitted, the interpreter will execute the node after the hook finishes. And for safety reasons — to prevent silent, partial execution — you cannot stop a node from running unless you throw an error.

So if you detect wrong behaviour according to your custom rules, you can do this:

const sumWithNoLoops = monitor({
    main: {
        ref: sumUp,
    },
    inspector: (visit) => {
        visit.is('ForOfStatement',()=>{
            throw new Error('For of statements are not allowed.')
        })
    }
});

console.log('Result: ',sumWithNoLoops([1,2,3,4,5]));

Output

Error: For of statements are not allowed.

For logging purposes, we can also use the beforeEachCall and afterEachCall hooks.
beforeEachCall receives the arguments before the function is called while afterEachCall receives the result or an error after the function is called:

const monitoredSumUp = monitor({
    main: {
        ref: sumUp,
    },
    beforeEachCall:(nums)=>{
        console.log('Logging args: ',nums);
    },
    afterEachCall:(result)=>{
        console.log('Logging result: ',result);
    },
    //...Our inspector hook
});

When we call it we can see when they are called through the logs:

console.log('Result: ',monitoredSumUp([1,2,3,4,5]));

Output

Logging args:  [ 1, 2, 3, 4, 5 ]
intermediate result:  -1
intermediate result:  -3
intermediate result:  -6
intermediate result:  -10
intermediate result:  -15
Logging result:  -15
Result:  -15

Extending our Example by Modifying the Return Statement

We can add this query to our inspector hook to do two things:

modify the returned value
query the scope for the sum before mutating the result

const monitoredSumUp = monitor({
    main: {
        ref: sumUp,
    },
    inspector:(visit)=>{
        //...Our other query
        visit.is('ReturnStatement', event => {
            const result = visit.execute();
            const finalSum = event.scope.variables.search('sum');

            console.log('final sum: ', finalSum);
            result.RES = 'I CHANGED THE VALUE';
        });
    }
    //...Our other hooks
});

When we call it, the returned result is changed before it reaches the caller and the afterEachCall hook.

console.log('Result: ',monitoredSumUp([1,2,3,4,5]));

Output

Logging args:  [ 1, 2, 3, 4, 5 ]
intermediate result:  -1
intermediate result:  -3
intermediate result:  -6
intermediate result:  -10
intermediate result:  -15
final sum:  -15
Logging result:  I CHANGED THE VALUE
Result:  I CHANGED THE VALUE

Understanding how to search the scope

Let's look at this line:

const finalSum = event.scope.variables.search('sum');

Here, event.scope gives us a snapshot of the interpreted function’s scope at the point where the ReturnStatement is being handled.

For safety reasons, the scope cannot be mutated like the node through the visit object and thus, a snapshot is freshly allocated for the event.

This searches the scope chain for a variable named sum.

event.scope.variables.search('sum')

In this case, it finds the sum variable declared inside the monitored function:

let sum: number = 0;

By the time the return statement is reached, the loop has already finished executing, so sum holds the final interpreted value:

console.log('final sum: ', finalSum);

Output

final sum:  -15

At that moment, before we mutate the return value, the value inside the function scope and the value produced by the return statement are still the same.

Then we change the return result:

result.RES = 'I CHANGED THE VALUE';

Captures: bringing outside values into the interpreter context

If our sumUp function wasn't self-contained and used an outside variable, we will need a way to pass it into the interpreter's context, else we will get a reference error if we tried to call the monitoredSumUp function:

In this example above, sumUp uses zero, which lives outside the function.

const zero = 0;

const sumUp = (nums: number[]) => {
    let sum: number = zero;
    for (const num of nums) {
        sum += num;
    }
    return sum;
};
//...Our monitored function  setup
console.log('Result: ',monitoredSumUp([1,2,3,4,5]));

You'll see the error logged twice — once by afterEachCall and once by JavaScript's native error handling:

Output

Logging args:  [ 1, 2, 3, 4, 5 ]
Logging result:  ReferenceError: 
zero is not defined

-Monitored functions cannot access variables from the outside.
-They must either be passed as an argument on each call or captured/embedded upon creation.
...

ReferenceError: 
zero is not defined

-Monitored functions cannot access variables from the outside.
-They must either be passed as an argument on each call or captured/embedded upon creation.
...

To fix this, we can add a check:

const monitoredSumUp = monitor({
    main: {
        ref: sumUp,
    },
    afterEachCall:(result)=>{
        if (!(result instanceof Error)) {
            console.log('Logging result: ',result);
        }
    },
    //...Our other hooks
})

So we can address the error by extending the monitoredSumUp configuration to capture it. We map the name zero to the actual value from the surrounding JavaScript environment.

const monitoredSumUp = monitor({
    main: {
        ref: sumUp,
        captures:{
            zero
        }
    },
    //...Our other hooks
})

When we then call it, it will run as expected:

console.log('Result: ',monitoredSumUp([1,2,3,4,5]));

Output

Logging args:  [ 1, 2, 3, 4, 5 ]
intermediate result:  -1
intermediate result:  -3
intermediate result:  -6
intermediate result:  -10
intermediate result:  -15
final sum:  -15
Logging result:  I CHANGED THE VALUE
Result:  I CHANGED THE VALUE

The Full Example

Here's the complete example:

import { monitor } from "@typescript-guy/fn-monitor"

const zero = 0;

const sumUp = (nums: number[]) => {
    let sum: number = zero;
    for (const num of nums) {
        sum += num;
    }
    return sum;
};

const monitoredSumUp = monitor({
    main: {
        ref: sumUp,
        captures:{
            zero
        }
    },
    beforeEachCall:(nums)=>{
        console.log('Logging args: ',nums);
    },
    afterEachCall:(result)=>{
        if (!(result instanceof Error)) {
            console.log('Logging result: ',result);
        }
    },
    inspector: (visit) => {
        visit.is('AssignmentExpression', event => {
            event.node.operator = "-="; // silently change the operator
            console.log('intermediate result: ',visit.execute());
        });

        visit.is('ReturnStatement', event => {
            const result = visit.execute();
            const finalSum = event.scope.variables.search('sum');

            console.log('final sum: ', finalSum);
            result.RES = 'I CHANGED THE VALUE';
        });
    }
});

console.log('Result: ',monitoredSumUp([1,2,3,4,5]));

Important caveats:

ES Support

You can use any function with the interpreter as long as it uses ES2024 syntax or earlier.

`visit.is` is eager

One thing worth understanding early is that visit.is(...) does not keep your callback as a persistent hook.

From the README, it eagerly evaluates the query against the current node. If it matches, it allocates a scope, wraps it with the node in an event object, and fires the callback. If it doesn't, it discards the callback.

That design choice is intentional. It keeps the interpreter fast and memory efficient by avoiding the bloat of book-keeping closures in memory.

AST mutations persist

From the README, the function is parsed into an AST only once. This means that any mutations made to an AST node within the inspector hook will persist and affect all subsequent calls to that function.

That can be powerful if you want a persistent runtime transformation but it can also surprise you if you expected the mutation to apply only to one call.

If the interpreter were to parse it on every call, it would be too slow for practical use.

What this package is good for

This kind of tool is especially interesting if you are building something like:

experimentation tools
runtime transformations
execution visualizers
teaching tools
instrumentation layers
advanced testing utilities
controlled evaluation pipelines
custom function wrappers

What this package is not

Even though the package lexically isolates monitored functions, it is not a secure sandbox by default, as explicitly stated in the README.

You can build stricter execution boundaries using hooks, but it does not secure the host from malicious code.

Key limitations to keep in mind

fn-monitor is a powerful tool, but it is not a one-size-fits-all solution. Here are the most critical constraints to be aware of:

Setup Cost: monitor() incurs overhead. Always call it once outside of hot loops and reuse the returned function.
No Dynamic Imports: You cannot use import() inside monitored functions. Use captures instead.
Stack Traces: Errors thrown inside monitored functions won't map directly to your original source lines in your editor.
Advanced Nuances: For edge cases like native generators and complex library proxies, please refer to the Advanced Behavior section of the README.

The right mental model for this package

Despite its name, the package is a runtime execution layer rather than a metric tool.

Instead of asking:

"What did this function return?"
"How long did it run for?"

you can ask:

"What AST nodes executed?"
"Can I intercept them?"
"Can I inspect their results?"
"Can I inspect the scope around them?"
"Can I change their behavior while they run?"

Final thoughts

JavaScript usually gives you very little control over what happens inside a function once it starts executing.

This package changes that by running functions through an interpreter on the same JS thread and exposing hooks into the AST itself. This lets you do things that normally feel out of reach in ordinary runtime JavaScript.

It is not a secure sandbox, and it is not free in terms of performance. But as a tool for runtime introspection and programmatic control, it opens up a genuinely interesting space.

If you had any trouble following along, spotted a typo, or just want to show off a unique use case you built with fn-monitor, feel free to open a discussion on GitHub.

And if you're interested in using fn-monitor in your own projects, check out the main repository for the full documentation.

DEV Community: typescript-guy

Catch the Silent Failures Your Vitest Suite is Missing

The project

Setup

The Code Under Test

The Tests

The Black-box Test (The Blind Spot)

The Upgraded Test

Output

The "Gotcha" Moment (Breaking the Code)

Output

When to Use This

Further Reading

Next Steps

Stop a Function Call From Hanging the Main Thread Without Using Web Workers

Making our timeout function

Output

Output

Capturing vs Embedding Functions

Output

Output

Output

What is Embedding?

Output

Peeking at the generated code (only when you need it)

Conclusion

Rewrite JavaScript Behavior at Runtime with AST Mutation, From the Same Thread

How to Wrap a Function in an Interpreter Context

Output

Mutating an Assignment Operator at Runtime

Output

Output

Output

Output

Output

Extending our Example by Modifying the Return Statement

Output

Understanding how to search the scope

Output

Captures: bringing outside values into the interpreter context

Output

Output

The Full Example

Important caveats:

ES Support

visit.is is eager

AST mutations persist

What this package is good for

What this package is not

Key limitations to keep in mind

The right mental model for this package

Final thoughts

`visit.is` is eager