@nhtio/adk

Appearance

12 min read · 2,495 words

Class: SpooledXmlArtifact ​

Defined in: src/batteries/artifacts/xml/index.ts:107

A @nhtio/adk!SpooledArtifact specialisation that adds XML-aware read operations.

Remarks ​

The artifact parses XML into a JSON projection on first access and caches it for the lifetime of the instance. The projection uses ignoreAttributes and attributeNamePrefix as supplied to the constructor — defaulting to false and '_' — with preserveOrder: false.

Under this mapping, an XML element like:

root-element with an href attribute and text content becomes a JSON object like: { root: { element: { _href: 'value', '#text': 'content' } } }

Attributes are prefixed with _ by default rather than the conventional @_, because jsonpath-plus reads a leading @ in a path segment as its type-selector sigil before honouring quotes: $..["@_href"] throws Unknown value type _hr, while $..["_href"] matches. Text nodes use the #text key.

All XML methods are async, consistent with @nhtio/adk!SpooledArtifact.

Path-based methods (xml_get, xml_filter, xml_pluck) use JSONPath-Plus expressions over the projection. Full JSONPath syntax is supported, including recursive descent (..), filter expressions, and union selectors.

Extends ​

Constructors ​

Constructor ​

ts
new SpooledXmlArtifact(reader: SpoolReader, options?: {
  attributeNamePrefix?: string;
  ignoreAttributes?: boolean;
}): SpooledXmlArtifact;

Defined in: src/batteries/artifacts/xml/index.ts:123

Parameters ​

ParameterTypeDescription
readerSpoolReaderThe backing store to read from.
options?{ attributeNamePrefix?: string; ignoreAttributes?: boolean; }Optional parser configuration.
options.attributeNamePrefix?stringPrefix for attribute keys (default: ''). Set to '@' if you need the conventional XML-to-JSON mapping, but be aware that naming such a key in a JSONPath segment fails — $..["@_attr"] throws Unknown value type _at, and quoting does not escape it. A filter expression still reaches it ($..[?(@['@_attr'])]); a wildcard does too, but only when placed exactly one level above the key, so the working path depends on whether repeated elements collapsed into an array.
options.ignoreAttributes?booleanWhen true, ignore element attributes (default: false).

Returns ​

SpooledXmlArtifact

Overrides ​

SpooledArtifact.constructor

Properties ​

PropertyModifierTypeDescriptionOverridesDefined in
toolMethodsstaticreadonly ToolMethodDescriptor[]The XML-specific artifact-query descriptors this class adds on top of the base set. Remarks Lists artifact_xml_root, artifact_xml_keys, artifact_xml_tags, artifact_xml_length, artifact_xml_get, artifact_xml_filter, artifact_xml_pluck. The base seven descriptors (artifact_head, etc.) are NOT included here — they are forged separately by SpooledXmlArtifact.forgeTools.SpooledArtifact.toolMethodssrc/batteries/artifacts/xml/index.ts:179

Methods ​

[ENCODE_METHOD]() ​

ts
ENCODE_METHOD: unknown;

Defined in: src/batteries/artifacts/xml/index.ts:524

Serialise this SpooledXmlArtifact into an @nhtio/encoder snapshot — the reader handle plus the constructor options for attributeNamePrefix and ignoreAttributes.

Returns ​

unknown

A snapshot consumed by SpooledXmlArtifact.[DECODE_METHOD].

Remarks ​

Overrides SpooledArtifact.[ENCODE_METHOD] to carry the constructor's options (the parsed projection cache is derived and not encoded). Round-trips via SpooledXmlArtifact.[DECODE_METHOD].

Inherited from ​

SpooledArtifact.[ENCODE_METHOD]

[ENCODE_METHOD]() ​

ts
ENCODE_METHOD: unknown;

Defined in: src/lib/classes/spooled_artifact.ts:314

Serialise this SpooledArtifact into an @nhtio/encoder snapshot — the reader handle, not the bytes.

Returns ​

unknown

A snapshot consumed by SpooledArtifact.[DECODE_METHOD].

Remarks ​

Emits the backing reader's ReaderDescriptor; decode re-binds the reader through the registered resolver. Throws @nhtio/adk!E_READER_NOT_DESCRIBABLE when the reader cannot describe itself. Subclasses override this to include their own discriminators (e.g. @nhtio/adk!SpooledJsonArtifact adds format).

Inherited from ​

ts
SpooledArtifact.[ENCODE_METHOD]

asString() ​

ts
asString(): Promise<string>;

