node-rls - Request Local Storage for nodejs

node-rls Is a library for attaching metadata to a nodejs call stack. It provides high-level key-value store style functions that are concurrency safe.

This can be extremely useful for logging where you want to attach metadata like request ids which you want to implicitly propagate to your logging function.

To accomplish this node-rls uses nodejs async hooks. For more information see node-continuation-local-storage and cls-hooked.

Installation

$ npm install node-rls

Usage

const RLS = require('./index.js')
 
async function main () {
  await RLS.set('foo', 'bar')
  return RLS.get('foo')
}
 
RLS.run(main).then(console.log).catch(err => {
  console.error(err)
  process.exit(1)
})

For more examples see the tests

Using as an express middleware

In this example we attach a request id to incoming requests

const RLSMiddleware = require('node-rls/middleware')
const RLS = require('node-rls')
const Express = require('express')
const UUID = require('uuid')
 
const app = Express()
 
// Initialize the context
app.use(RLSMiddleware.express)
 
// Attach the requestid to the request
app.use((req, res, next) => {
  const requestid = UUID.v4()
  RLS.set('requestid', requestid)
    .then(() => next())
  })
 
// Create an endpoint returning the request id
app.get('/', async function (req, res) {
  res.status(200).json({
    'requestid': await RLS.get('requestid')
  })
})

API Reference

• node-rls
  • .NotInitializedError : Error
    • new NotInitializedError(message)
  • .run(callback) ⇒ Object
  • .get(key) ⇒ Object
  • .copy() ⇒ Object
  • .set(key, value) ⇒ undefined
  • .delete(key) ⇒ undefined
  • .update(obj) ⇒ undefined
  • .incr(key, count) ⇒ Number
  • .decr(key, count) ⇒ Number

node-rls.NotInitializedError : Error

Kind: static class of node-rls

new NotInitializedError(message)

Thrown when context has not yet been initialized

node-rls.run(callback) ⇒ Object

Create a new context and run callback.

Kind: static method of node-rls
Returns: Object - Result from callback

Example

// Any called function will have access to conext
// even async ones
 
function func () {
  return RLS.get('requestid')
}
 
RLS.run(async () => {
  const requestid = 'somerandomvalue'
  await RLS.set('requestid', requestid)
 
  assert.strictEqual(await func(), requestid)
})

node-rls.get(key) ⇒ Object

Get object from storage.

Kind: static method of node-rls
Returns: Object - Stored object
Throws:

• NotInitializedError

node-rls.copy() ⇒ Object

Get KV store as a javascript object Mutating this object will NOT mutate the KV store

Kind: static method of node-rls
Returns: Object - Shallow copy of KV store
Throws:

• NotInitializedError

node-rls.set(key, value) ⇒ undefined

Set storage object

Kind: static method of node-rls
Returns: undefined - Returns nothing
Throws:

• NotInitializedError

node-rls.delete(key) ⇒ undefined

Delete storage object

Kind: static method of node-rls
Returns: undefined - Returns nothing
Throws:

• NotInitializedError

node-rls.update(obj) ⇒ undefined

Update storage from a map

Kind: static method of node-rls
Returns: undefined - No return value
Throws:

• NotInitializedError

Example

// Update storage with all values from object
const obj = {foo: 'bar', someKey: 'someValue'}
await update(obj)
console.log(await get('foo'))  // Prints bar

node-rls.incr(key, count) ⇒ Number

Atomically increment a counter

Kind: static method of node-rls
Returns: Number - Counter after increment
Throws:

• NotInitializedError

node-rls.decr(key, count) ⇒ Number

Atomically decrement a counter

Kind: static method of node-rls
Returns: Number - Counter after decrement
Throws:

• NotInitializedError