@zintrust/trace 0.4.92 → 0.4.94

package/dist/build-manifest.json

@@ -1,14 +1,14 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.4.92",
-  "buildDate": "2026-04-10T08:41:38.521Z",
+  "version": "0.4.94",
+  "buildDate": "2026-04-11T09:24:47.024Z",
   "buildEnvironment": {
     "node": "v20.20.2",
     "platform": "linux",
     "arch": "x64"
   },
   "git": {
-    "commit": "d195a996",
+    "commit": "785d0351",
     "branch": "master"
   },
   "package": {
@@ -70,12 +70,12 @@
       "sha256": "2903901d8c0c5076118aa691727daa79be7abe87fdb393c5b389a2b1a8fce170"
     },
     "index.d.ts": {
-      "size": 2470,
-      "sha256": "99c28d43f79dbb2b372bf6a8b611841c131f59f5066702b499915b874e9fa2b8"
+      "size": 2537,
+      "sha256": "1707d26322dbad17f6bf85938ae6fe2477e84c7fed3333760ce8d6eadfaaffd2"
     },
     "index.js": {
-      "size": 3255,
-      "sha256": "683151fa06b666ec62b150a4fda949c3d35221228b8538644ef740252b63587d"
+      "size": 3325,
+      "sha256": "0926788b00fc68f513ae20a508f2ef3c2f4e7e907fa32d70f146ce6e8b0ec812"
     },
     "migrations/20260331000001_create_zin_trace_entries_table.d.ts": {
       "size": 304,
@@ -130,8 +130,16 @@
       "sha256": "71d366165dd36f1675aa253a76262b226fb6c62e5ab632746b8aea61c0c625fc"
     },
     "register.js": {
-      "size": 14225,
-      "sha256": "07e1643982cc93149c609d44beb11dea168ecf1cac3f78d95d6d22fedcafbc23"
+      "size": 14327,
+      "sha256": "efc9bb131b9eef7e81a6f85ea3338fd8ac74257f794aa0fc7c76efed636f99d8"
+    },
+    "storage/TraceContentBudget.d.ts": {
+      "size": 159,
+      "sha256": "d899a615e6cf2a5eea51f6200347cb81fbaae11979b801859f57135083aaf85b"
+    },
+    "storage/TraceContentBudget.js": {
+      "size": 4022,
+      "sha256": "4b1d4f0ad7da15caeaa1f9fe8b4edcd3000b0000c5bdc270601cd6db2eedce2e"
     },
     "storage/TraceContentRedaction.d.ts": {
       "size": 207,

package/dist/index.d.ts

@@ -8,6 +8,7 @@
 export { TraceConfig } from './config';
 export { TraceStorage } from './storage';
 export type { ITraceStorage } from './storage';
+export { TraceContentBudget } from './storage/TraceContentBudget';
 export { TraceContentRedaction } from './storage/TraceContentRedaction';
 export { TraceContext } from './context';
 export { registerTraceDashboard, registerTraceRoutes } from './dashboard/routes';

package/dist/index.js

@@ -14,6 +14,7 @@ export { TraceConfig } from './config.js';
 // Storage
 // ---------------------------------------------------------------------------
 export { TraceStorage } from './storage/index.js';
+export { TraceContentBudget } from './storage/TraceContentBudget.js';
 export { TraceContentRedaction } from './storage/TraceContentRedaction.js';
 // ---------------------------------------------------------------------------
 // Context

package/dist/register.js

@@ -22,6 +22,7 @@
 import { TraceConfig } from './config.js';
 import { TraceContext } from './context.js';
 import { TraceStorage } from './storage/index.js';
+import { TraceContentBudget } from './storage/TraceContentBudget.js';
 import { TraceContentRedaction } from './storage/TraceContentRedaction.js';
 import { TraceEntryFiltering } from './storage/TraceEntryFiltering.js';
 import { TraceWriteDiagnostics } from './storage/TraceWriteDiagnostics.js';
@@ -256,7 +257,7 @@ if (!traceAlreadyInitialized && Env) {
             envKey: 'TRACE_QUERY_CONNECTION',
         });
         await assertTraceStorageReady(core, storageDb, resolvedConnectionName);
