Request Meta

Vovk.ts lets you attach additional metadata to controller methods for logging, analytics, or custom processing. The primary use case is setting request metadata in a custom decorator so it can be used later in the handler or in decorators declared after the one that sets the metadata.

Metadata is accessible through the vovk.meta method in the controller handler and in decorators.


import { createDecorator, get, type VovkRequest } from 'vovk';
 
const myDecorator = createDecorator(async (req, next) => {
  req.vovk.meta({ hello: 'world' }); // set request meta for the request
  // ...
  return next();
});
 
export default class MyController {
  @get('/my-endpoint')
  @myDecorator()
  static async myHandler(req: VovkRequest) {
    console.log(req.vovk.meta<{ hello: string }>()); // { hello: 'world' }
    // ...
  }
}

The metadata is a key‑value object that is merged when you call vovk.meta multiple times with different keys, allowing you to set several entries in one or multiple calls.


// ...
req.vovk.meta({ foo: 'bar' });
req.vovk.meta({ baz: 'qux' });
console.log(req.vovk.meta<{ foo: string; baz: string }>()); // { foo: 'bar', baz: 'qux' }

As you can see, a generic is required only when you want type‑safe access to metadata. If you don’t provide a generic, the metadata is inferred from the argument. Calling req.vovk.meta() without arguments always returns the current metadata object.


const { hello } = req.vovk.meta({ hello: 'world' });

To reset metadata, call req.vovk.meta(null), which clears the metadata object.


req.vovk.meta(null);
console.log(req.vovk.meta()); // {}

To summarize:

To set metadata, use req.vovk.meta({ key: value }). It will return the metadata object typed as the passed object.
To access metadata, use req.vovk.meta<{ key: Type }>(), which will return the metadata object typed as the passed generic type.
To reset metadata, use req.vovk.meta(null), which will clear the metadata object.

Client-Side Meta with `xMetaHeader` Key

The RPC client can send custom metadata to the server in the x-meta header as a JSON string. This is useful for passing client‑side context such as user preferences, session data, or other request‑relevant information.


import { UserRPC } from 'vovk-client';
 
const user = await UserRPC.getUser({
  params: { id: '123' },
  meta: { hello: 'world' }, // pass metadata to the server
});

The getUser controller method, as well as decorators, can access this metadata via req.vovk.meta under the xMetaHeader key:


import { get, type VovkRequest } from 'vovk';
 
export default class UserController {
  @get(':id')
  static async getUser(req: VovkRequest) {
    const meta = req.vovk.meta<{ xMetaHeader: { hello: string } }>();
    console.log(meta.xMetaHeader); // { hello: 'world' }
    // ...
  }
}

This design prevents server‑side metadata from being overwritten by client input, as client values are only exposed under the xMetaHeader key.

Request Meta

Client-Side Meta with xMetaHeader Key

Client-Side Meta with `xMetaHeader` Key