QueryAggregationOptions

KIT · interface · Type contract

Query aggregation contract: several ordered reads collapsed into one item list.

Place in the package: an optional App-side helper for merging results of the same query shape run against several inputs. The Kit owns ordering and optional stable-key merging; every real read, the merge policy and the meaning of an item stay with the App.

Exports: QueryAggregationOptions.

Import

TypeScript

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

JavaScript

/** @typedef {import('@jangts/agent-core/kits/aggregation').QueryAggregationOptions} QueryAggregationOptions */

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

Definition

interface QueryAggregationOptions<Input, Item, Context>

Type parameters

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

Field structure

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.

Member index

Member	Purpose
execute	Reads one input. Called once per input, in caller order, and must return synchronously.

Member details

execute

Reads one input. Called once per input, in caller order, and must return synchronously.

QueryAggregationOptions.execute(input: Input, context: Context): readonly Item[]

Parameter	Type	Passing	Description
input	Input	Required	—
context	Context	Required	—

Returns: readonly 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