defineContentProjection

KIT · function · Runtime value

Compile a JSON-preserving projector.

Keep valid JSON while reducing prose before dropping records; budgets are caller policy. The candidate list is tried in order (outer counts, inner lengths), so callers control whether trimming text or dropping items is preferred, and the configured fallback is used only when no candidate fits.

Import

TypeScript

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

JavaScript

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

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

Definition

Call

defineContentProjection(options: ContentProjectionOptions): Readonly<{ project: ({ value, maxChars: limit, }: { value: unknown; maxChars: number; }) => ContentProjection; }>

Compile a JSON-preserving projector.

Keep valid JSON while reducing prose before dropping records; budgets are caller policy. The candidate list is tried in order (outer counts, inner lengths), so callers control whether trimming text or dropping items is preferred, and the configured fallback is used only when no candidate fits.

Parameter	Type	Passing	Description
options	ContentProjectionOptions	Required	—

Fields of options

Field	Type	Required	Description
counts	readonly number[]	Required	Read-only. Maximum array items to keep, tried in order before moving to the next length.
lengths	readonly number[]	Required	Read-only. Maximum characters per string, tried in order inside each count candidate.
render	(excerpt: unknown) => string	Required	Read-only. Renders a shortened value; must be synchronous.
fallback	(limit: number) => string	Required	Read-only. Builds fallback text for a limit, used when no candidate fits; must be synchronous.

Returns: Readonly<{ project: ({ value, maxChars: limit, }: { value: unknown; maxChars: number; }) => ContentProjection; }>.

Return value structure

Field	Type	Required	Description
project	({ value, maxChars: limit, }: { value: unknown; maxChars: number; }) => ContentProjection	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

• ContentProjectionOptions