--- url: >- https://adk.nht.io/api/@nhtio/adk/spooled_artifact/classes/SpooledJsonArtifact.md description: >- A {@link @nhtio/adk!SpooledArtifact} specialisation that adds JSON-aware read operations. --- # Class: SpooledJsonArtifact\ Defined in: [lib/classes/spooled\_json\_artifact.ts:96](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_json_artifact.ts#L96) A [@nhtio/adk!SpooledArtifact](SpooledArtifact.md) specialisation that adds JSON-aware read operations. ## Remarks Construct with an optional `format` hint. When omitted the format is auto-detected on first access by reading the full artifact and running inferFormat. Once detected (or provided), the format is cached for the lifetime of the instance. All JSON methods are async, consistent with [@nhtio/adk!SpooledArtifact](SpooledArtifact.md). Path-based methods (`json_get`, `json_filter`, `json_pluck`) use [JSONPath-Plus](https://github.com/JSONPath-Plus/JSONPath) expressions. Full JSONPath syntax is supported, including recursive descent (`..`), filter expressions (`[?(@.age > 18)]`), and union selectors. ## Extends * [`SpooledArtifact`](SpooledArtifact.md) ## Type Parameters | Type Parameter | Default type | Description | | -------------- | ------------ | ---------------------------------------------------------------- | | `T` | `unknown` | The expected shape of each parsed record. Defaults to `unknown`. | ## Constructors ### Constructor ```ts new SpooledJsonArtifact(reader: SpoolReader, format?: JsonArtifactFormat): SpooledJsonArtifact; ``` Defined in: [lib/classes/spooled\_json\_artifact.ts:104](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_json_artifact.ts#L104) #### Parameters | Parameter | Type | Description | | --------- | ------------------------------------------------------------- | --------------------------------------------------------------------------- | | `reader` | [`SpoolReader`](../interfaces/SpoolReader.md) | The backing store to read from. | | `format?` | [`JsonArtifactFormat`](../type-aliases/JsonArtifactFormat.md) | Optional format hint. When omitted, the format is inferred on first access. | #### Returns `SpooledJsonArtifact`<`T`> #### Overrides [`SpooledArtifact`](SpooledArtifact.md).[`constructor`](SpooledArtifact.md#constructor) ## Properties | Property | Modifier | Type | Description | Overrides | Defined in | | ----------------------------------------------- | -------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | `toolMethods` | `static` | readonly [`ToolMethodDescriptor`](../../common/interfaces/ToolMethodDescriptor.md)\[] | The JSON-specific artifact-query descriptors this class adds on top of the base set. **Remarks** Lists `artifact_json_type`, `artifact_json_keys`, `artifact_json_length`, `artifact_json_get`, `artifact_json_filter`, `artifact_json_slice`, `artifact_json_pluck`. The base seven descriptors (`artifact_head`, etc.) are NOT included here — they are forged separately by [SpooledJsonArtifact.forgeTools](#forgetools), which calls `SpooledArtifact.forgeTools(ctx)` to produce the base-narrowed tools and then registers its own JSON tools on the result. Downstream consumers building custom subclasses should follow the same pattern: own only your own descriptors; override `forgeTools` to compose with the base output. | [`SpooledArtifact`](SpooledArtifact.md).[`toolMethods`](SpooledArtifact.md#property-toolmethods) | [lib/classes/spooled\_json\_artifact.ts:138](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_json_artifact.ts#L138) | ## Methods ### asString() ```ts asString(): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:421](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L421) Returns the full artifact body as a single byte-faithful string. #### Returns `Promise`<`string`> The full content as a single string. #### Remarks Round-trip faithful to whatever bytes the [@nhtio/adk!SpoolReader](../interfaces/SpoolReader.md) was constructed over — preserves trailing newlines and non-`\n` line terminators that [SpooledArtifact.cat](SpooledArtifact.md#cat) discards via its line-based view. This is the canonical primitive for "inline the artifact content directly into a message" use cases. `asString()` and the static `forgeTools(ctx)` factory on each subclass are independent alternatives — a consumer chooses per turn whether to inline the body in a message (`await tc.results.asString()`) or hand the model query tools (`SpooledArtifact.forgeTools(ctx)`). Neither calls the other; either works with neither. #### Inherited from [`SpooledArtifact`](SpooledArtifact.md).[`asString`](SpooledArtifact.md#asstring) *** ### byteLength() ```ts byteLength(): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:374](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L374) Returns the total byte length of the underlying data. #### Returns `Promise`<`number`> The byte length as reported by the [@nhtio/adk!SpoolReader](../interfaces/SpoolReader.md). #### Inherited from [`SpooledArtifact`](SpooledArtifact.md).[`byteLength`](SpooledArtifact.md#bytelength) *** ### cat() ```ts cat(start?: number, end?: number): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:355](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L355) Returns lines from the artifact, optionally bounded to a range. #### Parameters | Parameter | Type | Description | | --------- | -------- | -------------------------------------------------------------- | | `start?` | `number` | 0-based start line index (inclusive). Defaults to `0`. | | `end?` | `number` | 0-based end line index (exclusive). Defaults to `lineCount()`. | #### Returns `Promise`<`string`\[]> Array of line strings in the requested range. #### Remarks Without arguments, returns all lines — equivalent to POSIX `cat`. With `start` and/or `end`, behaves like `Array.prototype.slice`: `start` defaults to `0`, `end` defaults to the total line count, and only lines in `[start, end)` are fetched from the backing store. For large artifacts, prefer a bounded range or [SpooledArtifact.head](SpooledArtifact.md#head) / [SpooledArtifact.tail](SpooledArtifact.md#tail). #### Inherited from [`SpooledArtifact`](SpooledArtifact.md).[`cat`](SpooledArtifact.md#cat) *** ### estimateTokens() ```ts estimateTokens(encoding: | "gpt2" | "r50k_base" | "p50k_base" | "p50k_edit" | "cl100k_base" | "o200k_base" | "gemini" | "llama2" | "claude"): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:400](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L400) Estimates the total token count of the artifact under `encoding`. #### Parameters | Parameter | Type | Description | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | `encoding` | | `"gpt2"` | `"r50k_base"` | `"p50k_base"` | `"p50k_edit"` | `"cl100k_base"` | `"o200k_base"` | `"gemini"` | `"llama2"` | `"claude"` | The encoding identifier to use for counting. | #### Returns `Promise`<`number`> The estimated number of tokens. #### Remarks Reads the full byte-faithful content via [SpooledArtifact.asString](SpooledArtifact.md#asstring) (which delegates to [@nhtio/adk!SpoolReader.readAll](../interfaces/SpoolReader.md#readall)) and delegates to [@nhtio/adk!Tokenizable.estimateTokens](../../common/classes/Tokenizable.md#estimatetokens). The estimate therefore reflects the actual source bytes — including trailing newlines and non-`\n` line terminators that the line-based [SpooledArtifact.cat](SpooledArtifact.md#cat) view would otherwise discard or misrepresent. #### Inherited from [`SpooledArtifact`](SpooledArtifact.md).[`estimateTokens`](SpooledArtifact.md#estimatetokens) *** ### grep() ```ts grep(pattern: RegExp): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:327](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L327) Returns all lines that match `pattern`. #### Parameters | Parameter | Type | Description | | --------- | -------- | ------------------------------------------------- | | `pattern` | `RegExp` | The regular expression to test each line against. | #### Returns `Promise`<`string`\[]> Array of matching line strings, in order. #### Remarks Behaves like POSIX `grep`: each line is tested against the pattern and included in the result when it matches. The pattern is applied as a JavaScript `RegExp`; flags (e.g. case- insensitivity) should be encoded in the expression itself. Stateful flags (`g`, `y`) on the supplied `RegExp` would normally cause `pattern.test()` to advance `lastIndex` across calls, producing skipped matches and order-dependent results. To keep the per-line semantics stateless, `grep` resets `pattern.lastIndex` to `0` before each line test. The forged `artifact_grep` tool also rejects `g` and `y` flags up-front at schema validation time. #### Inherited from [`SpooledArtifact`](SpooledArtifact.md).[`grep`](SpooledArtifact.md#grep) *** ### head() ```ts head(n?: number): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:274](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L274) Returns the first `n` lines of the artifact. #### Parameters | Parameter | Type | Default value | Description | | --------- | -------- | ------------- | ------------------------------------------ | | `n` | `number` | `10` | Number of lines to return. Defaults to 10. | #### Returns `Promise`<`string`\[]> Array of line strings, without trailing newlines. #### Remarks If the artifact contains fewer than `n` lines, all available lines are returned. Matches the behaviour of POSIX `head -n`. #### Inherited from [`SpooledArtifact`](SpooledArtifact.md).[`head`](SpooledArtifact.md#head) *** ### json\_filter() ```ts json_filter(path: string): Promise; ``` Defined in: [lib/classes/spooled\_json\_artifact.ts:424](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_json_artifact.ts#L424) Returns records matched by a JSONPath filter expression. #### Parameters | Parameter | Type | Description | | --------- | -------- | ------------------------------------------------------------- | | `path` | `string` | A JSONPath expression (e.g. `'$[?(@.status === "active")]'`). | #### Returns `Promise`<`T`\[]> Array of matching records. #### Remarks Evaluates `path` against each record and returns those for which the expression produces at least one match. For `json`/`json5`, evaluates against the root value and returns it in an array if matched. *** ### json\_get() ```ts json_get(path: string): Promise; ``` Defined in: [lib/classes/spooled\_json\_artifact.ts:384](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_json_artifact.ts#L384) Evaluates a JSONPath expression against the parsed content. #### Parameters | Parameter | Type | Description | | --------- | -------- | ------------------------------------------------------------------ | | `path` | `string` | A JSONPath expression (e.g. `'$.user.address.city'`, `'$..name'`). | #### Returns `Promise`<`unknown`\[]> Array of matched values. Empty array when no matches are found. #### Remarks Uses [JSONPath-Plus](https://github.com/JSONPath-Plus/JSONPath). Full JSONPath syntax is supported: recursive descent (`$..*`), filter expressions (`$[?(@.age > 18)]`), union selectors, and more. * For `json`/`json5`: evaluates the expression against the root value. * For `jsonl`/`ndjson`: evaluates the expression against each record and returns a flat array of all matches across all records. *** ### json\_keys() ```ts json_keys(): Promise; ``` Defined in: [lib/classes/spooled\_json\_artifact.ts:334](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_json_artifact.ts#L334) Returns the top-level keys of the parsed content. #### Returns `Promise`<`string`\[] | `undefined`> Array of key strings, or `undefined` when no object keys are present. #### Remarks * For `json`/`json5`: returns the keys of the root object, or `undefined` when the root is not a plain object (e.g. an array or scalar). * For `jsonl`/`ndjson`: returns the union of keys across all records that are plain objects. Duplicate keys are deduplicated. *** ### json\_length() ```ts json_length(): Promise; ``` Defined in: [lib/classes/spooled\_json\_artifact.ts:364](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_json_artifact.ts#L364) Returns the total number of records in the artifact. #### Returns `Promise`<`number`> The record count. #### Remarks * For `json`/`json5`: always `1` (the entire artifact is a single value). * For `jsonl`/`ndjson`: the number of non-empty lines. *** ### json\_pluck() ```ts json_pluck(path: string): Promise; ``` Defined in: [lib/classes/spooled\_json\_artifact.ts:443](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_json_artifact.ts#L443) Returns all values matched by a JSONPath expression across every record. #### Parameters | Parameter | Type | Description | | --------- | -------- | ----------------------------------------- | | `path` | `string` | A JSONPath expression (e.g. `'$..name'`). | #### Returns `Promise`<`unknown`\[]> Array of matched values. #### Remarks Convenience over [SpooledJsonArtifact.json\_get](#json_get) with an identical signature — use whichever name better communicates intent at the call site. `json_pluck` reads well for extracting a single field column; `json_get` reads well for structured queries. *** ### json\_slice() ```ts json_slice(start?: number, end?: number): Promise; ``` Defined in: [lib/classes/spooled\_json\_artifact.ts:404](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_json_artifact.ts#L404) Returns a slice of the parsed records by index range. #### Parameters | Parameter | Type | Description | | --------- | -------- | ---------------------------------------------------- | | `start?` | `number` | Start index (inclusive). Defaults to `0`. | | `end?` | `number` | End index (exclusive). Defaults to the record count. | #### Returns `Promise`<`T`\[]> Array of sliced records. #### Remarks For `json`/`json5`: always returns `[root]` — the artifact is a single record so slicing is not meaningful. For `jsonl`/`ndjson`: behaves like `Array.prototype.slice`. *** ### json\_type() ```ts json_type(): Promise; ``` Defined in: [lib/classes/spooled\_json\_artifact.ts:319](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_json_artifact.ts#L319) Returns the detected or provided format for this artifact. #### Returns `Promise`<[`JsonArtifactFormat`](../type-aliases/JsonArtifactFormat.md)> One of `'json'`, `'json5'`, `'jsonl'`, or `'ndjson'`. *** ### lineCount() ```ts lineCount(): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:383](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L383) Returns the total number of lines in the artifact. #### Returns `Promise`<`number`> The line count as reported by the [@nhtio/adk!SpoolReader](../interfaces/SpoolReader.md). #### Inherited from [`SpooledArtifact`](SpooledArtifact.md).[`lineCount`](SpooledArtifact.md#linecount) *** ### tail() ```ts tail(n?: number): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:297](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L297) Returns the last `n` lines of the artifact. #### Parameters | Parameter | Type | Default value | Description | | --------- | -------- | ------------- | ------------------------------------------ | | `n` | `number` | `10` | Number of lines to return. Defaults to 10. | #### Returns `Promise`<`string`\[]> Array of line strings, without trailing newlines. #### Remarks If the artifact contains fewer than `n` lines, all available lines are returned. Matches the behaviour of POSIX `tail -n`. #### Inherited from [`SpooledArtifact`](SpooledArtifact.md).[`tail`](SpooledArtifact.md#tail) *** ### forgeTools() ```ts static forgeTools(ctx: DispatchContext): ToolRegistry; ``` Defined in: [lib/classes/spooled\_json\_artifact.ts:215](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_json_artifact.ts#L215) Forges base-class tools plus JSON-specific tools narrowed to SpooledJsonArtifact. #### Parameters | Parameter | Type | | --------- | -------------------------------------------------------------- | | `ctx` | [`DispatchContext`](../../types/interfaces/DispatchContext.md) | #### Returns [`ToolRegistry`](../../forge/classes/ToolRegistry.md) #### Remarks Standard subclass extension pattern: call `SpooledArtifact.forgeTools(ctx)` to produce the base seven `artifact_*` tools narrowed to any `SpooledArtifact` in the turn, then register one `ArtifactTool` per JSON-specific descriptor narrowed to JSON artifacts. Downstream consumers building their own subclasses should follow the same shape. #### Overrides [`SpooledArtifact`](SpooledArtifact.md).[`forgeTools`](SpooledArtifact.md#forgetools) *** ### isSpooledArtifact() ```ts static isSpooledArtifact(value: unknown): value is SpooledArtifact; ``` Defined in: [lib/classes/spooled\_artifact.ts:234](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L234) Returns `true` if `value` is a [SpooledArtifact](SpooledArtifact.md) instance (including any subclass). #### Parameters | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to test. | #### Returns `value is SpooledArtifact` `true` when `value` is a [SpooledArtifact](SpooledArtifact.md) instance. #### Remarks Uses the cross-realm-safe [@nhtio/adk!isInstanceOf](../../guards/functions/isInstanceOf.md) guard: `instanceof` first, then `Symbol.hasInstance`, then a `constructor.name` fallback. Subclass instances (e.g. @nhtio/adk!SpooledJsonArtifact) satisfy this guard because `instanceof` walks the prototype chain. The fallbacks handle the dual-module-copy case where two distinct `SpooledArtifact` classes coexist in the same realm (e.g. one bundled into a downstream library, one in the consumer's `node_modules`). #### Inherited from [`SpooledArtifact`](SpooledArtifact.md).[`isSpooledArtifact`](SpooledArtifact.md#isspooledartifact) *** ### isSpooledArtifactConstructor() ```ts static isSpooledArtifactConstructor(value: unknown): value is SpooledArtifactConstructor; ``` Defined in: [lib/classes/spooled\_artifact.ts:251](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L251) Returns `true` if `value` is a constructor function whose prototype chain includes [SpooledArtifact](SpooledArtifact.md) (including `SpooledArtifact` itself). #### Parameters | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to test. | #### Returns `value is SpooledArtifactConstructor` `true` when `value` is a constructor for `SpooledArtifact` or a subclass. #### Remarks Used by [@nhtio/adk!Tool](../../forge/classes/Tool.md) to validate the optional `artifactConstructor` field. Performs an `instanceof`-based check on the prototype chain; falls back to a duck-type test that looks for the canonical SpooledArtifact instance methods on `value.prototype` for cross-realm safety (constructors passed from a different module copy or VM context). #### Inherited from [`SpooledArtifact`](SpooledArtifact.md).[`isSpooledArtifactConstructor`](SpooledArtifact.md#isspooledartifactconstructor) *** ### isSpooledJsonArtifact() ```ts static isSpooledJsonArtifact(value: unknown): value is SpooledJsonArtifact; ``` Defined in: [lib/classes/spooled\_json\_artifact.ts:121](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_json_artifact.ts#L121) Returns `true` if `value` is a SpooledJsonArtifact instance. #### Parameters | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to test. | #### Returns `value is SpooledJsonArtifact` `true` when `value` is a SpooledJsonArtifact instance. #### Remarks Uses the cross-realm-safe [@nhtio/adk!isInstanceOf](../../guards/functions/isInstanceOf.md) guard: `instanceof` first, then `Symbol.hasInstance`, then a `constructor.name` fallback. Matches the pattern used by every other class guard in the ADK; safe against the dual-module-copy case where two distinct `SpooledJsonArtifact` classes coexist in the same realm.