@nhtio/adk

Appearance

10 min read · 2,014 words

Class: SpooledMarkdownArtifact ​

A @nhtio/adk!SpooledArtifact specialisation that adds markdown-aware structural queries.

Remarks ​

Designed for large markdown documents where loading the full content into memory is impractical. The structural index (heading positions, code block positions) is built by a single line-by-line scan of the @nhtio/adk!SpoolReader without retaining any content. Only the tiny metadata index and the parsed frontmatter object are cached.

Content retrieval is always bounded — use cat(start, end) or the startLine/endLine parameters on inline methods to fetch only the lines you need.

Inline methods (md_links, md_images, md_text, md_ast) accept optional line-range arguments. Without a range they read the full document — documented trade-off, caller responsibility to bound the range for large documents.

The processor always applies remark-gfm (tables, task lists, strikethrough, autolinks) in addition to standard CommonMark and YAML frontmatter.

Extends ​

Constructors ​

Constructor ​

ts
new SpooledMarkdownArtifact(reader: SpoolReader): SpooledMarkdownArtifact;

Parameters ​

ParameterTypeDescription
readerSpoolReaderThe backing store to read from.

Returns ​

SpooledMarkdownArtifact

Overrides ​

SpooledArtifact.constructor

Properties ​

PropertyModifierTypeDescriptionOverrides
toolMethodsstaticreadonly ToolMethodDescriptor[]The markdown-specific artifact-query descriptors this class adds on top of the base set. Remarks Lists artifact_md_frontmatter, artifact_md_headings, artifact_md_code_blocks, artifact_md_sections, artifact_md_links, artifact_md_images, artifact_md_text, artifact_md_ast. The base seven descriptors (artifact_head, etc.) are NOT included here — they are forged separately by SpooledMarkdownArtifact.forgeTools, which calls SpooledArtifact.forgeTools(ctx) to produce the base-narrowed tools and then registers its own markdown 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

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

md_ast() ​

ts
md_ast(startLine?: number, endLine?: number): Promise<Root>;

Returns the full MDAST Root for the specified line range.

Parameters ​

ParameterTypeDescription
startLine?number0-based start line (inclusive). Defaults to 0.
endLine?number0-based end line (exclusive). Defaults to lineCount().

Returns ​

Promise<Root>

Remarks ​

Without a range, reads the full document — for large documents, use SpooledMarkdownArtifact.md_sections to locate sections and pass bounded line ranges here.

md_code_blocks() ​

ts
md_code_blocks(lang?: string): Promise<MarkdownCodeEntry[]>;

Returns all fenced code block entries, optionally filtered by language identifier.

Parameters ​

ParameterTypeDescription
lang?stringWhen provided, only blocks with this exact lang identifier are returned. Pass an empty string to match blocks with no lang identifier.

Returns ​

Promise<MarkdownCodeEntry[]>

Remarks ​

Returns line-range metadata only — no content is fetched. Use cat(entry.startLine + 1, entry.endLine) to retrieve the code body (excluding fence lines).

md_frontmatter() ​

ts
md_frontmatter(): Promise<
  | Record<string, unknown>
| undefined>;

Returns the parsed YAML frontmatter, or undefined when no frontmatter block is present.

Returns ​

Promise< | Record<string, unknown> | undefined>

Remarks ​

Short-circuits after reading the frontmatter block — never reads the document body. Caches the result so subsequent calls are free. The result is undefined (not an empty object) when no frontmatter is found, distinguishing "no frontmatter" from "empty frontmatter".

md_headings() ​

ts
md_headings(depth?: 1 | 2 | 3 | 4 | 5 | 6): Promise<MarkdownHeadingEntry[]>;

Returns all headings in document order, optionally filtered by depth.

Parameters ​

ParameterTypeDescription
depth?1 | 2 | 3 | 4 | 5 | 6When provided, only headings at this ATX depth (1–6) are returned.

Returns ​

Promise<MarkdownHeadingEntry[]>

Remarks ​

Uses the cached structural index — no content is fetched from the @nhtio/adk!SpoolReader.

md_images() ​

ts
md_images(startLine?: number, endLine?: number): Promise<{
  alt: string;
  title?: string;
  url: string;
}[]>;

Returns all images in the specified line range.

Parameters ​

ParameterTypeDescription
startLine?number0-based start line (inclusive). Defaults to 0.
endLine?number0-based end line (exclusive). Defaults to lineCount().

Returns ​

Promise<{ alt: string; title?: string; url: string; }[]>

ts
md_links(startLine?: number, endLine?: number): Promise<{
  text: string;
  title?: string;
  url: string;
}[]>;

Returns all inline and reference links in the specified line range.

Parameters ​

ParameterTypeDescription
startLine?number0-based start line (inclusive). Defaults to 0.
endLine?number0-based end line (exclusive). Defaults to lineCount().

Returns ​

Promise<{ text: string; title?: string; url: string; }[]>

md_sections() ​

ts
md_sections(depth?: 1 | 2 | 3 | 4 | 5 | 6): Promise<MarkdownSection[]>;

Returns document sections derived from the structural index.

Parameters ​

ParameterTypeDescription
depth?1 | 2 | 3 | 4 | 5 | 6When provided, only sections at this ATX depth (1–6) are returned.

Returns ​

Promise<MarkdownSection[]>

Remarks ​

Returns only line-range metadata — body content is never fetched. To retrieve the body of a section, call cat(section.bodyStartLine, section.bodyEndLine + 1).

When depth is provided, only sections introduced by a heading at that depth are returned; deeper headings become part of the body.

md_text() ​

ts
md_text(startLine?: number, endLine?: number): Promise<string>;

Returns all document text with markup stripped, for the specified line range.

Parameters ​

ParameterTypeDescription
startLine?number0-based start line (inclusive). Defaults to 0.
endLine?number0-based end line (exclusive). Defaults to lineCount().

Returns ​

Promise<string>

Remarks ​

Uses mdast-util-to-string to extract plain text from the AST — code, link text, and alt text are included; markdown syntax is removed.

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 markdown-specific tools narrowed to SpooledMarkdownArtifact.

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 markdown-specific descriptor narrowed to markdown 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

isSpooledMarkdownArtifact() ​

ts
static isSpooledMarkdownArtifact(value: unknown): value is SpooledMarkdownArtifact;

Returns true if value is a SpooledMarkdownArtifact instance.

Parameters ​

ParameterType
valueunknown

Returns ​

value is SpooledMarkdownArtifact

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 SpooledMarkdownArtifact classes coexist in the same realm.

Copyright © 2025-present New Horizon Technology LTD