TextBlock

KIT · interface · Type contract

One structure-aware block of a long text.

Import

TypeScript

import type { TextBlock } from '@jangts/agent-core/kits/text-blocks';

JavaScript

/** @typedef {import('@jangts/agent-core/kits/text-blocks').TextBlock} TextBlock */

Other public entry points:@jangts/agent-core/types, @jangts/agent-core/kits, @jangts/agent-core/kits/text-blocks.

Definition

interface TextBlock

Field structure

Field	Type	Required	Description
number	number	Required	Read-only. One-based position in source order; stable for a given text and target size.
text	string	Required	Read-only. Exact source substring, including its own line endings.
start	number	Required	Read-only. Start offset in UTF-16 code units.
end	number	Required	Read-only. End offset (exclusive) in UTF-16 code units; end - start === text.length.

Examples

• TextBlocks: structure-aware splitting of long text: Split long text into bounded structural blocks while keeping the original text and offsets for paging or indexing.

First split a short document with two sections

Beginner · Node.js

The example only demonstrates the splitting contract; paging windows, context budgets and prompts still belong to the App.

TypeScript

import { TextBlocks } from '@jangts/agent-core/kits/text-blocks';
const text = '# 概览\n\n' + '说明内容\n'.repeat(4) + '\n## 细节\n\n' + '更多内容\n'.repeat(4);
const blocks = TextBlocks.split(text, { targetChars: 40 });
console.log(blocks.map(block => [block.number, block.start, block.end]));
console.log(blocks.map(block => block.text).join('') === text);

JavaScript

import { TextBlocks } from '@jangts/agent-core/kits/text-blocks';
const text = '# 概览\n\n' + '说明内容\n'.repeat(4) + '\n## 细节\n\n' + '更多内容\n'.repeat(4);
const blocks = TextBlocks.split(text, { targetChars: 40 });
console.log(blocks.map(block => [block.number, block.start, block.end]));
console.log(blocks.map(block => block.text).join('') === text);

Page through blocks and record coverage

Configuration · Node.js

Block boundaries are not a fixed character window; record each block start/end instead of inferring character positions.

TypeScript

import { TextBlocks, type TextBlock } from '@jangts/agent-core/kits/text-blocks';
const text = '# 报告\n\n' + '记录内容\n'.repeat(200);
const blocks = TextBlocks.split(text, { targetChars: 4000 });
const page = (offset: number, limit: number): { blocks: TextBlock[]; nextOffset?: number } => ({
  blocks: blocks.slice(offset, offset + limit),
  nextOffset: offset + limit < blocks.length ? offset + limit : undefined,
});
const first = page(0, 2);
console.log(first.blocks.map(block => block.number), first.nextOffset);

JavaScript

import { TextBlocks } from '@jangts/agent-core/kits/text-blocks';
const text = '# 报告\n\n' + '记录内容\n'.repeat(200);
const blocks = TextBlocks.split(text, { targetChars: 4000 });
const page = (offset, limit) => ({
    blocks: blocks.slice(offset, offset + limit),
    nextOffset: offset + limit < blocks.length ? offset + limit : undefined,
});
const first = page(0, 2);
console.log(first.blocks.map(block => block.number), first.nextOffset);

Related policy source

• Structural boundaries, exact reassembly, and source offsets