@adminforth/dashboard 1.0.0 → 1.2.0

package/schema/widget.ts

@@ -13,6 +13,62 @@ const DashboardWidgetSizeSchema = z.enum([
   'full',
 ])
 
+export const AggregationOperationZodSchema = z.enum([
+  'sum',
+  'count',
+  'avg',
+  'min',
+  'max',
+  'median',
+])
+
+export const AggregationRuleZodSchema = z.object({
+  operation: AggregationOperationZodSchema,
+  field: z.string().optional(),
+}).superRefine((rule, ctx) => {
+  if (rule.operation !== 'count' && !rule.field) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['field'],
+      message: `field is required for ${rule.operation}`,
+    })
+  }
+})
+
+export const GroupByRuleZodSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('field'),
+    field: z.string(),
+  }),
+  z.object({
+    type: z.literal('date_trunc'),
+    field: z.string(),
+    truncation: z.enum(['day', 'week', 'month', 'year']),
+    timezone: z.string().optional(),
+  }),
+])
+
+export const AggregateDataSourceZodSchema = z.object({
+  type: z.literal('aggregate'),
+  resourceId: z.string(),
+  aggregations: z.record(z.string(), AggregationRuleZodSchema),
+  groupBy: GroupByRuleZodSchema.optional(),
+  filters: z.unknown().optional(),
+}).strict()
+
+export const ResourceDataSourceZodSchema = z.object({
+  type: z.literal('resource'),
+  resourceId: z.string(),
+  columns: z.array(z.string()).optional(),
+  filters: z.unknown().optional(),
+  sort: z.unknown().optional(),
+}).strict()
+
+export const WidgetDataSourceZodSchema = z.discriminatedUnion('type', [
+  ResourceDataSourceZodSchema,
+  AggregateDataSourceZodSchema,
+])
+
 const WidgetBaseSchema = z.object({
   id: z.string().optional(),
   group_id: z.string().optional(),
@@ -23,6 +79,7 @@ const WidgetBaseSchema = z.object({
   minWidth: z.number().nonnegative('Min width must be a non-negative number').optional(),
   maxWidth: z.number().nonnegative('Max width must be a non-negative number').nullable().optional(),
   order: z.number().optional(),
+  dataSource: WidgetDataSourceZodSchema.optional(),
 })
 
 const ChartBaseSchema = z.object({
@@ -97,16 +154,6 @@ export const ChartConfigSchema = z.discriminatedUnion('type', [
   FunnelChartSchema,
 ])
 
-export const DashboardWidgetQuerySchema = z.object({
-  resource: z.string().min(1, 'Query resource must be a non-empty string'),
-  select: z.array(z.string()).optional(),
-  order: z.object({
-    field: z.string().min(1, 'Order field is required'),
-    direction: z.enum(['asc', 'desc']),
-  }).optional(),
-  limit: z.number().optional(),
-})
-
 export const EmptyWidgetConfigSchema = WidgetBaseSchema.extend({
   target: z.literal('empty'),
 })
@@ -114,31 +161,114 @@ export const EmptyWidgetConfigSchema = WidgetBaseSchema.extend({
 const TableWidgetConfigSchema = WidgetBaseSchema.extend({
   target: z.literal('table'),
   table: z.unknown().optional(),
-  query: DashboardWidgetQuerySchema.optional(),
+}).superRefine((widget, ctx) => {
+  if (!widget.dataSource) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['dataSource'],
+      message: 'Table widget must have dataSource config',
+    })
+  }
+
+  if (widget.dataSource?.type === 'aggregate') {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['dataSource'],
+      message: 'Table widget dataSource must use resource type',
+    })
+  }
 })
 
 const ChartWidgetTargetConfigSchema = WidgetBaseSchema.extend({
   target: z.literal('chart'),
   chart: ChartConfigSchema,
-  query: DashboardWidgetQuerySchema,
+}).superRefine((widget, ctx) => {
+  if (!widget.dataSource) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['dataSource'],
+      message: 'Chart widget must have dataSource config',
+    })
+  }
+
+  if (widget.dataSource?.type === 'resource') {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['dataSource'],
+      message: 'Chart widget dataSource must use aggregate type',
+    })
+  }
+
+  if (widget.dataSource?.type === 'aggregate' && !widget.dataSource.groupBy) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['dataSource', 'groupBy'],
+      message: 'Chart widget aggregate dataSource must define groupBy',
+    })
+  }
 })
 
 const KpiCardWidgetConfigSchema = WidgetBaseSchema.extend({
   target: z.literal('kpi_card'),
   kpi_card: z.unknown().optional(),
-  query: DashboardWidgetQuerySchema.optional(),
+}).superRefine((widget, ctx) => {
+  if (!widget.dataSource) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['dataSource'],
+      message: 'KPI card widget must have dataSource config',
+    })
+  }
+
+  if (widget.dataSource?.type === 'aggregate' && widget.dataSource.groupBy) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['dataSource', 'groupBy'],
+      message: 'KPI card aggregate dataSource must not define groupBy',
+    })
+  }
 })
 
 const GaugeCardWidgetConfigSchema = WidgetBaseSchema.extend({
   target: z.literal('gauge_card'),
   gauge_card: z.unknown().optional(),
-  query: DashboardWidgetQuerySchema.optional(),
+}).superRefine((widget, ctx) => {
+  if (!widget.dataSource) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['dataSource'],
+      message: 'Gauge card widget must have dataSource config',
+    })
+  }
+
+  if (widget.dataSource?.type === 'aggregate' && widget.dataSource.groupBy) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['dataSource', 'groupBy'],
+      message: 'Gauge card aggregate dataSource must not define groupBy',
+    })
+  }
 })
 
 const PivotTableWidgetConfigSchema = WidgetBaseSchema.extend({
   target: z.literal('pivot_table'),
   pivot_table: z.unknown().optional(),
-  query: DashboardWidgetQuerySchema.optional(),
+}).superRefine((widget, ctx) => {
+  if (!widget.dataSource) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['dataSource'],
+      message: 'Pivot table widget must have dataSource config',
+    })
+  }
+
+  if (widget.dataSource?.type === 'aggregate' && !widget.dataSource.groupBy) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['dataSource', 'groupBy'],
+      message: 'Pivot table aggregate dataSource must define groupBy',
+    })
+  }
 })
 
 export const WidgetConfigSchema = z.discriminatedUnion('target', [

package/services/widgetConfigValidator.ts

@@ -1,7 +1,7 @@
 import type { IAdminForth } from 'adminforth';
 import type { DashboardWidgetConfig } from '../custom/model/dashboard.types.js';
+import { normalizeChartWidgetConfig } from '../custom/widgets/chart/chart.types.js';
 import type { DashboardWidgetConfigValidationError } from '../schema/widget.js';
-import type { DashboardWidgetQueryConfig } from './widgetDataService.js';
 
 export type WidgetConfigValidatorService = {
   validateDashboardWidgetApiConfig: (
@@ -19,15 +19,9 @@ export function validateDashboardWidgetApiConfig(
 
   const errors: DashboardWidgetConfigValidationError[] = [];
 
-  if (!widget.query) {
-    errors.push({
-      field: 'query',
-      message: 'Chart widget must have query config',
-    });
-    return errors;
-  }
+  const chart = normalizeChartWidgetConfig(widget.chart);
 
-  if (!widget.chart) {
+  if (!chart) {
     errors.push({
       field: 'chart',
       message: 'Chart widget must have chart config',
@@ -35,52 +29,33 @@ export function validateDashboardWidgetApiConfig(
     return errors;
   }
 
-  const query = widget.query as DashboardWidgetQueryConfig;
-  const chart = widget.chart;
-
-  const resource = adminforth.config.resources.find((item) => item.resourceId === query.resource);
-
-  if (!resource) {
-    errors.push({
-      field: 'query.resource',
-      message: `Resource "${query.resource}" is not registered`,
-    });
-    return errors;
-  }
+  const aggregateDataSource = getAggregateDataSource(widget.dataSource);
 
-  if (!query.select) {
-    return errors;
-  }
+  if (aggregateDataSource) {
+    const resource = adminforth.config.resources.find((item) => item.resourceId === aggregateDataSource.resourceId);
 
-  const resourceFields = resource.columns.map((column) => column.name);
-
-  for (const field of query.select) {
-    if (!resourceFields.includes(field)) {
+    if (!resource) {
       errors.push({
-        field: 'query.select',
-        message: `Field "${field}" is not in resource "${query.resource}"`,
+        field: 'data_source.resource_id',
+        message: `Resource "${aggregateDataSource.resourceId}" is not registered`,
       });
     }
-  }
-
-  const chartFields = [
-    chart.x_field,
-    chart.y_field,
-    chart.label_field,
-    chart.value_field,
-    chart.bucket_field,
-    ...(chart.series?.map((series: { field: string }) => series.field) ?? []),
-  ].filter((field): field is string => typeof field === 'string');
 
-  for (const field of chartFields) {
-    if (!query.select.includes(field)) {
+    if (!aggregateDataSource.groupBy) {
       errors.push({
-        field: 'query.select',
-        message: `Query select must include chart field "${field}"`,
+        field: 'data_source.group_by',
+        message: 'Chart aggregate dataSource must define groupBy',
       });
     }
+
+    return errors;
   }
 
+  errors.push({
+    field: 'data_source',
+    message: 'Chart widget must have aggregate dataSource config',
+  });
+
   return errors;
 }
 
@@ -90,4 +65,21 @@ export function createWidgetConfigValidatorService(
   return {
     validateDashboardWidgetApiConfig: (widget) => validateDashboardWidgetApiConfig(adminforth, widget),
   };
+}
+
+function getAggregateDataSource(dataSource: unknown) {
+  if (
+    typeof dataSource !== 'object'
+    || dataSource === null
+    || (dataSource as { type?: string }).type !== 'aggregate'
+    || typeof (dataSource as { resourceId?: unknown }).resourceId !== 'string'
+  ) {
+    return null;
+  }
+
+  return dataSource as {
+    type: 'aggregate';
+    resourceId: string;
+    groupBy?: unknown;
+  };
 }

package/services/widgetDataService.ts

@@ -1,57 +1,204 @@
-import { Sorts } from 'adminforth';
-import type { IAdminForth } from 'adminforth';
-import type { DashboardWidgetConfig } from '../custom/model/dashboard.types.js';
-
-export type DashboardWidgetQueryConfig = {
-  resource: string;
-  select?: string[];
-  order?: {
-    field: string;
-    direction: 'asc' | 'desc';
+import { Aggregates, GroupBy, Sorts } from 'adminforth';
+import type {
+  IAdminForth,
+  IAdminForthAndOrFilter,
+  IAdminForthSingleFilter,
+  IAdminForthSort,
+} from 'adminforth';
+import type {
+  AggregationRule,
+  DashboardWidgetConfig,
+  DashboardWidgetData,
+  GroupByRule,
+  WidgetDataSource,
+} from '../custom/model/dashboard.types.js';
+
+export type DashboardWidgetDataOptions = {
+  pagination?: {
+    page: number;
+    pageSize: number;
   };
-  limit?: number;
 };
 
-export type DashboardWidgetData = {
-  columns: string[];
-  rows: Record<string, unknown>[];
-};
+type DashboardWidgetFilters =
+  | IAdminForthSingleFilter
+  | IAdminForthAndOrFilter
+  | Array<IAdminForthSingleFilter | IAdminForthAndOrFilter>;
 
 export type WidgetDataService = {
-  getWidgetData: (widget: DashboardWidgetConfig) => Promise<DashboardWidgetData | null>;
+  getWidgetData: (widget: DashboardWidgetConfig, options?: DashboardWidgetDataOptions) => Promise<DashboardWidgetData | null>;
 };
 
 export async function getWidgetData(
   adminforth: IAdminForth,
   widget: DashboardWidgetConfig,
+  options: DashboardWidgetDataOptions = {},
 ): Promise<DashboardWidgetData | null> {
-  if (!widget.query) {
+  const dataSource = getWidgetDataSource(widget.dataSource);
+
+  if (!dataSource) {
     return null;
   }
 
-  const query = widget.query as DashboardWidgetQueryConfig;
+  if (dataSource.type === 'aggregate') {
+    return getAggregateWidgetData(adminforth, dataSource);
+  }
 
-  const rows = await adminforth.resource(query.resource).list(
-    [],
-    query.limit,
-    0,
-    query.order
-      ? [query.order.direction === 'desc' ? Sorts.DESC(query.order.field) : Sorts.ASC(query.order.field)]
-      : undefined,
+  return getResourceWidgetData(adminforth, dataSource, options);
+}
+
+async function getResourceWidgetData(
+  adminforth: IAdminForth,
+  dataSource: Extract<WidgetDataSource, { type: 'resource' }>,
+  options: DashboardWidgetDataOptions,
+): Promise<DashboardWidgetData> {
+  const resource = adminforth.resource(dataSource.resourceId);
+  const filters = normalizeFilters(dataSource.filters);
+  const sort = normalizeSort(dataSource.sort);
+  const pagination = options.pagination;
+  const offset = pagination ? (pagination.page - 1) * pagination.pageSize : 0;
+  const limit = pagination ? pagination.pageSize : undefined;
+
+  const rows = await resource.list(
+    filters,
+    limit ?? undefined,
+    offset,
+    sort,
   );
 
-  const columns = query.select ?? Object.keys(rows[0] ?? {});
+  const columns = dataSource.columns ?? Object.keys(rows[0] ?? {});
+  const total = pagination ? await resource.count(filters) : 0;
 
   return {
     columns,
     rows: rows.map((row) => (
       Object.fromEntries(columns.map((column) => [column, row[column]]))
     )),
+    ...(pagination ? {
+      pagination: {
+        page: pagination.page,
+        pageSize: pagination.pageSize,
+        total,
+        totalPages: Math.max(Math.ceil(total / pagination.pageSize), 1),
+      },
+    } : {}),
+  };
+}
+
+async function getAggregateWidgetData(
+  adminforth: IAdminForth,
+  dataSource: Extract<WidgetDataSource, { type: 'aggregate' }>,
+): Promise<DashboardWidgetData> {
+  const resource = adminforth.resource(dataSource.resourceId);
+  const rows = await resource.aggregate(
+    normalizeFilters(dataSource.filters),
+    Object.fromEntries(
+      Object.entries(dataSource.aggregations).map(([alias, rule]) => [
+        alias,
+        createAggregationRule(rule),
+      ]),
+    ),
+    dataSource.groupBy ? createGroupByRule(dataSource.groupBy) : undefined,
+  );
+  const columns = Object.keys(rows[0] ?? {});
+
+  if (!dataSource.groupBy) {
+    const values = rows[0] ?? {};
+
+    return {
+      kind: 'aggregate',
+      columns: Object.keys(values),
+      rows: Object.keys(values).length ? [values] : [],
+      values,
+    };
+  }
+
+  return {
+    kind: 'aggregate',
+    columns,
+    rows,
   };
 }
 
+function getWidgetDataSource(dataSource: unknown): WidgetDataSource | undefined {
+  if (isWidgetDataSource(dataSource)) {
+    return dataSource;
+  }
+
+  return undefined;
+}
+
+function isWidgetDataSource(value: unknown): value is WidgetDataSource {
+  return isRecord(value)
+    && (value.type === 'resource' || value.type === 'aggregate')
+    && typeof value.resourceId === 'string';
+}
+
+function normalizeFilters(filters: unknown): DashboardWidgetFilters {
+  if (Array.isArray(filters)) {
+    return filters as DashboardWidgetFilters;
+  }
+
+  if (isRecord(filters)) {
+    return filters as DashboardWidgetFilters;
+  }
+
+  return [];
+}
+
+function normalizeSort(sort: unknown): IAdminForthSort | IAdminForthSort[] | undefined {
+  if (Array.isArray(sort)) {
+    return sort as IAdminForthSort[];
+  }
+
+  if (!isRecord(sort) || typeof sort.field !== 'string') {
+    return undefined;
+  }
+
+  if (sort.direction === 'asc') {
+    return [Sorts.ASC(sort.field)];
+  }
+
+  if (sort.direction === 'desc') {
+    return [Sorts.DESC(sort.field)];
+  }
+
+  return sort as IAdminForthSort;
+}
+
+function createAggregationRule(rule: AggregationRule) {
+  switch (rule.operation) {
+    case 'sum':
+      return Aggregates.sum(rule.field!);
+    case 'count':
+      return Aggregates.count();
+    case 'avg':
+      return Aggregates.avg(rule.field!);
+    case 'min':
+      return Aggregates.min(rule.field!);
+    case 'max':
+      return Aggregates.max(rule.field!);
+    case 'median':
+      return Aggregates.median(rule.field!);
+    default:
+      throw new Error(`Unsupported aggregation operation: ${(rule as AggregationRule).operation}`);
+  }
+}
+
+function createGroupByRule(rule: GroupByRule) {
+  if (rule.type === 'field') {
+    return GroupBy.Field(rule.field);
+  }
+
+  return GroupBy.DateTrunc(rule.field, rule.truncation, rule.timezone);
+}
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return typeof value === 'object' && value !== null;
+}
+
 export function createWidgetDataService(adminforth: IAdminForth): WidgetDataService {
   return {
-    getWidgetData: (widget) => getWidgetData(adminforth, widget),
+    getWidgetData: (widget, options) => getWidgetData(adminforth, widget, options),
   };
-}
+}