@nhtio/adk

Appearance

12 min read · 2,416 words

Class: SpooledYamlArtifact ​

Defined in: src/batteries/artifacts/yaml/index.ts:95

A SpooledArtifact specialisation that adds YAML-aware read operations.

Remarks ​

Handles both single-document YAML and multi-document streams (delimited by ---). Parsed documents are cached in a private field for the lifetime of the instance.

For multi-document streams:

  • yaml_length reports the document count.
  • yaml_keys returns the deduplicated union of keys across all documents.
  • yaml_get / yaml_filter / yaml_pluck evaluate paths against all documents and return a flat array of all matches.

Non-finite numbers (.NaN, .inf, -.inf) present in the YAML are preserved through the yaml_to_json converter using a custom replacer.

Extends ​

Constructors ​

Constructor ​

ts
new SpooledYamlArtifact(reader: SpoolReader, options?: {
  multiDocument?: boolean;
}): SpooledYamlArtifact;

Defined in: src/batteries/artifacts/yaml/index.ts:108

Parameters ​

ParameterTypeDescription
readerSpoolReaderThe backing store to read from.
options?{ multiDocument?: boolean; }Optional configuration for parsing.
options.multiDocument?booleanDeclares the source's document mode. true parses as a stream and makes SpooledYamlArtifact.yaml_type report 'multi-document' regardless of the current count. false asserts exactly one document and parses with load, so a --- stream raises E_YAML_PARSE_ERROR instead of being silently accepted. When omitted, mode is auto-detected by parsing the content with loadAll.

Returns ​

SpooledYamlArtifact

Overrides ​

SpooledArtifact.constructor

Properties ​

PropertyModifierTypeDescriptionOverridesDefined in
toolMethodsstaticreadonly ToolMethodDescriptor[]The YAML-specific artifact-query descriptors this class adds on top of the base set. Remarks Lists artifact_yaml_type, artifact_yaml_keys, artifact_yaml_length, artifact_yaml_get, artifact_yaml_filter, artifact_yaml_slice, artifact_yaml_pluck. The base seven descriptors (artifact_head, etc.) are NOT included here — they are forged separately by SpooledYamlArtifact.forgeTools.SpooledArtifact.toolMethodssrc/batteries/artifacts/yaml/index.ts:139

Methods ​

[ENCODE_METHOD]() ​

ts
ENCODE_METHOD: unknown;

Defined in: src/batteries/artifacts/yaml/index.ts:455

Serialise this SpooledYamlArtifact into an @nhtio/encoder snapshot.

Returns ​

unknown

A snapshot consumed by SpooledYamlArtifact.[DECODE_METHOD].

Remarks ​

Overrides SpooledArtifact.[ENCODE_METHOD] to carry the constructor's multiDocument option. The parsed-document cache is derived and not encoded. Round-trips via SpooledYamlArtifact.[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

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

yaml_filter() ​

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

Defined in: src/batteries/artifacts/yaml/index.ts:408

Returns documents matched by a JSONPath filter expression.

Parameters ​

ParameterTypeDescription
pathstringA JSONPath expression (e.g. '$[?(@.status === "active")]').

Returns ​

Promise<unknown[]>

Array of matching documents.

Remarks ​

Evaluates path against each document and returns those for which the expression produces at least one match.

yaml_get() ​

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

Defined in: src/batteries/artifacts/yaml/index.ts:393

Evaluates a JSONPath expression against the parsed documents.

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 ​

For single-document: evaluates the expression against the root value. For multi-document: evaluates the expression against each document and returns a flat array of all matches across all documents.

Uses JSONPath-Plus. Full JSONPath syntax is supported.

yaml_keys() ​

ts
yaml_keys(): Promise<string[] | undefined>;

Defined in: src/batteries/artifacts/yaml/index.ts:347

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 single-document: returns the keys of the root object, or undefined when the root is not a plain object. For multi-document: returns the union of keys across all documents that are plain objects. Duplicate keys are deduplicated.

yaml_length() ​

ts
yaml_length(): Promise<number>;

Defined in: src/batteries/artifacts/yaml/index.ts:374

Returns the total number of documents in the artifact.

Returns ​

Promise<number>

The document count.

Remarks ​

The result comes directly from js-yaml.loadAll(). For sources with no actual YAML content (empty, whitespace-only, or BOM-only), the parser typically returns 0 documents, but certain whitespace arrangements (such as a bare double newline) may yield 1. Do not rely on the exact count to test for emptiness. For real documents, the count is reliable: a single-document YAML returns 1, and a ----separated stream returns its exact document count.

yaml_pluck() ​

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

Defined in: src/batteries/artifacts/yaml/index.ts:441

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

Parameters ​

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

Returns ​

Promise<unknown[]>

Array of matched values.

Remarks ​

Convenience over yaml_get with an identical signature — use whichever name better communicates intent at the call site.

yaml_slice() ​

ts
yaml_slice(start?: number, end?: number): Promise<unknown[]>;

Defined in: src/batteries/artifacts/yaml/index.ts:426

Returns a slice of documents by index range.

Parameters ​

ParameterTypeDescription
start?numberStart index (inclusive). Defaults to 0.
end?numberEnd index (exclusive). Defaults to the document count.

Returns ​

Promise<unknown[]>

Array of sliced documents.

Remarks ​

Behaves like Array.prototype.slice over the document array.

yaml_type() ​

ts
yaml_type(): Promise<"single-document" | "multi-document">;

Defined in: src/batteries/artifacts/yaml/index.ts:328

Returns whether this artifact contains a single document or multiple documents.

Returns ​

Promise<"single-document" | "multi-document">

'single-document' or 'multi-document'.

Remarks ​

When the constructor was given multiDocument: true, the source is treated as a stream and this reports 'multi-document' even if that stream currently holds one document — a one-element stream is still a stream, and SpooledYamlArtifact.yaml_length reports the real count either way. multiDocument: false cannot disagree with the count, because parsing a --- stream under it fails outright rather than silently reporting the wrong mode.

[DECODE_METHOD]() ​

ts
static DECODE_METHOD: SpooledYamlArtifact;

Defined in: src/batteries/artifacts/yaml/index.ts:466

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

Parameters ​

ParameterTypeDescription
dataunknownThe snapshot produced by SpooledYamlArtifact.[ENCODE_METHOD].

Returns ​

SpooledYamlArtifact

A fresh SpooledYamlArtifact} 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/yaml/index.ts:216

Forges base-class tools plus YAML-specific tools narrowed to SpooledYamlArtifact.

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

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

isSpooledYamlArtifact() ​

ts
static isSpooledYamlArtifact(value: unknown): value is SpooledYamlArtifact;

Defined in: src/batteries/artifacts/yaml/index.ts:126

Returns true if value is a SpooledYamlArtifact instance.

Parameters ​

ParameterTypeDescription
valueunknownThe value to test.

Returns ​

value is SpooledYamlArtifact

true when value is a SpooledYamlArtifact instance.

Remarks ​

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

Copyright © 2025-present New Horizon Technology LTD