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.
$ npm install node-rls
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
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')
})
})
- node-rls
- .NotInitializedError :
Error
- .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
- .NotInitializedError :
Kind: static class of node-rls
Thrown when context has not yet been initialized
Param | Type | Description |
---|---|---|
message | string |
Error message |
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)
})
Get object from storage.
Kind: static method of node-rls
Returns: Object
- Stored object
Throws:
NotInitializedError
Param | Type | Description |
---|---|---|
key | String |
Storage key |
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
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 |
Delete storage object
Kind: static method of node-rls
Returns: undefined
- Returns nothing
Throws:
NotInitializedError
Param | Type | Description |
---|---|---|
key | String |
Storage key |
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
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 |
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 |