gRPC Metadata Creator Utility

4.0.1 · active · verified Sun Apr 19

This utility package, `grpc-create-metadata`, provides a straightforward helper function to convert plain JavaScript objects into gRPC `Metadata` instances. It automatically handles type conversion for common primitives like numbers and booleans by calling their `toString()` method, while `Buffer` and `String` values are passed directly. The package is currently at version 4.0.1 and primarily receives updates for dependency maintenance, especially related to its `@grpc/grpc-js` peer dependency. Its core differentiation lies in simplifying the common task of populating `grpc.Metadata` objects, which strictly require string or buffer values, by abstracting the conversion logic, making it easier for developers to work with gRPC services in Node.js. It maintains a stable, albeit infrequent, release cadence driven by underlying gRPC dependency updates and security patches.

Common errors

```
TypeError: The 'metadata' argument must be an instance of 'Metadata'.
```
cause Attempting to pass a plain JavaScript object directly to a gRPC client method's metadata argument instead of an `grpc.Metadata` instance created by `grpc-create-metadata`.

fix Ensure that plain JavaScript objects intended as metadata are first processed by `create()` from `grpc-create-metadata` before being passed to gRPC client calls: `client.someMethod(request, create(myObject))`.
```
TypeError: Value must be a string or buffer (argument 2).
```
cause Attempting to manually add a non-string or non-buffer value directly to a `grpc.Metadata` object using `metadata.add(key, value)` without `grpc-create-metadata`'s type conversion.

fix Use the `grpc-create-metadata` utility, which handles `toString()` conversion for non-string/buffer types, or manually convert values to string/buffer before adding them to `grpc.Metadata`.

Warnings

deprecated Version 3.1.0 of `grpc-create-metadata` is explicitly deprecated. Users should upgrade to version 3.0.0 or any 4.x.x release for continued support and security updates, as v3.1.0 contained an accidental re-release of v4.0.0's dependencies.
Fix: Upgrade package to `^3.0.0` (excluding 3.1.0) or `^4.0.0`. For example: `npm install grpc-create-metadata@^4.0.0`.
breaking Version 4.0.0 updated the underlying `@grpc/grpc-js` peer dependency. While `grpc-create-metadata`'s API remains consistent, ensure your project's `@grpc/grpc-js` version is compatible (>=1.2.5 as specified in peer dependencies) to avoid runtime issues related to gRPC version mismatches.
Fix: Verify and update your project's `@grpc/grpc-js` installation to a compatible version, e.g., `npm install @grpc/grpc-js@^1.2.5`.
gotcha gRPC `Metadata` objects, and consequently the `create` utility, strictly process values as strings or Buffers. Non-string/Buffer JavaScript types (e.g., numbers, booleans, objects) are automatically converted to strings via their `toString()` method, which might not always yield the desired serialization format for complex data.
Fix: For complex data types or specific serialization needs, manually convert them to a string (e.g., `JSON.stringify()`) or a Buffer before passing them to `grpc-create-metadata` if the default `toString()` behavior is insufficient.
gotcha Metadata keys must conform to gRPC naming conventions (e.g., lowercase, hyphens allowed, no special characters or spaces). Supplying invalid keys in the input object will result in them being ignored by the underlying gRPC `Metadata` object or causing runtime errors within gRPC itself, not `grpc-create-metadata`.
Fix: Validate input object keys to ensure they are valid gRPC metadata keys (e.g., `/^[a-z0-9][a-z0-9_-]*$/`).

Install

npm install grpc-create-metadata npm
yarn add grpc-create-metadata yarn
pnpm add grpc-create-metadata pnpm

Imports

create
wrong:
```
const create = require('grpc-create-metadata');
```
correct:
```
import create from 'grpc-create-metadata';
```
The library provides a single default export. While CommonJS `require` is compatible and shown in older examples, ESM `import` is preferred for new projects and modern Node.js environments.
Metadata
wrong:
```
const grpc = require('grpc'); const Metadata = grpc.Metadata;
```
correct:
```
import { Metadata } from '@grpc/grpc-js';
```
The `create` function returns an instance of `grpc.Metadata`. This import from the peer dependency `@grpc/grpc-js` is necessary for type checking, `instanceof` checks, or direct interaction with gRPC metadata objects.
Client
wrong:
```
const grpc = require('grpc');
```
correct:
```
import { Client, credentials } from '@grpc/grpc-js';
```
Although not directly part of `grpc-create-metadata`, usage often involves importing gRPC client or server components from `@grpc/grpc-js` to integrate the created metadata into service calls. Ensure consistency with `@grpc/grpc-js` versioning.

Quickstart

Demonstrates how to use the 'grpc-create-metadata' utility to transform a plain JavaScript object into a gRPC Metadata object, inspect its contents, and understand its behavior with existing Metadata instances.

import create from 'grpc-create-metadata';
import { Metadata } from '@grpc/grpc-js';

const userDetails = {
  name: 'Alice',
  age: 30,
  isAdmin: true,
  // Buffers are passed as-is
  token: Buffer.from('my-secret-token')
};

const metadata = create(userDetails);

console.log('Is instance of Metadata?', metadata instanceof Metadata); // true
console.log('Metadata map:', metadata.getMap());
// Example output might be: { name: 'Alice', age: '30', isadmin: 'true', token: <Buffer ...> }

// Demonstrating passing an existing Metadata object (it's returned as-is)
const existingMeta = new Metadata();
existingMeta.add('correlation-id', 'abc-123');
const sameMeta = create(existingMeta);
console.log('Existing Metadata handled:', sameMeta.getMap());

view raw JSON →