defineQueryAggregation

KIT · function · 运行时值

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.

导入

TypeScript

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

JavaScript

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

其他公开入口：@jangts/agent-core/types、@jangts/agent-core/kits/aggregation、@jangts/agent-core/kits。

定义

泛型参数

类型参数	约束	默认类型
Input	—	—
Item	—	—
Context	—	—

调用

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.

类型参数	约束	默认类型
Input	—	—
Item	—	—
Context	—	—

参数	类型	传递	说明
options	QueryAggregationOptions<Input, Item, Context>	必需	—

options 的字段

字段	类型	必需	说明
execute	(input: Input, context: Context) => readonly Item[]	必需	只读。Reads one input. Called once per input, in caller order, and must return synchronously.
key	((item: Item, input: Input, context: Context) => string) | undefined	可省略	只读。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	可省略	只读。Combines a duplicate with the value merged so far; receives undefined for the first item.

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

返回值结构

字段	类型	必需	说明
collect	(inputs: readonly Input[], context: Context, execution?: Partial<import("../structs/common.js").ExecutionContext>) => { total: number; items: Item[]; }	必需	Run every input in order.

使用示例

• Aggregation：查询汇总与稳定合并：顺序读取 App 数据，将重复项如何合并留在同一份配置中。

顺序汇总两次读取

入门 · 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));

同一 collect 增加主键与保留策略

配置 · 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));

相关策略源码

• 稳定键合并与读取顺序

相关定义

• QueryAggregationOptions