@n8n/frontend-module-insights 0.1.0

package/src/insights.utils.test.ts

@@ -0,0 +1,339 @@
+import { CalendarDate, getLocalTimeZone, today } from '@internationalized/date';
+import type { InsightsSummary } from '@n8n/api-types';
+
+import {
+	INSIGHTS_UNIT_MAPPING,
+	INSIGHTS_DEVIATION_UNIT_MAPPING,
+	INSIGHTS_SUMMARY_ORDER,
+} from './insights.constants';
+import {
+	transformInsightsTimeSaved,
+	transformInsightsAverageRunTime,
+	transformInsightsFailureRate,
+	transformInsightsValues,
+	transformInsightsDeviation,
+	transformInsightsSummary,
+	formatDateRange,
+	getMatchingPreset,
+	timeRangeMappings,
+} from './insights.utils';
+
+describe('Insights Transformers', () => {
+	describe('transformInsightsTimeSaved', () => {
+		it('should return minutes if absolute value is less than 60', () => {
+			expect(transformInsightsTimeSaved(30)).toBe(30);
+			expect(transformInsightsTimeSaved(59)).toBe(59);
+			expect(transformInsightsTimeSaved(-30)).toBe(-30);
+			expect(transformInsightsTimeSaved(-59)).toBe(-59);
+		});
+
+		it('should return hours if absolute value is 60 or more, rounding to nearest hour', () => {
+			expect(transformInsightsTimeSaved(60)).toBe(1);
+			expect(transformInsightsTimeSaved(120)).toBe(2);
+			expect(transformInsightsTimeSaved(89)).toBe(1);
+			expect(transformInsightsTimeSaved(90)).toBe(2);
+			expect(transformInsightsTimeSaved(-60)).toBe(-1);
+			expect(transformInsightsTimeSaved(-120)).toBe(-2);
+			expect(transformInsightsTimeSaved(-89)).toBe(-1);
+			expect(transformInsightsTimeSaved(-90)).toBe(-1);
+		});
+
+		it('should return 0 for 0 minutes', () => {
+			expect(transformInsightsTimeSaved(0)).toBe(0);
+		});
+	});
+
+	describe('transformInsightsAverageRunTime', () => {
+		it('should convert milliseconds to seconds', () => {
+			expect(transformInsightsAverageRunTime(1000)).toBe(1);
+			expect(transformInsightsAverageRunTime(500)).toBe(0.5);
+			expect(transformInsightsAverageRunTime(1234)).toBe(1.234);
+			expect(transformInsightsAverageRunTime(0)).toBe(0);
+		});
+	});
+
+	describe('transformInsightsFailureRate', () => {
+		it('should convert decimal to percentage', () => {
+			expect(transformInsightsFailureRate(0.5)).toBe(50);
+			expect(transformInsightsFailureRate(1)).toBe(100);
+			expect(transformInsightsFailureRate(0.253)).toBe(25.3);
+			expect(transformInsightsFailureRate(0)).toBe(0);
+		});
+	});
+
+	describe('transformInsightsValues', () => {
+		it('should correctly transform values based on type', () => {
+			expect(transformInsightsValues.total(100)).toBe(100);
+			expect(transformInsightsValues.failed(10)).toBe(10);
+			expect(transformInsightsValues.timeSaved(120)).toBe(2);
+			expect(transformInsightsValues.timeSaved(30)).toBe(30);
+			expect(transformInsightsValues.averageRunTime(2000)).toBe(2);
+			expect(transformInsightsValues.failureRate(0.1)).toBe(10);
+		});
+	});
+
+	describe('transformInsightsDeviation', () => {
+		describe('for total and failed types', () => {
+			it('should calculate percentage deviation', () => {
+				expect(transformInsightsDeviation.total(110, 10)).toBe(10);
+				expect(transformInsightsDeviation.failed(55, 5)).toBe(10);
+			});
+
+			it('should return 0 if value and deviation are 0', () => {
+				expect(transformInsightsDeviation.total(0, 0)).toBe(0);
+				expect(transformInsightsDeviation.failed(0, 0)).toBe(0);
+			});
+
+			it('should return Infinity if value equals deviation (and thus previous value is 0)', () => {
+				expect(transformInsightsDeviation.total(10, 10)).toBe(null);
+				expect(transformInsightsDeviation.failed(5, 5)).toBe(null);
+			});
+
+			it('should return 0 if deviation is 0 and value is not 0', () => {
+				expect(transformInsightsDeviation.total(100, 0)).toBe(0);
+				expect(transformInsightsDeviation.failed(50, 0)).toBe(0);
+			});
+		});
+
+		it('for timeSaved type, should transform deviation using transformInsightsTimeSaved', () => {
+			expect(transformInsightsDeviation.timeSaved(1000, 120)).toBe(2);
+			expect(transformInsightsDeviation.timeSaved(1000, 30)).toBe(30);
+		});
+
+		it('for averageRunTime type, should transform deviation using transformInsightsAverageRunTime', () => {
+			expect(transformInsightsDeviation.averageRunTime(5000, 1000)).toBe(1);
+		});
+
+		it('for failureRate type, should transform deviation using transformInsightsFailureRate', () => {
+			expect(transformInsightsDeviation.failureRate(0.5, 0.1)).toBe(10);
+		});
+	});
+
+	describe('transformInsightsSummary', () => {
+		beforeEach(() => {
+			vi.clearAllMocks();
+
+			INSIGHTS_SUMMARY_ORDER.forEach((key) => {
+				vi.spyOn(INSIGHTS_UNIT_MAPPING, key);
+				vi.spyOn(INSIGHTS_DEVIATION_UNIT_MAPPING, key);
+			});
+		});
+
+		it('should return an empty array if data is null', () => {
+			expect(transformInsightsSummary(null)).toEqual([]);
+		});
+
+		it('should correctly transform InsightsSummary data and respect INSIGHTS_SUMMARY_ORDER', () => {
+			const summaryData: InsightsSummary = {
+				timeSaved: { value: 1200, deviation: 120, unit: 'minute' },
+				total: { value: 110, deviation: 10, unit: 'count' },
+				failureRate: { value: 0.05, deviation: 0.01, unit: 'ratio' },
+				averageRunTime: { value: 5000, deviation: 1000, unit: 'millisecond' },
+				failed: { value: 5, deviation: 1, unit: 'count' },
+			};
+
+			const expectedOutput = [
+				{
+					id: 'total',
+					value: 110,
+					deviation: 10,
+					deviationUnit: '%',
+					unit: '',
+				},
+				{
+					id: 'failed',
+					value: 5,
+					deviation: 25,
+					deviationUnit: '%',
+					unit: '',
+				},
+				{
+					id: 'failureRate',
+					value: 5,
+					deviation: 1,
+					deviationUnit: 'pp',
+					unit: '%',
+				},
+				{
+					id: 'timeSaved',
+					value: 20,
+					deviation: 2,
+					deviationUnit: 'h',
+					unit: 'h',
+				},
+				{
+					id: 'averageRunTime',
+					value: 5,
+					deviation: 1,
+					deviationUnit: 's',
+					unit: 's',
+				},
+			];
+
+			const result = transformInsightsSummary(summaryData);
+			expect(result).toEqual(expectedOutput);
+			expect(result.map((item) => item.id)).toEqual([
+				'total',
+				'failed',
+				'failureRate',
+				'timeSaved',
+				'averageRunTime',
+			]);
+
+			expect(INSIGHTS_UNIT_MAPPING.total).toHaveBeenCalledWith(110);
+			expect(INSIGHTS_DEVIATION_UNIT_MAPPING.total).toHaveBeenCalledWith(10);
+			expect(INSIGHTS_UNIT_MAPPING.failed).toHaveBeenCalledWith(5);
+			expect(INSIGHTS_DEVIATION_UNIT_MAPPING.failed).toHaveBeenCalledWith(1);
+			expect(INSIGHTS_UNIT_MAPPING.timeSaved).toHaveBeenCalledWith(1200);
+			expect(INSIGHTS_DEVIATION_UNIT_MAPPING.timeSaved).toHaveBeenCalledWith(120);
+			expect(INSIGHTS_UNIT_MAPPING.averageRunTime).toHaveBeenCalledWith(5000);
+			expect(INSIGHTS_DEVIATION_UNIT_MAPPING.averageRunTime).toHaveBeenCalledWith(1000);
+			expect(INSIGHTS_UNIT_MAPPING.failureRate).toHaveBeenCalledWith(0.05);
+			expect(INSIGHTS_DEVIATION_UNIT_MAPPING.failureRate).toHaveBeenCalledWith(0.01);
+		});
+
+		it('should handle null deviation correctly', () => {
+			const summaryData: InsightsSummary = {
+				total: { value: 100, deviation: null, unit: 'count' },
+				failed: { value: 5, deviation: 1, unit: 'count' },
+				timeSaved: { value: 30, deviation: null, unit: 'minute' },
+				averageRunTime: { value: 2000, deviation: 500, unit: 'millisecond' },
+				failureRate: { value: 0.1, deviation: null, unit: 'ratio' },
+			};
+
+			const expectedOutput = [
+				{
+					id: 'total',
+					value: 100,
+					deviation: null,
+					deviationUnit: '',
+					unit: '',
+				},
+				{
+					id: 'failed',
+					value: 5,
+					deviation: 25,
+					deviationUnit: '%',
+					unit: '',
+				},
+				{
+					id: 'failureRate',
+					value: 10,
+					deviation: null,
+					deviationUnit: '',
+					unit: '%',
+				},
+				{
+					id: 'timeSaved',
+					value: 30,
+					deviation: null,
+					deviationUnit: '',
+					unit: 'm',
+				},
+				{
+					id: 'averageRunTime',
+					value: 2,
+					deviation: 0.5,
+					deviationUnit: 's',
+					unit: 's',
+				},
+			];
+			expect(transformInsightsSummary(summaryData)).toEqual(expectedOutput);
+
+			expect(INSIGHTS_UNIT_MAPPING.total).toHaveBeenCalledWith(100);
+			expect(INSIGHTS_DEVIATION_UNIT_MAPPING.total).not.toHaveBeenCalled(); // deviation is null
+
+			expect(INSIGHTS_UNIT_MAPPING.timeSaved).toHaveBeenCalledWith(30);
+			expect(INSIGHTS_DEVIATION_UNIT_MAPPING.timeSaved).not.toHaveBeenCalled(); // deviation is null
+		});
+	});
+
+	describe('formatDateRange', () => {
+		afterEach(() => {
+			vi.clearAllMocks();
+		});
+
+		it('should return empty string if start date is not provided', () => {
+			const result = formatDateRange({ end: new CalendarDate(2025, 6, 5) });
+
+			expect(result).toBe('');
+		});
+
+		it('should return formatted start date if the end date is not provided', () => {
+			const result = formatDateRange({ start: new CalendarDate(2025, 2, 28) });
+
+			expect(result).toBe('28 Feb, 2025');
+		});
+
+		it('should return formatted start date if the end date is the same as the start date', () => {
+			const result = formatDateRange({
+				start: new CalendarDate(2025, 10, 20),
+				end: new CalendarDate(2025, 10, 20),
+			});
+
+			expect(result).toBe('20 Oct, 2025');
+		});
+
+		it('should return formatted range for same year range', () => {
+			const result = formatDateRange({
+				start: new CalendarDate(2025, 10, 20),
+				end: new CalendarDate(2025, 10, 25),
+			});
+
+			expect(result).toBe('20 Oct - 25 Oct, 2025');
+		});
+
+		it('should return formatted range for different year range', () => {
+			const result = formatDateRange({
+				start: new CalendarDate(2024, 12, 20),
+				end: new CalendarDate(2025, 1, 5),
+			});
+
+			expect(result).toBe('20 Dec, 2024 - 5 Jan, 2025');
+		});
+	});
+
+	describe('getMatchingPreset', () => {
+		it('should return null if the end date is not provided', () => {
+			const result = getMatchingPreset({ start: new CalendarDate(2025, 10, 20) });
+
+			expect(result).toBeNull();
+		});
+
+		it('should return null if the start date is not provided', () => {
+			const result = getMatchingPreset({ end: new CalendarDate(2025, 10, 20) });
+
+			expect(result).toBeNull();
+		});
+
+		it('should return null if the end date is not today', () => {
+			const result = getMatchingPreset({
+				start: new CalendarDate(2025, 10, 20),
+				end: new CalendarDate(2025, 10, 21),
+			});
+
+			expect(result).toBeNull();
+		});
+
+		it('should return null for custom range', () => {
+			const result = getMatchingPreset({
+				start: new CalendarDate(2025, 10, 20),
+				end: today(getLocalTimeZone()),
+			});
+
+			expect(result).toBeNull();
+		});
+
+		test.each(Object.entries(timeRangeMappings))(
+			'should return the %s" preset for for %d days',
+			(key, days) => {
+				const end = today(getLocalTimeZone());
+				const start = end.subtract({ days });
+
+				const result = getMatchingPreset({ start, end });
+
+				expect(result).toBe(key);
+			},
+		);
+	});
+});

