Skip to content
Request Local Storage for nodejs
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
jsdoc2md
test
.envrc
.eslintignore
.gitignore
.travis.yml
LICENSE
Makefile
README.md
index.js
jsdoc.json
middleware.js
package.json
shell.nix
shrinkwrap.yaml

README.md

view on npm Build Status js-standard-style

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

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
You can’t perform that action at this time.