@hyperse-hub/hps-plugin-data-aggregation
Data aggregation plugin for storefront composition, cached summary payloads, and unified frontend data orchestration.
Example: wire it into Vendure and query unionMain
The plugin exposes a Shop API query unionMain(keys?: string[]): UnionMain!.
keys is optional. When provided, only the matching AggregationStrategy.key items are collected.
- Response always includes
items: { key, payload }[] where payload is a JSON string.
- You can also auto-extend
UnionMain with extra runtime fields via unionMainFields.
Minimal "end-to-end" example:
import type { VendureConfig } from '@vendure/core';
import {
HpsPluginDataAggregation,
type AggregationStrategy,
type UnionMainFieldStrategy,
} from '@hyperse-hub/hps-plugin-data-aggregation';
class ExampleAggregationStrategy implements AggregationStrategy {
readonly key = 'example';
async execute(ctx) {
return {
channelId: String(ctx.channelId),
languageCode: String(ctx.languageCode),
};
}
}
class ExampleUnionMainFieldStrategy implements UnionMainFieldStrategy {
readonly key = 'example-field';
readonly fieldName = 'sampleProducts';
readonly graphQLType = '[UnionProductSummary!]!';
readonly description = 'Example field resolved by an in-memory strategy';
readonly extraTypeDefs = [
`
type UnionProductSummary {
id: ID!
slug: String!
name: String!
}
`,
] as const;
async execute() {
return [
{ id: '1', slug: 'demo-1', name: 'Demo Product 1' },
{ id: '2', slug: 'demo-2', name: 'Demo Product 2' },
];
}
}
export const config: VendureConfig = {
plugins: [
HpsPluginDataAggregation.init({
defaultCacheTtl: 5 * 60 * 1000,
strategies: [new ExampleAggregationStrategy()],
unionMainFields: [new ExampleUnionMainFieldStrategy()],
}),
],
};
Then query it from Shop API:
query UnionMainExample {
unionMain(keys: ["example"]) {
items {
key
payload
}
sampleProducts {
id
slug
name
}
}
}
If you need to clear cache from Admin API, this plugin also adds a mutation:
mutation {
cleanUnionCache
}
cleanUnionCache requires SuperAdmin permission.
Strategy-first container
This plugin is now a standalone aggregation container and does not depend on
business plugins. Integrators can register custom strategies:
import type { AggregationStrategy } from '@hyperse-hub/hps-plugin-data-aggregation';
class ExampleStrategy implements AggregationStrategy {
readonly key = 'example';
async execute(ctx) {
return { languageCode: ctx.languageCode };
}
}
HpsPluginDataAggregation.init({
defaultCacheTtl: 5 * 60 * 1000,
strategies: [new ExampleStrategy()],
});
Auto-extend UnionMain fields (example)
If your frontend expects a unionMain object with additional fields, you can
register runtime unionMainFields strategies. Each strategy:
- Appends one GraphQL field to
UnionMain
- Resolves the field value by calling Vendure services
Example: add a sampleProducts field backed by your own strategy implementation:
import type { UnionMainFieldStrategy } from '@hyperse-hub/hps-plugin-data-aggregation';
import { HpsPluginDataAggregation } from '@hyperse-hub/hps-plugin-data-aggregation';
class ExampleUnionMainFieldStrategy implements UnionMainFieldStrategy {
readonly key = 'example-field';
readonly fieldName = 'sampleProducts';
readonly graphQLType = '[UnionProductSummary!]!';
readonly description = 'Example field resolved by an in-memory strategy';
readonly extraTypeDefs = [
`
type UnionProductSummary {
id: ID!
slug: String!
name: String!
}
`,
] as const;
async execute() {
return [{ id: '1', slug: 'demo', name: 'Demo Product' }];
}
}
HpsPluginDataAggregation.init({
unionMainFields: [new ExampleUnionMainFieldStrategy()],
});
Then you can query:
query {
unionMain {
sampleProducts {
id
slug
name
}
}
}