@x12i/provider-metadata 1.0.0 → 1.1.0

package/README.md

@@ -30,6 +30,36 @@ const record = openMetadata(wire);
 
 `record` is the full string map. Another caller map, with different keys, packs and opens the same way.
 
+## Automatic trim
+
+Writers create one packer at initialization. `pack` keeps the record inside 4096 base64 characters. It drops the lowest-priority pair, then the next, and reports every key it removed.
+
+`priority` is highest priority first. Listed keys are kept ahead of keys that are not in the list. An earlier list entry is kept ahead of a later one. Among keys with the same priority, the longest value is dropped first.
+
+```ts
+import { createMetadataPacker, openMetadata } from "@x12i/provider-metadata";
+
+const packer = createMetadataPacker({
+  priority: ["agentId", "orgId", "stepId", "skillId", "recordId", "objectType"]
+});
+
+const packed = packer.pack({
+  objectType: "finding",
+  recordId: "rec-1",
+  note: veryLongText
+});
+
+if (packed.dropped.length) {
+  // packed.dropped lists the keys that did not fit, least important first
+}
+
+const record = openMetadata(packed.wire);
+```
+
+`@x12i/ai-dispatcher` does this on every call. Pass the same list once as `metadataPriority`. A trimmed call adds a `METADATA_RECORD_TRIMMED` warning. `metadataTrimWarning(packed.dropped)` builds that warning from a direct `pack` result.
+
+`packMetadata` does not drop keys. A record that does not fit throws `METADATA_RECORD_TOO_LARGE`.
+
 `packMetadata(...layers)` accepts `Record<string, unknown> | undefined`. Later layers win on the same key. String, number, and boolean values are stored. A number becomes its decimal string, and a boolean becomes `"true"` or `"false"`. Objects and arrays are omitted. When a later value is an object or array, the earlier scalar for that key stays. An empty result is `undefined`.
 
 ## Wire object
@@ -41,7 +71,7 @@ The stored value is UTF-8 JSON of the string map, with keys sorted, then base64.
 | `PROVIDER_METADATA_CHUNK_SIZE` | 256 characters |
 | `PROVIDER_METADATA_MAX_CHUNKS` | 16 |
 
-A larger record throws `METADATA_RECORD_TOO_LARGE` (4096 base64 characters).
+The limit is 4096 base64 characters. `createMetadataPacker` drops pairs until the record fits. `packMetadata` throws `METADATA_RECORD_TOO_LARGE` instead.
 
 `openMetadata` joins `m.0`, `m.1`, … in order, decodes the base64, and returns every string in that JSON object. A missing record, or a value that is not an object, returns `{}`.
 
@@ -54,4 +84,4 @@ These provider slots hold that same object:
 | Bedrock | `requestMetadata` |
 | Cloudflare | Body `metadata` and the `cf-aig-metadata` header |
 
-`@x12i/ai-dispatcher` calls `packMetadata` for the caller. The caller sends one map on the request. The dispatcher writes this object onto the provider that runs the call.
+`@x12i/ai-dispatcher` creates one packer for the caller. The caller sends one map on the request. The dispatcher writes this object onto the provider that runs the call.

package/dist/index.cjs

@@ -20,8 +20,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  METADATA_RECORD_TRIMMED: () => METADATA_RECORD_TRIMMED,
   PROVIDER_METADATA_CHUNK_SIZE: () => PROVIDER_METADATA_CHUNK_SIZE,
   PROVIDER_METADATA_MAX_CHUNKS: () => PROVIDER_METADATA_MAX_CHUNKS,
+  createMetadataPacker: () => createMetadataPacker,
+  metadataTrimWarning: () => metadataTrimWarning,
   openMetadata: () => openMetadata,
   packMetadata: () => packMetadata
 });
@@ -29,16 +32,49 @@ module.exports = __toCommonJS(index_exports);
 var PROVIDER_METADATA_CHUNK_SIZE = 256;
 var PROVIDER_METADATA_MAX_CHUNKS = 16;
 var MAX_ENCODED_LENGTH = PROVIDER_METADATA_CHUNK_SIZE * PROVIDER_METADATA_MAX_CHUNKS;
