@adminforth/dashboard 1.4.2 → 1.6.0

package/schema/widgets/common.ts

@@ -0,0 +1,194 @@
+import { z } from 'zod'
+
+export const DashboardWidgetSizeSchema = z.enum([
+  'small',
+  'medium',
+  'large',
+  'wide',
+  'full',
+])
+
+export const ValueFormatSchema = z.enum([
+  'number',
+  'integer',
+  'compact_number',
+  'currency',
+  'percent',
+  'percent_delta',
+  'number_delta',
+  'currency_delta',
+]).optional()
+
+export const VariablesConfigSchema = z.record(z.string(), z.unknown())
+
+export const ChartFieldRefSchema = z.object({
+  field: z.string(),
+  label: z.string().optional(),
+  format: ValueFormatSchema,
+}).strict()
+
+const RelativeDateValueSchema = z.union([
+  z.object({
+    now: z.literal(true),
+  }).strict(),
+  z.object({
+    now_minus: z.string().regex(/^\d+(h|d|w|mo|y)$/),
+  }).strict(),
+])
+
+const FilterValueSchema: z.ZodType = z.lazy(() => z.union([
+  RelativeDateValueSchema,
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+  z.array(FilterValueSchema),
+  z.record(z.string(), FilterValueSchema),
+]))
+
+export const FilterExpressionSchema: z.ZodType = z.lazy(() => z.union([
+  z.array(FilterExpressionSchema),
+  z.object({
+    and: z.array(FilterExpressionSchema),
+  }).strict(),
+  z.object({
+    or: z.array(FilterExpressionSchema),
+  }).strict(),
+  z.object({
+    field: z.string(),
+    eq: FilterValueSchema.optional(),
+    neq: FilterValueSchema.optional(),
+    gt: FilterValueSchema.optional(),
+    gte: FilterValueSchema.optional(),
+    lt: FilterValueSchema.optional(),
+    lte: FilterValueSchema.optional(),
+    in: z.array(FilterValueSchema).optional(),
+    not_in: z.array(FilterValueSchema).optional(),
+    like: FilterValueSchema.optional(),
+    ilike: FilterValueSchema.optional(),
+  }).strict(),
+]))
+
+export const QueryAggregateOperationSchema = z.enum([
+  'sum',
+  'count',
+  'count_distinct',
+  'avg',
+  'min',
+  'max',
+  'median',
+])
+
+export const QueryFieldSelectItemSchema = z.object({
+  field: z.string(),
+  as: z.string().optional(),
+  grain: z.enum(['day', 'week', 'month', 'year']).optional(),
+}).strict()
+
+export const QueryAggregateSelectItemSchema = z.object({
+  agg: QueryAggregateOperationSchema,
+  field: z.string().optional(),
+  as: z.string(),
+  filters: FilterExpressionSchema.optional(),
+}).strict().superRefine((item, ctx) => {
+  if (!['count'].includes(item.agg) && !item.field) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['field'],
+      message: `field is required for ${item.agg}`,
+    })
+  }
+})
+
+export const QueryCalcSelectItemSchema = z.object({
+  calc: z.string(),
+  as: z.string(),
+}).strict()
+
+export const QuerySelectItemSchema = z.union([
+  QueryFieldSelectItemSchema,
+  QueryAggregateSelectItemSchema,
+  QueryCalcSelectItemSchema,
+])
+
+export const QueryGroupByItemSchema = z.union([
+  z.string(),
+  z.object({
+    field: z.string(),
+    as: z.string().optional(),
+    grain: z.enum(['day', 'week', 'month', 'year']).optional(),
+    timezone: z.string().optional(),
+  }).strict(),
+])
+
+export const QueryOrderByItemSchema = z.object({
+  field: z.string(),
+  direction: z.enum(['asc', 'desc']).optional(),
+}).strict()
+
+const BucketConfigSchema = z.object({
+  field: z.string(),
+  buckets: z.array(z.object({
+    label: z.string(),
+    min: z.number().optional(),
+    max: z.number().optional(),
+  }).strict()),
+}).strict()
+
+export const QueryCalcItemSchema = z.object({
+  calc: z.string(),
+  as: z.string(),
+}).strict()
+
+export const QueryConfigSchema = z.object({
+  resource: z.string(),
+  select: z.array(QuerySelectItemSchema).optional(),
+  sparkline: z.object({
+    field: z.string(),
+    grain: z.enum(['day', 'week', 'month', 'year']),
+    as: z.string(),
+    fill_missing: z.record(z.string(), z.unknown()).optional(),
+  }).strict().optional(),
+  filters: FilterExpressionSchema.optional(),
+  group_by: z.array(QueryGroupByItemSchema).optional(),
+  order_by: z.array(QueryOrderByItemSchema).optional(),
+  limit: z.number().int().positive().optional(),
+  offset: z.number().int().nonnegative().optional(),
+  bucket: BucketConfigSchema.optional(),
+  calcs: z.array(QueryCalcItemSchema).optional(),
+  formatting: z.record(z.string(), z.unknown()).optional(),
+}).strict()
+
+const FunnelQueryStepSchema = z.object({
+  name: z.string(),
+  resource: z.string(),
+  metric: QueryAggregateSelectItemSchema,
+  filters: FilterExpressionSchema.optional(),
+}).strict()
+
+export const FunnelQueryConfigSchema = z.object({
+  steps: z.array(FunnelQueryStepSchema).min(1),
+  calcs: z.array(QueryCalcItemSchema).optional(),
+}).strict()
+
+export const WidgetPersistedFieldsSchema = z.object({
+  id: z.string(),
+  group_id: z.string(),
+  order: z.number(),
+}).strict()
+
+export const WidgetEditableBaseSchema = z.object({
+  label: z.string().optional(),
+  variables: VariablesConfigSchema.optional(),
+  size: DashboardWidgetSizeSchema.optional(),
+  width: z.number().positive('Width must be greater than 0').optional(),
+  height: z.number().positive('Height must be greater than 0').optional(),
+  min_width: z.number().nonnegative('Min width must be a non-negative number').optional(),
+  max_width: z.number().nonnegative('Max width must be a non-negative number').nullable().optional(),
+}).strict()
+
+export const WidgetBaseSchema = WidgetPersistedFieldsSchema.merge(WidgetEditableBaseSchema)
+
+export const EmptyWidgetConfigSchema = WidgetBaseSchema.extend({
+  target: z.literal('empty'),
+})

