feat(packages): Expose canonical attribute read chains

javascript/sentry-conventions/README.md

@@ -23,5 +23,22 @@
 The package exports:
 
 - `attributes`: contains constants for all attribute names and their types, as defined in the Sentry semantic conventions
+- `attributes.<ATTRIBUTE>_KEYS`: contains readonly lookup keys for an attribute
+- `attribute-utils.getAttributeValue`: reads an attribute using its lookup keys
 - `attributes.Attributes`: represents a bag of typed attributes
 - `op`: contains constants for span operations used in Sentry
+
+## Reading Attributes
+
+Import a readonly `<ATTRIBUTE>_KEYS` tuple from `@sentry/conventions/attributes` and pass it to `getAttributeValue<T>` from `@sentry/conventions/attribute-utils`:
+
+```ts
+import { getAttributeValue } from '@sentry/conventions/attribute-utils';
+import { HTTP_REQUEST_METHOD_KEYS } from '@sentry/conventions/attributes';
+
+const method = getAttributeValue<string>(attributes, HTTP_REQUEST_METHOD_KEYS);
+```
+
+Each tuple lists the stable key first, followed by deprecated predecessors in alphabetical order. The helper returns the raw value from the first key whose value is not `undefined`. It does not validate or transform values. The caller-supplied generic is only a TypeScript type assertion and adds no runtime checks.
+
+Keys that contain a dynamic `<key>` segment are patterns, not literal lookup keys. Materialize each pattern by replacing `<key>` with the actual segment before calling the helper. The generated package does not include expanded lists for dynamic keys.

javascript/sentry-conventions/attribute-utils.d.ts

@@ -0,0 +1,3 @@
+// This file is a compatibility shim for TypeScript compilers that do not
+// support the package.json `exports` field for resolving subpath exports.
+export * from './dist/attribute-utils';

javascript/sentry-conventions/attribute-utils.js

@@ -0,0 +1,3 @@
+// This file is a compatibility shim for bundlers (e.g. webpack 4) that do not
+// support the package.json `exports` field for resolving subpath exports.
+module.exports = require('./dist/attribute-utils.cjs');

javascript/sentry-conventions/build.config.ts

@@ -1,7 +1,7 @@
 import { defineBuildConfig } from 'unbuild';
 
 export default defineBuildConfig({
-  entries: ['./src/index', './src/attributes', './src/op'],
+  entries: ['./src/index', './src/attributes', './src/attribute-utils', './src/op'],
   outDir: 'dist',
   declaration: 'compatible',
   sourcemap: true,

javascript/sentry-conventions/package.json

@@ -11,6 +11,10 @@
       "import": "./dist/attributes.mjs",
       "require": "./dist/attributes.cjs"
     },
+    "./attribute-utils": {
+      "import": "./dist/attribute-utils.mjs",
+      "require": "./dist/attribute-utils.cjs"
+    },
     "./op": {
       "import": "./dist/op.mjs",
       "require": "./dist/op.cjs"
@@ -34,6 +38,8 @@
     "dist",
     "attributes.js",
     "attributes.d.ts",
+    "attribute-utils.js",
+    "attribute-utils.d.ts",
     "op.js",
     "op.d.ts"
   ],

javascript/sentry-conventions/src/attribute-utils.ts

@@ -0,0 +1,26 @@
+/**
+ * Takes a record of attributes (key-value pairs) and a list of keys.
+ * Returns the value of the first key that exists in the attributes record has a defined value.
+ *
+ * This is useful when passing in a deprecation chain or alias list where we want to obtain a
+ * value from the first key that is defined in the attributes record.
+ *
+ * @example
+ * const attributes = {
+ *   "old_key": "value",
+ * };
+ * const keys = ["new_key", "old_key"];
+ * const value = getAttributeValue(attributes, keys);
+ * console.log(value); // "value"
+ *
+ * @param attributes a key-value pair of attributes. Not compatible with typed attributes where the value is a `{value, type, unit?}` object.
+ * @param keys a list of attribute keys. Use `<ATTRIBUTE_NAME>_KEYS` to get the list of current and deprecated attribute keys for an attribute.
+ *
+ * @returns the attribute value of the first key that is defined in the attributes record.
+ */
+export function getAttributeValue<T = unknown>(
+  attributes: Record<string, unknown>,
+  keys: readonly string[],
+): T | undefined {
+  return keys.map((key) => attributes[key]).find((value) => value !== undefined) as T | undefined;
+}