Skip to content

Results ​

analyze() returns CjslashResult. It extends TwoslashGenericResult from twoslash-protocol, preserves upstream node shapes, and adds Cangjie metadata and derived getters.

Top-level fields ​

FieldTypeMeaning
codestringFinal source for display
extension'cj'Output language extension
nodesTwoslashNode[]All semantic, diagnostic, and annotation nodes
metaCjslashResultMetaSettings and metadata in original-source coordinates
hoversNodeHover[]Automatic hover nodes
queriesNodeQuery[]Explicit type query nodes
errorsNodeError[]Diagnostics, including warnings and other levels
highlightsNodeHighlight[]Range highlights
tagsNodeTag[]Custom annotation tags
completionsNodeCompletion[]Completion nodes requested by ^| or explicit positions

nodes is the single source of node data. The categorized getters derive their values from nodes each time they are read.

ts
import { 
createCjslasher
} from '@cjslash/core'
await using
cjslasher
= await
createCjslasher
({
sdkPath
: '/path/to/cangjie' })
const
result
= await
cjslasher
.
analyze
('let answer = 42\n// ^?\nmain() { println(answer) }\n')
const
query
=
result
.
queries
[0]
if (
query
) {
console
.
log
(
query
.
text
)
console
.
log
(
result
.
code
.
slice
(
query
.
start
,
query
.
start
+
query
.
length
))
}

The second log prints the query target, answer.

Information nodes ​

Nodes are discriminated by type. Position fields retain the upstream shape:

Common fieldMeaning
typehover, query, error, highlight, tag, or completion
startZero-based starting offset in the output source
lengthRange length; may be zero
lineZero-based starting line
characterZero-based starting column

Common type-specific fields:

NodeFields
hover, querytarget is the source text, text is the signature, and docs may be present
errortext is the message; code, level, filename, and id may be present
highlightMay include an annotation text
tagname is the tag name; text is optional content
completioncompletions is { name, kind? }[], completionsPrefix is the typed prefix, and length is 0

Narrow the union through node.type before reading type-specific fields. NodeHover, NodeQuery, and other node types come directly from twoslash-protocol; there is no separate Cangjie node format.

Coordinates and cropping ​

start, length, character, and explicit position options use UTF-16 code units, rather than bytes or visual character widths. JavaScript string indexing and slice() use the same unit; an emoji can occupy two code units.

DataCoordinate base
result.nodes and categorized gettersFinal result.code
result.meta.removalsOriginal input
result.meta.positionQueriesOriginal input
result.meta.positionCompletionsOriginal input
result.meta.positionHighlightsOriginal input
CjslashError.diagnosticsOriginal input of the failed analysis

Node intervals are [start, start + length). Removal and highlight ranges are [start, end), with the right endpoint excluded.

By default, positions are recalculated after annotations and hidden source are removed. With keepNotations, result.code stays identical to the input, and nodes use input positions. meta.removals still records the ranges that would otherwise be removed.

Metadata ​

CjslashResultMeta fieldMeaning
extensionAlways cj
handbookOptionsFully resolved defaults, API options, and source annotations
removalsRanges to remove from the original input
positionQueriesExplicit query offsets in the original input
positionCompletionsCompletion cursor offsets in the original input
positionHighlightsOriginal-input highlights as [start, end, text?]

Metadata connects author input to final presentation. When using Shiki, still pass the original source; the transformer reads the prepared result.

In multi-file examples, node offsets and line numbers still refer to the complete code block. They do not reset at file boundaries. Diagnostic filename fields identify the virtual source file and remain unchanged by cropping.

Protocol utilities ​

@cjslash/protocol directly exports upstream Position, Range, TwoslashNode, NodeWithoutPosition, and node types, alongside these utilities:

createPositionConverter, splitLines, isInRange, isInRanges, mergeRanges, removeCodeRanges, resolveNodePositions.

These utilities retain their upstream semantics. For example, isInRange includes both endpoints by default, so its default behavior differs from the half-open ranges described above.

Serialization ​

To store or transfer a result, use code, extension, nodes, and meta as data. JSON parsing does not restore getters. Derive dynamic categorized views from the restored nodes using node.type if needed. The core API does not expose a separate cache-restoration factory.