@adminforth/dashboard 1.0.0 → 1.2.0

package/dist/schema/widget.js

@@ -6,6 +6,56 @@ const DashboardWidgetSizeSchema = z.enum([
     'wide',
     '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(),
@@ -16,6 +66,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({
     title: z.string().optional(),
@@ -79,42 +130,115 @@ export const ChartConfigSchema = z.discriminatedUnion('type', [
     HistogramChartSchema,
     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'),
 });
 const TableWidgetConfigSchema = WidgetBaseSchema.extend({
     target: z.literal('table'),
     table: z.unknown().optional(),
-    query: DashboardWidgetQuerySchema.optional(),
+}).superRefine((widget, ctx) => {
+    var _a;
+    if (!widget.dataSource) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['dataSource'],
+            message: 'Table widget must have dataSource config',
+        });
+    }
+    if (((_a = widget.dataSource) === null || _a === void 0 ? void 0 : _a.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) => {
+    var _a, _b;
+    if (!widget.dataSource) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['dataSource'],
+            message: 'Chart widget must have dataSource config',
+        });
+    }
+    if (((_a = widget.dataSource) === null || _a === void 0 ? void 0 : _a.type) === 'resource') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['dataSource'],
+            message: 'Chart widget dataSource must use aggregate type',
+        });
+    }
+    if (((_b = widget.dataSource) === null || _b === void 0 ? void 0 : _b.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) => {
+    var _a;
+    if (!widget.dataSource) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['dataSource'],
+            message: 'KPI card widget must have dataSource config',
+        });
+    }
+    if (((_a = widget.dataSource) === null || _a === void 0 ? void 0 : _a.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) => {
+    var _a;
+    if (!widget.dataSource) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['dataSource'],
+            message: 'Gauge card widget must have dataSource config',
+        });
+    }
+    if (((_a = widget.dataSource) === null || _a === void 0 ? void 0 : _a.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) => {
+    var _a;
+    if (!widget.dataSource) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['dataSource'],
+            message: 'Pivot table widget must have dataSource config',
+        });
+    }
+    if (((_a = widget.dataSource) === null || _a === void 0 ? void 0 : _a.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', [
     TableWidgetConfigSchema,

package/dist/services/widgetConfigValidator.js

@@ -1,61 +1,38 @@
+import { normalizeChartWidgetConfig } from '../custom/widgets/chart/chart.types.js';
 export function validateDashboardWidgetApiConfig(adminforth, widget) {
-    var _a, _b;
     if (widget.target !== 'chart') {
         return [];
     }
     const errors = [];
-    if (!widget.query) {
-        errors.push({
-            field: 'query',
-            message: 'Chart widget must have query config',
-        });
-        return errors;
-    }
-    if (!widget.chart) {
+    const chart = normalizeChartWidgetConfig(widget.chart);
+    if (!chart) {
         errors.push({
             field: 'chart',
             message: 'Chart widget must have chart config',
         });
         return errors;
     }
-    const query = widget.query;
-    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;
-    }
-    if (!query.select) {
-        return errors;
-    }
-    const resourceFields = resource.columns.map((column) => column.name);
-    for (const field of query.select) {
-        if (!resourceFields.includes(field)) {
+    const aggregateDataSource = getAggregateDataSource(widget.dataSource);
+    if (aggregateDataSource) {
+        const resource = adminforth.config.resources.find((item) => item.resourceId === aggregateDataSource.resourceId);
+        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,
-        ...((_b = (_a = chart.series) === null || _a === void 0 ? void 0 : _a.map((series) => series.field)) !== null && _b !== void 0 ? _b : []),
-    ].filter((field) => 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;
 }
 export function createWidgetConfigValidatorService(adminforth) {
@@ -63,3 +40,12 @@ export function createWidgetConfigValidatorService(adminforth) {
         validateDashboardWidgetApiConfig: (widget) => validateDashboardWidgetApiConfig(adminforth, widget),
     };
 }
+function getAggregateDataSource(dataSource) {
+    if (typeof dataSource !== 'object'
+        || dataSource === null
+        || dataSource.type !== 'aggregate'
+        || typeof dataSource.resourceId !== 'string') {
+        return null;
+    }
+    return dataSource;
+}

package/dist/services/widgetDataService.d.ts

@@ -1,20 +1,13 @@
 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 type { DashboardWidgetConfig, DashboardWidgetData } 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>[];
 };
 export type WidgetDataService = {
-    getWidgetData: (widget: DashboardWidgetConfig) => Promise<DashboardWidgetData | null>;
+    getWidgetData: (widget: DashboardWidgetConfig, options?: DashboardWidgetDataOptions) => Promise<DashboardWidgetData | null>;
 };
-export declare function getWidgetData(adminforth: IAdminForth, widget: DashboardWidgetConfig): Promise<DashboardWidgetData | null>;
+export declare function getWidgetData(adminforth: IAdminForth, widget: DashboardWidgetConfig, options?: DashboardWidgetDataOptions): Promise<DashboardWidgetData | null>;
 export declare function createWidgetDataService(adminforth: IAdminForth): WidgetDataService;

package/dist/services/widgetDataService.js

@@ -7,26 +7,130 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { Sorts } from 'adminforth';
-export function getWidgetData(adminforth, widget) {
+import { Aggregates, GroupBy, Sorts } from 'adminforth';
+export function getWidgetData(adminforth_1, widget_1) {
+    return __awaiter(this, arguments, void 0, function* (adminforth, widget, options = {}) {
+        const dataSource = getWidgetDataSource(widget.dataSource);
+        if (!dataSource) {
+            return null;
+        }
+        if (dataSource.type === 'aggregate') {
+            return getAggregateWidgetData(adminforth, dataSource);
+        }
+        return getResourceWidgetData(adminforth, dataSource, options);
+    });
+}
+function getResourceWidgetData(adminforth, dataSource, options) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b;
-        if (!widget.query) {
-            return null;
+        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 = yield resource.list(filters, limit !== null && limit !== void 0 ? limit : undefined, offset, sort);
+        const columns = (_a = dataSource.columns) !== null && _a !== void 0 ? _a : Object.keys((_b = rows[0]) !== null && _b !== void 0 ? _b : {});
+        const total = pagination ? yield resource.count(filters) : 0;
+        return Object.assign({ 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),
+            },
+        } : {}));
+    });
+}
+function getAggregateWidgetData(adminforth, dataSource) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const resource = adminforth.resource(dataSource.resourceId);
+        const rows = yield 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((_a = rows[0]) !== null && _a !== void 0 ? _a : {});
+        if (!dataSource.groupBy) {
+            const values = (_b = rows[0]) !== null && _b !== void 0 ? _b : {};
+            return {
+                kind: 'aggregate',
+                columns: Object.keys(values),
+                rows: Object.keys(values).length ? [values] : [],
+                values,
+            };
         }