-        const storage = TraceWriteDiagnostics.wrapStorage(TraceContentRedaction.wrapStorage(TraceEntryFiltering.wrapStorage(TraceStorage.resolveStorage(storageDb), config), config.redaction), {
+        const storage = TraceWriteDiagnostics.wrapStorage(TraceContentBudget.wrapStorage(TraceContentRedaction.wrapStorage(TraceEntryFiltering.wrapStorage(TraceStorage.resolveStorage(storageDb), config), config.redaction)), {
             connectionName: resolvedConnectionName,
             logger: core.Logger,
         });

package/dist/storage/TraceContentBudget.d.ts

@@ -0,0 +1,4 @@
+import type { ITraceStorage } from '../types';
+export declare const TraceContentBudget: Readonly<{
+    wrapStorage(storage: ITraceStorage): ITraceStorage;
+}>;

package/dist/storage/TraceContentBudget.js

@@ -0,0 +1,114 @@
+const DEFAULT_MAX_ENTRY_BYTES = 64 * 1024;
+const DEFAULT_MAX_STRING_BYTES = 16 * 1024;
+const DEFAULT_MAX_ARRAY_ITEMS = 25;
+const DEFAULT_MAX_OBJECT_ENTRIES = 40;
+const DEFAULT_MAX_DEPTH = 6;
+const DROPPED_FIELD_MESSAGE = '[trace] Value dropped because the field exceeded the trace storage size limit.';
+const COMPACTED_CONTENT_MESSAGE = '[trace] Trace content was compacted because it exceeded the trace storage size limit.';
+const encoder = new TextEncoder();
+const serializedSize = (value) => {
+    try {
+        return encoder.encode(JSON.stringify(value)).length;
+    }
+    catch {
+        return Number.MAX_SAFE_INTEGER;
+    }
+};
+const describeValueType = (value) => {
+    if (Array.isArray(value))
+        return 'array';
+    if (value === null)
+        return 'null';
+    return typeof value;
+};
+const compactValue = (value, depth) => {
+    if (depth >= DEFAULT_MAX_DEPTH) {
+        return DROPPED_FIELD_MESSAGE;
+    }
+    if (typeof value === 'string') {
+        return serializedSize(value) > DEFAULT_MAX_STRING_BYTES ? DROPPED_FIELD_MESSAGE : value;
+    }
+    if (Array.isArray(value)) {
+        const next = value
+            .slice(0, DEFAULT_MAX_ARRAY_ITEMS)
+            .map((item) => compactValue(item, depth + 1));
+        if (value.length > DEFAULT_MAX_ARRAY_ITEMS) {
+            next.push(`[trace] ${String(value.length - DEFAULT_MAX_ARRAY_ITEMS)} additional items were dropped.`);
+        }
+        return next;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+    const entries = Object.entries(value);
+    const compactedEntries = entries
+        .slice(0, DEFAULT_MAX_OBJECT_ENTRIES)
+        .map(([key, entryValue]) => [key, compactValue(entryValue, depth + 1)]);
+    if (entries.length > DEFAULT_MAX_OBJECT_ENTRIES) {
+        compactedEntries.push([
+            '__traceNotice',
+            `[trace] ${String(entries.length - DEFAULT_MAX_OBJECT_ENTRIES)} additional fields were dropped.`,
+        ]);
+    }
+    return Object.fromEntries(compactedEntries);
+};
+const compactTopLevelObjectToBudget = (value) => {
+    const compacted = {
+        ...value,
+        __traceNotice: COMPACTED_CONTENT_MESSAGE,
+    };
+    const keysByDescendingSize = Object.keys(compacted)
+        .filter((key) => key !== '__traceNotice')
+        .sort((left, right) => serializedSize(compacted[right]) - serializedSize(compacted[left]));
+    for (const key of keysByDescendingSize) {
+        if (serializedSize(compacted) <= DEFAULT_MAX_ENTRY_BYTES)
+            break;
+        compacted[key] = DROPPED_FIELD_MESSAGE;
+    }
+    return compacted;
+};
+const fitContentToBudget = (content) => {
+    if (serializedSize(content) <= DEFAULT_MAX_ENTRY_BYTES) {
+        return content;
+    }
+    const compacted = compactValue(content, 0);
+    if (serializedSize(compacted) <= DEFAULT_MAX_ENTRY_BYTES) {
+        return compacted;
+    }
+    if (typeof compacted === 'object' && compacted !== null && !Array.isArray(compacted)) {
+        const topLevelCompacted = compactTopLevelObjectToBudget(compacted);
+        if (serializedSize(topLevelCompacted) <= DEFAULT_MAX_ENTRY_BYTES) {
+            return topLevelCompacted;
+        }
+    }
+    return {
+        __traceNotice: COMPACTED_CONTENT_MESSAGE,
+        dropped: true,
+        valueType: describeValueType(content),
+    };
+};
+const fitEntryToBudget = (entry) => ({
+    ...entry,
+    content: fitContentToBudget(entry.content),
+});
+const fitPatchToBudget = (patch) => {
+    if (patch.content === undefined)
+        return patch;
+    return {
+        ...patch,
+        content: fitContentToBudget(patch.content),
+    };
+};
+export const TraceContentBudget = Object.freeze({
+    wrapStorage(storage) {
+        return Object.freeze({
+            ...storage,
+            writeEntry: async (entry) => {
+                await storage.writeEntry(fitEntryToBudget(entry));
+            },
+            updateEntry: async (uuid, patch) => {
+                await storage.updateEntry(uuid, fitPatchToBudget(patch));
+            },
+        });
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.4.92",
+  "version": "0.4.94",
   "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
   "private": false,
   "type": "module",
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@zintrust/core": "^0.4.91"
+    "@zintrust/core": "^0.4.93"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -18,6 +18,7 @@ export { TraceConfig } from './config';
 // ---------------------------------------------------------------------------
 export { TraceStorage } from './storage';
 export type { ITraceStorage } from './storage';
+export { TraceContentBudget } from './storage/TraceContentBudget';
 export { TraceContentRedaction } from './storage/TraceContentRedaction';
 
 // ---------------------------------------------------------------------------

package/src/register.ts

@@ -22,6 +22,7 @@
 import { TraceConfig } from './config';
 import { TraceContext } from './context';
 import { TraceStorage } from './storage';
+import { TraceContentBudget } from './storage/TraceContentBudget';
 import { TraceContentRedaction } from './storage/TraceContentRedaction';
 import { TraceEntryFiltering } from './storage/TraceEntryFiltering';
 import { TraceWriteDiagnostics } from './storage/TraceWriteDiagnostics';
@@ -379,9 +380,11 @@ if (!traceAlreadyInitialized && Env) {
     await assertTraceStorageReady(core, storageDb, resolvedConnectionName);
 
     const storage = TraceWriteDiagnostics.wrapStorage(
-      TraceContentRedaction.wrapStorage(
-        TraceEntryFiltering.wrapStorage(TraceStorage.resolveStorage(storageDb), config),
-        config.redaction
+      TraceContentBudget.wrapStorage(
+        TraceContentRedaction.wrapStorage(
+          TraceEntryFiltering.wrapStorage(TraceStorage.resolveStorage(storageDb), config),
+          config.redaction
+        )
       ),
       {
         connectionName: resolvedConnectionName,

package/src/storage/TraceContentBudget.ts

@@ -0,0 +1,145 @@
+import type { ITraceEntry, ITraceStorage } from '../types';
+
+const DEFAULT_MAX_ENTRY_BYTES = 64 * 1024;
+const DEFAULT_MAX_STRING_BYTES = 16 * 1024;
+const DEFAULT_MAX_ARRAY_ITEMS = 25;
+const DEFAULT_MAX_OBJECT_ENTRIES = 40;
+const DEFAULT_MAX_DEPTH = 6;
+
+const DROPPED_FIELD_MESSAGE =
+  '[trace] Value dropped because the field exceeded the trace storage size limit.';
+const COMPACTED_CONTENT_MESSAGE =
+  '[trace] Trace content was compacted because it exceeded the trace storage size limit.';
+
+const encoder = new TextEncoder();
+
+const serializedSize = (value: unknown): number => {
+  try {
+    return encoder.encode(JSON.stringify(value)).length;
+  } catch {
+    return Number.MAX_SAFE_INTEGER;
+  }
+};
+
+const describeValueType = (value: unknown): string => {
+  if (Array.isArray(value)) return 'array';
+  if (value === null) return 'null';
+  return typeof value;
+};
+
+const compactValue = (value: unknown, depth: number): unknown => {
+  if (depth >= DEFAULT_MAX_DEPTH) {
+    return DROPPED_FIELD_MESSAGE;
+  }
+
+  if (typeof value === 'string') {
+    return serializedSize(value) > DEFAULT_MAX_STRING_BYTES ? DROPPED_FIELD_MESSAGE : value;
+  }
+
+  if (Array.isArray(value)) {
+    const next = value
+      .slice(0, DEFAULT_MAX_ARRAY_ITEMS)
+      .map((item) => compactValue(item, depth + 1));
+
+    if (value.length > DEFAULT_MAX_ARRAY_ITEMS) {
+      next.push(
+        `[trace] ${String(value.length - DEFAULT_MAX_ARRAY_ITEMS)} additional items were dropped.`
+      );
+    }
+
+    return next;
+  }
+
+  if (typeof value !== 'object' || value === null) {
+    return value;
+  }
+
+  const entries = Object.entries(value);
+  const compactedEntries = entries
+    .slice(0, DEFAULT_MAX_OBJECT_ENTRIES)
+    .map(([key, entryValue]) => [key, compactValue(entryValue, depth + 1)]);
+
+  if (entries.length > DEFAULT_MAX_OBJECT_ENTRIES) {
+    compactedEntries.push([
+      '__traceNotice',
+      `[trace] ${String(entries.length - DEFAULT_MAX_OBJECT_ENTRIES)} additional fields were dropped.`,
+    ]);
+  }
+
+  return Object.fromEntries(compactedEntries);
+};
+
+const compactTopLevelObjectToBudget = (value: Record<string, unknown>): Record<string, unknown> => {
+  const compacted: Record<string, unknown> = {
+    ...value,
+    __traceNotice: COMPACTED_CONTENT_MESSAGE,
+  };
+
+  const keysByDescendingSize = Object.keys(compacted)
+    .filter((key) => key !== '__traceNotice')
+    .sort((left, right) => serializedSize(compacted[right]) - serializedSize(compacted[left]));
+
+  for (const key of keysByDescendingSize) {
+    if (serializedSize(compacted) <= DEFAULT_MAX_ENTRY_BYTES) break;
+    compacted[key] = DROPPED_FIELD_MESSAGE;
+  }
+
+  return compacted;
+};
+
+const fitContentToBudget = (content: unknown): unknown => {
+  if (serializedSize(content) <= DEFAULT_MAX_ENTRY_BYTES) {
+    return content;
+  }
+
+  const compacted = compactValue(content, 0);
+  if (serializedSize(compacted) <= DEFAULT_MAX_ENTRY_BYTES) {
+    return compacted;
+  }
+
+  if (typeof compacted === 'object' && compacted !== null && !Array.isArray(compacted)) {
+    const topLevelCompacted = compactTopLevelObjectToBudget(compacted as Record<string, unknown>);
+    if (serializedSize(topLevelCompacted) <= DEFAULT_MAX_ENTRY_BYTES) {
+      return topLevelCompacted;
+    }
+  }
+
+  return {
+    __traceNotice: COMPACTED_CONTENT_MESSAGE,
+    dropped: true,
+    valueType: describeValueType(content),
+  };
+};
+
+const fitEntryToBudget = (entry: ITraceEntry): ITraceEntry => ({
+  ...entry,
+  content: fitContentToBudget(entry.content),
+});
+
+const fitPatchToBudget = (
+  patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>
+): Partial<Pick<ITraceEntry, 'content' | 'isLatest'>> => {
+  if (patch.content === undefined) return patch;
+
+  return {
+    ...patch,
+    content: fitContentToBudget(patch.content),
+  };
+};
+
+export const TraceContentBudget = Object.freeze({
+  wrapStorage(storage: ITraceStorage): ITraceStorage {
+    return Object.freeze({
+      ...storage,
+      writeEntry: async (entry: ITraceEntry): Promise<void> => {
+        await storage.writeEntry(fitEntryToBudget(entry));
+      },
+      updateEntry: async (
+        uuid: string,
+        patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>
+      ): Promise<void> => {
+        await storage.updateEntry(uuid, fitPatchToBudget(patch));
+      },
+    });
+  },
+});