A platform for community discussion. Free, open, simple.
DEV: Convert the admin report model to TypeScript (#45204)
Sérgio Saquetime48445bc6090
diff --git a/frontend/discourse/admin/models/report.js b/frontend/discourse/admin/models/report.tssimilarity index 53%rename from frontend/discourse/admin/models/report.jsrename to frontend/discourse/admin/models/report.tsindex 5cd6cc95145..2bd85688ab4 100644--- a/frontend/discourse/admin/models/report.js+++ b/frontend/discourse/admin/models/report.ts@@ -1,5 +1,7 @@+/* eslint-disable prefer-const -- Preserve the original JavaScript emit for this types-only port. */import EmberObject, { computed } from "@ember/object";import { isEmpty } from "@ember/utils";+import type { Moment, MomentInput } from "moment";import { REPORT_MODES } from "discourse/admin/lib/constants";import { ajax } from "discourse/lib/ajax";import { durationTiny, number } from "discourse/lib/formatter";@@ -15,12 +17,178 @@ import {import { renderAvatar } from "discourse/ui-kit/helpers/d-user-avatar";import I18n, { i18n } from "discourse-i18n";-// Change this line each time report format change-// and you want to ensure cache is reset-export const SCHEMA_VERSION = 5;+/** Change when the report format changes and cached reports must be reset. */+export const SCHEMA_VERSION = 5 as const;+/** Table keys are supplied by column descriptors; SQL decimals can be strings. */+export type ReportCellValue = string | number | boolean | null | undefined;+export type ReportRow = Record<string, ReportCellValue>;++export interface ReportPoint {+ x: string;+ y: number;+ end_date?: string;+}++export interface ReportSeries {+ req?: string;+ label: string;+ color: string;+ data: ReportPoint[];+}++export interface ReportStorageStats {+ backups: {+ used_bytes: number;+ free_bytes: number | null;+ count: number;+ last_backup_taken_at: string | null;+ } | null;+ uploads: { used_bytes: number; free_bytes: number | null };+}++export type ReportData =+ | ReportPoint[]+ | ReportSeries[]+ | ReportRow[]+ | ReportStorageStats+ | null;+export type ReportComparison = number | ReportRow | ReportRow[] | null;+export type ReportGrouping = "daily" | "weekly" | "monthly";+export type ReportTrend =+ | "high-trending-up"+ | "high-trending-down"+ | "trending-up"+ | "trending-down"+ | "no-change";+export type ReportTrendIcon =+ | "angle-up"+ | "angle-down"+ | "angles-up"+ | "angles-down"+ | "minus";++/** Semantic names (or link positions) map to keys in a table row. */+export type ReportLabelProperties = Record<string, string> | string[];+export interface ReportLabel {+ title: string;+ html_title?: string;+ type?: string;+ property?: string;+ properties?: ReportLabelProperties;+ sort_property?: string;+}++export interface ReportCellOptions {+ useSortProperty?: boolean;+ formatNumbers?: boolean;+}++/** Table consumers may add the descriptor's type and property to a computed cell. */+export interface ReportCell {+ value: ReportCellValue;+ formattedValue: ReportCellValue;+ type?: string;+ property?: string;+}++export interface ReportComputedLabel {+ title: string;+ htmlTitle?: string;+ mainProperty: string;+ sortProperty: string;+ type: string;+ compute: (row: ReportRow, options?: ReportCellOptions) => ReportCell;+}++export interface ReportFilter {+ id: string;+ type: string;+ default?: ReportCellValue | string[] | number[];+ choices?: (string | { id: string | number; name: string })[];+ allow_any?: boolean;+ auto_insert_none_item?: boolean;+ disabled?: boolean;+}++/** Related-item renderers interpret their own JSON, including nested plugin payloads. */+export type ReportRelatedValue =+ | string+ | number+ | boolean+ | null+ | ReportRelatedValue[]+ | { [key: string]: ReportRelatedValue };++/** Full endpoint view and client state. */+export interface ReportFields {+ type: string;+ title: string | null;+ xaxis: string | Record<string, string> | null;+ yaxis: string | null;+ data: ReportData;+ start_date: string;+ end_date: string;+ prev_start_date: string;+ prev_end_date: string;+ prev_data: ReportPoint[] | ReportSeries[] | null;+ prev30Days: number | ReportRow[] | null;+ prev_period?: ReportComparison;+ dates_filtering: boolean;+ report_key: string;+ primary_color: string;+ secondary_color: string;+ available_filters: ReportFilter[];+ labels: ReportLabel[] | string[];+ modes: string[];+ legacy?: boolean;+ icon?: string;+ error?: "not_found" | "timeout" | "exception" | null;+ total?: number | string;+ limit?: number;+ default_group_by?: string;+ y_axis_title?: string;+ related_items?: Record<string, ReportRelatedValue[]>;+ related_items_totals?: Record<string, number>;+ related_report?: ReportPayload | null;+ relatedReport?: Report;+ chartData?: ReportPoint[] | ReportSeries[];+ prevChartData?: ReportPoint[] | ReportSeries[];+ empty?: boolean;+}++/** Full endpoint JSON without Ember methods or computed properties. */+export type ReportPayload = ReportFields &+ Pick<+ Report,+ | "average"+ | "percent"+ | "higher_is_better"+ | "description"+ | "description_link"+ >;+export type ReportCreateAttrs<M extends EmberObject = Report> = Partial<M>;++/** Property names to read/write, rather than date values. */+export interface ReportFillOptions {+ dataField?: string;+ filledField?: string;+ startDate?: string;+ endDate?: string;+}++// eslint-disable-next-line @typescript-eslint/no-empty-object-type, @typescript-eslint/no-unsafe-declaration-merging+export default interface Report extends ReportFields {}++// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-mergingexport default class Report extends EmberObject {- static groupingForDatapoints(count) {+ /** Inherited factory; find initially creates only type, and tests may supply only data. */+ declare static create: <C extends typeof EmberObject>(+ this: C,+ ...args: ReportCreateAttrs<InstanceType<C>>[]+ ) => InstanceType<C>;++ static groupingForDatapoints(count: number): ReportGrouping | undefined {if (count < DAILY_LIMIT_DAYS) {return "daily";}@@ -34,7 +202,7 @@ export default class Report extends EmberObject {}}- static unitForDatapoints(count) {+ static unitForDatapoints(count: number): "day" | "week" | "month" {if (count >= DAILY_LIMIT_DAYS && count < WEEKLY_LIMIT_DAYS) {return "week";} else if (count >= WEEKLY_LIMIT_DAYS) {@@ -44,7 +212,9 @@ export default class Report extends EmberObject {}}- static unitForGrouping(grouping) {+ static unitForGrouping(+ grouping: string | undefined+ ): "day" | "week" | "month" {switch (grouping) {case "monthly":return "month";@@ -55,7 +225,25 @@ export default class Report extends EmberObject {}}- static collapse(model, data, grouping) {+ static collapse(+ model: {+ start_date: MomentInput;+ end_date: MomentInput;+ average?: boolean;+ },+ data: ReportPoint[],+ grouping?: string+ ): ReportPoint[];++ static collapse(+ model: {+ start_date: MomentInput;+ end_date: MomentInput;+ average?: boolean;+ },+ data: ReportPoint[],+ grouping: string | undefined+ ): ReportPoint[] {grouping = grouping || Report.groupingForDatapoints(data.length);if (grouping === "daily") {@@ -118,7 +306,15 @@ export default class Report extends EmberObject {return data;}- static fillMissingDates(report, options = {}) {+ static fillMissingDates<T extends { modes: string[] }>(+ report: T,+ options?: ReportFillOptions+ ): void;++ static fillMissingDates(+ report: { modes: string[]; [key: string]: unknown },+ options: ReportFillOptions = {}+ ): void {const dataField = options.dataField || "data";const filledField = options.filledField || "data";const startDate = options.startDate || "start_date";@@ -126,11 +322,11 @@ export default class Report extends EmberObject {if (Array.isArray(report[dataField])) {const startDateFormatted = moment- .utc(report[startDate])+ .utc(report[startDate] as MomentInput).locale("en").format("YYYY-MM-DD");const endDateFormatted = moment- .utc(report[endDate])+ .utc(report[endDate] as MomentInput).locale("en").format("YYYY-MM-DD");@@ -138,18 +334,20 @@ export default class Report extends EmberObject {report.modes[0] === "stacked_chart" ||report.modes[0] === "stacked_line_chart") {- report[filledField] = report[dataField].map((rep) => {- return {- req: rep.req,- label: rep.label,- color: rep.color,- data: fillMissingDates(- JSON.parse(JSON.stringify(rep.data)),- startDateFormatted,- endDateFormatted- ),- };- });+ report[filledField] = (report[dataField] as ReportSeries[]).map(+ (rep) => {+ return {+ req: rep.req,+ label: rep.label,+ color: rep.color,+ data: fillMissingDates(+ JSON.parse(JSON.stringify(rep.data)),+ startDateFormatted,+ endDateFormatted+ ),+ };+ }+ );} else if (report.modes[0] !== "radar") {report[filledField] = fillMissingDates(JSON.parse(JSON.stringify(report[dataField])),@@ -160,7 +358,22 @@ export default class Report extends EmberObject {}}- static find(type, startDate, endDate, categoryId, groupId) {+ static find(+ type: string,+ startDate: string,+ endDate: string,+ categoryId?: number,+ groupId?: number+ ): Promise<Report>;++ static find(+ type: string,+ startDate: string,+ endDate: string,+ categoryId: number | undefined,+ groupId: number | undefined+ ): Promise<Report> {+ // TODO(typescript-pending): ajax has no response generic; remove this callback annotation when it does.return ajax("/admin/reports/" + type, {data: {start_date: startDate,@@ -168,7 +381,7 @@ export default class Report extends EmberObject {category_id: categoryId,group_id: groupId,},- }).then((json) => {+ }).then((json: { report: ReportPayload }) => {// don’t fill for large multi column tables// which are not date basedconst modes = json.report.modes;@@ -177,14 +390,16 @@ export default class Report extends EmberObject {}const model = Report.create({ type });- model.setProperties(json.report);+ model.setProperties<keyof ReportPayload, ReportPayload>(json.report);if (json.report.related_report) {// TODO: fillMissingDates if xaxis is dateconst related = Report.create({type: json.report.related_report.type,});- related.setProperties(json.report.related_report);+ related.setProperties<keyof ReportPayload, ReportPayload>(+ json.report.related_report+ );model.set("relatedReport", related);}@@ -192,7 +407,7 @@ export default class Report extends EmberObject {});}- static #dateMoment(value) {+ static #dateMoment(value: MomentInput): Moment {if (moment.isMoment(value)) {return value.clone().startOf("day");}@@ -204,18 +419,19 @@ export default class Report extends EmberObject {return moment.utc(value).startOf("day");}+ /** Forwarded to the avatar renderer, but nothing assigns it on reports. */+ declare siteSettings?: unknown;+average = false;percent = false;higher_is_better = true;- /** @type {string | null} */- description_link = null;+ description_link: string | null = null;- /** @type {string | null} */- description = null;+ description: string | null = null;@computed("type", "start_date", "end_date")- get reportUrl() {+ get reportUrl(): string {const start_date = moment.utc(this.start_date).locale("en")@@ -231,16 +447,20 @@ export default class Report extends EmberObject {);}- get combinedData() {+ /** Only stacked-chart mode is flattened; other modes retain their original data shape. */+ get combinedData(): ReportData {if (this.modes?.includes(REPORT_MODES.stacked_chart)) {return Object.values(- this.data+ (this.data as ReportSeries[]).flatMap((series) => series.data)- .reduce((acc, { x, y }) => {- acc[x] ??= { x, y: 0 };- acc[x].y += y;- return acc;- }, {})+ .reduce(+ (acc, { x, y }) => {+ acc[x] ??= { x, y: 0 };+ acc[x].y += y;+ return acc;+ },+ {} as Record<string, ReportPoint>+ ));}return this.data;@@ -294,17 +514,22 @@ export default class Report extends EmberObject {);}+ /** Flat numeric points are assumed here, even though other report modes carry different data. */@computed("data")get currentTotal() {- return this.data.reduce((cur, pair) => cur + pair.y, 0);+ return (this.data as ReportPoint[]).reduce((cur, pair) => cur + pair.y, 0);}+ /** Keeps the original parseFloat coercion of the point count. */@computed("data", "currentTotal")get currentAverage() {- return makeArray(this.data).length === 0+ return makeArray<ReportData>(this.data).length === 0? 0: parseFloat(- (this.currentTotal / parseFloat(this.data.length)).toFixed(1)+ (+ this.currentTotal /+ parseFloat((this.data as ReportPoint[]).length as unknown as string)+ ).toFixed(1));}@@ -349,7 +574,7 @@ export default class Report extends EmberObject {}@computed("type")- get method() {+ get method(): "average" | "sum" {if (this.type === "time_to_first_response") {return "average";} else {@@ -357,21 +582,28 @@ export default class Report extends EmberObject {}}+ /** Average-mode formatting assumes a numeric comparison, without validating other producer shapes. */@computed("prev_period", "currentTotal", "currentAverage")- get trendTitle() {- let prev = this.prev_period;- let current = this.average ? this.currentAverage : this.currentTotal;+ get trendTitle(): string {+ let prev: number | string | null | undefined = this.prev_period as+ | number+ | null+ | undefined;+ let current: number | string = this.average+ ? this.currentAverage+ : this.currentTotal;let percent = this.percentChangeString(prev, current);if (this.average) {- prev = prev ? prev.toFixed(1) : "0";+ prev = prev ? (prev as number).toFixed(1) : "0";if (this.percent) {- current += "%";+ (current as number | string) += "%";prev += "%";}} else {- prev = number(prev);- current = number(current);+ // TODO(typescript-pending): formatter.number's inferred signature requires optional options; remove casts when typed.+ prev = (number as (value: unknown) => string)(prev);+ current = (number as (value: unknown) => string)(current);}return i18n("admin.dashboard.reports.trend_title", {@@ -395,6 +627,7 @@ export default class Report extends EmberObject {);}+ /** Returns the comparison value itself, including zero, null, or an omitted period. */@computed("prev30Days", "prev_period")get canDisplayTrendIcon() {return this.prev30Days ?? this.prev_period;@@ -409,35 +642,48 @@ export default class Report extends EmberObject {);}+ /** Array modes only; storage data and null are not iterable. */@computed("data")- get sortedData() {- return this.xAxisIsDate ? [...this.data].reverse() : [...this.data];+ get sortedData(): (ReportPoint | ReportSeries | ReportRow)[] {+ return this.xAxisIsDate+ ? [+ ...(this.data as Exclude<ReportData, ReportStorageStats | null>),+ ].reverse()+ : [...(this.data as Exclude<ReportData, ReportStorageStats | null>)];}+ /** Assumes flat string-x points and returns the match result, rather than a boolean. */@computed("data")- get xAxisIsDate() {- if (!this.data[0]) {+ get xAxisIsDate(): false | RegExpMatchArray | null {+ if (!(this.data as ReportPoint[])[0]) {return false;}- return this.data && this.data[0].x.match(/\d{4}-\d{1,2}-\d{1,2}/);+ return (+ this.data &&+ (this.data as ReportPoint[])[0].x.match(/\d{4}-\d{1,2}-\d{1,2}/)+ );}+ /** Table mode assumes descriptors; plugin string labels are consumed by their custom renderers. */@computed("labels")- get computedLabels() {- return this.labels.map((label) => {+ get computedLabels(): ReportComputedLabel[] {+ // Descriptor types select semantic keys; the wire format does not enforce their correlation.+ return (this.labels as ReportLabel[]).map((label) => {const type = label.type || "string";let mainProperty;if (label.property) {mainProperty = label.property;} else if (type === "user") {- mainProperty = label.properties["username"];+ mainProperty = (label.properties as Record<string, string>)["username"];} else if (type === "topic") {- mainProperty = label.properties["title"];+ mainProperty = (label.properties as Record<string, string>)["title"];} else if (type === "post") {- mainProperty = label.properties["truncated_raw"];+ mainProperty = (label.properties as Record<string, string>)[+ "truncated_raw"+ ];} else {- mainProperty = label.properties[0];+ mainProperty = (label.properties as string[])[0];}return {@@ -446,7 +692,7 @@ export default class Report extends EmberObject {sortProperty: label.sort_property || mainProperty,mainProperty,type,- compute: (row, opts = {}) => {+ compute: (row: ReportRow, opts: ReportCellOptions = {}): ReportCell => {let value;if (opts.useSortProperty) {@@ -456,19 +702,28 @@ export default class Report extends EmberObject {}if (type === "user") {- return this._userLabel(label.properties, row);+ return this._userLabel(+ label.properties as Record<string, string>,+ row+ );}if (type === "post") {- return this._postLabel(label.properties, row);+ return this._postLabel(+ label.properties as Record<string, string>,+ row+ );}if (type === "topic") {- return this._topicLabel(label.properties, row);+ return this._topicLabel(+ label.properties as Record<string, string>,+ row+ );}if (type === "seconds") {return this._secondsLabel(value);}if (type === "link") {- return this._linkLabel(label.properties, row);+ return this._linkLabel(label.properties as string[], row);}if (type === "percent") {return this._percentLabel(value);@@ -480,13 +735,13 @@ export default class Report extends EmberObject {return this._numberLabel(value, opts);}if (type === "date") {- const date = moment(value);+ const date = moment(value as MomentInput);if (date.isValid()) {return this._dateLabel(value, date);}}if (type === "precise_date") {- const date = moment(value);+ const date = moment(value as MomentInput);if (date.isValid()) {return this._dateLabel(value, date, "LLL");}@@ -506,13 +761,16 @@ export default class Report extends EmberObject {});}- valueAt(numDaysAgo) {+ /** Count helpers assume combinedData is a flat numeric time series. */+ valueAt(numDaysAgo: number): number {if (this.combinedData) {const wantedDate = moment().subtract(numDaysAgo, "days").locale("en").format("YYYY-MM-DD");- const item = this.combinedData.find((d) => d.x === wantedDate);+ const item = (this.combinedData as ReportPoint[]).find(+ (d) => d.x === wantedDate+ );if (item) {return item.y;}@@ -520,14 +778,15 @@ export default class Report extends EmberObject {return 0;}- valueFor(startDaysAgo, endDaysAgo) {+ /** Returns undefined when data is absent, including on partially constructed reports. */+ valueFor(startDaysAgo: number, endDaysAgo: number): number | undefined {if (this.combinedData) {const earliestDate = moment().subtract(endDaysAgo, "days").startOf("day");const latestDate = moment().subtract(startDaysAgo, "days").startOf("day");- let d,+ let d: Moment,sum = 0,count = 0;- this.combinedData.forEach((datum) => {+ (this.combinedData as ReportPoint[]).forEach((datum) => {d = moment(datum.x);if (d >= earliestDate && d <= latestDate) {sum += datum.y;@@ -541,11 +800,15 @@ export default class Report extends EmberObject {}}- averageCount(count, value) {- return this.average ? value / count : value;+ /** Undefined is passed through, or coerced to NaN by division for average reports. */+ averageCount(count: number, value: number | undefined): number | undefined {+ return this.average ? (value as number) / count : value;}- percentChangeString(val1, val2) {+ percentChangeString(+ val1: ReportComparison | undefined,+ val2: number | string | undefined+ ): string | null {const change = this._computeChange(val1, val2);if (isNaN(change) || !isFinite(change)) {@@ -557,7 +820,11 @@ export default class Report extends EmberObject {}}- changeTitle(valAtT1, valAtT2, prevPeriodString) {+ changeTitle(+ valAtT1: ReportComparison | undefined,+ valAtT2: number | undefined,+ prevPeriodString: string+ ): string {const change = this.percentChangeString(valAtT1, valAtT2);const title = [];if (change) {@@ -572,20 +839,28 @@ export default class Report extends EmberObject {`admin.dashboard.reports.percent_change_tooltip_previous_value.${prevPeriodString}`,{count: valAtT1,- previousValue: number(valAtT1),+ // TODO(typescript-pending): remove when formatter.number types its optional options.+ previousValue: (number as (value: unknown) => string)(valAtT1),}));return title.join(" ");}- _userLabel(properties, row) {+ _userLabel(properties: Record<string, string>, row: ReportRow): ReportCell {const username = row[properties.username];const formattedValue = () => {const userId = row[properties.id];- const user = EmberObject.create({+ // EmberObject.create only accepts declared members, and this anonymous record declares none.+ const user = (+ EmberObject.create as (attrs: {+ username: ReportCellValue;+ name: string;+ avatar_template: ReportCellValue;+ }) => EmberObject & { name: string }+ )({username,name: formatUsername(username),avatar_template: row[properties.avatar],@@ -608,7 +883,7 @@ export default class Report extends EmberObject {};}- _topicLabel(properties, row) {+ _topicLabel(properties: Record<string, string>, row: ReportRow): ReportCell {const topicTitle = row[properties.title];const formattedValue = () => {@@ -623,7 +898,7 @@ export default class Report extends EmberObject {};}- _postLabel(properties, row) {+ _postLabel(properties: Record<string, string>, row: ReportRow): ReportCell {const postTitle = row[properties.truncated_raw];const postNumber = row[properties.number];const topicId = row[properties.topic_id];@@ -639,21 +914,27 @@ export default class Report extends EmberObject {};}- _secondsLabel(value) {+ _secondsLabel(value: ReportCellValue): ReportCell {return {value: toNumber(value),- formattedValue: durationTiny(value),+ // TODO(typescript-pending): remove when durationTiny types its optional options.+ formattedValue: (durationTiny as (value: ReportCellValue) => string)(+ value+ ),};}- _percentLabel(value) {+ _percentLabel(value: ReportCellValue): ReportCell {return {value: toNumber(value),formattedValue: value === null || value === undefined ? "—" : `${value}%`,};}- _numberLabel(value, options = {}) {+ _numberLabel(+ value: ReportCellValue,+ options: ReportCellOptions = {}+ ): ReportCell {const formatNumbers = isEmpty(options.formatNumbers)? true: options.formatNumbers;@@ -667,21 +948,24 @@ export default class Report extends EmberObject {};}- _bytesLabel(value) {+ _bytesLabel(value: ReportCellValue): ReportCell {return {value: toNumber(value),- formattedValue: I18n.toHumanSize(value),+ // TODO(typescript-pending): remove when toHumanSize publishes its optional options and string return.+ formattedValue: (I18n.toHumanSize as (value: ReportCellValue) => string)(+ value+ ),};}- _dateLabel(value, date, format = "LL") {+ _dateLabel(value: ReportCellValue, date: Moment, format = "LL"): ReportCell {return {value,formattedValue: value ? date.format(format) : "—",};}- _textLabel(value) {+ _textLabel(value: ReportCellValue): ReportCell {const escaped = escapeExpression(value);return {@@ -690,10 +974,10 @@ export default class Report extends EmberObject {};}- _linkLabel(properties, row) {+ _linkLabel(properties: string[], row: ReportRow): ReportCell {const property = properties[0];- const value = getURL(row[property]);- const formattedValue = (href, anchor) => {+ const value = getURL(row[property] as string);+ const formattedValue = (href: string, anchor: ReportCellValue) => {return `<a href="${escapeExpression(href)}">${escapeExpression(anchor)}</a>`;@@ -705,11 +989,21 @@ export default class Report extends EmberObject {};}- _computeChange(valAtT1, valAtT2) {- return ((valAtT2 - valAtT1) / valAtT1) * 100;+ /** Preserves arithmetic coercion of nullable, object, and row-valued comparisons. */+ _computeChange(+ valAtT1: ReportComparison | undefined,+ valAtT2: number | string | undefined+ ): number {+ return (+ (((valAtT2 as number) - (valAtT1 as number)) / (valAtT1 as number)) * 100+ );}- _computeTrend(valAtT1, valAtT2, higherIsBetter) {+ _computeTrend(+ valAtT1: ReportComparison | undefined,+ valAtT2: number | undefined,+ higherIsBetter: boolean+ ): ReportTrend | undefined {const change = this._computeChange(valAtT1, valAtT2);if (change > 50) {@@ -725,7 +1019,10 @@ export default class Report extends EmberObject {}}- _iconForTrend(trend, higherIsBetter) {+ _iconForTrend(+ trend: ReportTrend | undefined,+ higherIsBetter: boolean+ ): ReportTrendIcon {switch (trend) {case "trending-up":return higherIsBetter ? "angle-up" : "angle-down";@@ -741,10 +1038,13 @@ export default class Report extends EmberObject {}}-export const WEEKLY_LIMIT_DAYS = 365;-export const DAILY_LIMIT_DAYS = 34;+export const WEEKLY_LIMIT_DAYS = 365 as const;+export const DAILY_LIMIT_DAYS = 34 as const;-function applyAverage(value, start, end) {+function applyAverage(value: number, start: Moment, end: Moment): number {const count = end.diff(start, "day") + 1; // 1 to include startreturn parseFloat((value / count).toFixed(2));}++/** The application provides moment globally. */+declare const moment: typeof import("moment");diff --git a/frontend/discourse/type-tests/models/admin-report-test.ts b/frontend/discourse/type-tests/models/admin-report-test.tsnew file mode 100644index 00000000000..04f3c925426--- /dev/null+++ b/frontend/discourse/type-tests/models/admin-report-test.ts@@ -0,0 +1,418 @@+import type EmberObject from "@ember/object";+import { expectTypeOf } from "expect-type";+import Report, {+ DAILY_LIMIT_DAYS,+ type ReportCell,+ type ReportCellValue,+ type ReportCreateAttrs,+ type ReportData,+ type ReportPayload,+ type ReportPoint,+ type ReportRow,+ type ReportSeries,+ SCHEMA_VERSION,+ WEEKLY_LIMIT_DAYS,+} from "discourse/admin/models/report";+import type RestModel from "discourse/models/rest";++type Trend =+ | "high-trending-up"+ | "high-trending-down"+ | "trending-up"+ | "trending-down"+ | "no-change";+type TrendIcon =+ | "angle-up"+ | "angle-down"+ | "angles-up"+ | "angles-down"+ | "minus";++expectTypeOf(SCHEMA_VERSION).toEqualTypeOf<5>();+expectTypeOf(WEEKLY_LIMIT_DAYS).toEqualTypeOf<365>();+expectTypeOf(DAILY_LIMIT_DAYS).toEqualTypeOf<34>();++/* Statics. */++expectTypeOf(Report.groupingForDatapoints(10)).toEqualTypeOf<+ "daily" | "weekly" | "monthly" | undefined+>();+expectTypeOf(Report.unitForDatapoints(10)).toEqualTypeOf<+ "day" | "week" | "month"+>();+expectTypeOf(Report.unitForGrouping("weekly")).toEqualTypeOf<+ "day" | "week" | "month"+>();+// Chart options may leave the grouping unset.+Report.unitForGrouping(undefined);+// Charts collapse plain `{ start_date, end_date, data }` objects too, not only reports.+const collapsed = Report.collapse(+ { start_date: "2026-10-01", end_date: "2026-10-31" },+ [{ x: "2026-10-01", y: 1 }],+ "weekly"+);+expectTypeOf(collapsed).not.toBeAny();+expectTypeOf(collapsed).toExtend<{ x: string; y: number }[]>();+Report.collapse({ start_date: "2026-10-01", end_date: "2026-10-31" }, []);+// The options name the properties to read and write.+expectTypeOf(+ Report.fillMissingDates(+ {+ modes: ["chart"],+ data: [{ x: "2026-10-01", y: 1 }],+ start_date: "2026-10-01T00:00:00Z",+ end_date: "2026-10-31T23:59:59Z",+ },+ { filledField: "chartData" }+ )+).toEqualTypeOf<void>();+Report.fillMissingDates(+ { modes: ["chart"], data: [], prev_data: [] },+ {+ dataField: "prev_data",+ filledField: "prevChartData",+ startDate: "prev_start_date",+ endDate: "prev_end_date",+ }+);+Report.fillMissingDates(+ { modes: ["chart"], data: [] },+ // @ts-expect-error `startDate` is the option name+ { starDate: "prev_start_date" }+);+expectTypeOf(+ Report.find("topics", "2026-10-01", "2026-10-31")+).resolves.toEqualTypeOf<Report>();+Report.find("topics", "2026-10-01", "2026-10-31", 3, 4);++/* Construction from `/admin/reports/:type` payloads. */++Report.create({+ type: "topics",+ title: "Topics",+ xaxis: "Day",+ yaxis: "Number of new topics",+ description: "New topics created during this period.",+ description_link: null,+ data: [{ x: "2026-10-27", y: 1 }],+ start_date: "2026-10-27T00:00:00Z",+ end_date: "2026-11-26T23:59:59Z",+ prev_data: null,+ prev_start_date: "2026-09-26T00:00:00Z",+ prev_end_date: "2026-10-27T00:00:00Z",+ prev30Days: 0,+ dates_filtering: true,+ report_key: "reports:topics:20261027:20261126",+ primary_color: "rgba(0,136,204,1)",+ secondary_color: "rgba(0,136,204,0.1)",+ available_filters: [{ id: "category", type: "category", default: null }],+ labels: [+ { type: "date", property: "x", title: "Day" },+ { type: "number", property: "y", title: "Count" },+ ],+ average: false,+ percent: false,+ higher_is_better: true,+ modes: ["chart", "table"],+ total: 1,+ prev_period: 0,+ limit: 5,+});+// Stacked reports send series and translate each axis key.+Report.create({+ type: "visits",+ xaxis: { desktop: "Desktop", mobile: "Mobile" },+ data: [+ {+ req: "desktop",+ label: "Desktop",+ color: "#1EB8D1",+ data: [{ x: "2026-10-27", y: 1 }],+ },+ ],+ // SQL decimals arrive as strings.+ total: "2.0",+ icon: "user",+ default_group_by: "weekly",+});+Report.create({+ type: "user_flagging_ratio",+ title: null,+ data: [{ user_id: 1, username: "anne", score: "0.0" }],+ labels: [+ {+ type: "user",+ properties: {+ username: "username",+ id: "user_id",+ avatar: "avatar_template",+ },+ title: "User",+ },+ {+ type: "topic",+ properties: { title: "topic_title", id: "topic_id" },+ title: "Topic",+ },+ {+ type: "post",+ properties: {+ topic_id: "topic_id",+ number: "post_number",+ truncated_raw: "post_raw",+ },+ title: "Post",+ },+ { type: "link", properties: ["url", "title"], title: "Link" },+ { property: "share_formatted", title: "Share", sort_property: "share" },+ {+ type: "number",+ property: "like_count",+ title: "heart",+ html_title: "<img>",+ },+ ],+});+Report.create({+ type: "storage_stats",+ data: {+ backups: {+ used_bytes: 0,+ free_bytes: null,+ count: 0,+ last_backup_taken_at: null,+ },+ uploads: { used_bytes: 2062105, free_bytes: null },+ },+});+Report.create({+ type: "trust_level_pipeline",+ prev_period: { direction: "climbing", net: 2 },+});+Report.create({+ type: "web_hook_events_daily_aggregate",+ prev30Days: [],+ available_filters: [+ {+ id: "type_of_web_hook_event",+ type: "list",+ default: "all",+ choices: [{ id: "all", name: "all" }],+ allow_any: false,+ auto_insert_none_item: false,+ },+ { id: "groups", type: "groups", default: ["staff"] },+ { id: "category_ids", type: "category_list", default: [1, 2] },+ { id: "include_subcategories", type: "bool", default: false },+ ],+});+Report.create({+ type: "signups",+ related_items: {+ users: [+ {+ user: {+ id: 1,+ username: "bruce",+ name: null,+ avatar_template: "/a.png",+ },+ timestamp: "2026-10-28T00:32:54Z",+ },+ ],+ },+ related_items_totals: { users: 1 },+});+// Bulk responses send `error: null` for reports that loaded.+Report.create({ type: "topics", error: null, data: null });+Report.create({ type: "nonexistent", error: "not_found" });+// The dashboard provider adds `empty`.+Report.create({ type: "topics", empty: false });+// Some plugin reports send plain string labels.+Report.create({+ type: "sentiment_analysis",+ labels: ["Positive", "Negative", "Neutral"],+});+// @ts-expect-error the type is a string+Report.create({ type: 5 });++/* Instance fields. */++declare const report: Report;+expectTypeOf(report).toExtend<EmberObject>();+expectTypeOf(report).not.toExtend<RestModel>();+expectTypeOf(report).not.toBeAny();+expectTypeOf(report.type).toEqualTypeOf<string>();+expectTypeOf(report.title).toEqualTypeOf<string | null>();+expectTypeOf(report.yaxis).toEqualTypeOf<string | null>();+expectTypeOf(report.description).toEqualTypeOf<string | null>();+expectTypeOf(report.description_link).toEqualTypeOf<string | null>();+expectTypeOf(report.start_date).toEqualTypeOf<string>();+expectTypeOf(report.end_date).toEqualTypeOf<string>();+expectTypeOf(report.prev_start_date).toEqualTypeOf<string>();+expectTypeOf(report.prev_end_date).toEqualTypeOf<string>();+expectTypeOf(report.dates_filtering).toEqualTypeOf<boolean>();+expectTypeOf(report.report_key).toEqualTypeOf<string>();+expectTypeOf(report.primary_color).toEqualTypeOf<string>();+expectTypeOf(report.secondary_color).toEqualTypeOf<string>();+expectTypeOf(report.average).toEqualTypeOf<boolean>();+expectTypeOf(report.percent).toEqualTypeOf<boolean>();+expectTypeOf(report.higher_is_better).toEqualTypeOf<boolean>();+expectTypeOf(report.modes).toEqualTypeOf<string[]>();+expectTypeOf(report.limit).toEqualTypeOf<number | undefined>();+expectTypeOf(report.icon).toEqualTypeOf<string | undefined>();+expectTypeOf(report.default_group_by).toEqualTypeOf<string | undefined>();+expectTypeOf(report.y_axis_title).toEqualTypeOf<string | undefined>();+expectTypeOf(report.empty).toEqualTypeOf<boolean | undefined>();+expectTypeOf(report.error).toEqualTypeOf<+ "not_found" | "timeout" | "exception" | null | undefined+>();+// The report component records loader failures on the instance.+report.error = "exception";+expectTypeOf(report.data).not.toBeAny();+expectTypeOf(report.labels).not.toBeAny();+expectTypeOf(report.available_filters[0].id).toEqualTypeOf<string>();+expectTypeOf(report.xaxis).not.toBeAny();+expectTypeOf<null>().toExtend<Report["xaxis"]>();+expectTypeOf<null>().toExtend<Report["prev30Days"]>();+expectTypeOf<undefined>().toExtend<Report["prev_period"]>();+expectTypeOf<undefined>().toExtend<Report["total"]>();+expectTypeOf<undefined>().toExtend<Report["legacy"]>();+expectTypeOf(report.related_items).not.toBeAny();+expectTypeOf(report.related_items_totals).not.toBeAny();+expectTypeOf(report.relatedReport).toEqualTypeOf<Report | undefined>();+expectTypeOf(report.chartData).not.toBeAny();+expectTypeOf(report.prevChartData).not.toBeAny();++/* Derived values. */++expectTypeOf(report.reportUrl).toEqualTypeOf<string>();+expectTypeOf(report.combinedData).not.toBeAny();+expectTypeOf(report.todayCount).toEqualTypeOf<number>();+expectTypeOf(report.yesterdayCount).toEqualTypeOf<number>();+expectTypeOf(report.sevenDaysAgoCount).toEqualTypeOf<number>();+expectTypeOf(report.thirtyDaysAgoCount).toEqualTypeOf<number>();+expectTypeOf(report.lastSevenDaysCount).toEqualTypeOf<number | undefined>();+expectTypeOf(report.lastThirtyDaysCount).toEqualTypeOf<number | undefined>();+expectTypeOf(report.currentTotal).toEqualTypeOf<number>();+expectTypeOf(report.currentAverage).toEqualTypeOf<number>();+expectTypeOf(report.trend).toEqualTypeOf<Trend | undefined>();+expectTypeOf(report.yesterdayTrend).toEqualTypeOf<Trend | undefined>();+expectTypeOf(report.sevenDaysTrend).toEqualTypeOf<Trend | undefined>();+expectTypeOf(report.thirtyDaysTrend).toEqualTypeOf<Trend | undefined>();+expectTypeOf(report.trendIcon).toEqualTypeOf<TrendIcon>();+expectTypeOf(report.yesterdayTrendIcon).toEqualTypeOf<TrendIcon>();+expectTypeOf(report.sevenDaysTrendIcon).toEqualTypeOf<TrendIcon>();+expectTypeOf(report.thirtyDaysTrendIcon).toEqualTypeOf<TrendIcon>();+expectTypeOf(report.method).toEqualTypeOf<"average" | "sum">();+expectTypeOf(report.trendTitle).toEqualTypeOf<string>();+expectTypeOf(report.yesterdayCountTitle).toEqualTypeOf<string>();+expectTypeOf(report.sevenDaysCountTitle).toEqualTypeOf<string>();+expectTypeOf(report.thirtyDaysCountTitle).toEqualTypeOf<string>();+// Returns the comparison value itself, not a boolean.+expectTypeOf(report.canDisplayTrendIcon).toEqualTypeOf<+ NonNullable<Report["prev30Days"]> | Report["prev_period"]+>();+expectTypeOf(report.sortedData).not.toBeAny();+expectTypeOf(report.xAxisIsDate).toEqualTypeOf<+ false | RegExpMatchArray | null+>();+expectTypeOf(report.valueAt(1)).toEqualTypeOf<number>();+expectTypeOf(report.valueFor(1, 7)).toEqualTypeOf<number | undefined>();+expectTypeOf(report.percentChangeString(1, 2)).toEqualTypeOf<string | null>();+expectTypeOf(report.changeTitle(1, 2, "yesterday")).toEqualTypeOf<string>();++/* Table columns. */++const [column] = report.computedLabels;+expectTypeOf(column.title).toEqualTypeOf<string>();+expectTypeOf(column.htmlTitle).toEqualTypeOf<string | undefined>();+expectTypeOf(column.mainProperty).toEqualTypeOf<string>();+expectTypeOf(column.sortProperty).toEqualTypeOf<string>();+expectTypeOf(column.type).toEqualTypeOf<string>();+const cell = column.compute({ username: "anne", y: 3 });+expectTypeOf(cell).not.toBeAny();+expectTypeOf(cell).toHaveProperty("value");+expectTypeOf(cell).toHaveProperty("formattedValue");+column.compute({ y: 3 }, { useSortProperty: true });+column.compute({ y: 3 }, { formatNumbers: false });++/* Partial construction and raw hashes. */++const partial = Report.create({ type: "topics", data: [] });+expectTypeOf(partial).toEqualTypeOf<Report>();+expectTypeOf(Report.create()).toEqualTypeOf<Report>();+expectTypeOf<typeof Report>().toExtend<typeof EmberObject>();+expectTypeOf<ReportCreateAttrs>().toEqualTypeOf<Partial<Report>>();+expectTypeOf(partial.siteSettings).not.toBeAny();+Report.create({+ type: "web_hook_events_daily_aggregate",+ prev30Days: [+ {+ id: 1,+ date: null,+ mean_duration: "0.25",+ failed_event_count: null,+ successful_event_count: 2,+ },+ ],+ prev_period: [{ date: "2026-10-01", mean_duration: null }],+ chartData: [{ x: "2026-10-01", y: 1 }],+ prevChartData: [+ { label: "Previous", color: "red", data: [{ x: "2026-09-01", y: 0 }] },+ ],+});+// Related-item renderers read their own nested JSON.+Report.create({+ related_items: {+ custom_items: [{ topic: { title: "Example" }, users: [], category: null }],+ },+});+Report.fillMissingDates(partial);+Report.fillMissingDates(+ { modes: ["chart"], points: [], from: "2026-10-01", to: "2026-10-31" },+ {+ dataField: "points",+ filledField: "filled",+ startDate: "from",+ endDate: "to",+ }+);+expectTypeOf(+ Report.collapse(+ { start_date: new Date(), end_date: new Date(), average: true },+ []+ )+).toEqualTypeOf<ReportPoint[]>();+expectTypeOf<Report["data"]>().toEqualTypeOf<ReportData>();+expectTypeOf<Report["prev_data"]>().toEqualTypeOf<+ ReportPoint[] | ReportSeries[] | null+>();+expectTypeOf<ReportPayload>().not.toHaveProperty("computedLabels");+expectTypeOf(+ partial.computedLabels[0].compute({ score: "0.0" }).value+).toEqualTypeOf<ReportCellValue>();+expectTypeOf(partial._bytesLabel(10)).toEqualTypeOf<ReportCell>();+expectTypeOf(+ partial._numberLabel("2.0", { formatNumbers: false })+).toEqualTypeOf<ReportCell>();+expectTypeOf(partial.averageCount(7, undefined)).toEqualTypeOf<+ number | undefined+>();++// Class modifications can replace the helpers with matching signatures.+const changes = {+ _computeChange(+ previous: Report["prev_period"],+ current: number | string | undefined+ ) {+ return partial._computeChange(previous, current);+ },+ _userLabel(properties: Record<string, string>, row: ReportRow) {+ return partial._userLabel(properties, row);+ },+ valueAt(days: number) {+ return partial.valueAt(days);+ },+} satisfies Pick<Report, "_computeChange" | "_userLabel" | "valueAt">;+Report.reopen(changes);