@adminforth/dashboard 1.1.0 → 1.3.0

package/services/widgetDataService.ts

@@ -1,4 +1,4 @@
-import { Aggregates, GroupBy, Sorts } from 'adminforth';
+import { Filters, Sorts } from 'adminforth';
 import type {
   IAdminForth,
   IAdminForthAndOrFilter,
@@ -6,23 +6,21 @@ import type {
   IAdminForthSort,
 } from 'adminforth';
 import type {
-  AggregationRule,
   DashboardWidgetConfig,
   DashboardWidgetData,
-  GroupByRule,
-  WidgetDataSource,
+  FilterExpression,
+  FunnelQueryConfig,
+  QueryAggregateOperation,
+  QueryAggregateSelectItem,
+  QueryCalcSelectItem,
+  QueryConfig,
+  QueryFieldSelectItem,
+  QueryGroupByItem,
+  QueryOrderByItem,
+  QuerySelectItem,
+  TimeGrain,
 } from '../custom/model/dashboard.types.js';
 
-export type DashboardWidgetQueryConfig = {
-  resource: string;
-  select?: string[];
-  order?: {
-    field: string;
-    direction: 'asc' | 'desc';
-  };
-  limit?: number;
-};
-
 export type DashboardWidgetDataOptions = {
   pagination?: {
     page: number;
@@ -35,6 +33,15 @@ type DashboardWidgetFilters =
   | IAdminForthAndOrFilter
   | Array<IAdminForthSingleFilter | IAdminForthAndOrFilter>;
 
+type QueryRowGroup = {
+  rows: Record<string, unknown>[];
+  values: Record<string, unknown>;
+};
+
+const NOW_MINUS_RE = /^(\d+)([dhw])$/;
+const CALC_IDENTIFIER_RE = /\b[a-zA-Z_][a-zA-Z0-9_]*\b/g;
+const SAFE_CALC_EXPRESSION_RE = /^[\d+\-*/().\s]+$/;
+
 export type WidgetDataService = {
   getWidgetData: (widget: DashboardWidgetConfig, options?: DashboardWidgetDataOptions) => Promise<DashboardWidgetData | null>;
 };
@@ -44,188 +51,530 @@ export async function getWidgetData(
   widget: DashboardWidgetConfig,
   options: DashboardWidgetDataOptions = {},
 ): Promise<DashboardWidgetData | null> {
-  const legacyQuery = getLegacyQueryConfig(widget.query);
-  const dataSource = getWidgetDataSource(widget, legacyQuery);
-
-  if (!dataSource) {
+  if (!('query' in widget)) {
     return null;
   }
 
-  if (dataSource.type === 'aggregate') {
-    return getAggregateWidgetData(adminforth, dataSource);
+  const data = 'steps' in widget.query
+    ? await getFunnelWidgetData(adminforth, widget.query)
+    : await getQueryWidgetData(adminforth, widget.query);
+
+  if (widget.target !== 'table' || !options.pagination) {
+    return data;
   }
 
-  return getResourceWidgetData(adminforth, dataSource, legacyQuery, options);
+  const page = options.pagination.page;
+  const pageSize = options.pagination.pageSize;
+  const offset = (page - 1) * pageSize;
+
+  return {
+    ...data,
+    rows: data.rows.slice(offset, offset + pageSize),
+    pagination: {
+      page,
+      pageSize,
+      total: data.rows.length,
+      totalPages: Math.max(Math.ceil(data.rows.length / pageSize), 1),
+    },
+  };
 }
 
-async function getResourceWidgetData(
+async function getFunnelWidgetData(
   adminforth: IAdminForth,
-  dataSource: Extract<WidgetDataSource, { type: 'resource' }>,
-  legacyQuery: DashboardWidgetQueryConfig | undefined,
-  options: DashboardWidgetDataOptions,
+  query: FunnelQueryConfig,
 ): Promise<DashboardWidgetData> {
-  const resource = adminforth.resource(dataSource.resourceId);
-  const filters = normalizeFilters(dataSource.filters);
-  const sort = normalizeSort(dataSource.sort ?? legacyQuery?.order);
-  const pagination = options.pagination;
-  const offset = pagination ? (pagination.page - 1) * pagination.pageSize : 0;
-  const queryLimit = legacyQuery?.limit;
-  const limit = pagination
-    ? Math.max(Math.min(pagination.pageSize, (queryLimit ?? Infinity) - offset), 0)
-    : queryLimit;
-
-  const rows = await resource.list(
-    filters,
-    limit ?? undefined,
-    offset,
-    sort,
-  );
+  const rows = await Promise.all(query.steps.map(async (step) => {
+    const valueField = step.metric.as;
+    const sourceRows = await getResourceRows(adminforth, step.resource, step.filters);
 
-  const columns = dataSource.columns ?? legacyQuery?.select ?? Object.keys(rows[0] ?? {});
-  const total = pagination ? Math.min(await resource.count(filters), queryLimit ?? Infinity) : 0;
+    return {
+      name: step.name,
+      [valueField]: calculateAggregate(sourceRows, step.metric),
+    };
+  }));
 
   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),
-      },
-    } : {}),
+    kind: 'aggregate',
+    columns: ['name', ...Array.from(new Set(query.steps.map((step) => step.metric.as)))],
+    rows,
   };
 }
 
-async function getAggregateWidgetData(
+async function getQueryWidgetData(
   adminforth: IAdminForth,
-  dataSource: Extract<WidgetDataSource, { type: 'aggregate' }>,
+  query: QueryConfig,
 ): 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] ?? {});
