defineQueryAggregation

KIT · function · Runtime value

Compile one ordered read plan over a list of inputs.

Ordered synchronous queries with optional stable-key merging; each real read stays host-owned. Inputs run sequentially in the given order, so a host can rely on a deterministic visit sequence. Without key every item is kept; with key the last write wins per key but the position of the first occurrence is retained.

Import

TypeScript

import { defineQueryAggregation } from '@jangts/agent-core/kits/aggregation';

JavaScript

import { defineQueryAggregation } from '@jangts/agent-core/kits/aggregation';

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

Definition

Type parameters

Type parameter	Constraint	Default type
Input	—	—
Item	—	—
Context	—	—

Call

defineQueryAggregation<Input, Item, Context>(options: QueryAggregationOptions<Input, Item, Context>): Readonly<{ collect(inputs: readonly Input[], context: Context, execution?: Partial<import("../structs/common.js").ExecutionContext>): { total: number; items: Item[]; }; }>

Compile one ordered read plan over a list of inputs.

Ordered synchronous queries with optional stable-key merging; each real read stays host-owned. Inputs run sequentially in the given order, so a host can rely on a deterministic visit sequence. Without key every item is kept; with key the last write wins per key but the position of the first occurrence is retained.

Type parameter	Constraint	Default type
Input	—	—
Item	—	—
Context	—	—

Parameter	Type	Passing	Description
options	QueryAggregationOptions<Input, Item, Context>	Required	—

Fields of options

Field	Type	Required	Description
execute	(input: Input, context: Context) => readonly Item[]	Required	Read-only. Reads one input. Called once per input, in caller order, and must return synchronously.
key	((item: Item, input: Input, context: Context) => string) | undefined	Optional	Read-only. Optional stable merge key. Items with the same key collapse into the first position seen.
merge	((item: Item, previous: Item | undefined, input: Input, context: Context) => Item) | undefined	Optional	Read-only. Combines a duplicate with the value merged so far; receives undefined for the first item.

Returns: Readonly<{ collect(inputs: readonly Input[], context: Context, execution?: Partial<import("../structs/common.js").ExecutionContext>): { total: number; items: Item[]; }; }>.

Return value structure

Field	Type	Required	Description
collect	(inputs: readonly Input[], context: Context, execution?: Partial<import("../structs/common.js").ExecutionContext>) => { total: number; items: Item[]; }	Required	Run every input in order.

Examples

• Aggregation: query aggregation and stable merging: Read App data in order and keep how duplicate items are merged in the same configuration.

Aggregate two reads in order

Beginner · Node.js

TypeScript

import { Aggregation } from '@jangts/agent-core/kits/aggregation';
const pages = new Map([[1, [{ id: 'a', title: '第一页' }]], [2, [{ id: 'a', title: '重复项' }, { id: 'b', title: '第二页' }]]]);
const query = Aggregation.defineQueryAggregation({ execute: (page: number) => pages.get(page) ?? [] });
console.log(query.collect([1, 2], undefined));

JavaScript

import { Aggregation } from '@jangts/agent-core/kits/aggregation';
const pages = new Map([[1, [{ id: 'a', title: '第一页' }]], [2, [{ id: 'a', title: '重复项' }, { id: 'b', title: '第二页' }]]]);
const query = Aggregation.defineQueryAggregation({ execute: (page) => pages.get(page) ?? [] });
console.log(query.collect([1, 2], undefined));

Add a primary key and retention policy to the same collect

Configuration · Node.js

TypeScript

import { Aggregation } from '@jangts/agent-core/kits/aggregation';
type Row = { id: string; title: string };
const pages = new Map<number, Row[]>([[1, [{ id: 'a', title: '第一页' }]], [2, [{ id: 'a', title: '重复项' }, { id: 'b', title: '第二页' }]]]);
const query = Aggregation.defineQueryAggregation({
  execute: (page: number) => pages.get(page) ?? [],
  key: (row: Row) => row.id,
  merge: (row: Row, previous: Row | undefined) => previous ?? row,
});
console.log(query.collect([1, 2], undefined));
console.log(Aggregation.mergeByKey([...pages.values()].flat(), row => row.id, (row, previous) => previous ?? row));

JavaScript

import { Aggregation } from '@jangts/agent-core/kits/aggregation';
const pages = new Map([[1, [{ id: 'a', title: '第一页' }]], [2, [{ id: 'a', title: '重复项' }, { id: 'b', title: '第二页' }]]]);
const query = Aggregation.defineQueryAggregation({
    execute: (page) => pages.get(page) ?? [],
    key: (row) => row.id,
    merge: (row, previous) => previous ?? row,
});
console.log(query.collect([1, 2], undefined));
console.log(Aggregation.mergeByKey([...pages.values()].flat(), row => row.id, (row, previous) => previous ?? row));

Related policy source

• Stable key merging and read order

Related definitions

• QueryAggregationOptions