-function packMetadata(...layers) {
-  const map = {};
-  for (const layer of layers) {
-    if (!layer) continue;
-    for (const [key, value] of Object.entries(layer)) {
-      const asString = asMetadataString(value);
-      if (asString !== void 0) map[key] = asString;
+var METADATA_RECORD_TRIMMED = "METADATA_RECORD_TRIMMED";
+function createMetadataPacker(options) {
+  const priority = [...options?.priority ?? []];
+  const rank = /* @__PURE__ */ new Map();
+  for (let index = 0; index < priority.length; index += 1) {
+    const key = priority[index];
+    if (key !== void 0 && !rank.has(key)) rank.set(key, index);
+  }
+  return {
+    pack(...layers) {
+      const map = collectStrings(layers);
+      const dropped = [];
+      let encoded = encodeProviderRecord(map);
+      while (encoded.tooLarge) {
+        const victim = leastImportantKey(map, rank, priority.length);
+        if (!victim) break;
+        delete map[victim];
+        dropped.push(victim);
+        encoded = encodeProviderRecord(map);
+      }
+      return {
+        ...encoded.wire ? { wire: encoded.wire } : {},
+        dropped
+      };
     }
+  };
+}
+function metadataTrimWarning(dropped) {
+  if (!dropped.length) return void 0;
+  return {
+    code: METADATA_RECORD_TRIMMED,
+    message: `Dropped metadata keys so the provider record fits: ${dropped.join(", ")}.`,
+    details: { dropped: [...dropped] }
+  };
+}
+function packMetadata(...layers) {
+  const encoded = encodeProviderRecord(collectStrings(layers));
+  if (encoded.tooLarge) {
+    throw new Error(
+      `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.encodedLength} base64 characters; the maximum is ${MAX_ENCODED_LENGTH}.`
+    );
   }
-  return encodeProviderRecord(map);
+  return encoded.wire;
 }
 function openMetadata(wire) {
   if (!isRecord(wire)) return {};
@@ -57,29 +93,53 @@ function openMetadata(wire) {
   }
   return record;
 }
+function collectStrings(layers) {
+  const map = {};
+  for (const layer of layers) {
+    if (!layer) continue;
+    for (const [key, value] of Object.entries(layer)) {
+      const asString = asMetadataString(value);
+      if (asString !== void 0) map[key] = asString;
+    }
+  }
+  return map;
+}
 function encodeProviderRecord(map) {
   const keys = Object.keys(map).sort();
-  if (!keys.length) return void 0;
+  if (!keys.length) return { encodedLength: 0, tooLarge: false };
   const ordered = {};
   for (const key of keys) {
     const value = map[key];
     if (value !== void 0) ordered[key] = value;
   }
   const encoded = Buffer.from(JSON.stringify(ordered), "utf8").toString("base64");
-  const chunks = Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE);
-  if (chunks > PROVIDER_METADATA_MAX_CHUNKS) {
-    throw new Error(
-      `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.length} base64 characters; the maximum is ${MAX_ENCODED_LENGTH}.`
-    );
+  if (Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE) > PROVIDER_METADATA_MAX_CHUNKS) {
+    return { encodedLength: encoded.length, tooLarge: true };
   }
   const wire = {};
-  for (let index = 0; index < chunks; index += 1) {
+  for (let index = 0; index < Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE); index += 1) {
     wire[`m.${index}`] = encoded.slice(
       index * PROVIDER_METADATA_CHUNK_SIZE,
       (index + 1) * PROVIDER_METADATA_CHUNK_SIZE
     );
   }
-  return wire;
+  return { wire, encodedLength: encoded.length, tooLarge: false };
+}
+function leastImportantKey(map, rank, unlistedRank) {
+  let chosen;
+  let chosenRank = -1;
+  let chosenSize = -1;
+  for (const [key, value] of Object.entries(map)) {
+    const keyRank = rank.get(key) ?? unlistedRank;
+    const size = value.length;
+    const lessImportant = chosen === void 0 || keyRank > chosenRank || keyRank === chosenRank && size > chosenSize || keyRank === chosenRank && size === chosenSize && key > chosen;
+    if (lessImportant) {
+      chosen = key;
+      chosenRank = keyRank;
+      chosenSize = size;
+    }
+  }
+  return chosen;
 }
 function asMetadataString(value) {
   if (typeof value === "string") return value;
@@ -92,8 +152,11 @@ function isRecord(value) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  METADATA_RECORD_TRIMMED,
   PROVIDER_METADATA_CHUNK_SIZE,
   PROVIDER_METADATA_MAX_CHUNKS,
+  createMetadataPacker,
+  metadataTrimWarning,
   openMetadata,
   packMetadata
 });

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const PROVIDER_METADATA_CHUNK_SIZE = 256;\r\nexport const PROVIDER_METADATA_MAX_CHUNKS = 16;\r\n\r\nconst MAX_ENCODED_LENGTH = PROVIDER_METADATA_CHUNK_SIZE * PROVIDER_METADATA_MAX_CHUNKS;\r\n\r\n/**\r\n * Packs caller maps into one provider metadata object.\r\n * Later layers win on the same key. String, number, and boolean values are stored.\r\n * Numbers and booleans are stored as their string form. Objects and arrays are omitted.\r\n * An empty result is `undefined`.\r\n * The packed object is the same for every provider: `m.0`, `m.1`, and so on.\r\n */\r\nexport function packMetadata(\r\n  ...layers: Array<Record<string, unknown> | undefined>\r\n): Record<string, string> | undefined {\r\n  const map: Record<string, string> = {};\r\n  for (const layer of layers) {\r\n    if (!layer) continue;\r\n    for (const [key, value] of Object.entries(layer)) {\r\n      const asString = asMetadataString(value);\r\n      if (asString !== undefined) map[key] = asString;\r\n    }\r\n  }\r\n  return encodeProviderRecord(map);\r\n}\r\n\r\n/**\r\n * Opens the `m.0`, `m.1`, ... object from a provider log.\r\n * Returns every stored pair. A missing record returns `{}`.\r\n */\r\nexport function openMetadata(wire: unknown): Record<string, string> {\r\n  if (!isRecord(wire)) return {};\r\n  const parts: string[] = [];\r\n  for (let index = 0; ; index += 1) {\r\n    const chunk = wire[`m.${index}`];\r\n    if (typeof chunk !== \"string\") break;\r\n    parts.push(chunk);\r\n  }\r\n  if (!parts.length) return {};\r\n  const parsed: unknown = JSON.parse(Buffer.from(parts.join(\"\"), \"base64\").toString(\"utf8\"));\r\n  if (!isRecord(parsed)) return {};\r\n  const record: Record<string, string> = {};\r\n  for (const [key, value] of Object.entries(parsed)) {\r\n    if (typeof value === \"string\") record[key] = value;\r\n  }\r\n  return record;\r\n}\r\n\r\nfunction encodeProviderRecord(map: Record<string, string>): Record<string, string> | undefined {\r\n  const keys = Object.keys(map).sort();\r\n  if (!keys.length) return undefined;\r\n  const ordered: Record<string, string> = {};\r\n  for (const key of keys) {\r\n    const value = map[key];\r\n    if (value !== undefined) ordered[key] = value;\r\n  }\r\n  const encoded = Buffer.from(JSON.stringify(ordered), \"utf8\").toString(\"base64\");\r\n  const chunks = Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE);\r\n  if (chunks > PROVIDER_METADATA_MAX_CHUNKS) {\r\n    throw new Error(\r\n      `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.length} base64 characters; the maximum is ${MAX_ENCODED_LENGTH}.`\r\n    );\r\n  }\r\n  const wire: Record<string, string> = {};\r\n  for (let index = 0; index < chunks; index += 1) {\r\n    wire[`m.${index}`] = encoded.slice(\r\n      index * PROVIDER_METADATA_CHUNK_SIZE,\r\n      (index + 1) * PROVIDER_METADATA_CHUNK_SIZE\r\n    );\r\n  }\r\n  return wire;\r\n}\r\n\r\nfunction asMetadataString(value: unknown): string | undefined {\r\n  if (typeof value === \"string\") return value;\r\n  if (typeof value === \"boolean\") return value ? \"true\" : \"false\";\r\n  if (typeof value === \"number\" && Number.isFinite(value)) return String(value);\r\n  return undefined;\r\n}\r\n\r\nfunction isRecord(value: unknown): value is Record<string, unknown> {\r\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,IAAM,+BAA+B;AACrC,IAAM,+BAA+B;AAE5C,IAAM,qBAAqB,+BAA+B;AASnD,SAAS,gBACX,QACiC;AACpC,QAAM,MAA8B,CAAC;AACrC,aAAW,SAAS,QAAQ;AAC1B,QAAI,CAAC,MAAO;AACZ,eAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,YAAM,WAAW,iBAAiB,KAAK;AACvC,UAAI,aAAa,OAAW,KAAI,GAAG,IAAI;AAAA,IACzC;AAAA,EACF;AACA,SAAO,qBAAqB,GAAG;AACjC;AAMO,SAAS,aAAa,MAAuC;AAClE,MAAI,CAAC,SAAS,IAAI,EAAG,QAAO,CAAC;AAC7B,QAAM,QAAkB,CAAC;AACzB,WAAS,QAAQ,KAAK,SAAS,GAAG;AAChC,UAAM,QAAQ,KAAK,KAAK,KAAK,EAAE;AAC/B,QAAI,OAAO,UAAU,SAAU;AAC/B,UAAM,KAAK,KAAK;AAAA,EAClB;AACA,MAAI,CAAC,MAAM,OAAQ,QAAO,CAAC;AAC3B,QAAM,SAAkB,KAAK,MAAM,OAAO,KAAK,MAAM,KAAK,EAAE,GAAG,QAAQ,EAAE,SAAS,MAAM,CAAC;AACzF,MAAI,CAAC,SAAS,MAAM,EAAG,QAAO,CAAC;AAC/B,QAAM,SAAiC,CAAC;AACxC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AACjD,QAAI,OAAO,UAAU,SAAU,QAAO,GAAG,IAAI;AAAA,EAC/C;AACA,SAAO;AACT;AAEA,SAAS,qBAAqB,KAAiE;AAC7F,QAAM,OAAO,OAAO,KAAK,GAAG,EAAE,KAAK;AACnC,MAAI,CAAC,KAAK,OAAQ,QAAO;AACzB,QAAM,UAAkC,CAAC;AACzC,aAAW,OAAO,MAAM;AACtB,UAAM,QAAQ,IAAI,GAAG;AACrB,QAAI,UAAU,OAAW,SAAQ,GAAG,IAAI;AAAA,EAC1C;AACA,QAAM,UAAU,OAAO,KAAK,KAAK,UAAU,OAAO,GAAG,MAAM,EAAE,SAAS,QAAQ;AAC9E,QAAM,SAAS,KAAK,KAAK,QAAQ,SAAS,4BAA4B;AACtE,MAAI,SAAS,8BAA8B;AACzC,UAAM,IAAI;AAAA,MACR,mDAAmD,QAAQ,MAAM,sCAAsC,kBAAkB;AAAA,IAC3H;AAAA,EACF;AACA,QAAM,OAA+B,CAAC;AACtC,WAAS,QAAQ,GAAG,QAAQ,QAAQ,SAAS,GAAG;AAC9C,SAAK,KAAK,KAAK,EAAE,IAAI,QAAQ;AAAA,MAC3B,QAAQ;AAAA,OACP,QAAQ,KAAK;AAAA,IAChB;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,iBAAiB,OAAoC;AAC5D,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,MAAI,OAAO,UAAU,UAAW,QAAO,QAAQ,SAAS;AACxD,MAAI,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,EAAG,QAAO,OAAO,KAAK;AAC5E,SAAO;AACT;AAEA,SAAS,SAAS,OAAkD;AAClE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const PROVIDER_METADATA_CHUNK_SIZE = 256;\r\nexport const PROVIDER_METADATA_MAX_CHUNKS = 16;\r\n\r\nconst MAX_ENCODED_LENGTH = PROVIDER_METADATA_CHUNK_SIZE * PROVIDER_METADATA_MAX_CHUNKS;\r\n\r\nexport const METADATA_RECORD_TRIMMED = \"METADATA_RECORD_TRIMMED\";\r\n\r\nexport interface MetadataPackerOptions {\r\n  /**\r\n   * Highest priority first.\r\n   * Listed keys are kept ahead of every key that is not in the list.\r\n   * Within the list, an earlier key is kept ahead of a later key.\r\n   */\r\n  priority?: readonly string[];\r\n}\r\n\r\nexport interface PackedMetadata {\r\n  /** Provider wire object. Omitted when the map is empty or every pair was dropped. */\r\n  wire?: Record<string, string>;\r\n  /** Keys removed so the record fits, least important first. Empty when nothing was dropped. */\r\n  dropped: readonly string[];\r\n}\r\n\r\nexport interface MetadataTrimWarning {\r\n  code: typeof METADATA_RECORD_TRIMMED;\r\n  message: string;\r\n  details: { dropped: string[] };\r\n}\r\n\r\nexport interface MetadataPacker {\r\n  pack(...layers: Array<Record<string, unknown> | undefined>): PackedMetadata;\r\n}\r\n\r\n/**\r\n * One packer for a process.\r\n * Pass the priority list here. Every `pack` call trims to the provider limit and reports dropped keys.\r\n */\r\nexport function createMetadataPacker(options?: MetadataPackerOptions): MetadataPacker {\r\n  const priority = [...(options?.priority ?? [])];\r\n  const rank = new Map<string, number>();\r\n  for (let index = 0; index < priority.length; index += 1) {\r\n    const key = priority[index];\r\n    if (key !== undefined && !rank.has(key)) rank.set(key, index);\r\n  }\r\n\r\n  return {\r\n    pack(...layers) {\r\n      const map = collectStrings(layers);\r\n      const dropped: string[] = [];\r\n      let encoded = encodeProviderRecord(map);\r\n      while (encoded.tooLarge) {\r\n        const victim = leastImportantKey(map, rank, priority.length);\r\n        if (!victim) break;\r\n        delete map[victim];\r\n        dropped.push(victim);\r\n        encoded = encodeProviderRecord(map);\r\n      }\r\n      return {\r\n        ...(encoded.wire ? { wire: encoded.wire } : {}),\r\n        dropped\r\n      };\r\n    }\r\n  };\r\n}\r\n\r\n/** Warning for a pack that had to drop keys. Omitted when nothing was dropped. */\r\nexport function metadataTrimWarning(dropped: readonly string[]): MetadataTrimWarning | undefined {\r\n  if (!dropped.length) return undefined;\r\n  return {\r\n    code: METADATA_RECORD_TRIMMED,\r\n    message: `Dropped metadata keys so the provider record fits: ${dropped.join(\", \")}.`,\r\n    details: { dropped: [...dropped] }\r\n  };\r\n}\r\n\r\n/**\r\n * Packs caller maps into one provider metadata object.\r\n * Later layers win on the same key. String, number, and boolean values are stored.\r\n * Numbers and booleans are stored as their string form. Objects and arrays are omitted.\r\n * An empty result is `undefined`.\r\n * A record over the size limit throws `METADATA_RECORD_TOO_LARGE`.\r\n * Writers that should drop pairs instead use `createMetadataPacker`.\r\n * The packed object is the same for every provider: `m.0`, `m.1`, and so on.\r\n */\r\nexport function packMetadata(\r\n  ...layers: Array<Record<string, unknown> | undefined>\r\n): Record<string, string> | undefined {\r\n  const encoded = encodeProviderRecord(collectStrings(layers));\r\n  if (encoded.tooLarge) {\r\n    throw new Error(\r\n      `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.encodedLength} base64 characters; the maximum is ${MAX_ENCODED_LENGTH}.`\r\n    );\r\n  }\r\n  return encoded.wire;\r\n}\r\n\r\n/**\r\n * Opens the `m.0`, `m.1`, ... object from a provider log.\r\n * Returns every stored pair. A missing record returns `{}`.\r\n */\r\nexport function openMetadata(wire: unknown): Record<string, string> {\r\n  if (!isRecord(wire)) return {};\r\n  const parts: string[] = [];\r\n  for (let index = 0; ; index += 1) {\r\n    const chunk = wire[`m.${index}`];\r\n    if (typeof chunk !== \"string\") break;\r\n    parts.push(chunk);\r\n  }\r\n  if (!parts.length) return {};\r\n  const parsed: unknown = JSON.parse(Buffer.from(parts.join(\"\"), \"base64\").toString(\"utf8\"));\r\n  if (!isRecord(parsed)) return {};\r\n  const record: Record<string, string> = {};\r\n  for (const [key, value] of Object.entries(parsed)) {\r\n    if (typeof value === \"string\") record[key] = value;\r\n  }\r\n  return record;\r\n}\r\n\r\nfunction collectStrings(layers: Array<Record<string, unknown> | undefined>): Record<string, string> {\r\n  const map: Record<string, string> = {};\r\n  for (const layer of layers) {\r\n    if (!layer) continue;\r\n    for (const [key, value] of Object.entries(layer)) {\r\n      const asString = asMetadataString(value);\r\n      if (asString !== undefined) map[key] = asString;\r\n    }\r\n  }\r\n  return map;\r\n}\r\n\r\nfunction encodeProviderRecord(map: Record<string, string>): {\r\n  wire?: Record<string, string>;\r\n  encodedLength: number;\r\n  tooLarge: boolean;\r\n} {\r\n  const keys = Object.keys(map).sort();\r\n  if (!keys.length) return { encodedLength: 0, tooLarge: false };\r\n  const ordered: Record<string, string> = {};\r\n  for (const key of keys) {\r\n    const value = map[key];\r\n    if (value !== undefined) ordered[key] = value;\r\n  }\r\n  const encoded = Buffer.from(JSON.stringify(ordered), \"utf8\").toString(\"base64\");\r\n  if (Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE) > PROVIDER_METADATA_MAX_CHUNKS) {\r\n    return { encodedLength: encoded.length, tooLarge: true };\r\n  }\r\n  const wire: Record<string, string> = {};\r\n  for (let index = 0; index < Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE); index += 1) {\r\n    wire[`m.${index}`] = encoded.slice(\r\n      index * PROVIDER_METADATA_CHUNK_SIZE,\r\n      (index + 1) * PROVIDER_METADATA_CHUNK_SIZE\r\n    );\r\n  }\r\n  return { wire, encodedLength: encoded.length, tooLarge: false };\r\n}\r\n\r\nfunction leastImportantKey(\r\n  map: Record<string, string>,\r\n  rank: Map<string, number>,\r\n  unlistedRank: number\r\n): string | undefined {\r\n  let chosen: string | undefined;\r\n  let chosenRank = -1;\r\n  let chosenSize = -1;\r\n  for (const [key, value] of Object.entries(map)) {\r\n    const keyRank = rank.get(key) ?? unlistedRank;\r\n    const size = value.length;\r\n    const lessImportant = chosen === undefined\r\n      || keyRank > chosenRank\r\n      || (keyRank === chosenRank && size > chosenSize)\r\n      || (keyRank === chosenRank && size === chosenSize && key > chosen);\r\n    if (lessImportant) {\r\n      chosen = key;\r\n      chosenRank = keyRank;\r\n      chosenSize = size;\r\n    }\r\n  }\r\n  return chosen;\r\n}\r\n\r\nfunction asMetadataString(value: unknown): string | undefined {\r\n  if (typeof value === \"string\") return value;\r\n  if (typeof value === \"boolean\") return value ? \"true\" : \"false\";\r\n  if (typeof value === \"number\" && Number.isFinite(value)) return String(value);\r\n  return undefined;\r\n}\r\n\r\nfunction isRecord(value: unknown): value is Record<string, unknown> {\r\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\r\n}\r\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -1,10 +1,44 @@
 declare const PROVIDER_METADATA_CHUNK_SIZE = 256;
 declare const PROVIDER_METADATA_MAX_CHUNKS = 16;
+declare const METADATA_RECORD_TRIMMED = "METADATA_RECORD_TRIMMED";
+interface MetadataPackerOptions {
+    /**
+     * Highest priority first.
+     * Listed keys are kept ahead of every key that is not in the list.
+     * Within the list, an earlier key is kept ahead of a later key.
+     */
+    priority?: readonly string[];
+}
+interface PackedMetadata {
+    /** Provider wire object. Omitted when the map is empty or every pair was dropped. */
+    wire?: Record<string, string>;
+    /** Keys removed so the record fits, least important first. Empty when nothing was dropped. */
+    dropped: readonly string[];
+}
+interface MetadataTrimWarning {
+    code: typeof METADATA_RECORD_TRIMMED;
+    message: string;
+    details: {
+        dropped: string[];
+    };
+}
+interface MetadataPacker {
+    pack(...layers: Array<Record<string, unknown> | undefined>): PackedMetadata;
+}
+/**
+ * One packer for a process.
+ * Pass the priority list here. Every `pack` call trims to the provider limit and reports dropped keys.
+ */
+declare function createMetadataPacker(options?: MetadataPackerOptions): MetadataPacker;
+/** Warning for a pack that had to drop keys. Omitted when nothing was dropped. */
+declare function metadataTrimWarning(dropped: readonly string[]): MetadataTrimWarning | undefined;
 /**
  * Packs caller maps into one provider metadata object.
  * Later layers win on the same key. String, number, and boolean values are stored.
  * Numbers and booleans are stored as their string form. Objects and arrays are omitted.
  * An empty result is `undefined`.
+ * A record over the size limit throws `METADATA_RECORD_TOO_LARGE`.
+ * Writers that should drop pairs instead use `createMetadataPacker`.
  * The packed object is the same for every provider: `m.0`, `m.1`, and so on.
  */
 declare function packMetadata(...layers: Array<Record<string, unknown> | undefined>): Record<string, string> | undefined;
@@ -14,4 +48,4 @@ declare function packMetadata(...layers: Array<Record<string, unknown> | undefin
  */
 declare function openMetadata(wire: unknown): Record<string, string>;
 
-export { PROVIDER_METADATA_CHUNK_SIZE, PROVIDER_METADATA_MAX_CHUNKS, openMetadata, packMetadata };
+export { METADATA_RECORD_TRIMMED, type MetadataPacker, type MetadataPackerOptions, type MetadataTrimWarning, PROVIDER_METADATA_CHUNK_SIZE, PROVIDER_METADATA_MAX_CHUNKS, type PackedMetadata, createMetadataPacker, metadataTrimWarning, openMetadata, packMetadata };

package/dist/index.d.ts

@@ -1,10 +1,44 @@
 declare const PROVIDER_METADATA_CHUNK_SIZE = 256;
 declare const PROVIDER_METADATA_MAX_CHUNKS = 16;
+declare const METADATA_RECORD_TRIMMED = "METADATA_RECORD_TRIMMED";
+interface MetadataPackerOptions {
+    /**
+     * Highest priority first.
+     * Listed keys are kept ahead of every key that is not in the list.
+     * Within the list, an earlier key is kept ahead of a later key.
+     */
+    priority?: readonly string[];
+}
+interface PackedMetadata {
+    /** Provider wire object. Omitted when the map is empty or every pair was dropped. */
+    wire?: Record<string, string>;
+    /** Keys removed so the record fits, least important first. Empty when nothing was dropped. */
+    dropped: readonly string[];
+}
+interface MetadataTrimWarning {
+    code: typeof METADATA_RECORD_TRIMMED;
+    message: string;
+    details: {
+        dropped: string[];
+    };
+}
+interface MetadataPacker {
+    pack(...layers: Array<Record<string, unknown> | undefined>): PackedMetadata;
+}
+/**
+ * One packer for a process.
+ * Pass the priority list here. Every `pack` call trims to the provider limit and reports dropped keys.
+ */
+declare function createMetadataPacker(options?: MetadataPackerOptions): MetadataPacker;
+/** Warning for a pack that had to drop keys. Omitted when nothing was dropped. */
+declare function metadataTrimWarning(dropped: readonly string[]): MetadataTrimWarning | undefined;
 /**
  * Packs caller maps into one provider metadata object.
  * Later layers win on the same key. String, number, and boolean values are stored.
  * Numbers and booleans are stored as their string form. Objects and arrays are omitted.
  * An empty result is `undefined`.
+ * A record over the size limit throws `METADATA_RECORD_TOO_LARGE`.
+ * Writers that should drop pairs instead use `createMetadataPacker`.
  * The packed object is the same for every provider: `m.0`, `m.1`, and so on.
  */
 declare function packMetadata(...layers: Array<Record<string, unknown> | undefined>): Record<string, string> | undefined;
@@ -14,4 +48,4 @@ declare function packMetadata(...layers: Array<Record<string, unknown> | undefin
  */
 declare function openMetadata(wire: unknown): Record<string, string>;
 
-export { PROVIDER_METADATA_CHUNK_SIZE, PROVIDER_METADATA_MAX_CHUNKS, openMetadata, packMetadata };
+export { METADATA_RECORD_TRIMMED, type MetadataPacker, type MetadataPackerOptions, type MetadataTrimWarning, PROVIDER_METADATA_CHUNK_SIZE, PROVIDER_METADATA_MAX_CHUNKS, type PackedMetadata, createMetadataPacker, metadataTrimWarning, openMetadata, packMetadata };

package/dist/index.js

@@ -2,16 +2,49 @@
 var PROVIDER_METADATA_CHUNK_SIZE = 256;
 var PROVIDER_METADATA_MAX_CHUNKS = 16;
 var MAX_ENCODED_LENGTH = PROVIDER_METADATA_CHUNK_SIZE * PROVIDER_METADATA_MAX_CHUNKS;
-function packMetadata(...layers) {
-  const map = {};
-  for (const layer of layers) {
-    if (!layer) continue;
-    for (const [key, value] of Object.entries(layer)) {
-      const asString = asMetadataString(value);
-      if (asString !== void 0) map[key] = asString;
+var METADATA_RECORD_TRIMMED = "METADATA_RECORD_TRIMMED";
+function createMetadataPacker(options) {
+  const priority = [...options?.priority ?? []];
+  const rank = /* @__PURE__ */ new Map();
+  for (let index = 0; index < priority.length; index += 1) {
+    const key = priority[index];
+    if (key !== void 0 && !rank.has(key)) rank.set(key, index);
+  }
+  return {
+    pack(...layers) {
+      const map = collectStrings(layers);
+      const dropped = [];
+      let encoded = encodeProviderRecord(map);
+      while (encoded.tooLarge) {
+        const victim = leastImportantKey(map, rank, priority.length);
+        if (!victim) break;
+        delete map[victim];
+        dropped.push(victim);
+        encoded = encodeProviderRecord(map);
+      }
+      return {
+        ...encoded.wire ? { wire: encoded.wire } : {},
+        dropped
+      };
     }
+  };
+}
+function metadataTrimWarning(dropped) {
+  if (!dropped.length) return void 0;
+  return {
+    code: METADATA_RECORD_TRIMMED,
+    message: `Dropped metadata keys so the provider record fits: ${dropped.join(", ")}.`,
+    details: { dropped: [...dropped] }
+  };
+}
+function packMetadata(...layers) {
+  const encoded = encodeProviderRecord(collectStrings(layers));
+  if (encoded.tooLarge) {
+    throw new Error(
+      `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.encodedLength} base64 characters; the maximum is ${MAX_ENCODED_LENGTH}.`
+    );
   }
-  return encodeProviderRecord(map);
+  return encoded.wire;
 }
 function openMetadata(wire) {
   if (!isRecord(wire)) return {};
@@ -30,29 +63,53 @@ function openMetadata(wire) {
   }
   return record;
 }
+function collectStrings(layers) {
+  const map = {};
+  for (const layer of layers) {
+    if (!layer) continue;
+    for (const [key, value] of Object.entries(layer)) {
+      const asString = asMetadataString(value);
+      if (asString !== void 0) map[key] = asString;
+    }
+  }
+  return map;
+}
 function encodeProviderRecord(map) {
   const keys = Object.keys(map).sort();
-  if (!keys.length) return void 0;
+  if (!keys.length) return { encodedLength: 0, tooLarge: false };
   const ordered = {};
   for (const key of keys) {
     const value = map[key];
     if (value !== void 0) ordered[key] = value;
   }
   const encoded = Buffer.from(JSON.stringify(ordered), "utf8").toString("base64");
-  const chunks = Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE);
-  if (chunks > PROVIDER_METADATA_MAX_CHUNKS) {
-    throw new Error(
-      `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.length} base64 characters; the maximum is ${MAX_ENCODED_LENGTH}.`
-    );
+  if (Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE) > PROVIDER_METADATA_MAX_CHUNKS) {
+    return { encodedLength: encoded.length, tooLarge: true };
   }
   const wire = {};
-  for (let index = 0; index < chunks; index += 1) {
+  for (let index = 0; index < Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE); index += 1) {
     wire[`m.${index}`] = encoded.slice(
       index * PROVIDER_METADATA_CHUNK_SIZE,
       (index + 1) * PROVIDER_METADATA_CHUNK_SIZE
     );
   }
-  return wire;
+  return { wire, encodedLength: encoded.length, tooLarge: false };
+}
+function leastImportantKey(map, rank, unlistedRank) {
+  let chosen;
+  let chosenRank = -1;
+  let chosenSize = -1;
+  for (const [key, value] of Object.entries(map)) {
+    const keyRank = rank.get(key) ?? unlistedRank;
+    const size = value.length;
+    const lessImportant = chosen === void 0 || keyRank > chosenRank || keyRank === chosenRank && size > chosenSize || keyRank === chosenRank && size === chosenSize && key > chosen;
+    if (lessImportant) {
+      chosen = key;
+      chosenRank = keyRank;
+      chosenSize = size;
+    }
+  }
+  return chosen;
 }
 function asMetadataString(value) {
   if (typeof value === "string") return value;
@@ -64,8 +121,11 @@ function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 export {
+  METADATA_RECORD_TRIMMED,
   PROVIDER_METADATA_CHUNK_SIZE,
   PROVIDER_METADATA_MAX_CHUNKS,
+  createMetadataPacker,
+  metadataTrimWarning,
   openMetadata,
   packMetadata
 };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const PROVIDER_METADATA_CHUNK_SIZE = 256;\r\nexport const PROVIDER_METADATA_MAX_CHUNKS = 16;\r\n\r\nconst MAX_ENCODED_LENGTH = PROVIDER_METADATA_CHUNK_SIZE * PROVIDER_METADATA_MAX_CHUNKS;\r\n\r\n/**\r\n * Packs caller maps into one provider metadata object.\r\n * Later layers win on the same key. String, number, and boolean values are stored.\r\n * Numbers and booleans are stored as their string form. Objects and arrays are omitted.\r\n * An empty result is `undefined`.\r\n * The packed object is the same for every provider: `m.0`, `m.1`, and so on.\r\n */\r\nexport function packMetadata(\r\n  ...layers: Array<Record<string, unknown> | undefined>\r\n): Record<string, string> | undefined {\r\n  const map: Record<string, string> = {};\r\n  for (const layer of layers) {\r\n    if (!layer) continue;\r\n    for (const [key, value] of Object.entries(layer)) {\r\n      const asString = asMetadataString(value);\r\n      if (asString !== undefined) map[key] = asString;\r\n    }\r\n  }\r\n  return encodeProviderRecord(map);\r\n}\r\n\r\n/**\r\n * Opens the `m.0`, `m.1`, ... object from a provider log.\r\n * Returns every stored pair. A missing record returns `{}`.\r\n */\r\nexport function openMetadata(wire: unknown): Record<string, string> {\r\n  if (!isRecord(wire)) return {};\r\n  const parts: string[] = [];\r\n  for (let index = 0; ; index += 1) {\r\n    const chunk = wire[`m.${index}`];\r\n    if (typeof chunk !== \"string\") break;\r\n    parts.push(chunk);\r\n  }\r\n  if (!parts.length) return {};\r\n  const parsed: unknown = JSON.parse(Buffer.from(parts.join(\"\"), \"base64\").toString(\"utf8\"));\r\n  if (!isRecord(parsed)) return {};\r\n  const record: Record<string, string> = {};\r\n  for (const [key, value] of Object.entries(parsed)) {\r\n    if (typeof value === \"string\") record[key] = value;\r\n  }\r\n  return record;\r\n}\r\n\r\nfunction encodeProviderRecord(map: Record<string, string>): Record<string, string> | undefined {\r\n  const keys = Object.keys(map).sort();\r\n  if (!keys.length) return undefined;\r\n  const ordered: Record<string, string> = {};\r\n  for (const key of keys) {\r\n    const value = map[key];\r\n    if (value !== undefined) ordered[key] = value;\r\n  }\r\n  const encoded = Buffer.from(JSON.stringify(ordered), \"utf8\").toString(\"base64\");\r\n  const chunks = Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE);\r\n  if (chunks > PROVIDER_METADATA_MAX_CHUNKS) {\r\n    throw new Error(\r\n      `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.length} base64 characters; the maximum is ${MAX_ENCODED_LENGTH}.`\r\n    );\r\n  }\r\n  const wire: Record<string, string> = {};\r\n  for (let index = 0; index < chunks; index += 1) {\r\n    wire[`m.${index}`] = encoded.slice(\r\n      index * PROVIDER_METADATA_CHUNK_SIZE,\r\n      (index + 1) * PROVIDER_METADATA_CHUNK_SIZE\r\n    );\r\n  }\r\n  return wire;\r\n}\r\n\r\nfunction asMetadataString(value: unknown): string | undefined {\r\n  if (typeof value === \"string\") return value;\r\n  if (typeof value === \"boolean\") return value ? \"true\" : \"false\";\r\n  if (typeof value === \"number\" && Number.isFinite(value)) return String(value);\r\n  return undefined;\r\n}\r\n\r\nfunction isRecord(value: unknown): value is Record<string, unknown> {\r\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\r\n}\r\n"],"mappings":";AAAO,IAAM,+BAA+B;AACrC,IAAM,+BAA+B;AAE5C,IAAM,qBAAqB,+BAA+B;AASnD,SAAS,gBACX,QACiC;AACpC,QAAM,MAA8B,CAAC;AACrC,aAAW,SAAS,QAAQ;AAC1B,QAAI,CAAC,MAAO;AACZ,eAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,YAAM,WAAW,iBAAiB,KAAK;AACvC,UAAI,aAAa,OAAW,KAAI,GAAG,IAAI;AAAA,IACzC;AAAA,EACF;AACA,SAAO,qBAAqB,GAAG;AACjC;AAMO,SAAS,aAAa,MAAuC;AAClE,MAAI,CAAC,SAAS,IAAI,EAAG,QAAO,CAAC;AAC7B,QAAM,QAAkB,CAAC;AACzB,WAAS,QAAQ,KAAK,SAAS,GAAG;AAChC,UAAM,QAAQ,KAAK,KAAK,KAAK,EAAE;AAC/B,QAAI,OAAO,UAAU,SAAU;AAC/B,UAAM,KAAK,KAAK;AAAA,EAClB;AACA,MAAI,CAAC,MAAM,OAAQ,QAAO,CAAC;AAC3B,QAAM,SAAkB,KAAK,MAAM,OAAO,KAAK,MAAM,KAAK,EAAE,GAAG,QAAQ,EAAE,SAAS,MAAM,CAAC;AACzF,MAAI,CAAC,SAAS,MAAM,EAAG,QAAO,CAAC;AAC/B,QAAM,SAAiC,CAAC;AACxC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AACjD,QAAI,OAAO,UAAU,SAAU,QAAO,GAAG,IAAI;AAAA,EAC/C;AACA,SAAO;AACT;AAEA,SAAS,qBAAqB,KAAiE;AAC7F,QAAM,OAAO,OAAO,KAAK,GAAG,EAAE,KAAK;AACnC,MAAI,CAAC,KAAK,OAAQ,QAAO;AACzB,QAAM,UAAkC,CAAC;AACzC,aAAW,OAAO,MAAM;AACtB,UAAM,QAAQ,IAAI,GAAG;AACrB,QAAI,UAAU,OAAW,SAAQ,GAAG,IAAI;AAAA,EAC1C;AACA,QAAM,UAAU,OAAO,KAAK,KAAK,UAAU,OAAO,GAAG,MAAM,EAAE,SAAS,QAAQ;AAC9E,QAAM,SAAS,KAAK,KAAK,QAAQ,SAAS,4BAA4B;AACtE,MAAI,SAAS,8BAA8B;AACzC,UAAM,IAAI;AAAA,MACR,mDAAmD,QAAQ,MAAM,sCAAsC,kBAAkB;AAAA,IAC3H;AAAA,EACF;AACA,QAAM,OAA+B,CAAC;AACtC,WAAS,QAAQ,GAAG,QAAQ,QAAQ,SAAS,GAAG;AAC9C,SAAK,KAAK,KAAK,EAAE,IAAI,QAAQ;AAAA,MAC3B,QAAQ;AAAA,OACP,QAAQ,KAAK;AAAA,IAChB;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,iBAAiB,OAAoC;AAC5D,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,MAAI,OAAO,UAAU,UAAW,QAAO,QAAQ,SAAS;AACxD,MAAI,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,EAAG,QAAO,OAAO,KAAK;AAC5E,SAAO;AACT;AAEA,SAAS,SAAS,OAAkD;AAClE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const PROVIDER_METADATA_CHUNK_SIZE = 256;\r\nexport const PROVIDER_METADATA_MAX_CHUNKS = 16;\r\n\r\nconst MAX_ENCODED_LENGTH = PROVIDER_METADATA_CHUNK_SIZE * PROVIDER_METADATA_MAX_CHUNKS;\r\n\r\nexport const METADATA_RECORD_TRIMMED = \"METADATA_RECORD_TRIMMED\";\r\n\r\nexport interface MetadataPackerOptions {\r\n  /**\r\n   * Highest priority first.\r\n   * Listed keys are kept ahead of every key that is not in the list.\r\n   * Within the list, an earlier key is kept ahead of a later key.\r\n   */\r\n  priority?: readonly string[];\r\n}\r\n\r\nexport interface PackedMetadata {\r\n  /** Provider wire object. Omitted when the map is empty or every pair was dropped. */\r\n  wire?: Record<string, string>;\r\n  /** Keys removed so the record fits, least important first. Empty when nothing was dropped. */\r\n  dropped: readonly string[];\r\n}\r\n\r\nexport interface MetadataTrimWarning {\r\n  code: typeof METADATA_RECORD_TRIMMED;\r\n  message: string;\r\n  details: { dropped: string[] };\r\n}\r\n\r\nexport interface MetadataPacker {\r\n  pack(...layers: Array<Record<string, unknown> | undefined>): PackedMetadata;\r\n}\r\n\r\n/**\r\n * One packer for a process.\r\n * Pass the priority list here. Every `pack` call trims to the provider limit and reports dropped keys.\r\n */\r\nexport function createMetadataPacker(options?: MetadataPackerOptions): MetadataPacker {\r\n  const priority = [...(options?.priority ?? [])];\r\n  const rank = new Map<string, number>();\r\n  for (let index = 0; index < priority.length; index += 1) {\r\n    const key = priority[index];\r\n    if (key !== undefined && !rank.has(key)) rank.set(key, index);\r\n  }\r\n\r\n  return {\r\n    pack(...layers) {\r\n      const map = collectStrings(layers);\r\n      const dropped: string[] = [];\r\n      let encoded = encodeProviderRecord(map);\r\n      while (encoded.tooLarge) {\r\n        const victim = leastImportantKey(map, rank, priority.length);\r\n        if (!victim) break;\r\n        delete map[victim];\r\n        dropped.push(victim);\r\n        encoded = encodeProviderRecord(map);\r\n      }\r\n      return {\r\n        ...(encoded.wire ? { wire: encoded.wire } : {}),\r\n        dropped\r\n      };\r\n    }\r\n  };\r\n}\r\n\r\n/** Warning for a pack that had to drop keys. Omitted when nothing was dropped. */\r\nexport function metadataTrimWarning(dropped: readonly string[]): MetadataTrimWarning | undefined {\r\n  if (!dropped.length) return undefined;\r\n  return {\r\n    code: METADATA_RECORD_TRIMMED,\r\n    message: `Dropped metadata keys so the provider record fits: ${dropped.join(\", \")}.`,\r\n    details: { dropped: [...dropped] }\r\n  };\r\n}\r\n\r\n/**\r\n * Packs caller maps into one provider metadata object.\r\n * Later layers win on the same key. String, number, and boolean values are stored.\r\n * Numbers and booleans are stored as their string form. Objects and arrays are omitted.\r\n * An empty result is `undefined`.\r\n * A record over the size limit throws `METADATA_RECORD_TOO_LARGE`.\r\n * Writers that should drop pairs instead use `createMetadataPacker`.\r\n * The packed object is the same for every provider: `m.0`, `m.1`, and so on.\r\n */\r\nexport function packMetadata(\r\n  ...layers: Array<Record<string, unknown> | undefined>\r\n): Record<string, string> | undefined {\r\n  const encoded = encodeProviderRecord(collectStrings(layers));\r\n  if (encoded.tooLarge) {\r\n    throw new Error(\r\n      `METADATA_RECORD_TOO_LARGE: provider metadata is ${encoded.encodedLength} base64 characters; the maximum is ${MAX_ENCODED_LENGTH}.`\r\n    );\r\n  }\r\n  return encoded.wire;\r\n}\r\n\r\n/**\r\n * Opens the `m.0`, `m.1`, ... object from a provider log.\r\n * Returns every stored pair. A missing record returns `{}`.\r\n */\r\nexport function openMetadata(wire: unknown): Record<string, string> {\r\n  if (!isRecord(wire)) return {};\r\n  const parts: string[] = [];\r\n  for (let index = 0; ; index += 1) {\r\n    const chunk = wire[`m.${index}`];\r\n    if (typeof chunk !== \"string\") break;\r\n    parts.push(chunk);\r\n  }\r\n  if (!parts.length) return {};\r\n  const parsed: unknown = JSON.parse(Buffer.from(parts.join(\"\"), \"base64\").toString(\"utf8\"));\r\n  if (!isRecord(parsed)) return {};\r\n  const record: Record<string, string> = {};\r\n  for (const [key, value] of Object.entries(parsed)) {\r\n    if (typeof value === \"string\") record[key] = value;\r\n  }\r\n  return record;\r\n}\r\n\r\nfunction collectStrings(layers: Array<Record<string, unknown> | undefined>): Record<string, string> {\r\n  const map: Record<string, string> = {};\r\n  for (const layer of layers) {\r\n    if (!layer) continue;\r\n    for (const [key, value] of Object.entries(layer)) {\r\n      const asString = asMetadataString(value);\r\n      if (asString !== undefined) map[key] = asString;\r\n    }\r\n  }\r\n  return map;\r\n}\r\n\r\nfunction encodeProviderRecord(map: Record<string, string>): {\r\n  wire?: Record<string, string>;\r\n  encodedLength: number;\r\n  tooLarge: boolean;\r\n} {\r\n  const keys = Object.keys(map).sort();\r\n  if (!keys.length) return { encodedLength: 0, tooLarge: false };\r\n  const ordered: Record<string, string> = {};\r\n  for (const key of keys) {\r\n    const value = map[key];\r\n    if (value !== undefined) ordered[key] = value;\r\n  }\r\n  const encoded = Buffer.from(JSON.stringify(ordered), \"utf8\").toString(\"base64\");\r\n  if (Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE) > PROVIDER_METADATA_MAX_CHUNKS) {\r\n    return { encodedLength: encoded.length, tooLarge: true };\r\n  }\r\n  const wire: Record<string, string> = {};\r\n  for (let index = 0; index < Math.ceil(encoded.length / PROVIDER_METADATA_CHUNK_SIZE); index += 1) {\r\n    wire[`m.${index}`] = encoded.slice(\r\n      index * PROVIDER_METADATA_CHUNK_SIZE,\r\n      (index + 1) * PROVIDER_METADATA_CHUNK_SIZE\r\n    );\r\n  }\r\n  return { wire, encodedLength: encoded.length, tooLarge: false };\r\n}\r\n\r\nfunction leastImportantKey(\r\n  map: Record<string, string>,\r\n  rank: Map<string, number>,\r\n  unlistedRank: number\r\n): string | undefined {\r\n  let chosen: string | undefined;\r\n  let chosenRank = -1;\r\n  let chosenSize = -1;\r\n  for (const [key, value] of Object.entries(map)) {\r\n    const keyRank = rank.get(key) ?? unlistedRank;\r\n    const size = value.length;\r\n    const lessImportant = chosen === undefined\r\n      || keyRank > chosenRank\r\n      || (keyRank === chosenRank && size > chosenSize)\r\n      || (keyRank === chosenRank && size === chosenSize && key > chosen);\r\n    if (lessImportant) {\r\n      chosen = key;\r\n      chosenRank = keyRank;\r\n      chosenSize = size;\r\n    }\r\n  }\r\n  return chosen;\r\n}\r\n\r\nfunction asMetadataString(value: unknown): string | undefined {\r\n  if (typeof value === \"string\") return value;\r\n  if (typeof value === \"boolean\") return value ? \"true\" : \"false\";\r\n  if (typeof value === \"number\" && Number.isFinite(value)) return String(value);\r\n  return undefined;\r\n}\r\n\r\nfunction isRecord(value: unknown): value is Record<string, unknown> {\r\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\r\n}\r\n"],"mappings":";AAAO,IAAM,+BAA+B;AACrC,IAAM,+BAA+B;AAE5C,IAAM,qBAAqB,+BAA+B;AAEnD,IAAM,0BAA0B;AAgChC,SAAS,qBAAqB,SAAiD;AACpF,QAAM,WAAW,CAAC,GAAI,SAAS,YAAY,CAAC,CAAE;AAC9C,QAAM,OAAO,oBAAI,IAAoB;AACrC,WAAS,QAAQ,GAAG,QAAQ,SAAS,QAAQ,SAAS,GAAG;AACvD,UAAM,MAAM,SAAS,KAAK;AAC1B,QAAI,QAAQ,UAAa,CAAC,KAAK,IAAI,GAAG,EAAG,MAAK,IAAI,KAAK,KAAK;AAAA,EAC9D;AAEA,SAAO;AAAA,IACL,QAAQ,QAAQ;AACd,YAAM,MAAM,eAAe,MAAM;AACjC,YAAM,UAAoB,CAAC;AAC3B,UAAI,UAAU,qBAAqB,GAAG;AACtC,aAAO,QAAQ,UAAU;AACvB,cAAM,SAAS,kBAAkB,KAAK,MAAM,SAAS,MAAM;AAC3D,YAAI,CAAC,OAAQ;AACb,eAAO,IAAI,MAAM;AACjB,gBAAQ,KAAK,MAAM;AACnB,kBAAU,qBAAqB,GAAG;AAAA,MACpC;AACA,aAAO;AAAA,QACL,GAAI,QAAQ,OAAO,EAAE,MAAM,QAAQ,KAAK,IAAI,CAAC;AAAA,QAC7C;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AAGO,SAAS,oBAAoB,SAA6D;AAC/F,MAAI,CAAC,QAAQ,OAAQ,QAAO;AAC5B,SAAO;AAAA,IACL,MAAM;AAAA,IACN,SAAS,sDAAsD,QAAQ,KAAK,IAAI,CAAC;AAAA,IACjF,SAAS,EAAE,SAAS,CAAC,GAAG,OAAO,EAAE;AAAA,EACnC;AACF;AAWO,SAAS,gBACX,QACiC;AACpC,QAAM,UAAU,qBAAqB,eAAe,MAAM,CAAC;AAC3D,MAAI,QAAQ,UAAU;AACpB,UAAM,IAAI;AAAA,MACR,mDAAmD,QAAQ,aAAa,sCAAsC,kBAAkB;AAAA,IAClI;AAAA,EACF;AACA,SAAO,QAAQ;AACjB;AAMO,SAAS,aAAa,MAAuC;AAClE,MAAI,CAAC,SAAS,IAAI,EAAG,QAAO,CAAC;AAC7B,QAAM,QAAkB,CAAC;AACzB,WAAS,QAAQ,KAAK,SAAS,GAAG;AAChC,UAAM,QAAQ,KAAK,KAAK,KAAK,EAAE;AAC/B,QAAI,OAAO,UAAU,SAAU;AAC/B,UAAM,KAAK,KAAK;AAAA,EAClB;AACA,MAAI,CAAC,MAAM,OAAQ,QAAO,CAAC;AAC3B,QAAM,SAAkB,KAAK,MAAM,OAAO,KAAK,MAAM,KAAK,EAAE,GAAG,QAAQ,EAAE,SAAS,MAAM,CAAC;AACzF,MAAI,CAAC,SAAS,MAAM,EAAG,QAAO,CAAC;AAC/B,QAAM,SAAiC,CAAC;AACxC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AACjD,QAAI,OAAO,UAAU,SAAU,QAAO,GAAG,IAAI;AAAA,EAC/C;AACA,SAAO;AACT;AAEA,SAAS,eAAe,QAA4E;AAClG,QAAM,MAA8B,CAAC;AACrC,aAAW,SAAS,QAAQ;AAC1B,QAAI,CAAC,MAAO;AACZ,eAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,YAAM,WAAW,iBAAiB,KAAK;AACvC,UAAI,aAAa,OAAW,KAAI,GAAG,IAAI;AAAA,IACzC;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,qBAAqB,KAI5B;AACA,QAAM,OAAO,OAAO,KAAK,GAAG,EAAE,KAAK;AACnC,MAAI,CAAC,KAAK,OAAQ,QAAO,EAAE,eAAe,GAAG,UAAU,MAAM;AAC7D,QAAM,UAAkC,CAAC;AACzC,aAAW,OAAO,MAAM;AACtB,UAAM,QAAQ,IAAI,GAAG;AACrB,QAAI,UAAU,OAAW,SAAQ,GAAG,IAAI;AAAA,EAC1C;AACA,QAAM,UAAU,OAAO,KAAK,KAAK,UAAU,OAAO,GAAG,MAAM,EAAE,SAAS,QAAQ;AAC9E,MAAI,KAAK,KAAK,QAAQ,SAAS,4BAA4B,IAAI,8BAA8B;AAC3F,WAAO,EAAE,eAAe,QAAQ,QAAQ,UAAU,KAAK;AAAA,EACzD;AACA,QAAM,OAA+B,CAAC;AACtC,WAAS,QAAQ,GAAG,QAAQ,KAAK,KAAK,QAAQ,SAAS,4BAA4B,GAAG,SAAS,GAAG;AAChG,SAAK,KAAK,KAAK,EAAE,IAAI,QAAQ;AAAA,MAC3B,QAAQ;AAAA,OACP,QAAQ,KAAK;AAAA,IAChB;AAAA,EACF;AACA,SAAO,EAAE,MAAM,eAAe,QAAQ,QAAQ,UAAU,MAAM;AAChE;AAEA,SAAS,kBACP,KACA,MACA,cACoB;AACpB,MAAI;AACJ,MAAI,aAAa;AACjB,MAAI,aAAa;AACjB,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,GAAG,GAAG;AAC9C,UAAM,UAAU,KAAK,IAAI,GAAG,KAAK;AACjC,UAAM,OAAO,MAAM;AACnB,UAAM,gBAAgB,WAAW,UAC5B,UAAU,cACT,YAAY,cAAc,OAAO,cACjC,YAAY,cAAc,SAAS,cAAc,MAAM;AAC7D,QAAI,eAAe;AACjB,eAAS;AACT,mBAAa;AACb,mBAAa;AAAA,IACf;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,iBAAiB,OAAoC;AAC5D,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,MAAI,OAAO,UAAU,UAAW,QAAO,QAAQ,SAAS;AACxD,MAAI,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,EAAG,QAAO,OAAO,KAAK;AAC5E,SAAO;AACT;AAEA,SAAS,SAAS,OAAkD;AAClE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/provider-metadata",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Pack and open one provider metadata record. The same wire object for every provider.",
   "type": "module",
   "main": "./dist/index.cjs",