package/schema/widgets/gauge-card.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod'
+import {
+  QueryConfigSchema,
+  ValueFormatSchema,
+  WidgetBaseSchema,
+} from './common.js'
+
+export const GaugeCardViewConfigSchema = z.object({
+  title: z.string().optional(),
+  value: z.object({
+    field: z.string(),
+    format: ValueFormatSchema,
+    prefix: z.string().optional(),
+    suffix: z.string().optional(),
+  }).strict(),
+  target: z.object({
+    value: z.number().optional(),
+    field: z.string().optional(),
+    label: z.string().optional(),
+  }).strict().optional(),
+  progress: z.object({
+    value_field: z.string(),
+    target_value: z.number().optional(),
+    target_field: z.string().optional(),
+    format: ValueFormatSchema,
+  }).strict().optional(),
+  color: z.string().optional(),
+}).strict()
+
+export const GaugeCardWidgetConfigSchema = WidgetBaseSchema.extend({
+  target: z.literal('gauge_card'),
+  card: GaugeCardViewConfigSchema,
+  query: QueryConfigSchema,
+})

package/schema/widgets/kpi-card.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod'
+import {
+  QueryConfigSchema,
+  ValueFormatSchema,
+  WidgetBaseSchema,
+} from './common.js'
+
+export const KpiCardViewConfigSchema = z.object({
+  title: z.string().optional(),
+  value: z.object({
+    field: z.string(),
+    format: ValueFormatSchema,
+    prefix: z.string().optional(),
+    suffix: z.string().optional(),
+  }).strict(),
+  subtitle: z.object({
+    text: z.string().optional(),
+    field: z.string().optional(),
+  }).strict().optional(),
+  comparison: z.object({
+    field: z.string(),
+    format: ValueFormatSchema,
+    positive_is_good: z.boolean().optional(),
+    compact: z.object({
+      show: z.boolean().optional(),
+      template: z.string().optional(),
+    }).strict().optional(),
+    tooltip: z.object({
+      label: z.string().optional(),
+      template: z.string().optional(),
+    }).strict().optional(),
+  }).strict().optional(),
+  sparkline: z.object({
+    type: z.enum(['line']).optional(),
+    field: z.string(),
+    x: z.string(),
+    show_axes: z.boolean().optional(),
+    show_labels: z.boolean().optional(),
+    fill: z.object({
+      type: z.enum(['gradient', 'solid']).optional(),
+    }).strict().optional(),
+  }).strict().optional(),
+}).strict()
+
+export const KpiCardWidgetConfigSchema = WidgetBaseSchema.extend({
+  target: z.literal('kpi_card'),
+  card: KpiCardViewConfigSchema,
+  query: QueryConfigSchema,
+})

