Bounded, redaction-aware value capture for traces.
A trace has to hold values — the old and new side of every write, the body
of every resource response — and it has to hold them as JSON. Three things
make that harder than calling JSON.stringify:
- The values are reactive proxies. Recording the proxy would re-enter the reactive system and track dependencies against whichever watcher happened to be running, silently changing application behaviour.
- Some values cannot survive the round trip (DOM nodes, class instances, functions, cycles). Recording a placeholder is fine; claiming the trace can be replayed afterwards is not, so capture reports when it was lossy.
- Some values must never be recorded at all. Redaction is applied here, during capture, so a secret never reaches the buffer.
Capture is bounded in depth and breadth. A trace of a thousand-row list must not clone the list a thousand times.
- Source:
Members
(static, constant) DEFAULT_MAX_DEPTH :number
How deep a captured value is walked before it is summarised.
Type:
- number
- Source:
(static, constant) DEFAULT_MAX_ITEMS :number
How many array entries or object keys are captured before the rest is summarised as a count.
Type:
- number
- Source:
(static, constant) DEFAULT_MAX_STRING :number
How long a captured string may be before it is truncated.
Type:
- number
- Source:
(inner) lastCaptureLossy :boolean
Set by captureValue when the most recent capture could not represent a value exactly. Module-scoped rather than returned in a wrapper object because capture runs on hot paths and this avoids an allocation per write. Capture is synchronous, so there is no interleaving to worry about.
Type:
- boolean
- Source:
Methods
(static) captureValue(value, optionsopt) → {any}
Captures a value for storage in a trace.
Call wasLossy straight afterwards to learn whether the capture is exact. A lossy capture is still worth recording — it explains the shape of what happened — but it means replay cannot restore this value, and the caller is responsible for downgrading the trace's determinism accordingly.
Parameters:
| Name | Type | Attributes | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
value |
any | The value to capture. |
|||||||||||||||||||||||||
options |
object |
<optional> |
Capture options. Properties
|
- Source:
Returns:
A JSON-representable capture of the value.
- Type
- any
(static) formatCaptured(value) → {string}
Formats a captured value for single-line display in avenx trace view.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
any | A captured value. |
- Source:
Returns:
A compact rendering.
- Type
- string
(static) wasLossy() → {boolean}
Whether the most recent captureValue call lost information.
- Source:
Returns:
True when the captured value is a summary, not the value.
- Type
- boolean
(inner) describeOpaque(value) → {string}
Describes a value that cannot be represented in JSON.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
any | The value. |
- Source:
Returns:
A short human-readable placeholder.
- Type
- string
(inner) unwrap(value) → {any}
Unwraps a reactive proxy so capture reads the plain object underneath.
toRaw() is not used here: it goes through the proxy's get trap, which
would call track() and attribute the read to whatever watcher is running.
Reading the symbol directly on a non-proxy is simply undefined.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
any | A possibly reactive value. |
- Source:
Returns:
The raw value.
- Type
- any
(inner) walk(value, options, path, depth, seen) → {any}
Recursively captures a value within the configured bounds.
Parameters:
- Source:
Returns:
A JSON-representable capture.
- Type
- any