package/src/insights.utils.ts

@@ -0,0 +1,172 @@
+import type { DateValue } from '@internationalized/date';
+import { getLocalTimeZone, isToday, now, toCalendarDateTime, today } from '@internationalized/date';
+import type { InsightsDateRange, InsightsSummary, InsightsSummaryType } from '@n8n/api-types';
+import type { DateRange } from '@n8n/design-system';
+import { useI18n } from '@n8n/i18n';
+import dateformat from 'dateformat';
+
+import {
+	INSIGHTS_DEVIATION_UNIT_MAPPING,
+	INSIGHTS_SUMMARY_ORDER,
+	INSIGHTS_UNIT_MAPPING,
+} from './insights.constants';
+import type { InsightsSummaryDisplay } from './insights.types';
+
+const DATE_FORMAT_DAY_MONTH_YEAR = 'd mmm, yyyy';
+const DATE_FORMAT_DAY_MONTH = 'd mmm';
+
+export const transformInsightsTimeSaved = (minutes: number): number =>
+	Math.round(minutes / (Math.abs(minutes) < 60 ? 1 : 60)); // we want to show saved time in minutes or hours
+export const transformInsightsAverageRunTime = (ms: number): number => ms / 1000; // we want to show average run time in seconds
+export const transformInsightsFailureRate = (value: number): number => value * 100; // we want to show failure rate in percentage
+
+export const transformInsightsValues: Record<InsightsSummaryType, (value: number) => number> = {
+	total: (value: number) => value,
+	failed: (value: number) => value,
+	timeSaved: transformInsightsTimeSaved,
+	averageRunTime: transformInsightsAverageRunTime,
+	failureRate: transformInsightsFailureRate,
+};
+
+const getPreviousValue = (value: number, deviation: number): number => value - deviation;
+
+const getDeviation = (value: number, deviation: number): number | null => {
+	if (value === 0 && deviation === 0) return 0;
+
+	const previousValue = getPreviousValue(value, deviation);
+	if (previousValue === 0) return null; // avoid division by zero
+
+	return (deviation / previousValue) * 100;
+};
+
+export const transformInsightsDeviation: Record<
+	InsightsSummaryType,
+	(value: number, deviation: number) => number | null
+> = {
+	total: getDeviation,
+	failed: getDeviation,
+	timeSaved: (_: number, deviation: number) => transformInsightsTimeSaved(deviation),
+	averageRunTime: (_: number, deviation: number) => transformInsightsAverageRunTime(deviation),
+	failureRate: (_: number, deviation: number) => transformInsightsFailureRate(deviation),
+};
+
+export const transformInsightsSummary = (data: InsightsSummary | null): InsightsSummaryDisplay =>
+	data
+		? INSIGHTS_SUMMARY_ORDER.map((key) => ({
+				id: key,
+				value: transformInsightsValues[key](data[key].value),
+				deviation:
+					data[key].deviation === null
+						? null
+						: transformInsightsDeviation[key](data[key].value, data[key].deviation),
+				deviationUnit:
+					data[key].deviation === null
+						? ''
+						: INSIGHTS_DEVIATION_UNIT_MAPPING[key](data[key].deviation),
+				unit: INSIGHTS_UNIT_MAPPING[key](data[key].value),
+			}))
+		: [];
+
+export const timeRangeMappings: Record<InsightsDateRange['key'], number> = {
+	day: 1,
+	week: 7,
+	'2weeks': 14,
+	month: 30,
+	quarter: 90,
+	'6months': 180,
+	year: 365,
+} as const;
+
+export const getTimeRangeLabels = () => {
+	const i18n = useI18n();
+
+	return {
+		day: i18n.baseText('insights.lastNHours', { interpolate: { count: 24 } }),
+		week: i18n.baseText('insights.lastNDays', { interpolate: { count: 7 } }),
+		'2weeks': i18n.baseText('insights.lastNDays', { interpolate: { count: 14 } }),
+		month: i18n.baseText('insights.lastNDays', { interpolate: { count: 30 } }),
+		quarter: i18n.baseText('insights.lastNDays', { interpolate: { count: 90 } }),
+		'6months': i18n.baseText('insights.months', { interpolate: { count: 6 } }),
+		year: i18n.baseText('insights.oneYear'),
+	};
+};
+
+/**
+ * @returns A human readable string representing the date range e.g '01 Jan - 05 Jan 2025'
+ */
+export const formatDateRange = (range: { start?: DateValue; end?: DateValue }): string => {
+	const { start, end } = range;
+	if (!start) return '';
+
+	const startDate = start.toDate(getLocalTimeZone());
+	const endDate = end?.toDate(getLocalTimeZone());
+
+	if (!end || start.compare(end) === 0) {
+		return dateformat(startDate, DATE_FORMAT_DAY_MONTH_YEAR);
+	}
+
+	if (start.year === end.year) {
+		return `${dateformat(startDate, DATE_FORMAT_DAY_MONTH)} - ${dateformat(endDate, DATE_FORMAT_DAY_MONTH_YEAR)}`;
+	}
+
+	return `${dateformat(startDate, DATE_FORMAT_DAY_MONTH_YEAR)} - ${dateformat(endDate, DATE_FORMAT_DAY_MONTH_YEAR)}`;
+};
+
+/**
+ * @returns The matching preset key if the range matches a preset, null for custom ranges
+ */
+export const getMatchingPreset = (range: { start?: DateValue; end?: DateValue }):
+	| InsightsDateRange['key']
+	| null => {
+	const { start, end } = range;
+	if (!start || !end || !isToday(end, getLocalTimeZone())) return null;
+
+	const daysDiff = end.compare(start);
+
+	for (const [key, days] of Object.entries(timeRangeMappings)) {
+		if (daysDiff === days) return key as InsightsDateRange['key'];
+	}
+
+	return null;
+};
+
+/**
+ * Converts DateValue range to adjusted Date objects for API calls
+ * - For single-day ranges ending today: injects current time into both dates (exact 24 hours)
+ * - For multi-day ranges ending today: injects current time into end date only
+ * - For past dates: uses end-of-day for end date
+ *
+ * @param dateRange - The date range to adjust
+ */
+export const getAdjustedDateRange = (dateRange: DateRange): { startDate: Date; endDate: Date } => {
+	if (!dateRange.start || !dateRange.end) return { startDate: new Date(), endDate: new Date() };
+
+	const timezone = getLocalTimeZone();
+
+	const todayInTimezone = today(timezone);
+	const isEndDateToday = dateRange.end && dateRange.end.compare(todayInTimezone) === 0;
+	const daysDiff = dateRange.end && dateRange.start ? dateRange.end.compare(dateRange.start) : 0;
+
+	if (isEndDateToday) {
+		const nowInTimezone = now(timezone);
+
+		if (daysDiff === 1) {
+			// For single-day ranges (e.g., "Last 24 hours"), inject current time into both dates
+			// This gives exact 24-hour ranges
+			const startDate = toCalendarDateTime(dateRange.start, nowInTimezone).toDate(timezone);
+			const endDate = toCalendarDateTime(dateRange.end, nowInTimezone).toDate(timezone);
+			return { startDate, endDate };
+		} else {
+			// For multi-day ranges, use start-of-day for start but current time for end
+			const startDate = dateRange.start?.toDate(timezone) ?? new Date();
+			const endDate = toCalendarDateTime(dateRange.end, nowInTimezone).toDate(timezone);
+			return { startDate, endDate };
+		}
+	} else {
+		// For past dates, use beginning of day for start and end of day for end to ensure full day coverage
+		const startDate = dateRange.start?.toDate(timezone) ?? new Date();
+		const endDate = dateRange.end?.toDate(timezone) ?? new Date();
+		endDate.setHours(23, 59, 59, 999);
+		return { startDate, endDate };
+	}
+};

