# @g2a/request-id

> Library providing utility functions for manipulating and generating request ids

Latest version **1.3.0** (published 2020-10-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install @g2a/request-id
pnpm add @g2a/request-id
yarn add @g2a/request-id
bun add @g2a/request-id
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.0 |
| Published | 2020-10-22 |
| First published | 2019-09-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 19.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | wadrian12, gpolek, qzb |

## Links

- npm: https://www.npmjs.com/package/@g2a/request-id
- Repository: https://github.com/g2a-com/node-request-id
- Homepage: https://github.com/g2a-com/node-request-id#readme
- Issues: https://github.com/g2a-com/node-request-id/issues
- npm.io page: https://npm.io/package/@g2a/request-id

## Dependencies (1)

- [@types/node](https://npm.io/package/@types/node.md) ^10.0.0

## Recent versions

- 1.3.0 (latest) — 2020-10-22
- 1.2.0 — 2019-09-23

## README

# @g2a/request-id

[![npm][npm-image]][npm-url]

Library providing utility functions for manipulating and generating [Hierarchical Request IDs][hierarchical_request_id_standard].

## Installation

```shell
$ npm i @g2a/request-id
```

## Basic methods

The following methods are useful in everyday applications.

### `generateIncomingId()`

```ts
(baseId?: string) => string;
```

Generates an [incoming ID][incoming_id_description] based on a provided base ID.
If base ID is not provided or is invalid, generates it from scratch.

Use this function to generate a new ID based on one received in
the request from an external service. ID generated by this function should be
attached to all related log entries and should be used to create Outgoing IDs
assigned to all subsequential outgoing requests.

Example of use with Express.js:

```ts
const logger = new Logger();

// Generate new incoming id for each incoming request
app.use((req, res, next) => {
  res.locals.requestId = generateIncomingId(req.get("request-id"));
  next();
});

app.get("/some-endpoint", (req, res) => {
  // Attach previously generated id to log entries
  logger.trace({
    message: "Some very interesting message",
    requestId: res.locals.requestId
  });

  res.sendStatus(204);
});
```

### `generateOutgoingId()`

```ts
(id: string) => string;
```

Generates an [outgoing ID][outgoing_id_description] based on a provided base ID.
If base ID is not provided or is invalid, generates ID from scratch.

Use this function to generate unique ID each time you make a request to
any external service.

Example of use with:

```ts
app.post("/do-something", (req, res) => {
  // See how it's generated in the example to  the`generateIncomingId()` method
  const currentRequestId = res.locals.requestId;

  request.post({
    url: "http://some-external-service/api",
    headers: {
      "Request-Id": generateOutgoingId(currentRequestId)
    }
  });
});
```

## Advanced methods

Using the following methods requires a better understanding of the Hierarchical
Request Id format. These methods could be useful if you need to do some more
advanced manipulations on request IDs.

### `isValid()`

```ts
(id: string) => boolean;
```

Checks if the provided ID conforms to [Hierarchical Request ID
standard][hierarchical_request_id_standard].

### `isIncoming()`

```ts
(id: string) => boolean;
```

Checks if the provided ID is an [Incoming ID][incoming_id_description].

### `isOutgoing()`

```ts
(id: string) => boolean;
```

Checks if the provided ID is an [Outgoing ID][outgoing_id_description] (but not
a bare Root ID).

### `isRoot()`

```ts
(id: string) => boolean;
```

Checks if the provided ID is a [Root ID][root_id_description].

### `generateRootId()`

```ts
() => string;
```

Generates a new root ID.

### `generateOverflowedId()`

```ts
(id: string) => string;
```

Generates an [overflowed ID][overflowed_id_description] based on provided one.
If provided id is invalid, generates it from scratch.

### `extractRootId()`

```ts
(id: string) => string | null;
```

Extracts root ID from the provided hierarchical request ID. If root ID cannot be
extracted (ID is invalid) returns null instead.

[npm-image]: https://img.shields.io/npm/v/@g2a/request-id.svg
[npm-url]: https://www.npmjs.com/package/@g2a/request-id
[hierarchical_request_id_standard]:
  https://github.com/dotnet/corefx/blob/40b9d2226636d9234f755e01f5e36811a55d7cd2/src/System.Diagnostics.DiagnosticSource/src/HierarchicalRequestId.md
[root_id_description]:
  https://github.com/dotnet/corefx/blob/40b9d2226636d9234f755e01f5e36811a55d7cd2/src/System.Diagnostics.DiagnosticSource/src/HierarchicalRequestId.md#root-request-id-generation
[incoming_id_description]:
  https://github.com/dotnet/corefx/blob/40b9d2226636d9234f755e01f5e36811a55d7cd2/src/System.Diagnostics.DiagnosticSource/src/HierarchicalRequestId.md#incoming-request
[outgoing_id_description]:
  https://github.com/dotnet/corefx/blob/40b9d2226636d9234f755e01f5e36811a55d7cd2/src/System.Diagnostics.DiagnosticSource/src/HierarchicalRequestId.md#outgoing-request
[overflowed_id_description]:
  https://github.com/dotnet/corefx/blob/40b9d2226636d9234f755e01f5e36811a55d7cd2/src/System.Diagnostics.DiagnosticSource/src/HierarchicalRequestId.md#request-id-overflow

---
_Source: https://npm.io/package/@g2a/request-id · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._