ref(attribute): Add type to accept unknown and official attribute type (#18201)

Uses a conditional type to infer whether an attribute object has the
type of an official attribute by checking if it has a `value` or a
`unit`:

```ts
export type ValidatedAttributes<T> = {
  [K in keyof T]: T[K] extends { value: any } | { unit: any } ? ValidAttributeObject : unknown;
};
```

That way, TS can show an error when people attempt to use the attribute
type while still allowing non-official types.

<img width="673" height="250" alt="image"
src="https://github.com/user-attachments/assets/f635f46d-6c3f-49cb-b31f-a02a6ebf91d3"
/>



---

I also added a small helper type to generate the very long attribute
type object, so it can generate a type like this:
```ts
/*
  | { value: string; type: 'string' }
  | { value: number; type: 'integer' }
  | { value: number; type: 'double' }
  */
  ```

Author: s1gr1d

.size-limit.js

@@ -183,14 +183,14 @@ module.exports = [
     path: createCDNPath('bundle.min.js'),
     gzip: false,
     brotli: false,
-    limit: '80 KB',
+    limit: '82 KB',
   },
   {
     name: 'CDN Bundle (incl. Tracing) - uncompressed',
     path: createCDNPath('bundle.tracing.min.js'),
     gzip: false,
     brotli: false,
-    limit: '125 KB',
+    limit: '127 KB',
   },
   {
     name: 'CDN Bundle (incl. Tracing, Replay) - uncompressed',

packages/core/src/attributes.ts

@@ -2,43 +2,65 @@ export type Attributes = Record<string, TypedAttributeValue>;
 
 export type AttributeValueType = string | number | boolean | Array<string> | Array<number> | Array<boolean>;
 
-export type TypedAttributeValue = (
-  | {
-      value: string;
-      type: 'string';
-    }
-  | {
-      value: number;
-      type: 'integer';
-    }
-  | {
-      value: number;
-      type: 'double';
-    }
-  | {
-      value: boolean;
-      type: 'boolean';
-    }
-  | {
-      value: Array<string>;
-      type: 'string[]';
-    }
-  | {
-      value: Array<number>;
-      type: 'integer[]';
-    }
-  | {
-      value: Array<number>;
-      type: 'double[]';
-    }
-  | {
-      value: Array<boolean>;
-      type: 'boolean[]';
-    }
-) & { unit?: Units };
+type AttributeTypeMap = {
+  string: string;
+  integer: number;
+  double: number;
+  boolean: boolean;
+  'string[]': Array<string>;
+  'integer[]': Array<number>;
+  'double[]': Array<number>;
+  'boolean[]': Array<boolean>;
+};
+
+/* Generates a type from the AttributeTypeMap like:
+  | { value: string; type: 'string' }
+  | { value: number; type: 'integer' }
+  | { value: number; type: 'double' }
+ */
+type AttributeUnion = {
+  [K in keyof AttributeTypeMap]: {
+    value: AttributeTypeMap[K];
+    type: K;
+  };
+}[keyof AttributeTypeMap];
+
+export type TypedAttributeValue = AttributeUnion & { unit?: Units };
+
+type AttributeWithUnit = {
+  value: unknown;
+  unit: Units;
+};
 
 type Units = 'ms' | 's' | 'bytes' | 'count' | 'percent';
 
+type ValidAttributeObject = AttributeWithUnit | TypedAttributeValue;
+
+/* If an attribute has either a 'value' or 'unit' property, we use the ValidAttributeObject type. */
+export type ValidatedAttributes<T> = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [K in keyof T]: T[K] extends { value: any } | { unit: any } ? ValidAttributeObject : unknown;
+};
+
+/**
+ * Type-guard: The attribute object has the shape the official attribute object (value, type, unit).
+ * https://develop.sentry.dev/sdk/telemetry/scopes/#setting-attributes
+ */
+export function isAttributeObject(value: unknown): value is ValidAttributeObject {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+  // MUST have a 'value' property
+  if (!Object.prototype.hasOwnProperty.call(value, 'value')) {
+    return false;
+  }
+  // And it MUST have 'unit' OR 'type'
+  const hasUnit = Object.prototype.hasOwnProperty.call(value, 'unit');
+  const hasType = Object.prototype.hasOwnProperty.call(value, 'type');
+
+  return hasUnit || hasType;
+}
+
 /**
  * Converts an attribute value to a typed attribute value.
  *
@@ -47,7 +69,7 @@ type Units = 'ms' | 's' | 'bytes' | 'count' | 'percent';
  * @param value - The value of the passed attribute.
  * @returns The typed attribute.
  */
-export function attributeValueToTypedAttributeValue(value: AttributeValueType): TypedAttributeValue {
+export function attributeValueToTypedAttributeValue(value: unknown): TypedAttributeValue {
   switch (typeof value) {
     case 'number':
       if (Number.isInteger(value)) {

packages/core/src/scope.ts

@@ -1,6 +1,6 @@
 /* eslint-disable max-lines */
-import type { Attributes, AttributeValueType, TypedAttributeValue } from './attributes';
-import { attributeValueToTypedAttributeValue } from './attributes';
+import type { Attributes, AttributeValueType, TypedAttributeValue, ValidatedAttributes } from './attributes';
+import { attributeValueToTypedAttributeValue, isAttributeObject } from './attributes';
 import type { Client } from './client';
 import { DEBUG_BUILD } from './debug-build';
 import { updateSession } from './session';
@@ -326,14 +326,27 @@ export class Scope {
    * });
    * ```
    */
-  public setAttributes(newAttributes: Record<string, AttributeValueType | TypedAttributeValue>): this {
+  public setAttributes<T extends Record<string, unknown>>(newAttributes: T & ValidatedAttributes<T>): this {
     Object.entries(newAttributes).forEach(([key, value]) => {
-      if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-        this._attributes[key] = value;
+      if (isAttributeObject(value)) {
+        // Case 1: ({ value, unit })
+        if ('unit' in value && !('type' in value)) {
+          // Infer type from the inner value
+          this._attributes[key] = {
+            ...attributeValueToTypedAttributeValue(value.value),
+            unit: value.unit,
+          };
+        }
+        // Case 2: ({ value, type, unit? })
+        else {
+          this._attributes[key] = value;
+        }
       } else {
+        // Else: (string, number, etc.) or a random object (will stringify random values).
         this._attributes[key] = attributeValueToTypedAttributeValue(value);
       }
     });
+
     this._notifyScopeListeners();
     return this;
   }

packages/core/test/lib/attributes.test.ts

@@ -80,7 +80,6 @@ describe('attributeValueToTypedAttributeValue', () => {
     });
 
     it('stringifies an array of mixed types to a string attribute value', () => {
-      // @ts-expect-error - this is not allowed by types but we still test fallback behaviour
       const result = attributeValueToTypedAttributeValue([1, 'foo', true]);
       expect(result).toEqual({
         value: '[1,"foo",true]',
@@ -89,7 +88,6 @@ describe('attributeValueToTypedAttributeValue', () => {
     });
 
     it('stringifies an object value to a string attribute value', () => {
-      // @ts-expect-error - this is not allowed by types but we still test fallback behaviour
       const result = attributeValueToTypedAttributeValue({ foo: 'bar' });
       expect(result).toEqual({
         value: '{"foo":"bar"}',