package/schema/widgets/pivot-table.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod'
+import {
+  ChartFieldRefSchema,
+  QueryConfigSchema,
+  ValueFormatSchema,
+  WidgetBaseSchema,
+} from './common.js'
+
+export const PivotTableViewConfigSchema = z.object({
+  rows: z.array(ChartFieldRefSchema).min(1),
+  columns: z.array(ChartFieldRefSchema).optional(),
+  values: z.array(z.object({
+    field: z.string(),
+    label: z.string().optional(),
+    format: ValueFormatSchema,
+    aggregation: z.enum(['sum', 'count', 'avg', 'min', 'max']).optional(),
+  }).strict()).min(1),
+}).strict()
+
+export const PivotTableWidgetConfigSchema = WidgetBaseSchema.extend({
+  target: z.literal('pivot_table'),
+  pivot: PivotTableViewConfigSchema,
+  query: QueryConfigSchema,
+})

package/schema/widgets/table.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod'
+import {
+  ChartFieldRefSchema,
+  QueryConfigSchema,
+  WidgetBaseSchema,
+} from './common.js'
+
+export const TableViewConfigSchema = z.object({
+  columns: z.array(ChartFieldRefSchema).optional(),
+  pagination: z.boolean().optional(),
+  page_size: z.number().int().positive().optional(),
+}).strict()
+
+export const TableWidgetConfigSchema = WidgetBaseSchema.extend({
+  target: z.literal('table'),
+  table: TableViewConfigSchema.optional(),
+  query: QueryConfigSchema,
+})

package/services/dashboardConfigService.ts

@@ -26,6 +26,39 @@ export type PersistedDashboardResponse = {
   config: DashboardConfig;
 };
 
+type DashboardConfigMutator = (
+  config: DashboardConfig,
+  dashboard: DashboardRecord,
+) => DashboardConfig | null | Promise<DashboardConfig | null>;
+
+const dashboardConfigUpdateQueues = new Map<string, Promise<void>>();
+
+async function runDashboardConfigUpdateQueued<T>(
+  dashboardSlug: string,
+  callback: () => Promise<T>,
+): Promise<T> {
+  const previousUpdate = dashboardConfigUpdateQueues.get(dashboardSlug) ?? Promise.resolve();
+  let releaseCurrentUpdate!: () => void;
+  const currentUpdate = new Promise<void>((resolve) => {
+    releaseCurrentUpdate = resolve;
+  });
+  const queuedUpdate = previousUpdate.then(() => currentUpdate, () => currentUpdate);
+
+  dashboardConfigUpdateQueues.set(dashboardSlug, queuedUpdate);
+
+  await previousUpdate.catch(() => undefined);
+
+  try {
+    return await callback();
+  } finally {
+    releaseCurrentUpdate();
+
+    if (dashboardConfigUpdateQueues.get(dashboardSlug) === queuedUpdate) {
+      dashboardConfigUpdateQueues.delete(dashboardSlug);
+    }
+  }
+}
+
 function normalizeDashboardOrder(config: DashboardConfig): DashboardConfig {
   const widgetsByGroupId = new Map<string, DashboardWidgetConfig[]>();
 
@@ -91,6 +124,36 @@ export async function persistDashboardConfig(
   };
 }
 
