Aggregation

KIT · constant · Runtime value

Import

TypeScript

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

JavaScript

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

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

Definition

Member index

Member	Purpose
defineQueryAggregation	See the overload below for full inputs and outputs.
mergeByKey	See the overload below for full inputs and outputs.

Member details

defineQueryAggregation

Aggregation.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.

mergeByKey

Aggregation.mergeByKey<Item, Key>(items: Iterable<Item>, key: (item: Item) => Key, select: (item: Item, previous: Item | undefined) => Item): Item[]

Merge duplicates without moving their first position; selection policy remains host-owned.

The first occurrence of a key fixes the output position; select decides which item that position finally holds, so callers can prefer the newest or the most complete duplicate.

Type parameter	Constraint	Default type
Item	—	—
Key	—	—

Parameter	Type	Passing	Description
items	Iterable<Item>	Required	—
key	(item: Item) => Key	Required	—
select	(item: Item, previous: Item | undefined) => Item	Required	—

Returns: Item[].

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

• defineQueryAggregation
• mergeByKey
• QueryAggregationOptions