emartech/cls-adapter

Continuation Local Storage middleware for easier storage access inside function calls

@emartech/cls-adapter

A wrapper around the Continuation Local Storage library cls-hooked. Makes storing and retrieving of context dependent information easier. It acts as a thread aware storage.

When a value is set on the storage with a given key, that value will be available inside functions calls from the parent function.

Installation

npm install @emartech/cls-adapter

Usage

const Koa = require('koa');
const ClsAdapter = require('@emartech/cls-adapter');

const logWithStorage = (message) => {
  console.log(Object.assign({ message }, ClsAdapter.getContextStorage()));
};
const calculationResult = () => {
  logWithStorage(100);
};

const app = new Koa();
app.use(ClsAdapter.getKoaMiddleware());

app.use(async (ctx) => {
  ClsAdapter.setOnContext('customer_id', 1000);

  logWithStorage('works');
  // { message: 'works', request_id: 'd5caaa0e-b04e-4d94-bc88-3ed3b62dc94a' }
  
  calculationResult();
  // { message: 100, request_id: 'd5caaa0e-b04e-4d94-bc88-3ed3b62dc94a' }

  ctx.body = 'It works';
});

app.listen(3000);

API

ClsAdapter.getKoaMiddleware()

Returns a middleware function compatible with Koa that stores (or generates if missing) the request identifier from the header (X-Request-Id) and sets it on the storage as request_id.

const app = new Koa();
app.use(ClsAdapter.getKoaMiddleware());

app.use(async () => {
  ClsAdapter.getContextStorage();
  // { request_id: 'd5caaa0e-b04e-4d94-bc88-3ed3b62dc94a' }
});

ClsAdapter.getExpressMiddleware()

Returns a middleware function compatible with Express that stores (or generates if missing) the request identifier from the header (X-Request-Id) and sets it on the storage as request_id.

const app = express();
app.use(ClsAdapter.getExpressMiddleware());

app.use(() => {
  ClsAdapter.getContextStorage();
  // { request_id: 'd5caaa0e-b04e-4d94-bc88-3ed3b62dc94a' }
});

ClsAdapter.getContextStorage()

Returns the all the values set on the storage.

ClsAdapter.setOnContext(key, value)

Sets a key with a given value on the storage.

ClsAdapter.setOnContext('customer_id', 1);
ClsAdapter.setOnContext('application.customer.id', 11);

ClsAdapter.getContextStorage();
// { customer_id: 1, application: { customer: { id: 11 } } }

ClsAdapter.getRequestId()

Returns the the request identifier set on the storage. The identifiers key is request_id.

ClsAdapter.setOnContext('request_id', 'd5caaa0e-b04e-4d94-bc88-3ed3b62dc94a');
ClsAdapter.getRequestId();
// 'd5caaa0e-b04e-4d94-bc88-3ed3b62dc94a'

ClsAdapter.addContextStorageToInput()

Returns a function that extends the given object with the current storage.

ClsAdapter.setOnContext('customer_id', 1);

ClsAdapter.addContextStorageToInput()({ debug: true });
// { debug: true, customer_id: 1 }

ClsAdapter.addRequestIdToInput()

Returns a function that extends the given object with the request identifier set on the current storage.

ClsAdapter.setOnContext('request_id', 'd5caaa0e-b04e-4d94-bc88-3ed3b62dc94a');

ClsAdapter.addRequestIdToInput()({ debug: true });
// { debug: true, request_id: 'd5caaa0e-b04e-4d94-bc88-3ed3b62dc94a' }

cls-adapter's Issues

[rl-reuse_tool-2] Violation against OSS Rules of Play

A violation against the OSS Rules of Play has been detected.

Rule ID: rl-reuse_tool-2
Explanation: Does it have LICENSES directory with licenses? No

Find more information at: https://sap.github.io/fosstars-rating-core/oss_rules_of_play_rating.html

[rl-reuse_tool-3] Violation against OSS Rules of Play

A violation against the OSS Rules of Play has been detected.

Rule ID: rl-reuse_tool-3
Explanation: Is it registered in REUSE? No

Find more information at: https://sap.github.io/fosstars-rating-core/oss_rules_of_play_rating.html

[rl-reuse_tool-4] Violation against OSS Rules of Play

A violation against the OSS Rules of Play has been detected.

Rule ID: rl-reuse_tool-4
Explanation: Is it compliant with REUSE rules? No

Find more information at: https://sap.github.io/fosstars-rating-core/oss_rules_of_play_rating.html

[rl-assigned_teams-2] Violation against OSS Rules of Play

A violation against the OSS Rules of Play has been detected.

Rule ID: rl-assigned_teams-2
Explanation: Does it have an admin team on GitHub? No

Find more information at: https://sap.github.io/fosstars-rating-core/oss_rules_of_play_rating.html

The automated release is failing 🚨

🚨 The automated release from the master branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you could benefit from your bug fixes and new features.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can resolve this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here is some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

Invalid npm token.

The npm token configured in the NPM_TOKEN environment variable must be a valid token allowing to publish to the registry https://registry.npmjs.org/.

If you are using Two-Factor Authentication, make configure the auth-only level is supported. semantic-release cannot publish with the default auth-and-writes level.

Please make sure to set the NPM_TOKEN environment variable in your CI with the exact value of the npm token.

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

Compatibility with koa-logger

koa-logger is a Koa middleware that calls a user supplied callback at the start and end of requests, so as to print information such as latency, status code, etc.

When the callback is called at the beginning of the request we have access to the cls context. However, when we are called at the end this context is not there. This is because the callback is called in the context of a "finished" or "close" event on ctx.res. Relevant code.

I've made it work by altering the module code:

const namespace = cls.createNamespace();
res.once('finish', namespace.bind(onfinish));

Is there any way to do just from my app side?

[rl-assigned_teams-3] Violation against OSS Rules of Play

A violation against the OSS Rules of Play has been detected.

Rule ID: rl-assigned_teams-3
Explanation: Does it have enough admins on GitHub? No

Find more information at: https://sap.github.io/fosstars-rating-core/oss_rules_of_play_rating.html

Typescript declarations

I'm looking to use this adapter in one of my typescript projects.

Currently the library does nto have type declarations, here, or in the global DefinitelyTyped project.

I'm willing to put in the work to create typings for this project, and the best thing to do would be to include type declaration files in the repo itself.

If this is something you are open to i can look into generating the types and can raise a pull request with them. Alternatively i can submit them to the DefinitelyTyped project extnernaly.

[rl-reuse_tool-1] Violation against OSS Rules of Play

A violation against the OSS Rules of Play has been detected.

Rule ID: rl-reuse_tool-1
Explanation: Does README mention REUSE? No

Find more information at: https://sap.github.io/fosstars-rating-core/oss_rules_of_play_rating.html