+export async function updateDashboardConfig(
+  adminforth: IAdminForth,
+  dashboardConfigsResourceId: string,
+  slug: string,
+  mutateConfig: DashboardConfigMutator,
+): Promise<PersistedDashboardResponse | null> {
+  return runDashboardConfigUpdateQueued(slug, async () => {
+    const dashboard = await getDashboardRecord(adminforth, dashboardConfigsResourceId, slug);
+
+    if (!dashboard) {
+      return null;
+    }
+
+    const config = parseStoredDashboardConfig(dashboard.config);
+    const nextConfig = await mutateConfig(config, dashboard);
+
+    if (nextConfig === null) {
+      return {
+        id: dashboard.id,
+        slug: dashboard.slug,
+        label: dashboard.label,
+        revision: dashboard.revision,
+        config,
+      };
+    }
+
+    return persistDashboardConfig(adminforth, dashboardConfigsResourceId, dashboard, nextConfig);
+  });
+}
+
 export type DashboardConfigService = {
   getDashboardRecord: (slug: string) => Promise<DashboardRecord | null>;
   parseStoredDashboardConfig: typeof parseStoredDashboardConfig;
@@ -98,6 +161,10 @@ export type DashboardConfigService = {
     dashboard: DashboardRecord,
     config: DashboardConfig,
   ) => Promise<PersistedDashboardResponse>;
+  updateDashboardConfig: (
+    slug: string,
+    mutateConfig: DashboardConfigMutator,
+  ) => Promise<PersistedDashboardResponse | null>;
 };
 
 export function createDashboardConfigService(
@@ -113,5 +180,11 @@ export function createDashboardConfigService(
       dashboard,
       config,
     ),
+    updateDashboardConfig: (slug, mutateConfig) => updateDashboardConfig(
+      adminforth,
+      dashboardConfigsResourceId,
+      slug,
+      mutateConfig,
+    ),
   };
 }

package/services/widgetDataService.ts