Defined in: src/lib/classes/spooled_artifact.ts:630

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

Defined in: src/lib/classes/spooled_artifact.ts:501

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

Defined in: src/lib/classes/spooled_artifact.ts:482

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

estimateHandleTokens() ​

ts
estimateHandleTokens(
   callId: string,
   encoding:
  | "gpt2"
  | "r50k_base"
  | "p50k_base"
  | "p50k_edit"
  | "cl100k_base"
  | "o200k_base"
  | "gemini"
  | "gemma"
  | "llama2"
  | "claude",
   renderer?: (input: {
  artifact: unknown;
  byteLength: number;
  callId: string;
  encoding?: string;
  estimatedTokens?: number;
  lineCount: number;
}) => string): number;

Defined in: src/lib/classes/spooled_artifact.ts:547

Estimates tokens for the exact handle-body metadata rendered for this artifact.

The fallback renderer is an interim core-safe implementation. Its output is deliberately specified here for fan-in parity: the lines are the fixed prose and metadata strings below, with one \n separator, and method entries formatted as - name — description (or - name). The canonical renderer in chat_common should eventually delegate to this builder rather than maintain a second copy.

Parameters ​

ParameterTypeDescription
callIdstringThe turn-local artifact identifier.
encoding| "gpt2" | "r50k_base" | "p50k_base" | "p50k_edit" | "cl100k_base" | "o200k_base" | "gemini" | "gemma" | "llama2" | "claude"The token encoding used for estimation.
renderer?(input: { artifact: unknown; byteLength: number; callId: string; encoding?: string; estimatedTokens?: number; lineCount: number; }) => stringOptional renderer overriding the interim default.

Returns ​

number

A synchronous token estimate.

Inherited from ​

SpooledArtifact.estimateHandleTokens

estimateTokens() ​

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

Defined in: src/lib/classes/spooled_artifact.ts:609

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" | "gemma" | "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

getParserOptions() ​

ts
getParserOptions(): {
  attributeNamePrefix: string;
  ignoreAttributes: boolean;
};

Defined in: src/batteries/artifacts/xml/index.ts:160

Returns the effective XML-to-JSON parser configuration for this artifact.

Returns ​

ts
{
  attributeNamePrefix: string;
  ignoreAttributes: boolean;
}

An object with attributeNamePrefix and ignoreAttributes keys.

NameTypeDefined in
attributeNamePrefixstringsrc/batteries/artifacts/xml/index.ts:161
ignoreAttributesbooleansrc/batteries/artifacts/xml/index.ts:162

Remarks ​

When converting an XML artifact to JSON by call_id, the converter inherits the source artifact's attribute prefix and ignoreAttributes setting. This accessor exposes those options so the converter can apply them consistently.

grep() ​

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

Defined in: src/lib/classes/spooled_artifact.ts:454

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

hasSizeHints() ​

ts
hasSizeHints(): boolean;

Defined in: src/lib/classes/spooled_artifact.ts:520

Returns whether producer-computed size metadata is available.

Returns ​

boolean

true when SpooledArtifact._setSizeHints has populated the cache.

Inherited from ​

SpooledArtifact.hasSizeHints

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

Defined in: src/lib/classes/spooled_artifact.ts:401

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

lineCount() ​

ts
lineCount(): Promise<number>;

Defined in: src/lib/classes/spooled_artifact.ts:529

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

Defined in: src/lib/classes/spooled_artifact.ts:424

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

xml_filter() ​

ts
xml_filter(path: string): Promise<unknown[]>;

Defined in: src/batteries/artifacts/xml/index.ts:371

Returns the elements (subtrees) that match a JSONPath expression.

Parameters ​

ParameterTypeDescription
pathstringA JSONPath expression (e.g. '$.root.item[*]._id' or '$[?(@.status)]').

Returns ​

Promise<unknown[]>

Array of matching element subtrees. Empty array when no matches found.

Remarks ​

Evaluates the path against the XML projection and returns the elements that contain matching values. Unlike xml_get (which returns matched values), xml_filter returns the element objects containing those matches.

Candidate set definition for XML's single-rooted projection:

  • If the root element contains an array of repeated siblings (e.g., root.item where item is an array property), filters across those siblings and returns elements that have matching content.
  • If the root element contains a single object, evaluates the path against it and returns it when matched.

The path is evaluated using JSONPath-Plus with resultType 'all' to extract parent elements of matched values. The immediate parent object of any matched value is included in the result, deduplicating elements.