+  const rows = await getResourceRows(adminforth, query.resource, query.filters, getBackendSort(query.orderBy));
+  const selectedRows = buildQueryRows(rows, query);
+  const orderedRows = sortRows(selectedRows, query.orderBy);
+  const slicedRows = typeof query.limit === 'number'
+    ? orderedRows.slice(query.offset ?? 0, (query.offset ?? 0) + query.limit)
+    : orderedRows.slice(query.offset ?? 0);
+  const columns = getColumns(slicedRows, query);
 
-  if (!dataSource.groupBy) {
-    const values = rows[0] ?? {};
+  if (isAggregateQuery(query)) {
+    const values = slicedRows.length === 1 ? slicedRows[0] : undefined;
 
     return {
       kind: 'aggregate',
-      columns: Object.keys(values),
-      rows: Object.keys(values).length ? [values] : [],
-      values,
+      columns,
+      rows: slicedRows,
+      ...(values ? { values } : {}),
     };
   }
 
   return {
-    kind: 'aggregate',
+    kind: 'table',
     columns,
-    rows,
+    rows: slicedRows,
   };
 }
 
-function getLegacyQueryConfig(query: unknown): DashboardWidgetQueryConfig | undefined {
-  if (!isRecord(query) || typeof query.resource !== 'string') {
-    return undefined;
+async function getResourceRows(
+  adminforth: IAdminForth,
+  resourceId: string,
+  filters: unknown,
+  sort?: IAdminForthSort | IAdminForthSort[],
+) {
+  return adminforth.resource(resourceId).list(
+    normalizeFilters(filters),
+    undefined,
+    0,
+    sort,
+  );
+}
+
+function buildQueryRows(rows: Record<string, unknown>[], query: QueryConfig) {
+  const select = query.select ?? getDefaultSelect(rows);
+  const groupBy = query.groupBy ?? [];
+
+  if (isAggregateQuery(query)) {
+    return buildGroupedRows(rows, select, groupBy, query.calcs);
   }
 
-  return query as DashboardWidgetQueryConfig;
+  return rows.map((row) => buildPlainRow(row, select, query.calcs));
 }
 
-function getWidgetDataSource(
-  widget: DashboardWidgetConfig,
-  legacyQuery: DashboardWidgetQueryConfig | undefined,
-): WidgetDataSource | undefined {
-  if (isWidgetDataSource(widget.dataSource)) {
-    return widget.dataSource;
+function buildGroupedRows(
+  rows: Record<string, unknown>[],
+  select: QuerySelectItem[],
+  groupBy: QueryGroupByItem[],
+  calcs: QueryCalcSelectItem[] = [],
+) {
+  const groups = new Map<string, QueryRowGroup>();
+  const effectiveGroupBy = groupBy.length
+    ? groupBy
+    : select.filter(isFieldSelectItem).map((item) => ({ field: item.field, as: item.as, grain: item.grain }));
+
+  if (!effectiveGroupBy.length) {
+    const values = calculateGroupValues(rows, select, calcs);
+    return Object.keys(values).length ? [values] : [];
+  }
+
+  for (const row of rows) {
+    const values = Object.fromEntries(effectiveGroupBy.map((item) => {
+      const field = getGroupByField(item);
+      const alias = getGroupByAlias(item);
+      const grain = getGroupByGrain(item);
+
+      return [alias, formatGroupValue(row[field], grain)];
+    }));
+    const key = JSON.stringify(values);
+    const group = groups.get(key) ?? { values, rows: [] };
+
+    group.rows.push(row);
+    groups.set(key, group);
+  }
+
+  return Array.from(groups.values()).map((group) => ({
+    ...group.values,
+    ...calculateGroupValues(group.rows, select, calcs),
+  }));
+}
+
+function calculateGroupValues(
+  rows: Record<string, unknown>[],
+  select: QuerySelectItem[],
+  calcs: QueryCalcSelectItem[],
+) {
+  const values: Record<string, unknown> = {};
+
+  for (const item of select) {
+    if (isAggregateSelectItem(item)) {
+      const filteredRows = item.filters
+        ? rows.filter((row) => matchesFilterExpression(row, item.filters as FilterExpression))
+        : rows;
+
+      values[item.as] = calculateAggregate(filteredRows, item);
+    }
+  }
+
+  for (const item of [...select.filter(isCalcSelectItem), ...calcs]) {
+    values[item.as] = evaluateCalc(item.calc, values);
+  }
+
+  return values;
+}
+
+function buildPlainRow(
+  row: Record<string, unknown>,
+  select: QuerySelectItem[],
+  calcs: QueryCalcSelectItem[] = [],
+) {
+  const values: Record<string, unknown> = {};
+
+  for (const item of select) {
+    if (isFieldSelectItem(item)) {
+      values[item.as ?? item.field] = item.grain
+        ? formatGroupValue(row[item.field], item.grain)
+        : row[item.field];
+    }
   }
 
-  if (!legacyQuery) {
+  for (const item of [...select.filter(isCalcSelectItem), ...calcs]) {
+    values[item.as] = evaluateCalc(item.calc, values);
+  }
+
+  return values;
+}
+
+function calculateAggregate(rows: Record<string, unknown>[], item: QueryAggregateSelectItem) {
+  switch (item.agg) {
+    case 'count':
+      return rows.length;
+    case 'count_distinct':
+      return new Set(rows.map((row) => row[item.field!])).size;
+    case 'sum':
+      return aggregateNumbers(rows, item.field!, (values) => values.reduce((sum, value) => sum + value, 0));
+    case 'avg':
+      return aggregateNumbers(rows, item.field!, (values) => values.length
+        ? values.reduce((sum, value) => sum + value, 0) / values.length
+        : 0);
+    case 'min':
+      return aggregateNumbers(rows, item.field!, (values) => values.length ? Math.min(...values) : 0);
+    case 'max':
+      return aggregateNumbers(rows, item.field!, (values) => values.length ? Math.max(...values) : 0);
+    case 'median':
+      return aggregateNumbers(rows, item.field!, calculateMedian);
+    default:
+      throw new Error(`Unsupported aggregation operation: ${(item as { agg: QueryAggregateOperation }).agg}`);
+  }
+}
+
+function aggregateNumbers(
+  rows: Record<string, unknown>[],
+  field: string,
+  aggregate: (values: number[]) => number,
+) {
+  return aggregate(rows.map((row) => toFiniteNumber(row[field])).filter(Number.isFinite));
+}
+
+function calculateMedian(values: number[]) {
+  if (!values.length) {
+    return 0;
+  }
+
+  const sorted = [...values].sort((left, right) => left - right);
+  const middle = Math.floor(sorted.length / 2);
+
+  return sorted.length % 2
+    ? sorted[middle]
+    : (sorted[middle - 1] + sorted[middle]) / 2;
+}
+
+function evaluateCalc(calc: string, values: Record<string, unknown>) {
+  const expression = calc.replace(CALC_IDENTIFIER_RE, (name) => String(toFiniteNumber(values[name])));
+
+  if (!SAFE_CALC_EXPRESSION_RE.test(expression)) {
+    throw new Error(`Unsupported calc expression: ${calc}`);
+  }
+
+  return Function(`"use strict"; return (${expression});`)();
+}
+
+function sortRows(rows: Record<string, unknown>[], orderBy: QueryOrderByItem[] = []) {
+  if (!orderBy.length) {
+    return rows;
+  }
+
+  return [...rows].sort((left, right) => {
+    for (const order of orderBy) {
+      const direction = order.direction === 'asc' ? 1 : -1;
+      const result = compareValues(left[order.field], right[order.field]);
+
+      if (result !== 0) {
+        return result * direction;
+      }
+    }
+
+    return 0;
+  });
+}
+
+function compareValues(left: unknown, right: unknown) {
+  if (typeof left === 'number' && typeof right === 'number') {
+    return left - right;
+  }
+
+  return String(left ?? '').localeCompare(String(right ?? ''));
+}
+
+function getBackendSort(orderBy: QueryOrderByItem[] | undefined) {
+  if (!orderBy?.length) {
     return undefined;
   }
 
-  return {
-    type: 'resource',
-    resourceId: legacyQuery.resource,
-    columns: legacyQuery.select,
-    sort: legacyQuery.order,
-  };
+  return orderBy.map((order) => order.direction === 'asc'
+    ? Sorts.ASC(order.field)
+    : Sorts.DESC(order.field));
+}
+
+function getColumns(rows: Record<string, unknown>[], query: QueryConfig) {
+  const selectColumns = [
+    ...(query.groupBy ?? []).map(getGroupByAlias),
+    ...(query.select ?? []).map(getSelectAlias),
+    ...(query.calcs ?? []).map((item) => item.as),
+  ].filter(Boolean);
+
+  return Array.from(new Set(selectColumns.length ? selectColumns : Object.keys(rows[0] ?? {})));
+}
+
+function getDefaultSelect(rows: Record<string, unknown>[]): QuerySelectItem[] {
+  return Object.keys(rows[0] ?? {}).map((field) => ({ field }));
 }
 
-function isWidgetDataSource(value: unknown): value is WidgetDataSource {
-  return isRecord(value)
-    && (value.type === 'resource' || value.type === 'aggregate')
-    && typeof value.resourceId === 'string';
+function isAggregateQuery(query: QueryConfig) {
+  return Boolean(
+    query.groupBy?.length
+    || query.select?.some((item) => isAggregateSelectItem(item)),
+  );
+}
+
+function isFieldSelectItem(item: QuerySelectItem): item is QueryFieldSelectItem {
+  return 'field' in item && !('agg' in item);
+}
+
+function isAggregateSelectItem(item: QuerySelectItem): item is QueryAggregateSelectItem {
+  return 'agg' in item;
+}
+
+function isCalcSelectItem(item: QuerySelectItem): item is QueryCalcSelectItem {
+  return 'calc' in item;
+}
+
+function getSelectAlias(item: QuerySelectItem) {
+  if (isFieldSelectItem(item)) {
+    return item.as ?? item.field;
+  }
+
+  return item.as;
+}
+
+function getGroupByField(item: QueryGroupByItem) {
+  return typeof item === 'string' ? item : item.field;
+}
+
+function getGroupByAlias(item: QueryGroupByItem) {
+  return typeof item === 'string' ? item : item.as ?? item.field;
+}
+
+function getGroupByGrain(item: QueryGroupByItem) {
+  return typeof item === 'string' ? undefined : item.grain;
+}
+
+function formatGroupValue(value: unknown, grain: TimeGrain | undefined) {
+  if (!grain) {
+    return value;
+  }
+
+  const date = new Date(String(value));
+
+  if (!Number.isFinite(date.getTime())) {
+    return value;
+  }
+
+  if (grain === 'year') {
+    return `${date.getUTCFullYear()}`;
+  }
+
+  if (grain === 'quarter') {
+    return `${date.getUTCFullYear()}-Q${Math.floor(date.getUTCMonth() / 3) + 1}`;
+  }
+
+  const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+
+  if (grain === 'month') {
+    return `${date.getUTCFullYear()}-${month}`;
+  }
+
+  const day = String(date.getUTCDate()).padStart(2, '0');
+
+  if (grain === 'week') {
+    const weekStart = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+    weekStart.setUTCDate(weekStart.getUTCDate() - weekStart.getUTCDay());
+    return weekStart.toISOString().slice(0, 10);
+  }
+
+  if (grain === 'day') {
+    return `${date.getUTCFullYear()}-${month}-${day}`;
+  }
+
+  const hour = String(date.getUTCHours()).padStart(2, '0');
+  return `${date.getUTCFullYear()}-${month}-${day}T${hour}:00:00.000Z`;
 }
 
 function normalizeFilters(filters: unknown): DashboardWidgetFilters {
   if (Array.isArray(filters)) {
-    return filters as DashboardWidgetFilters;
+    return filters.map((filter) => normalizeFilterNode(filter)) as DashboardWidgetFilters;
   }
 
   if (isRecord(filters)) {
-    return filters as DashboardWidgetFilters;
+    return normalizeFilterNode(filters);
   }
 
   return [];
 }
 
-function normalizeSort(sort: unknown): IAdminForthSort | IAdminForthSort[] | undefined {
-  if (Array.isArray(sort)) {
-    return sort as IAdminForthSort[];
+function normalizeFilterNode(filter: unknown): IAdminForthSingleFilter | IAdminForthAndOrFilter {
+  if (!isRecord(filter)) {
+    return filter as IAdminForthSingleFilter;
   }
 
-  if (!isRecord(sort) || typeof sort.field !== 'string') {
-    return undefined;
+  if (Array.isArray(filter.and)) {
+    return Filters.AND(filter.and.map((item) => normalizeFilterNode(item)));
+  }
+
+  if (Array.isArray(filter.or)) {
+    return Filters.OR(filter.or.map((item) => normalizeFilterNode(item)));
+  }
+
+  if (typeof filter.field === 'string') {
+    if (Object.prototype.hasOwnProperty.call(filter, 'eq')) {
+      return Filters.EQ(filter.field, normalizeFilterValue(filter.eq));
+    }
+
+    if (Object.prototype.hasOwnProperty.call(filter, 'neq')) {
+      return Filters.NEQ(filter.field, normalizeFilterValue(filter.neq));
+    }
+
+    if (Object.prototype.hasOwnProperty.call(filter, 'gt')) {
+      return Filters.GT(filter.field, normalizeFilterValue(filter.gt));
+    }
+
+    if (Object.prototype.hasOwnProperty.call(filter, 'gte')) {
+      return Filters.GTE(filter.field, normalizeFilterValue(filter.gte));
+    }
+
+    if (Object.prototype.hasOwnProperty.call(filter, 'lt')) {
+      return Filters.LT(filter.field, normalizeFilterValue(filter.lt));
+    }
+
+    if (Object.prototype.hasOwnProperty.call(filter, 'lte')) {
+      return Filters.LTE(filter.field, normalizeFilterValue(filter.lte));
+    }
+
+    if (Object.prototype.hasOwnProperty.call(filter, 'in')) {
+      return Filters.IN(filter.field, normalizeFilterValue(filter.in));
+    }
+
+    if (Object.prototype.hasOwnProperty.call(filter, 'not_in')) {
+      return Filters.NOT_IN(filter.field, normalizeFilterValue(filter.not_in));
+    }
+  }
+
+  return filter as IAdminForthSingleFilter | IAdminForthAndOrFilter;
+}
+
+function matchesFilterExpression(row: Record<string, unknown>, filter: FilterExpression): boolean {
+  if (Array.isArray(filter)) {
+    return filter.every((item) => matchesFilterExpression(row, item));
+  }
+
+  if ('and' in filter) {
+    return filter.and.every((item) => matchesFilterExpression(row, item));
+  }
+
+  if ('or' in filter) {
+    return filter.or.some((item) => matchesFilterExpression(row, item));
+  }
+
+  const value = row[filter.field];
+
+  if (Object.prototype.hasOwnProperty.call(filter, 'eq')) {
+    return value === normalizeFilterValue(filter.eq);
+  }
+
+  if (Object.prototype.hasOwnProperty.call(filter, 'neq')) {
+    return value !== normalizeFilterValue(filter.neq);
+  }
+
+  if (Object.prototype.hasOwnProperty.call(filter, 'gt')) {
+    return compareComparableValues(value, normalizeFilterValue(filter.gt)) > 0;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(filter, 'gte')) {
+    return compareComparableValues(value, normalizeFilterValue(filter.gte)) >= 0;
   }
 
-  if (sort.direction === 'asc') {
-    return [Sorts.ASC(sort.field)];
+  if (Object.prototype.hasOwnProperty.call(filter, 'lt')) {
+    return compareComparableValues(value, normalizeFilterValue(filter.lt)) < 0;
   }
 
-  if (sort.direction === 'desc') {
-    return [Sorts.DESC(sort.field)];
+  if (Object.prototype.hasOwnProperty.call(filter, 'lte')) {
+    return compareComparableValues(value, normalizeFilterValue(filter.lte)) <= 0;
   }
 
-  return sort as IAdminForthSort;
+  if (Object.prototype.hasOwnProperty.call(filter, 'in')) {
+    return filter.in?.includes(value) ?? false;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(filter, 'not_in')) {
+    return !(filter.not_in?.includes(value) ?? false);
+  }
+
+  return true;
 }
 
-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 compareComparableValues(left: unknown, right: unknown) {
+  const leftNumber = Number(left);
+  const rightNumber = Number(right);
+
+  if (Number.isFinite(leftNumber) && Number.isFinite(rightNumber)) {
+    return leftNumber - rightNumber;
   }
+
+  return String(left ?? '').localeCompare(String(right ?? ''));
 }
 
-function createGroupByRule(rule: GroupByRule) {
-  if (rule.type === 'field') {
-    return GroupBy.Field(rule.field);
+function normalizeFilterValue(value: unknown) {
+  if (!isRecord(value) || typeof value.now_minus !== 'string') {
+    return value;
+  }
+
+  const match = value.now_minus.match(NOW_MINUS_RE);
+
+  if (!match) {
+    return value;
   }
 
-  return GroupBy.DateTrunc(rule.field, rule.truncation, rule.timezone);
+  const amount = Number(match[1]);
+  const unit = match[2];
+  const date = new Date();
+
+  if (unit === 'h') {
+    date.setHours(date.getHours() - amount);
+  } else if (unit === 'w') {
+    date.setDate(date.getDate() - amount * 7);
+  } else {
+    date.setDate(date.getDate() - amount);
+  }
+
+  return date.toISOString();
+}
+
+function toFiniteNumber(value: unknown) {
+  const numberValue = typeof value === 'number' ? value : Number(value);
+  return Number.isFinite(numberValue) ? numberValue : 0;
 }
 
 function isRecord(value: unknown): value is Record<string, any> {