@@ -70,7 +70,8 @@ type EffectiveGroupByItem = {
 const CALC_IDENTIFIER_RE = /\b[a-zA-Z_][a-zA-Z0-9_]*\b/g;
 const LOOKUP_CALL_RE = /lookup\(\s*(\$variables(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)\s*,\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*,\s*(-?\d+(?:\.\d+)?)\s*\)/g;
 const VARIABLE_PATH_PREFIX_RE = /^\$variables\.?/;
-const SAFE_CALC_EXPRESSION_RE = /^[\d+\-*/().\s]+$/;
+const SAFE_CALC_EXPRESSION_RE = /^[\d+\-*/().\s?:<>=!]+$/;
+const RELATIVE_DURATION_RE = /^(\d+)(h|d|w|mo|y)$/;
 const FILTER_OPERATORS = {
   eq: Filters.EQ,
   neq: Filters.NEQ,
@@ -165,6 +166,12 @@ async function getQueryWidgetData(
   query: QueryConfig,
   variables: DashboardVariables,
 ): Promise<DashboardWidgetData> {
+  const metricSelect = getSingleAggregateMetricSelect(query);
+
+  if (metricSelect) {
+    return getMetricWidgetData(adminforth, query, metricSelect);
+  }
+
   const selectedRows = isAggregateQuery(query)
     ? await buildAggregateQueryRows(adminforth, query, variables)
     : buildPlainQueryRows(
@@ -196,6 +203,64 @@ async function getQueryWidgetData(
   };
 }
 
+async function getMetricWidgetData(
+  adminforth: IAdminForth,
+  query: QueryConfig,
+  metric: QueryAggregateSelectItem,
+): Promise<DashboardWidgetData> {
+  const [currentValues = {}] = await getAggregateRows(
+    adminforth,
+    query.resource,
+    query.filters,
+    [metric],
+    [],
+  );
+  const values: Record<string, unknown> = {
+    [metric.as]: currentValues[metric.as] ?? 0,
+  };
+
+  const rows = query.sparkline
+    ? await getMetricSparklineRows(adminforth, query, metric, getAdminForthFilters(query.filters))
+    : [values];
+  const columns = Array.from(new Set([
+    metric.as,
+    ...(query.sparkline ? [query.sparkline.as] : []),
+  ]));
+
+  return {
+    kind: 'aggregate',
+    columns,
+    rows,
+    values,
+  };
+}
+
+async function getMetricSparklineRows(
+  adminforth: IAdminForth,
+  query: QueryConfig,
+  metric: QueryAggregateSelectItem,
+  filters: DashboardWidgetFilters,
+) {
+  const sparkline = query.sparkline!;
+  const groupBy = [{
+    field: sparkline.field,
+    as: sparkline.as,
+    grain: sparkline.grain,
+  }];
+  const rows = await getAggregateRows(
+    adminforth,
+    query.resource,
+    filters,
+    [metric],
+    groupBy,
+  );
+
+  return rows.map((row) => ({
+    ...query.sparkline?.fill_missing,
+    ...row,
+  }));
+}
+
 async function getResourceRows(
   adminforth: IAdminForth,
   resourceId: string,
@@ -237,7 +302,7 @@ async function buildAggregateQueryRows(
 async function getAggregateRows(
   adminforth: IAdminForth,
   resourceId: string,
-  baseFilters: FilterExpression | undefined,
+  baseFilters: FilterExpression | DashboardWidgetFilters | undefined,
   select: QueryAggregateSelectItem[],
   groupBy: EffectiveGroupByItem[],
 ) {
@@ -405,6 +470,21 @@ function isAggregateQuery(query: QueryConfig) {
   );
 }
 
+function getSingleAggregateMetricSelect(query: QueryConfig) {
+  if (query.group_by?.length) {
+    return undefined;
+  }
+
+  const select = query.select ?? [];
+  const aggregateItems = select.filter(isAggregateSelectItem);
+
+  if (aggregateItems.length !== 1 || aggregateItems.length !== select.length) {
+    return undefined;
+  }
+
+  return aggregateItems[0];
+}
+
 function isFieldSelectItem(item: QuerySelectItem): item is QueryFieldSelectItem {
   return 'field' in item && !('agg' in item);
 }
@@ -678,13 +758,59 @@ function toAdminForthFilter(filter: FilterExpression): IAdminForthSingleFilter |
 
   for (const [operator, createFilter] of Object.entries(FILTER_OPERATORS)) {
     if (Object.prototype.hasOwnProperty.call(filter, operator)) {
-      return createFilter(filter.field, filter[operator as keyof typeof FILTER_OPERATORS]);
+      return createFilter(filter.field, resolveFilterValue(filter[operator as keyof typeof FILTER_OPERATORS]));
     }
   }
 
   return Filters.AND([]);
 }
 
+function resolveFilterValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveFilterValue(item));
+  }
+
+  if (!isRecord(value)) {
+    return value;
+  }
+
+  if (value.now === true) {
+    return new Date().toISOString();
+  }
+
+  if (typeof value.now_minus === 'string') {
+    return subtractDuration(new Date(), value.now_minus).toISOString();
+  }
+
+  return value;
+}
+
+function subtractDuration(now: Date, duration: string) {
+  const match = duration.match(RELATIVE_DURATION_RE);
+
+  if (!match) {
+    throw new Error(`Unsupported relative date duration: ${duration}`);
+  }
+
+  const amount = Number(match[1]);
+  const unit = match[2];
+  const date = new Date(now);
+
+  if (unit === 'h') {
+    date.setUTCHours(date.getUTCHours() - amount);
+  } else if (unit === 'd') {
+    date.setUTCDate(date.getUTCDate() - amount);
+  } else if (unit === 'w') {
+    date.setUTCDate(date.getUTCDate() - amount * 7);
+  } else if (unit === 'mo') {
+    date.setUTCMonth(date.getUTCMonth() - amount);
+  } else if (unit === 'y') {
+    date.setUTCFullYear(date.getUTCFullYear() - amount);
+  }
+
+  return date;
+}
+
 function toFiniteNumber(value: unknown) {
   const numberValue = typeof value === 'number' ? value : Number(value);
   return Number.isFinite(numberValue) ? numberValue : 0;