stack-vars

A Node.js module for creating stack-like variable contexts using async hooks. Store and retrieve variables across async boundaries with full control over inheritance behavior.

Installation

npm install stack-vars

Quick Start

import stackVars from 'stack-vars';

var examle = () => {
    // Outputs 15
    console.log(stackVars().userId); 
}

// Start a new context
stackVars.init(() => {
    stackVar().userId = 15;

    setTimeout(() => {
        // Outputs 15
        console.log(stackVars().userId); 
        new Promise((res) => {
            example();
            res();
        })
    }, 1000);
})

// Is undefined
console.log(stackVars().userId); 

It can also create different contexts with different names:

// Creates "default"
stackVars.init(() => {
    stackVars.init('user', () => {
        stackVars().id = 15; // dets for "default"
        stackVars('user').id = 15; // sets for "user"
    })
})

How It Works

stack-vars uses Node.js async local storage to create execution contexts that persist across async operations. Variables set in one context are automatically available in nested async operations, making it perfect for request tracing, logging, and state management.
It is stable since node.js V13

Basic Usage

Setting and Getting Variables

Named Contexts

Create multiple isolated contexts within the same execution:

API Reference

stackVars.init()

Creates a new context

Parameters:
one of:

• cb (function): The function in which the context is available

or:

• name (string): The context name
• cb (function): The function in which the context is available

or:

• names (string[]): Array of context names to create
• cb (function): The function in which the contexts are available

or:

• properties (object): The context configuration
  • name (string|string[]): Context name(s) (default: "default")
• cb (function): The function in which the context(s) are available

Returns: a promise, resolving when the inner callback did resolve.

Examples:

// Single context
stackVars.init(() => {
    stackVars().value = 'test';
});

// Named context
stackVars.init('user', () => {
    stackVars('user').id = 123;
});

// Multiple contexts
stackVars.init(['auth', 'user', 'session'], () => {
    stackVars('auth').token = 'abc123';
    stackVars('user').id = 456;
    stackVars('session').expires = Date.now() + 3600000;
});

// Multiple contexts with object syntax
stackVars.init({name: ['auth', 'user']}, () => {
    stackVars('auth').token = 'abc123';
    stackVars('user').id = 456;
});

stackVars.has()

Check if a context exists

Parameters:

• contextName (string): The name of the context to check

Returns: boolean - True if the context exists, false otherwise

Examples:

// Check if default context exists
stackVars.init(() => {
    console.log(stackVars.has('default')); // true
    console.log(stackVars.has('user'));    // false
});

// Check if named context exists
stackVars.init('user', () => {
    console.log(stackVars.has('user'));    // true
    console.log(stackVars.has('auth'));    // false
});

// Check multiple contexts
stackVars.init(['auth', 'user'], () => {
    console.log(stackVars.has('auth'));    // true
    console.log(stackVars.has('user'));    // true
    console.log(stackVars.has('session')); // false
});

// Check outside of context
console.log(stackVars.has('default')); // false
console.log(stackVars.has('user'));    // false

// Invalid context names throw errors
try {
  stackVars.has(null); // throws "Context name must be a string"
} catch (error) {
  console.log(error.message);
}

Use Cases

Request Tracing

Example for express

import stackVars from 'stack-vars';

// Middleware to set request context
app.use((req, res, next) => {
    stackVars.init(() => {
        stackVars().requestId = req.headers['x-request-id'];
        stackVars().userId = req.user?.id;
        stackVars().startTime = Date.now();
        next();
    })
});

// Use in any route handler or service
app.get('/api/users', (req, res) => {
    const requestId = stackVars().requestId;
    const userId = stackVars().userId;
    
    // Log with context
    console.log(`[${requestId}] User ${userId} requested users list`);
    
    // Pass to services
    userService.getUsers().then(users => {
        console.log(`[${requestId}] Returning ${users.length} users`);
        res.json(users);
    });
});

Actual working examples

In /example there are two examples demonstating how to use stackVars() with express.

express-simple

Basicly just the code above

express-advanced

More detailed example using multiple files and contexts

License

MIT