@nhtio/adk

Appearance

10 min read · 1,901 words

Class: SpooledJsonArtifact<T> ​

A @nhtio/adk!SpooledArtifact 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.

Path-based methods (json_get, json_filter, json_pluck) use JSONPath-Plus expressions. Full JSONPath syntax is supported, including recursive descent (..), filter expressions ([?(@.age > 18)]), and union selectors.

Extends ​

Type Parameters ​

Type ParameterDefault typeDescription
TunknownThe expected shape of each parsed record. Defaults to unknown.

Constructors ​

Constructor ​

ts
new SpooledJsonArtifact<T>(reader: SpoolReader, format?: JsonArtifactFormat): SpooledJsonArtifact<T>;

Parameters ​

ParameterTypeDescription
readerSpoolReaderThe backing store to read from.
format?JsonArtifactFormatOptional format hint. When omitted, the format is inferred on first access.

Returns ​

SpooledJsonArtifact<T>

Overrides ​

SpooledArtifact.constructor

Properties ​

PropertyModifierTypeDescriptionOverrides
toolMethodsstaticreadonly ToolMethodDescriptor[]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, 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.toolMethods

Methods ​

asString() ​

ts
asString(): Promise<string>;

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 was constructed over — preserves trailing newlines and non-\n line terminators that SpooledArtifact.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.asString

byteLength() ​

ts
byteLength(): Promise<number>;

Returns the total byte length of the underlying data.

Returns ​

Promise<number>

The byte length as reported by the @nhtio/adk!SpoolReader.

Inherited from ​

SpooledArtifact.byteLength

cat() ​

ts
cat(start?: number, end?: number): Promise<string[]>;

Returns lines from the artifact, optionally bounded to a range.

Parameters ​

ParameterTypeDescription
start?number0-based start line index (inclusive). Defaults to 0.
end?number0-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.tail.

Inherited from ​

SpooledArtifact.cat

estimateTokens() ​

ts
estimateTokens(encoding:
  | "gpt2"
  | "r50k_base"
  | "p50k_base"
  | "p50k_edit"
  | "cl100k_base"
  | "o200k_base"
  | "gemini"
  | "llama2"
| "claude"): Promise<number>;

Estimates the total token count of the artifact under encoding.

Parameters ​

ParameterTypeDescription
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 (which delegates to @nhtio/adk!SpoolReader.readAll) and delegates to @nhtio/adk!Tokenizable.estimateTokens. The estimate therefore reflects the actual source bytes — including trailing newlines and non-\n line terminators that the line-based SpooledArtifact.cat view would otherwise discard or misrepresent.

Inherited from ​

SpooledArtifact.estimateTokens

grep() ​

ts
grep(pattern: RegExp): Promise<string[]>;

Returns all lines that match pattern.

Parameters ​

ParameterTypeDescription
patternRegExpThe 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.grep

ts
head(n?: number): Promise<string[]>;

Returns the first n lines of the artifact.

Parameters ​

ParameterTypeDefault valueDescription
nnumber10Number 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.head

json_filter() ​

ts
json_filter(path: string): Promise<T[]>;

Returns records matched by a JSONPath filter expression.

Parameters ​

ParameterTypeDescription
pathstringA 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<unknown[]>;

Evaluates a JSONPath expression against the parsed content.

Parameters ​

ParameterTypeDescription
pathstringA 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. 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<string[] | undefined>;

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<number>;

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<unknown[]>;

Returns all values matched by a JSONPath expression across every record.

Parameters ​

ParameterTypeDescription
pathstringA JSONPath expression (e.g. '$..name').

Returns ​

Promise<unknown[]>

Array of matched values.

Remarks ​

Convenience over SpooledJsonArtifact.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<T[]>;

Returns a slice of the parsed records by index range.

Parameters ​

ParameterTypeDescription
start?numberStart index (inclusive). Defaults to 0.
end?numberEnd 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<JsonArtifactFormat>;

Returns the detected or provided format for this artifact.

Returns ​

Promise<JsonArtifactFormat>

One of 'json', 'json5', 'jsonl', or 'ndjson'.

lineCount() ​

ts
lineCount(): Promise<number>;

Returns the total number of lines in the artifact.

Returns ​

Promise<number>

The line count as reported by the @nhtio/adk!SpoolReader.

Inherited from ​

SpooledArtifact.lineCount

tail() ​

ts
tail(n?: number): Promise<string[]>;

Returns the last n lines of the artifact.

Parameters ​

ParameterTypeDefault valueDescription
nnumber10Number 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.tail

forgeTools() ​

ts
static forgeTools(ctx: DispatchContext): ToolRegistry;

Forges base-class tools plus JSON-specific tools narrowed to SpooledJsonArtifact.

Parameters ​

ParameterType
ctxDispatchContext

Returns ​

ToolRegistry

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.forgeTools

isSpooledArtifact() ​

ts
static isSpooledArtifact(value: unknown): value is SpooledArtifact;

Returns true if value is a SpooledArtifact instance (including any subclass).

Parameters ​

ParameterTypeDescription
valueunknownThe value to test.

Returns ​

value is SpooledArtifact

true when value is a SpooledArtifact instance.

Remarks ​

Uses the cross-realm-safe @nhtio/adk!isInstanceOf 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.isSpooledArtifact

isSpooledArtifactConstructor() ​

ts
static isSpooledArtifactConstructor(value: unknown): value is SpooledArtifactConstructor<SpooledArtifact>;

Returns true if value is a constructor function whose prototype chain includes SpooledArtifact (including SpooledArtifact itself).

Parameters ​

ParameterTypeDescription
valueunknownThe value to test.

Returns ​

value is SpooledArtifactConstructor<SpooledArtifact>

true when value is a constructor for SpooledArtifact or a subclass.

Remarks ​

Used by @nhtio/adk!Tool 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.isSpooledArtifactConstructor

isSpooledJsonArtifact() ​

ts
static isSpooledJsonArtifact(value: unknown): value is SpooledJsonArtifact<unknown>;

Returns true if value is a SpooledJsonArtifact instance.

Parameters ​

ParameterTypeDescription
valueunknownThe value to test.

Returns ​

value is SpooledJsonArtifact<unknown>

true when value is a SpooledJsonArtifact instance.

Remarks ​

Uses the cross-realm-safe @nhtio/adk!isInstanceOf 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.

Copyright © 2025-present New Horizon Technology LTD