@primafuture/telemetry-structured-metadata 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @primafuture/telemetry-structured-metadata
+
+Shared structured metadata encoder for PrimaFuture telemetry libraries.
+
+It converts nested JavaScript metadata into OpenTelemetry-safe flat attributes
+and an optional JSON representation that can be decoded back later.
+
+## Usage
+
+```ts
+import {
+  encodeStructuredMetadata,
+  decodeStructuredMetadata,
+} from '@primafuture/telemetry-structured-metadata';
+
+const attributes = encodeStructuredMetadata({
+  request: {
+    id: 'abc',
+    deletedAt: null,
+  },
+  missing: undefined,
+});
+```
+
+Default output:
+
+```text
+app.value.request.id = "abc"
+app.type.request.deletedAt = "null"
+app.type.missing = "undefined"
+app.meta.json = "{\"request\":{\"id\":\"abc\",\"deletedAt\":null},\"missing\":{\"$pfType\":\"undefined\"}}"
+```
+
+`flatten` output is meant for queries. `json` output is meant for
+reconstruction. `raw` output is disabled by default and only passes through
+OpenTelemetry-safe scalar or homogeneous array values.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+npm run prepublishOnly
+```

package/dist/index.cjs

@@ -0,0 +1,427 @@
+'use strict';
+
+// src/index.ts
+var DEFAULT_NAMESPACE = "app";
+var DEFAULT_VALUE_PREFIX = "value";
+var DEFAULT_TYPE_PREFIX = "type";
+var DEFAULT_JSON_KEY = "app.meta.json";
+var DEFAULT_TYPE_KEY = "$pfType";
+var OMIT_PLAIN_JSON_VALUE = /* @__PURE__ */ Symbol("omit-plain-json-value");
+function normalizeStructuredMetadataOptions(options = {}) {
+  return {
+    flatten: {
+      enabled: options.flatten?.enabled ?? true,
+      namespace: options.flatten?.namespace ?? DEFAULT_NAMESPACE,
+      valuePrefix: options.flatten?.valuePrefix ?? DEFAULT_VALUE_PREFIX,
+      typePrefix: options.flatten?.typePrefix ?? DEFAULT_TYPE_PREFIX,
+      typeFields: options.flatten?.typeFields ?? "when-needed"
+    },
+    json: {
+      enabled: options.json?.enabled ?? true,
+      key: options.json?.key ?? DEFAULT_JSON_KEY,
+      valueEncoding: options.json?.valueEncoding ?? "typed",
+      typeKey: options.json?.typeKey ?? DEFAULT_TYPE_KEY
+    },
+    raw: {
+      enabled: options.raw?.enabled ?? false
+    }
+  };
+}
+function encodeStructuredMetadata(data, options = {}) {
+  if (Object.keys(data).length === 0) {
+    return {};
+  }
+  const normalizedOptions = normalizeStructuredMetadataOptions(options);
+  const attributes = {};
+  if (normalizedOptions.raw.enabled) {
+    addRawAttributes(attributes, data);
+  }
+  if (normalizedOptions.flatten.enabled) {
+    addFlattenedAttributes(attributes, data, normalizedOptions.flatten);
+  }
+  if (normalizedOptions.json.enabled) {
+    const jsonValue = normalizedOptions.json.valueEncoding === "typed" ? encodeTypedJsonValue(data, normalizedOptions.json.typeKey, /* @__PURE__ */ new WeakSet()) : encodePlainJsonValue(data, /* @__PURE__ */ new WeakSet(), false);
+    if (jsonValue !== OMIT_PLAIN_JSON_VALUE) {
+      attributes[normalizedOptions.json.key] = JSON.stringify(jsonValue);
+    }
+  }
+  return attributes;
+}
+function decodeStructuredMetadata(attributes, options = {}) {
+  const normalizedOptions = normalizeStructuredMetadataOptions(options);
+  const encodedValue = readJsonAttribute(attributes, normalizedOptions.json.key);
+  if (typeof encodedValue !== "string") {
+    return void 0;
+  }
+  const parsedValue = JSON.parse(encodedValue);
+  if (normalizedOptions.json.valueEncoding === "typed") {
+    return decodeTypedJsonValue(parsedValue, normalizedOptions.json.typeKey);
+  }
+  return parsedValue;
+}
+function readJsonAttribute(attributes, key) {
+  if (Object.prototype.hasOwnProperty.call(attributes, key)) {
+    return attributes[key];
+  }
+  const lokiNormalizedKey = key.replaceAll(".", "_");
+  return attributes[lokiNormalizedKey];
+}
+function addRawAttributes(attributes, data) {
+  for (const [key, value] of Object.entries(data)) {
+    const rawValue = getRawAttributeValue(value);
+    if (rawValue !== void 0) {
+      attributes[key] = rawValue;
+    }
+  }
+}
+function getRawAttributeValue(value) {
+  if (isScalarAttributeValue(value)) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return getHomogeneousScalarArray(value);
+  }
+  return void 0;
+}
+function isScalarAttributeValue(value) {
+  return typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value);
+}
+function getHomogeneousScalarArray(value) {
+  if (value.length === 0) {
+    return void 0;
+  }
+  if (value.every((item) => typeof item === "string")) {
+    return value;
+  }
+  if (value.every((item) => typeof item === "boolean")) {
+    return value;
+  }
+  if (value.every((item) => typeof item === "number" && Number.isFinite(item))) {
+    return value;
+  }
+  return void 0;
+}
+function addFlattenedAttributes(attributes, data, options) {
+  for (const [key, value] of Object.entries(data)) {
+    addFlattenedValue(attributes, [key], value, options, /* @__PURE__ */ new WeakSet());
+  }
+}
+function addFlattenedValue(attributes, path, value, options, seenObjects) {
+  if (value === null) {
+    addTypeAttribute(attributes, path, "null", options, true);
+    return;
+  }
+  if (value === void 0) {
+    addTypeAttribute(attributes, path, "undefined", options, true);
+    return;
+  }
+  if (typeof value === "string" || typeof value === "boolean") {
+    addValueAttribute(attributes, path, value, options);
+    addTypeAttribute(attributes, path, typeof value, options, false);
+    return;
+  }
+  if (typeof value === "number") {
+    if (Number.isFinite(value)) {
+      addValueAttribute(attributes, path, value, options);
+      addTypeAttribute(attributes, path, "number", options, false);
+    } else {
+      addValueAttribute(attributes, path, String(value), options);
+      addTypeAttribute(attributes, path, "non-finite-number", options, true);
+    }
+    return;
+  }
+  if (typeof value === "bigint") {
+    addValueAttribute(attributes, path, value.toString(), options);
+    addTypeAttribute(attributes, path, "bigint", options, true);
+    return;
+  }
+  if (typeof value === "function") {
+    addTypeAttribute(attributes, path, "function", options, true);
+    return;
+  }
+  if (typeof value === "symbol") {
+    addTypeAttribute(attributes, path, "symbol", options, true);
+    return;
+  }
+  if (value instanceof Date) {
+    addValueAttribute(attributes, path, value.toISOString(), options);
+    addTypeAttribute(attributes, path, "date", options, true);
+    return;
+  }
+  if (value instanceof Error) {
+    addFlattenedError(attributes, path, value, options);
+    return;
+  }
+  if (Array.isArray(value)) {
+    addFlattenedArray(attributes, path, value, options, seenObjects);
+    return;
+  }
+  if (isPlainObject(value)) {
+    addFlattenedObject(attributes, path, value, options, seenObjects);
+    return;
+  }
+  addValueAttribute(attributes, path, String(value), options);
+  addTypeAttribute(attributes, path, "unsupported-object", options, true);
+}
+function addFlattenedError(attributes, path, error, options) {
+  addTypeAttribute(attributes, path, "error", options, true);
+  addValueAttribute(attributes, [...path, "name"], error.name, options);
+  addValueAttribute(attributes, [...path, "message"], error.message, options);
+  if (error.stack !== void 0) {
+    addValueAttribute(attributes, [...path, "stack"], error.stack, options);
+  }
+}
+function addFlattenedArray(attributes, path, value, options, seenObjects) {
+  if (seenObjects.has(value)) {
+    addTypeAttribute(attributes, path, "circular-reference", options, true);
+    return;
+  }
+  if (value.length === 0) {
+    addTypeAttribute(attributes, path, "empty-array", options, true);
+    return;
+  }
+  addTypeAttribute(attributes, path, "array", options, false);
+  seenObjects.add(value);
+  for (const [index, item] of value.entries()) {
+    addFlattenedValue(attributes, [...path, String(index)], item, options, seenObjects);
+  }
+  seenObjects.delete(value);
+}
+function addFlattenedObject(attributes, path, value, options, seenObjects) {
+  if (seenObjects.has(value)) {
+    addTypeAttribute(attributes, path, "circular-reference", options, true);
+    return;
+  }
+  const entries = Object.entries(value);
+  if (entries.length === 0) {
+    addTypeAttribute(attributes, path, "empty-object", options, true);
+    return;
+  }
+  addTypeAttribute(attributes, path, "object", options, false);
+  seenObjects.add(value);
+  for (const [key, nestedValue] of entries) {
+    addFlattenedValue(attributes, [...path, key], nestedValue, options, seenObjects);
+  }
+  seenObjects.delete(value);
+}
+function addValueAttribute(attributes, path, value, options) {
+  attributes[createFlattenedKey(options, options.valuePrefix, path)] = value;
+}
+function addTypeAttribute(attributes, path, typeName, options, needed) {
+  if (options.typeFields === "never") {
+    return;
+  }
+  if (options.typeFields === "when-needed" && !needed) {
+    return;
+  }
+  attributes[createFlattenedKey(options, options.typePrefix, path)] = typeName;
+}
+function createFlattenedKey(options, prefix, path) {
+  return [
+    options.namespace,
+    prefix,
+    ...path
+  ].join(".");
+}
+function encodeTypedJsonValue(value, typeKey, seenObjects) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : createTypedMarker(typeKey, "non-finite-number", { value: String(value) });
+  }
+  if (value === void 0) {
+    return createTypedMarker(typeKey, "undefined");
+  }
+  if (typeof value === "bigint") {
+    return createTypedMarker(typeKey, "bigint", { value: value.toString() });
+  }
+  if (typeof value === "function") {
+    return createTypedMarker(typeKey, "function", value.name ? { name: value.name } : void 0);
+  }
+  if (typeof value === "symbol") {
+    return createTypedMarker(typeKey, "symbol", { value: String(value) });
+  }
+  if (value instanceof Date) {
+    return createTypedMarker(typeKey, "date", { value: value.toISOString() });
+  }
+  if (value instanceof Error) {
+    return createTypedError(typeKey, value);
+  }
+  if (Array.isArray(value)) {
+    return encodeTypedJsonArray(value, typeKey, seenObjects);
+  }
+  if (isPlainObject(value)) {
+    return encodeTypedJsonObject(value, typeKey, seenObjects);
+  }
+  return createTypedMarker(typeKey, "unsupported-object", { value: String(value) });
+}
+function encodeTypedJsonArray(value, typeKey, seenObjects) {
+  if (seenObjects.has(value)) {
+    return createTypedMarker(typeKey, "circular-reference");
+  }
+  seenObjects.add(value);
+  const result = value.map((item) => encodeTypedJsonValue(item, typeKey, seenObjects));
+  seenObjects.delete(value);
+  return result;
+}
+function encodeTypedJsonObject(value, typeKey, seenObjects) {
+  if (seenObjects.has(value)) {
+    return createTypedMarker(typeKey, "circular-reference");
+  }
+  seenObjects.add(value);
+  const result = {};
+  for (const [key, nestedValue] of Object.entries(value)) {
+    result[key] = encodeTypedJsonValue(nestedValue, typeKey, seenObjects);
+  }
+  seenObjects.delete(value);
+  if (Object.prototype.hasOwnProperty.call(result, typeKey)) {
+    return createTypedMarker(typeKey, "object", {
+      value: result
+    });
+  }
+  return result;
+}
+function createTypedError(typeKey, error) {
+  const errorValue = {
+    name: error.name,
+    message: error.message
+  };
+  if (error.stack !== void 0) {
+    errorValue.stack = error.stack;
+  }
+  return createTypedMarker(typeKey, "error", errorValue);
+}
+function createTypedMarker(typeKey, typeName, extra) {
+  return {
+    [typeKey]: typeName,
+    ...extra ?? {}
+  };
+}
+function encodePlainJsonValue(value, seenObjects, inArray) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (value === void 0 || typeof value === "function" || typeof value === "symbol") {
+    return inArray ? null : OMIT_PLAIN_JSON_VALUE;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (value instanceof Error) {
+    return encodePlainJsonError(value);
+  }
+  if (Array.isArray(value)) {
+    return encodePlainJsonArray(value, seenObjects);
+  }
+  if (isPlainObject(value)) {
+    return encodePlainJsonObject(value, seenObjects);
+  }
+  return String(value);
+}
+function encodePlainJsonArray(value, seenObjects) {
+  if (seenObjects.has(value)) {
+    return "[Circular]";
+  }
+  seenObjects.add(value);
+  const result = value.map((item) => {
+    const encodedItem = encodePlainJsonValue(item, seenObjects, true);
+    return encodedItem === OMIT_PLAIN_JSON_VALUE ? null : encodedItem;
+  });
+  seenObjects.delete(value);
+  return result;
+}
+function encodePlainJsonObject(value, seenObjects) {
+  if (seenObjects.has(value)) {
+    return "[Circular]";
+  }
+  seenObjects.add(value);
+  const result = {};
+  for (const [key, nestedValue] of Object.entries(value)) {
+    const encodedValue = encodePlainJsonValue(nestedValue, seenObjects, false);
+    if (encodedValue !== OMIT_PLAIN_JSON_VALUE) {
+      result[key] = encodedValue;
+    }
+  }
+  seenObjects.delete(value);
+  return result;
+}
+function encodePlainJsonError(error) {
+  const result = {
+    name: error.name,
+    message: error.message
+  };
+  if (error.stack !== void 0) {
+    result.stack = error.stack;
+  }
+  return result;
+}
+function decodeTypedJsonValue(value, typeKey) {
+  if (Array.isArray(value)) {
+    return value.map((item) => decodeTypedJsonValue(item, typeKey));
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  const markerType = value[typeKey];
+  if (typeof markerType === "string") {
+    return decodeTypedMarker(markerType, value, typeKey);
+  }
+  const result = {};
+  for (const [key, nestedValue] of Object.entries(value)) {
+    result[key] = decodeTypedJsonValue(nestedValue, typeKey);
+  }
+  return result;
+}
+function decodeTypedMarker(typeName, value, typeKey) {
+  if (typeName === "undefined") {
+    return void 0;
+  }
+  if (typeName === "bigint" && typeof value.value === "string") {
+    return BigInt(value.value);
+  }
+  if (typeName === "date" && typeof value.value === "string") {
+    return new Date(value.value);
+  }
+  if (typeName === "non-finite-number" && typeof value.value === "string") {
+    return Number(value.value);
+  }
+  if (typeName === "error") {
+    return decodeTypedError(value);
+  }
+  if (typeName === "object" && isPlainObject(value.value)) {
+    return decodeTypedJsonValue(value.value, typeKey);
+  }
+  return {
+    ...value,
+    [typeKey]: typeName
+  };
+}
+function decodeTypedError(value) {
+  const message = typeof value.message === "string" ? value.message : "";
+  const error = new Error(message);
+  if (typeof value.name === "string") {
+    error.name = value.name;
+  }
+  if (typeof value.stack === "string") {
+    error.stack = value.stack;
+  }
+  return error;
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+exports.decodeStructuredMetadata = decodeStructuredMetadata;
+exports.encodeStructuredMetadata = encodeStructuredMetadata;
+exports.normalizeStructuredMetadataOptions = normalizeStructuredMetadataOptions;

package/dist/index.d.cts

@@ -0,0 +1,62 @@
+type StructuredMetadataAttributeValue = string | number | boolean | string[] | number[] | boolean[];
+type StructuredMetadataAttributes = Record<string, StructuredMetadataAttributeValue>;
+type StructuredMetadataTypeFieldsMode = 'when-needed' | 'always' | 'never';
+type StructuredMetadataJsonValueEncoding = 'typed' | 'plain-json';
+interface StructuredMetadataFlattenOptions {
+    enabled?: boolean | undefined;
+    namespace?: string | undefined;
+    valuePrefix?: string | undefined;
+    typePrefix?: string | undefined;
+    typeFields?: StructuredMetadataTypeFieldsMode | undefined;
+}
+interface StructuredMetadataJsonOptions {
+    enabled?: boolean | undefined;
+    key?: string | undefined;
+    valueEncoding?: StructuredMetadataJsonValueEncoding | undefined;
+    typeKey?: string | undefined;
+}
+interface StructuredMetadataRawOptions {
+    enabled?: boolean | undefined;
+}
+interface StructuredMetadataOptions {
+    flatten?: StructuredMetadataFlattenOptions | undefined;
+    json?: StructuredMetadataJsonOptions | undefined;
+    raw?: StructuredMetadataRawOptions | undefined;
+}
+interface NormalizedFlattenOptions {
+    enabled: boolean;
+    namespace: string;
+    valuePrefix: string;
+    typePrefix: string;
+    typeFields: StructuredMetadataTypeFieldsMode;
+}
+interface NormalizedJsonOptions {
+    enabled: boolean;
+    key: string;
+    valueEncoding: StructuredMetadataJsonValueEncoding;
+    typeKey: string;
+}
+interface NormalizedStructuredMetadataOptions {
+    flatten: NormalizedFlattenOptions;
+    json: NormalizedJsonOptions;
+    raw: {
+        enabled: boolean;
+    };
+}
+/**
+ * Normalizuje volitelny config tak, aby zbytek encoderu nemusel vsude resit
+ * chybejici vetve. Defaulty jsou zamerne stejne pro logs, span attributes i events.
+ */
+declare function normalizeStructuredMetadataOptions(options?: StructuredMetadataOptions): NormalizedStructuredMetadataOptions;
+/**
+ * Prevede metadata na ploche atributy vhodne pro OTel. Jednotlive vystupy
+ * (`raw`, `flatten`, `json`) jsou nezavisle a mohou byt zapnute soucasne.
+ */
+declare function encodeStructuredMetadata(data: Record<string, unknown>, options?: StructuredMetadataOptions): StructuredMetadataAttributes;
+/**
+ * Dekoduje metadata z JSON atributu vytvoreneho `encodeStructuredMetadata`.
+ * Pri nacitani z Loki umi krom teckoveho klice zkusit i variantu s podtrzitky.
+ */
+declare function decodeStructuredMetadata(attributes: Record<string, unknown>, options?: StructuredMetadataOptions): unknown;
+
+export { type StructuredMetadataAttributeValue, type StructuredMetadataAttributes, type StructuredMetadataFlattenOptions, type StructuredMetadataJsonOptions, type StructuredMetadataJsonValueEncoding, type StructuredMetadataOptions, type StructuredMetadataRawOptions, type StructuredMetadataTypeFieldsMode, decodeStructuredMetadata, encodeStructuredMetadata, normalizeStructuredMetadataOptions };

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+type StructuredMetadataAttributeValue = string | number | boolean | string[] | number[] | boolean[];
+type StructuredMetadataAttributes = Record<string, StructuredMetadataAttributeValue>;
+type StructuredMetadataTypeFieldsMode = 'when-needed' | 'always' | 'never';
+type StructuredMetadataJsonValueEncoding = 'typed' | 'plain-json';
+interface StructuredMetadataFlattenOptions {
+    enabled?: boolean | undefined;
+    namespace?: string | undefined;
+    valuePrefix?: string | undefined;
+    typePrefix?: string | undefined;
+    typeFields?: StructuredMetadataTypeFieldsMode | undefined;
+}
+interface StructuredMetadataJsonOptions {
+    enabled?: boolean | undefined;
+    key?: string | undefined;
+    valueEncoding?: StructuredMetadataJsonValueEncoding | undefined;
+    typeKey?: string | undefined;
+}
+interface StructuredMetadataRawOptions {
+    enabled?: boolean | undefined;
+}
+interface StructuredMetadataOptions {
+    flatten?: StructuredMetadataFlattenOptions | undefined;
+    json?: StructuredMetadataJsonOptions | undefined;
+    raw?: StructuredMetadataRawOptions | undefined;
+}
+interface NormalizedFlattenOptions {
+    enabled: boolean;
+    namespace: string;
+    valuePrefix: string;
+    typePrefix: string;
+    typeFields: StructuredMetadataTypeFieldsMode;
+}
+interface NormalizedJsonOptions {
+    enabled: boolean;
+    key: string;
+    valueEncoding: StructuredMetadataJsonValueEncoding;
+    typeKey: string;
+}
+interface NormalizedStructuredMetadataOptions {
+    flatten: NormalizedFlattenOptions;
+    json: NormalizedJsonOptions;
+    raw: {
+        enabled: boolean;
+    };
+}
+/**
+ * Normalizuje volitelny config tak, aby zbytek encoderu nemusel vsude resit
+ * chybejici vetve. Defaulty jsou zamerne stejne pro logs, span attributes i events.
+ */
+declare function normalizeStructuredMetadataOptions(options?: StructuredMetadataOptions): NormalizedStructuredMetadataOptions;
+/**
+ * Prevede metadata na ploche atributy vhodne pro OTel. Jednotlive vystupy
+ * (`raw`, `flatten`, `json`) jsou nezavisle a mohou byt zapnute soucasne.
+ */
+declare function encodeStructuredMetadata(data: Record<string, unknown>, options?: StructuredMetadataOptions): StructuredMetadataAttributes;
+/**
+ * Dekoduje metadata z JSON atributu vytvoreneho `encodeStructuredMetadata`.
+ * Pri nacitani z Loki umi krom teckoveho klice zkusit i variantu s podtrzitky.
+ */
+declare function decodeStructuredMetadata(attributes: Record<string, unknown>, options?: StructuredMetadataOptions): unknown;
+
+export { type StructuredMetadataAttributeValue, type StructuredMetadataAttributes, type StructuredMetadataFlattenOptions, type StructuredMetadataJsonOptions, type StructuredMetadataJsonValueEncoding, type StructuredMetadataOptions, type StructuredMetadataRawOptions, type StructuredMetadataTypeFieldsMode, decodeStructuredMetadata, encodeStructuredMetadata, normalizeStructuredMetadataOptions };

package/dist/index.mjs

@@ -0,0 +1,423 @@
+// src/index.ts
+var DEFAULT_NAMESPACE = "app";
+var DEFAULT_VALUE_PREFIX = "value";
+var DEFAULT_TYPE_PREFIX = "type";
+var DEFAULT_JSON_KEY = "app.meta.json";
+var DEFAULT_TYPE_KEY = "$pfType";
+var OMIT_PLAIN_JSON_VALUE = /* @__PURE__ */ Symbol("omit-plain-json-value");
+function normalizeStructuredMetadataOptions(options = {}) {
+  return {
+    flatten: {
+      enabled: options.flatten?.enabled ?? true,
+      namespace: options.flatten?.namespace ?? DEFAULT_NAMESPACE,
+      valuePrefix: options.flatten?.valuePrefix ?? DEFAULT_VALUE_PREFIX,
+      typePrefix: options.flatten?.typePrefix ?? DEFAULT_TYPE_PREFIX,
+      typeFields: options.flatten?.typeFields ?? "when-needed"
+    },
+    json: {
+      enabled: options.json?.enabled ?? true,
+      key: options.json?.key ?? DEFAULT_JSON_KEY,
+      valueEncoding: options.json?.valueEncoding ?? "typed",
+      typeKey: options.json?.typeKey ?? DEFAULT_TYPE_KEY
+    },
+    raw: {
+      enabled: options.raw?.enabled ?? false
+    }
+  };
+}
+function encodeStructuredMetadata(data, options = {}) {
+  if (Object.keys(data).length === 0) {
+    return {};
+  }
+  const normalizedOptions = normalizeStructuredMetadataOptions(options);
+  const attributes = {};
+  if (normalizedOptions.raw.enabled) {
+    addRawAttributes(attributes, data);
+  }
+  if (normalizedOptions.flatten.enabled) {
+    addFlattenedAttributes(attributes, data, normalizedOptions.flatten);
+  }
+  if (normalizedOptions.json.enabled) {
+    const jsonValue = normalizedOptions.json.valueEncoding === "typed" ? encodeTypedJsonValue(data, normalizedOptions.json.typeKey, /* @__PURE__ */ new WeakSet()) : encodePlainJsonValue(data, /* @__PURE__ */ new WeakSet(), false);
+    if (jsonValue !== OMIT_PLAIN_JSON_VALUE) {
+      attributes[normalizedOptions.json.key] = JSON.stringify(jsonValue);
+    }
+  }
+  return attributes;
+}
+function decodeStructuredMetadata(attributes, options = {}) {
+  const normalizedOptions = normalizeStructuredMetadataOptions(options);
+  const encodedValue = readJsonAttribute(attributes, normalizedOptions.json.key);
+  if (typeof encodedValue !== "string") {
+    return void 0;
+  }
+  const parsedValue = JSON.parse(encodedValue);
+  if (normalizedOptions.json.valueEncoding === "typed") {
+    return decodeTypedJsonValue(parsedValue, normalizedOptions.json.typeKey);
+  }
+  return parsedValue;
+}
+function readJsonAttribute(attributes, key) {
+  if (Object.prototype.hasOwnProperty.call(attributes, key)) {
+    return attributes[key];
+  }
+  const lokiNormalizedKey = key.replaceAll(".", "_");
+  return attributes[lokiNormalizedKey];
+}
+function addRawAttributes(attributes, data) {
+  for (const [key, value] of Object.entries(data)) {
+    const rawValue = getRawAttributeValue(value);
+    if (rawValue !== void 0) {
+      attributes[key] = rawValue;
+    }
+  }
+}
+function getRawAttributeValue(value) {
+  if (isScalarAttributeValue(value)) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return getHomogeneousScalarArray(value);
+  }
+  return void 0;
+}
+function isScalarAttributeValue(value) {
+  return typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value);
+}
+function getHomogeneousScalarArray(value) {
+  if (value.length === 0) {
+    return void 0;
+  }
+  if (value.every((item) => typeof item === "string")) {
+    return value;
+  }
+  if (value.every((item) => typeof item === "boolean")) {
+    return value;
+  }
+  if (value.every((item) => typeof item === "number" && Number.isFinite(item))) {
+    return value;
+  }
+  return void 0;
+}
+function addFlattenedAttributes(attributes, data, options) {
+  for (const [key, value] of Object.entries(data)) {
+    addFlattenedValue(attributes, [key], value, options, /* @__PURE__ */ new WeakSet());
+  }
+}
+function addFlattenedValue(attributes, path, value, options, seenObjects) {
+  if (value === null) {
+    addTypeAttribute(attributes, path, "null", options, true);
+    return;
+  }
+  if (value === void 0) {
+    addTypeAttribute(attributes, path, "undefined", options, true);
+    return;
+  }
+  if (typeof value === "string" || typeof value === "boolean") {
+    addValueAttribute(attributes, path, value, options);
+    addTypeAttribute(attributes, path, typeof value, options, false);
+    return;
+  }
+  if (typeof value === "number") {
+    if (Number.isFinite(value)) {
+      addValueAttribute(attributes, path, value, options);
+      addTypeAttribute(attributes, path, "number", options, false);
+    } else {
+      addValueAttribute(attributes, path, String(value), options);
+      addTypeAttribute(attributes, path, "non-finite-number", options, true);
+    }
+    return;
+  }
+  if (typeof value === "bigint") {
+    addValueAttribute(attributes, path, value.toString(), options);
+    addTypeAttribute(attributes, path, "bigint", options, true);
+    return;
+  }
+  if (typeof value === "function") {
+    addTypeAttribute(attributes, path, "function", options, true);
+    return;
+  }
+  if (typeof value === "symbol") {
+    addTypeAttribute(attributes, path, "symbol", options, true);
+    return;
+  }
+  if (value instanceof Date) {
+    addValueAttribute(attributes, path, value.toISOString(), options);
+    addTypeAttribute(attributes, path, "date", options, true);
+    return;
+  }
+  if (value instanceof Error) {
+    addFlattenedError(attributes, path, value, options);
+    return;
+  }
+  if (Array.isArray(value)) {
+    addFlattenedArray(attributes, path, value, options, seenObjects);
+    return;
+  }
+  if (isPlainObject(value)) {
+    addFlattenedObject(attributes, path, value, options, seenObjects);
+    return;
+  }
+  addValueAttribute(attributes, path, String(value), options);
+  addTypeAttribute(attributes, path, "unsupported-object", options, true);
+}
+function addFlattenedError(attributes, path, error, options) {
+  addTypeAttribute(attributes, path, "error", options, true);
+  addValueAttribute(attributes, [...path, "name"], error.name, options);
+  addValueAttribute(attributes, [...path, "message"], error.message, options);
+  if (error.stack !== void 0) {
+    addValueAttribute(attributes, [...path, "stack"], error.stack, options);
+  }
+}
+function addFlattenedArray(attributes, path, value, options, seenObjects) {
+  if (seenObjects.has(value)) {
+    addTypeAttribute(attributes, path, "circular-reference", options, true);
+    return;
+  }
+  if (value.length === 0) {
+    addTypeAttribute(attributes, path, "empty-array", options, true);
+    return;
+  }
+  addTypeAttribute(attributes, path, "array", options, false);
+  seenObjects.add(value);
+  for (const [index, item] of value.entries()) {
+    addFlattenedValue(attributes, [...path, String(index)], item, options, seenObjects);
+  }
+  seenObjects.delete(value);
+}
+function addFlattenedObject(attributes, path, value, options, seenObjects) {
+  if (seenObjects.has(value)) {
+    addTypeAttribute(attributes, path, "circular-reference", options, true);
+    return;
+  }
+  const entries = Object.entries(value);
+  if (entries.length === 0) {
+    addTypeAttribute(attributes, path, "empty-object", options, true);
+    return;
+  }
+  addTypeAttribute(attributes, path, "object", options, false);
+  seenObjects.add(value);
+  for (const [key, nestedValue] of entries) {
+    addFlattenedValue(attributes, [...path, key], nestedValue, options, seenObjects);
+  }
+  seenObjects.delete(value);
+}
+function addValueAttribute(attributes, path, value, options) {
+  attributes[createFlattenedKey(options, options.valuePrefix, path)] = value;
+}
+function addTypeAttribute(attributes, path, typeName, options, needed) {
+  if (options.typeFields === "never") {
+    return;
+  }
+  if (options.typeFields === "when-needed" && !needed) {
+    return;
+  }
+  attributes[createFlattenedKey(options, options.typePrefix, path)] = typeName;
+}
+function createFlattenedKey(options, prefix, path) {
+  return [
+    options.namespace,
+    prefix,
+    ...path
+  ].join(".");
+}
+function encodeTypedJsonValue(value, typeKey, seenObjects) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : createTypedMarker(typeKey, "non-finite-number", { value: String(value) });
+  }
+  if (value === void 0) {
+    return createTypedMarker(typeKey, "undefined");
+  }
+  if (typeof value === "bigint") {
+    return createTypedMarker(typeKey, "bigint", { value: value.toString() });
+  }
+  if (typeof value === "function") {
+    return createTypedMarker(typeKey, "function", value.name ? { name: value.name } : void 0);
+  }
+  if (typeof value === "symbol") {
+    return createTypedMarker(typeKey, "symbol", { value: String(value) });
+  }
+  if (value instanceof Date) {
+    return createTypedMarker(typeKey, "date", { value: value.toISOString() });
+  }
+  if (value instanceof Error) {
+    return createTypedError(typeKey, value);
+  }
+  if (Array.isArray(value)) {
+    return encodeTypedJsonArray(value, typeKey, seenObjects);
+  }
+  if (isPlainObject(value)) {
+    return encodeTypedJsonObject(value, typeKey, seenObjects);
+  }
+  return createTypedMarker(typeKey, "unsupported-object", { value: String(value) });
+}
+function encodeTypedJsonArray(value, typeKey, seenObjects) {
+  if (seenObjects.has(value)) {
+    return createTypedMarker(typeKey, "circular-reference");
+  }
+  seenObjects.add(value);
+  const result = value.map((item) => encodeTypedJsonValue(item, typeKey, seenObjects));
+  seenObjects.delete(value);
+  return result;
+}
+function encodeTypedJsonObject(value, typeKey, seenObjects) {
+  if (seenObjects.has(value)) {
+    return createTypedMarker(typeKey, "circular-reference");
+  }
+  seenObjects.add(value);
+  const result = {};
+  for (const [key, nestedValue] of Object.entries(value)) {
+    result[key] = encodeTypedJsonValue(nestedValue, typeKey, seenObjects);
+  }
+  seenObjects.delete(value);
+  if (Object.prototype.hasOwnProperty.call(result, typeKey)) {
+    return createTypedMarker(typeKey, "object", {
+      value: result
+    });
+  }
+  return result;
+}
+function createTypedError(typeKey, error) {
+  const errorValue = {
+    name: error.name,
+    message: error.message
+  };
+  if (error.stack !== void 0) {
+    errorValue.stack = error.stack;
+  }
+  return createTypedMarker(typeKey, "error", errorValue);
+}
+function createTypedMarker(typeKey, typeName, extra) {
+  return {
+    [typeKey]: typeName,
+    ...extra ?? {}
+  };
+}
+function encodePlainJsonValue(value, seenObjects, inArray) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (value === void 0 || typeof value === "function" || typeof value === "symbol") {
+    return inArray ? null : OMIT_PLAIN_JSON_VALUE;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (value instanceof Error) {
+    return encodePlainJsonError(value);
+  }
+  if (Array.isArray(value)) {
+    return encodePlainJsonArray(value, seenObjects);
+  }
+  if (isPlainObject(value)) {
+    return encodePlainJsonObject(value, seenObjects);
+  }
+  return String(value);
+}
+function encodePlainJsonArray(value, seenObjects) {
+  if (seenObjects.has(value)) {
+    return "[Circular]";
+  }
+  seenObjects.add(value);
+  const result = value.map((item) => {
+    const encodedItem = encodePlainJsonValue(item, seenObjects, true);
+    return encodedItem === OMIT_PLAIN_JSON_VALUE ? null : encodedItem;
+  });
+  seenObjects.delete(value);
+  return result;
+}
+function encodePlainJsonObject(value, seenObjects) {
+  if (seenObjects.has(value)) {
+    return "[Circular]";
+  }
+  seenObjects.add(value);
+  const result = {};
+  for (const [key, nestedValue] of Object.entries(value)) {
+    const encodedValue = encodePlainJsonValue(nestedValue, seenObjects, false);
+    if (encodedValue !== OMIT_PLAIN_JSON_VALUE) {
+      result[key] = encodedValue;
+    }
+  }
+  seenObjects.delete(value);
+  return result;
+}
+function encodePlainJsonError(error) {
+  const result = {
+    name: error.name,
+    message: error.message
+  };
+  if (error.stack !== void 0) {
+    result.stack = error.stack;
+  }
+  return result;
+}
+function decodeTypedJsonValue(value, typeKey) {
+  if (Array.isArray(value)) {
+    return value.map((item) => decodeTypedJsonValue(item, typeKey));
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  const markerType = value[typeKey];
+  if (typeof markerType === "string") {
+    return decodeTypedMarker(markerType, value, typeKey);
+  }
+  const result = {};
+  for (const [key, nestedValue] of Object.entries(value)) {
+    result[key] = decodeTypedJsonValue(nestedValue, typeKey);
+  }
+  return result;
+}
+function decodeTypedMarker(typeName, value, typeKey) {
+  if (typeName === "undefined") {
+    return void 0;
+  }
+  if (typeName === "bigint" && typeof value.value === "string") {
+    return BigInt(value.value);
+  }
+  if (typeName === "date" && typeof value.value === "string") {
+    return new Date(value.value);
+  }
+  if (typeName === "non-finite-number" && typeof value.value === "string") {
+    return Number(value.value);
+  }
+  if (typeName === "error") {
+    return decodeTypedError(value);
+  }
+  if (typeName === "object" && isPlainObject(value.value)) {
+    return decodeTypedJsonValue(value.value, typeKey);
+  }
+  return {
+    ...value,
+    [typeKey]: typeName
+  };
+}
+function decodeTypedError(value) {
+  const message = typeof value.message === "string" ? value.message : "";
+  const error = new Error(message);
+  if (typeof value.name === "string") {
+    error.name = value.name;
+  }
+  if (typeof value.stack === "string") {
+    error.stack = value.stack;
+  }
+  return error;
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export { decodeStructuredMetadata, encodeStructuredMetadata, normalizeStructuredMetadataOptions };

package/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@primafuture/telemetry-structured-metadata",
+	"type": "module",
+	"version": "0.1.0",
+	"description": "Shared structured metadata encoder for PrimaFuture telemetry libraries.",
+	"author": "PrimaFuture.cz s.r.o. <dev@primafuture.cz>",
+	"license": "ISC",
+	"sideEffects": false,
+	"publishConfig": {
+		"access": "public"
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.mjs"
+			},
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			}
+		},
+		"./package.json": "./package.json"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"keywords": [
+		"telemetry",
+		"opentelemetry",
+		"metadata",
+		"structured-logs"
+	],
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsup",
+		"test": "node --import tsx --test __tests__/*.test.ts",
+		"test:package": "node ./__tests__/package-smoke.mjs",
+		"test:audit": "npm audit --omit=dev",
+		"test:pack": "npm pack --dry-run",
+		"typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.dev.json --noEmit",
+		"prepublishOnly": "npm run typecheck && npm test && npm run build && npm run test:package && npm run test:audit && npm run test:pack"
+	},
+	"devDependencies": {
+		"@types/node": "^18.19.0",
+		"tsup": "^8.5.0",
+		"tsx": "^4.20.6",
+		"typescript": "^5.9.2"
+	}
+}