defineTreeProjection

KIT · function · Runtime value

Compile a depth-limited tree transform.

Traverse synchronously in property/array order; only undefined omits a result. Because a visitor returns a new value instead of mutating, an omitted branch disappears from arrays and objects the same way, and maxDepth bounds both cycles and cost.

Import

TypeScript

import { defineTreeProjection } from '@jangts/agent-core/kits/projection';

JavaScript

import { defineTreeProjection } from '@jangts/agent-core/kits/projection';

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

Definition

Type parameters

Type parameter	Constraint	Default type
Context	—	—

Call

defineTreeProjection<Context>(options: TreeProjectionOptions<Context>): Readonly<{ visit: (value: unknown, context: Context) => unknown; }>

Compile a depth-limited tree transform.

Traverse synchronously in property/array order; only undefined omits a result. Because a visitor returns a new value instead of mutating, an omitted branch disappears from arrays and objects the same way, and maxDepth bounds both cycles and cost.

Type parameter	Constraint	Default type
Context	—	—

Parameter	Type	Passing	Description
options	TreeProjectionOptions<Context>	Required	—

Fields of options

Field	Type	Required	Description
maxDepth	number	Required	Read-only. Maximum included depth; deeper values are omitted. Must be a non-negative integer.
omit	((value: unknown, depth: number, context: Context) => boolean) | undefined	Optional	Read-only. Drops a value when it returns true; must be synchronous boolean.
visitRecord	((value: Record<string, unknown>, depth: number, context: Context) => void) | undefined	Optional	Read-only. Observes every retained record, for example to record which fields were kept.

Returns: Readonly<{ visit: (value: unknown, context: Context) => unknown; }>.

Return value structure

Field	Type	Required	Description
visit	(value: unknown, context: Context) => unknown	Required	See the type definition and usage context.

Examples

• Projection: project content under a budget: Shorten text first, then reduce entries; source data, projection result, and budget are explicitly separated by the App.

Prepare compact JSON for the same query result

Beginner · Node.js

TypeScript

import { Projection } from '@jangts/agent-core/kits/projection';
const projection = Projection.defineContentProjection({
  counts: [10, 3, 1], lengths: [200, 80, 20],
  render: value => JSON.stringify(value), fallback: () => '{}',
});
const result = projection.project({ value: { items: [{ title: '配置说明', body: '正文'.repeat(100) }] }, maxChars: 120 });
console.log(result.text, result.truncated);

JavaScript

import { Projection } from '@jangts/agent-core/kits/projection';
const projection = Projection.defineContentProjection({
    counts: [10, 3, 1], lengths: [200, 80, 20],
    render: value => JSON.stringify(value), fallback: () => '{}',
});
const result = projection.project({ value: { items: [{ title: '配置说明', body: '正文'.repeat(100) }] }, maxChars: 120 });
console.log(result.text, result.truncated);

Remove private fields from the same data, then project under budget

Configuration · Node.js

TypeScript

import { Projection } from '@jangts/agent-core/kits/projection';
const tree = Projection.defineTreeProjection({
  maxDepth: 4,
  visitRecord(record) { delete record.privateNote; },
});
const source = { items: [{ title: '配置说明', body: '正文'.repeat(100), privateNote: '不向模型提供' }] };
// 调用者明确选择副本所有权；visitor 不会碰原记录。
const publicData = tree.visit(structuredClone(source), undefined);
const compact = Projection.defineContentProjection({ counts: [10, 3, 1], lengths: [200, 80, 20], render: JSON.stringify, fallback: () => '{}' });
console.log(compact.project({ value: publicData, maxChars: 120 }));

JavaScript

import { Projection } from '@jangts/agent-core/kits/projection';
const tree = Projection.defineTreeProjection({
    maxDepth: 4,
    visitRecord(record) { delete record.privateNote; },
});
const source = { items: [{ title: '配置说明', body: '正文'.repeat(100), privateNote: '不向模型提供' }] };
// 调用者明确选择副本所有权；visitor 不会碰原记录。
const publicData = tree.visit(structuredClone(source), undefined);
const compact = Projection.defineContentProjection({ counts: [10, 3, 1], lengths: [200, 80, 20], render: JSON.stringify, fallback: () => '{}' });
console.log(compact.project({ value: publicData, maxChars: 120 }));

Keep continuous body text instead of splitting paragraphs

Extension · Node.js

The output length of render must grow monotonically with the prefix length for the binary search to be meaningful.

TypeScript

import { Projection } from '@jangts/agent-core/kits/projection';
const body = '一段连续的资料正文。'.repeat(100);
const excerpt = Projection.projectContinuousExcerpt(body, 120, length => JSON.stringify({ excerpt: body.slice(0, length) }));
if (excerpt) console.log(JSON.parse(excerpt.text));

JavaScript

import { Projection } from '@jangts/agent-core/kits/projection';
const body = '一段连续的资料正文。'.repeat(100);
const excerpt = Projection.projectContinuousExcerpt(body, 120, length => JSON.stringify({ excerpt: body.slice(0, length) }));
if (excerpt)
    console.log(JSON.parse(excerpt.text));

Related policy source

• Reduction order and tree traversal

Related definitions

• TreeProjectionOptions