-        const query = widget.query;
-        const rows = yield 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);
-        const columns = (_a = query.select) !== null && _a !== void 0 ? _a : Object.keys((_b = rows[0]) !== null && _b !== void 0 ? _b : {});
         return {
+            kind: 'aggregate',
             columns,
-            rows: rows.map((row) => (Object.fromEntries(columns.map((column) => [column, row[column]])))),
+            rows,
         };
     });
 }
+function getWidgetDataSource(dataSource) {
+    if (isWidgetDataSource(dataSource)) {
+        return dataSource;
+    }
+    return undefined;
+}
+function isWidgetDataSource(value) {
+    return isRecord(value)
+        && (value.type === 'resource' || value.type === 'aggregate')
+        && typeof value.resourceId === 'string';
+}
+function normalizeFilters(filters) {
+    if (Array.isArray(filters)) {
+        return filters;
+    }
+    if (isRecord(filters)) {
+        return filters;
+    }
+    return [];
+}
+function normalizeSort(sort) {
+    if (Array.isArray(sort)) {
+        return sort;
+    }
+    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;
+}
+function createAggregationRule(rule) {
+    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.operation}`);
+    }
+}
+function createGroupByRule(rule) {
+    if (rule.type === 'field') {
+        return GroupBy.Field(rule.field);
+    }
+    return GroupBy.DateTrunc(rule.field, rule.truncation, rule.timezone);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
 export function createWidgetDataService(adminforth) {
     return {
-        getWidgetData: (widget) => getWidgetData(adminforth, widget),
+        getWidgetData: (widget, options) => getWidgetData(adminforth, widget, options),
     };
 }

package/endpoint/widgets.ts

@@ -1,5 +1,8 @@
 import type { AdminUser, IHttpServer } from 'adminforth';
 import { randomUUID } from 'crypto';
+import {
+  normalizeDashboardWidgetConfig,
+} from '../custom/model/dashboard.types.js';
 import type { DashboardConfig, DashboardWidgetConfig } from '../custom/model/dashboard.types.js';
 import {
   DashboardApiResponseSchema,
@@ -7,8 +10,10 @@ import {
   GroupIdRequestSchema,
   MoveWidgetRequestSchema,
   SetWidgetConfigRequestSchema,
+  WidgetDataRequestSchema,
   WidgetIdRequestSchema,
 } from '../schema/api.js';
+import { StoredWidgetConfigSchema } from '../schema/widget.js';
 import type { DashboardWidgetConfigValidationError } from '../schema/widget.js';
 import type { DashboardRecord, PersistedDashboardResponse } from '../services/dashboardConfigService.js';
 
@@ -24,9 +29,42 @@ type WidgetEndpointsContext = {
   validateDashboardWidgetApiConfig: (
     widget: DashboardWidgetConfig,
   ) => DashboardWidgetConfigValidationError[];
-  getWidgetData: (widget: DashboardWidgetConfig) => Promise<unknown>;
+  getWidgetData: (
+    widget: DashboardWidgetConfig,
+    options?: { pagination?: { page: number, pageSize: number } },
+  ) => Promise<unknown>;
 };
 
+function formatWidgetConfigValidationErrors(error: { issues: { path: PropertyKey[], message: string }[] }) {
+  return error.issues.map((issue) => ({
+    field: issue.path.length ? formatWidgetConfigFieldPath(issue.path.map(String).join('.')) : 'config',
+    message: issue.message,
+  }));
+}
+
+function formatWidgetConfigApiValidationErrors(errors: DashboardWidgetConfigValidationError[]) {
+  return errors.map((error) => ({
+    ...error,
+    field: formatWidgetConfigFieldPath(error.field),
+  }));
+}
+
+function formatWidgetConfigFieldPath(field: string) {
+  const fieldAliases = new Map([
+    ['minWidth', 'min_width'],
+    ['maxWidth', 'max_width'],
+    ['dataSource', 'data_source'],
+    ['resourceId', 'resource_id'],
+    ['groupBy', 'group_by'],
+    ['pageSize', 'page_size'],
+  ]);
+
+  return field
+    .split('.')
+    .map((segment) => fieldAliases.get(segment) ?? segment)
+    .join('.');
+}
+
 export function registerWidgetEndpoints(
   server: IHttpServer,
   ctx: WidgetEndpointsContext,
@@ -197,14 +235,24 @@ export function registerWidgetEndpoints(
         return { error: 'Dashboard widget not found' };
       }
 
-      const typedWidgetConfig = body.config as DashboardWidgetConfig;
+      const parsedWidgetConfig = StoredWidgetConfigSchema.safeParse(normalizeDashboardWidgetConfig(body.config));
+
+      if (!parsedWidgetConfig.success) {
+        response.setStatus(422);
+        return {
+          error: 'Invalid widget config',
+          validationErrors: formatWidgetConfigValidationErrors(parsedWidgetConfig.error),
+        };
+      }
+
+      const typedWidgetConfig = parsedWidgetConfig.data as DashboardWidgetConfig;
       const apiValidationErrors = ctx.validateDashboardWidgetApiConfig(typedWidgetConfig);
 
       if (apiValidationErrors.length) {
         response.setStatus(422);
         return {
           error: 'Invalid widget config',
-          validationErrors: apiValidationErrors,
+          validationErrors: formatWidgetConfigApiValidationErrors(apiValidationErrors),
         };
       }
 
@@ -225,8 +273,8 @@ export function registerWidgetEndpoints(
   server.endpoint({
     method: 'POST',
     path: '/dashboard/get_dashboard_widget_data',
-    description: 'Loads query result data for one dashboard widget by dashboard slug and widget id.',
-    request_schema: WidgetIdRequestSchema,
+    description: 'Loads widget data for one dashboard widget by dashboard slug and widget id.',
+    request_schema: WidgetDataRequestSchema,
     response_schema: DashboardWidgetDataResponseSchema,
     handler: async ({ body, response }) => {
       const slug = String(body?.slug || 'default');
@@ -248,7 +296,9 @@ export function registerWidgetEndpoints(
 
       return {
         widget,
-        data: await ctx.getWidgetData(widget),
+        data: await ctx.getWidgetData(widget, {
+          pagination: body?.pagination,
+        }),
       };
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/dashboard",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",

package/schema/api.ts

@@ -72,6 +72,15 @@ export const WidgetIdRequestZodSchema = z.object({
   widgetId: z.string(),
 }).strict()
 
+export const WidgetDataRequestZodSchema = z.object({
+  slug: z.string().optional(),
+  widgetId: z.string(),
+  pagination: z.object({
+    page: z.number().int().positive(),
+    pageSize: z.number().int().positive(),
+  }).optional(),
+}).strict()
+
 export const MoveWidgetRequestZodSchema = z.object({
   slug: z.string().optional(),
   widgetId: z.string(),
@@ -81,7 +90,7 @@ export const MoveWidgetRequestZodSchema = z.object({
 export const SetWidgetConfigRequestZodSchema = z.object({
   slug: z.string().optional(),
   widgetId: z.string(),
-  config: WidgetConfigSchema,
+  config: z.record(z.string(), z.unknown()),
 }).strict()
 
 export const DashboardErrorResponseSchema = toAdminForthJsonSchema(DashboardErrorResponseZodSchema)
@@ -95,5 +104,6 @@ export const GroupIdRequestSchema = toAdminForthJsonSchema(GroupIdRequestZodSche
 export const MoveGroupRequestSchema = toAdminForthJsonSchema(MoveGroupRequestZodSchema)
 export const SetGroupConfigRequestSchema = toAdminForthJsonSchema(SetGroupConfigRequestZodSchema)
 export const WidgetIdRequestSchema = toAdminForthJsonSchema(WidgetIdRequestZodSchema)
+export const WidgetDataRequestSchema = toAdminForthJsonSchema(WidgetDataRequestZodSchema)
 export const MoveWidgetRequestSchema = toAdminForthJsonSchema(MoveWidgetRequestZodSchema)
 export const SetWidgetConfigRequestSchema = toAdminForthJsonSchema(SetWidgetConfigRequestZodSchema)