Example: for XML with root containing multiple 'item' elements each with an 'id' attribute, xml_filter('$.root.item[*]._id') returns the item elements that have an id attribute, whereas xml_get would return the id values themselves.

xml_get() ​

ts
xml_get(path: string): Promise<unknown[]>;

Defined in: src/batteries/artifacts/xml/index.ts:339

Query the document via JSONPath expression.

Parameters ​

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

Returns ​

Promise<unknown[]>

Array of matched values.

xml_keys() ​

ts
xml_keys(): Promise<string[]>;

Defined in: src/batteries/artifacts/xml/index.ts:271

Keys directly under the root element.

Returns ​

Promise<string[]>

Array of key names at the root level.

xml_length() ​

ts
xml_length(): Promise<number>;

Defined in: src/batteries/artifacts/xml/index.ts:322

Element count when the root contains an array of children; otherwise 1.

Returns ​

Promise<number>

Number of elements.

xml_pluck() ​

ts
xml_pluck(path: string): Promise<unknown[]>;

Defined in: src/batteries/artifacts/xml/index.ts:422

Alias for xml_get — extract values matching a JSONPath.

Parameters ​

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

Returns ​

Promise<unknown[]>

Array of matched values.

xml_root() ​

ts
xml_root(): Promise<string>;

Defined in: src/batteries/artifacts/xml/index.ts:257

The root element name of the XML document.

Returns ​

Promise<string>

The name of the root element.

Throws ​

Error when the document is malformed or empty.

xml_tags() ​

ts
xml_tags(): Promise<string[]>;

Defined in: src/batteries/artifacts/xml/index.ts:290

Every distinct element name in the document, deduplicated.

Returns ​

Promise<string[]>

Sorted array of unique element names.

Remarks ​

Walks the entire projection recursively, excluding attribute keys (prefixed with the configured attributeNamePrefix, default _) and #text keys. This is what a model calls before it can write a path into an unfamiliar document.

[DECODE_METHOD]() ​

ts
static DECODE_METHOD: SpooledXmlArtifact;

Defined in: src/batteries/artifacts/xml/index.ts:539

Reconstruct a SpooledXmlArtifact from a SpooledXmlArtifact.[ENCODE_METHOD] snapshot.

Parameters ​

ParameterTypeDescription
dataunknownThe snapshot produced by SpooledXmlArtifact.[ENCODE_METHOD].

Returns ​

SpooledXmlArtifact

A fresh SpooledXmlArtifact backed by a freshly-resolved reader.

Inherited from ​

SpooledArtifact.[DECODE_METHOD]

[DECODE_METHOD]() ​

ts
static DECODE_METHOD: SpooledArtifact;

Defined in: src/lib/classes/spooled_artifact.ts:328

Reconstruct a SpooledArtifact from an SpooledArtifact.[ENCODE_METHOD] snapshot.

Parameters ​

ParameterTypeDescription
dataunknownThe snapshot produced by SpooledArtifact.[ENCODE_METHOD].

Returns ​

SpooledArtifact

A fresh SpooledArtifact backed by a freshly-resolved reader.

Remarks ​

Re-binds the reader via @nhtio/adk!resolveSpoolReader; throws @nhtio/adk!E_NO_READER_RESOLVER when no resolver is registered for the descriptor's tag.

Inherited from ​

ts
SpooledArtifact.[DECODE_METHOD]

forgeTools() ​

ts
static forgeTools(ctx: DispatchContext): ToolRegistry;

Defined in: src/batteries/artifacts/xml/index.ts:431

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 XML-specific descriptor narrowed to XML artifacts.

Parameters ​

ParameterType
ctxDispatchContext

Returns ​

ToolRegistry

Overrides ​

SpooledArtifact.forgeTools

isSpooledArtifact() ​

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

Defined in: src/lib/classes/spooled_artifact.ts:361

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

Defined in: src/lib/classes/spooled_artifact.ts:378

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

isSpooledXmlArtifact() ​

ts
static isSpooledXmlArtifact(value: unknown): value is SpooledXmlArtifact;

Defined in: src/batteries/artifacts/xml/index.ts:146

Returns true if value is a SpooledXmlArtifact instance.

Parameters ​

ParameterTypeDescription
valueunknownThe value to test.

Returns ​

value is SpooledXmlArtifact

true when value is a SpooledXmlArtifact instance.

Remarks ​

Uses the cross-realm-safe @nhtio/adk!isInstanceOf guard. Safe against the dual-module-copy case where two distinct SpooledXmlArtifact classes coexist in the same realm.

Copyright © 2025-present New Horizon Technology LTD