{"id":10974,"library":"grpc-create-metadata","title":"gRPC Metadata Creator Utility","description":"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.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/bojand/grpc-create-metadata","tags":["javascript","protocol buffer","protobuf","grpc","metadata"],"install":[{"cmd":"npm install grpc-create-metadata","lang":"bash","label":"npm"},{"cmd":"yarn add grpc-create-metadata","lang":"bash","label":"yarn"},{"cmd":"pnpm add grpc-create-metadata","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency providing the core gRPC Metadata object and related functionalities.","package":"@grpc/grpc-js","optional":false}],"imports":[{"note":"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.","wrong":"const create = require('grpc-create-metadata');","symbol":"create","correct":"import create from 'grpc-create-metadata';"},{"note":"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.","wrong":"const grpc = require('grpc'); const Metadata = grpc.Metadata;","symbol":"Metadata","correct":"import { Metadata } from '@grpc/grpc-js';"},{"note":"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.","wrong":"const grpc = require('grpc');","symbol":"Client","correct":"import { Client, credentials } from '@grpc/grpc-js';"}],"quickstart":{"code":"import create from 'grpc-create-metadata';\nimport { Metadata } from '@grpc/grpc-js';\n\nconst userDetails = {\n  name: 'Alice',\n  age: 30,\n  isAdmin: true,\n  // Buffers are passed as-is\n  token: Buffer.from('my-secret-token')\n};\n\nconst metadata = create(userDetails);\n\nconsole.log('Is instance of Metadata?', metadata instanceof Metadata); // true\nconsole.log('Metadata map:', metadata.getMap());\n// Example output might be: { name: 'Alice', age: '30', isadmin: 'true', token: <Buffer ...> }\n\n// Demonstrating passing an existing Metadata object (it's returned as-is)\nconst existingMeta = new Metadata();\nexistingMeta.add('correlation-id', 'abc-123');\nconst sameMeta = create(existingMeta);\nconsole.log('Existing Metadata handled:', sameMeta.getMap());","lang":"javascript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"deprecated","affected_versions":"=3.1.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Validate input object keys to ensure they are valid gRPC metadata keys (e.g., `/^[a-z0-9][a-z0-9_-]*$/`).","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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))`.","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`.","error":"TypeError: The 'metadata' argument must be an instance of 'Metadata'."},{"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`.","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.","error":"TypeError: Value must be a string or buffer (argument 2)."}],"ecosystem":"npm"}