On-disk storage for recorded traces.
Traces live in .avenx/traces/ under the project root, one JSON file per
recording. A plain directory of plain files is deliberate: a developer can
read one, diff two, attach one to an issue, or delete the lot, without a
database, an index file that can go stale, or a tool.
Node-only, like everything else that touches the filesystem.
- Source:
Members
(static, constant) DEFAULT_KEEP :number
How many traces a project keeps before prune starts suggesting cleanup.
Type:
- number
- Source:
(static, constant) TRACE_DIR :string
Where traces are kept, relative to the project root.
Type:
- string
- Source:
Methods
(static) isValidTraceId(id) → {boolean}
Rejects a trace id that could escape the trace directory.
Ids arrive from the CLI and from the dev server's ingest endpoint, so they are untrusted input on a path join.
Parameters:
| Name | Type | Description |
|---|---|---|
id |
string | The candidate id. |
- Source:
Returns:
Whether it is safe to use as a file name.
- Type
- boolean
(static) listTraces(rootDir) → {Array:.<object:>}
Lists stored traces, newest first.
A file that cannot be parsed is listed with a broken flag rather than
skipped, so a corrupted recording is visible and can be pruned rather than
silently disappearing from the listing.
Parameters:
| Name | Type | Description |
|---|---|---|
rootDir |
string | The project root. |
- Source:
Returns:
Summaries, newest first.
(static) loadTrace(rootDir, id) → {Object|null}
Reads one trace.
Parameters:
| Name | Type | Description |
|---|---|---|
rootDir |
string | The project root. |
id |
string | The trace id, or |
- Source:
Throws:
-
When the file exists but is not a readable trace.
- Type
- Error
Returns:
The trace, or null when absent.
- Type
- Object | null
(static) pruneTraces(rootDir, optionsopt) → {Array:.<string:>}
Deletes stored traces.
Parameters:
| Name | Type | Attributes | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
rootDir |
string | The project root. |
|||||||||||||||||
options |
object |
<optional> |
What to remove. Properties
|
- Source:
Returns:
The ids removed.
(static) saveTrace(rootDir, trace) → {string}
Writes a trace to disk.
Parameters:
| Name | Type | Description |
|---|---|---|
rootDir |
string | The project root. |
trace |
object | The trace to save. |
- Source:
Throws:
-
When the trace has no usable id.
- Type
- Error
Returns:
The path written.
- Type
- string
(static) traceDir(rootDir) → {string}
Resolves and creates the trace directory for a project.
Parameters:
| Name | Type | Description |
|---|---|---|
rootDir |
string | The project root. |
- Source:
Returns:
The absolute trace directory.
- Type
- string