Class: SpooledEcmaScriptArtifact

Defined in: src/batteries/artifacts/ecmascript/index.ts:166

A @nhtio/adk!SpooledArtifact specialisation for EcmaScript (JavaScript and TypeScript) source files.

Remarks

Parses source code syntactically (no type checker) using the TypeScript compiler API, enabling structural queries without materialising the full file into memory.

The parser automatically infers the script kind (.js, .ts, .jsx, .tsx) from the fileName when provided; defaults to ts when omitted (it parses the widest grammar).

All parsing errors are non-fatal — TypeScript's parser is error-tolerant and produces a partial tree. Diagnostics are not surfaced by the query methods.

Extends

• SpooledArtifact

Constructors

Constructor

new SpooledEcmaScriptArtifact(reader: SpoolReader, options?: {
  fileName?: string;
  scriptKind?: "js" | "jsx" | "ts" | "tsx";
}): SpooledEcmaScriptArtifact;

Defined in: src/batteries/artifacts/ecmascript/index.ts:180

Parameters

Parameter	Type	Description
reader	SpoolReader	The backing store to read from.
options?	{ fileName?: string; scriptKind?: "js" | "jsx" | "ts" | "tsx"; }	Optional configuration.
options.fileName?	string	The source file name. When provided, script kind is inferred from the extension (.mts/.cts/.ts → 'ts', .mjs/.cjs/.js → 'js', .tsx → 'tsx', .jsx → 'jsx'). Defaults to undefined.
options.scriptKind?	"js" | "jsx" | "ts" | "tsx"	Explicit script kind override. Defaults to 'ts' when not provided and cannot be inferred from fileName.

Returns

SpooledEcmaScriptArtifact

Overrides

SpooledArtifact.constructor

Properties

Property	Modifier	Type	Description	Overrides	Defined in
toolMethods	static	readonly ToolMethodDescriptor[]	The EcmaScript-specific artifact-query descriptors this class adds. Remarks Lists seven descriptors; the base seven (artifact_head, etc.) are forged separately.	SpooledArtifact.toolMethods	src/batteries/artifacts/ecmascript/index.ts:209

Methods

[ENCODE_METHOD]()

ENCODE_METHOD: unknown;

Defined in: src/batteries/artifacts/ecmascript/index.ts:1135

Serialise this SpooledEcmaScriptArtifact into an encoder snapshot.

Returns

unknown

Inherited from

SpooledArtifact.[ENCODE_METHOD]

---

[ENCODE_METHOD]()

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

SpooledArtifact.[ENCODE_METHOD]

---

asString()

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()

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()

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

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

Inherited from

SpooledArtifact.cat

---

es_exports()

es_exports(): Promise<EcmaScriptExport[]>;

Defined in: src/batteries/artifacts/ecmascript/index.ts:578

Return every export declaration and re-export.

Returns

Promise<EcmaScriptExport[]>

---

es_imports()

es_imports(): Promise<EcmaScriptImport[]>;

Defined in: src/batteries/artifacts/ecmascript/index.ts:520

Return every import declaration.

Returns

Promise<EcmaScriptImport[]>

---

es_jsdoc()

es_jsdoc(name: string): Promise<string>;

Defined in: src/batteries/artifacts/ecmascript/index.ts:1077

Return the JSDoc comment for a named declaration. Searches top-level declarations (functions, classes, interfaces, enums, type aliases, const/let/var bindings), class members (methods, properties, constructors, accessors), and interface members (method signatures, property signatures) — the same lookup SpooledEcmaScriptArtifact.es_signature uses, so the two always agree on what a name resolves to.

Parameters

Parameter	Type
name	string

Returns

Promise<string>

---

es_outline()

es_outline(): Promise<OutlineEntry[]>;

Defined in: src/batteries/artifacts/ecmascript/index.ts:703

Return a structural outline of classes and interfaces with their members.

Returns

Promise<OutlineEntry[]>

---

es_references()

es_references(name: string): Promise<IdentifierReference[]>;

Defined in: src/batteries/artifacts/ecmascript/index.ts:1109

Return every line where an identifier appears (syntactic scan only).

Parameters

Parameter	Type
name	string

Returns

Promise<IdentifierReference[]>

---

es_signature()

es_signature(name: string): Promise<string>;

Defined in: src/batteries/artifacts/ecmascript/index.ts:1059

Return the signature text for a named declaration. Searches top-level declarations (functions, classes, interfaces, enums, type aliases, const/let/var bindings), class members (methods, properties, constructors, accessors), and interface members (method signatures, property signatures) — the same lookup SpooledEcmaScriptArtifact.es_jsdoc uses, so the two always agree on what a name resolves to.

Parameters

Parameter	Type
name	string

Returns

Promise<string>

---

es_symbols()

es_symbols(kind?: string): Promise<EcmaScriptSymbol[]>;

Defined in: src/batteries/artifacts/ecmascript/index.ts:419

Return every top-level declaration, optionally filtered by kind.

Parameters

Parameter	Type
kind?	string

Returns

Promise<EcmaScriptSymbol[]>

---

estimateHandleTokens()

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

Parameter	Type	Description
callId	string	The 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; }) => string	Optional renderer overriding the interim default.

Returns

number

A synchronous token estimate.

Inherited from

SpooledArtifact.estimateHandleTokens

---

estimateTokens()

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

Parameter	Type	Description
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()

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

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

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

---

hasSizeHints()

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

---

head()

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

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

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

---

lineCount()

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()

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

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

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

---

[DECODE_METHOD]()

static DECODE_METHOD: SpooledEcmaScriptArtifact;

Defined in: src/batteries/artifacts/ecmascript/index.ts:1146

Reconstruct a SpooledEcmaScriptArtifact from an encoder snapshot.

Parameters

Parameter	Type
data	unknown

Returns

SpooledEcmaScriptArtifact

Inherited from

SpooledArtifact.[DECODE_METHOD]

---

[DECODE_METHOD]()

static DECODE_METHOD: SpooledArtifact;

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

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

Parameters

Parameter	Type	Description
data	unknown	The 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

SpooledArtifact.[DECODE_METHOD]

---

forgeTools()

static forgeTools(ctx: DispatchContext): ToolRegistry;

Defined in: src/batteries/artifacts/ecmascript/index.ts:284

Forges base-class tools plus EcmaScript-specific tools narrowed to SpooledEcmaScriptArtifact.

Parameters

Parameter	Type
ctx	DispatchContext

Returns

ToolRegistry

Overrides

SpooledArtifact.forgeTools

---

isSpooledArtifact()

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

Parameter	Type	Description
value	unknown	The 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()

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

Parameter	Type	Description
value	unknown	The 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

---

isSpooledEcmaScriptArtifact()

static isSpooledEcmaScriptArtifact(value: unknown): value is SpooledEcmaScriptArtifact;

Defined in: src/batteries/artifacts/ecmascript/index.ts:199

Returns true if value is a SpooledEcmaScriptArtifact instance.

Parameters

Parameter	Type
value	unknown

Returns

value is SpooledEcmaScriptArtifact

Remarks

Uses the cross-realm-safe @nhtio/adk!isInstanceOf guard. Safe against the dual-module-copy case.