trackState

trackState wraps a plain object or a Map in a proxy that records every property read. When an error is captured, those reads are included in the incident package, showing the values your code observed before the failure.

Basic usage

import errorcore from "errorcore";

const featureFlags = errorcore.trackState("featureFlags", {
  newCheckout: true,
  betaBilling: false,
});

// later, in a request handler
function processOrder(order) {
  if (featureFlags.newCheckout) {
    // this read is recorded: featureFlags.newCheckout = true
    return newCheckoutFlow(order);
  }
  return legacyCheckoutFlow(order);
}

If processOrder throws, the incident package includes:

{
  "stateReads": [
    {
      "container": "featureFlags",
      "operation": "get",
      "key": "newCheckout",
      "value": true
    }
  ]
}

Tracking a Map

trackState also works with Map instances. It records get, has, entries, values, and forEach calls:

const sessionCache = errorcore.trackState(
  "sessionCache",
  new Map()
);

// reads on the map are recorded
const session = sessionCache.get(sessionId);
const exists = sessionCache.has(sessionId);

When to use it

trackState is most useful for shared state that influences branching: feature flags, cached lookups, configuration objects, permission maps. It answers the question "what did the code see when it decided to take this path?"

It is not designed for high-frequency data. Tracking a request body or a large result set will fill the read buffer quickly without adding useful signal.

Limits

• A maximum of 50 state reads are recorded per request context. Reads beyond that limit are silently dropped.
• Values are cloned and truncated at capture time using the same serialization limits as the rest of the package (depth, string length, array size).
• trackState must be called after init(). Calling it before initialization throws an error.
• Write operations (set, delete, property assignment) are not intercepted. Only reads are tracked.