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

| Param | Type | Description | | --- | --- | --- | | message | string | Error message |

node-rls.run(callback) ⇒ Object

Create a new context and run callback.

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

| Param | Type | Description | | --- | --- | --- | | callback | function | Async 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

| Param | Type | Description | | --- | --- | --- | | key | String | Storage key |

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

| Param | Type | Description | | --- | --- | --- | | key | String | Storage key | | value | Object | Storage key |

node-rls.delete(key) ⇒ undefined

Delete storage object

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

• NotInitializedError

| Param | Type | Description | | --- | --- | --- | | key | String | Storage key |

node-rls.update(obj) ⇒ undefined

Update storage from a map

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

• NotInitializedError

| Param | Type | Description | | --- | --- | --- | | obj | Object | KV mapping object |

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

| Param | Type | Description | | --- | --- | --- | | key | Object | Storage key | | count | Object | Increment by count |

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

Atomically decrement a counter

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

• NotInitializedError

| Param | Type | Description | | --- | --- | --- | | key | Object | Storage key | | count | Object | Decrement by count |