package/stylelint.config.mjs

@@ -0,0 +1,9 @@
+import { baseConfig } from '@n8n/stylelint-config/base';
+
+export default {
+	...baseConfig,
+	rules: {
+		...baseConfig.rules,
+		'@n8n/css-var-naming': [true, { severity: 'error' }],
+	},
+};

package/vite.config.ts

@@ -0,0 +1,29 @@
+import vue from '@vitejs/plugin-vue';
+import icons from 'unplugin-icons/vite';
+import svgLoader from 'vite-svg-loader';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { defineConfig, mergeConfig } from 'vite';
+import { frontendAliases } from '@n8n/frontend-vite-config';
+import { vitestConfig } from '@n8n/vitest-config/frontend';
+
+const packageDir = fileURLToPath(new URL('.', import.meta.url));
+const packagesDir = resolve(packageDir, '..', '..', '..');
+
+export default mergeConfig(
+	defineConfig({
+		// What lets a test render a design-system component. Its icon set imports
+		// `~icons/lucide/*` (unplugin-icons) and `./custom/*.svg` (svgLoader); without
+		// either, an icon resolves to a URL string and rendering throws. The shared
+		// vitest config stubs only the `nodes/*.svg` subset.
+		plugins: [vue(), icons({ compiler: 'vue3' }), svgLoader()],
+		resolve: {
+			// The same platform mapping the editor-ui dev server uses, so a test resolves
+			// `@n8n/stores/...` from source rather than from a stale `dist` — the two disagreeing is
+			// what put 1,111 specifiers on the wrong side of the src/dist line. Sibling modules are
+			// deliberately absent: nothing here should make a cross-module import resolve.
+			alias: frontendAliases(packagesDir),
+		},
+	}),
+	vitestConfig,
+);