Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

8.6 KB
Raw Blame
import type { Series } from '@posthog/quill-charts'

import type {
    ChartDisplayType,
    FunnelResult,
    HogQLResult,
    TrendsQuery,
    TrendsResultItem,
    WebOverviewItem,
} from './types'

export function getDisplayType(query: TrendsQuery | undefined): ChartDisplayType {
    return query?.trendsFilter?.display || 'ActionsLineGraph'
}

export interface InsightQueryProperties {
    queryKind?: string
    querySourceKind?: string
    display?: string
    funnelVizType?: string
}

export function insightQueryProperties(query: unknown): InsightQueryProperties {
    if (typeof query !== 'object' || query === null) {
        return {}
    }
    const node = query as Record<string, unknown>
    const hasSource = typeof node.source === 'object' && node.source !== null
    const source = (hasSource ? node.source : node) as Record<string, any>
    return {
        queryKind: typeof node.kind === 'string' ? node.kind : undefined,
        querySourceKind: hasSource && typeof source.kind === 'string' ? source.kind : undefined,
        // Only what the query set, so an unset display stays empty instead of looking like a pick.
        // SQL insights keep their display on the wrapper node, not on the HogQL source.
        display:
            source.trendsFilter?.display ??
            source.stickinessFilter?.display ??
            source.retentionFilter?.display ??
            (node.kind === 'DataVisualizationNode' && typeof node.display === 'string' ? node.display : undefined),
        funnelVizType: source.funnelsFilter?.funnelVizType,
    }
}

export function formatNumber(value: number): string {
    if (value >= 1_000_000) {
        return `${(value / 1_000_000).toFixed(1)}M`
    }
    if (value >= 1_000) {
        return `${(value / 1_000).toFixed(1)}K`
    }
    return value.toLocaleString()
}

export function formatPercent(value: number): string {
    return `${(value * 100).toFixed(1)}%`
}

/** Format a duration given in milliseconds as the two most-significant units (e.g. `1d 3h`, `34m 43s`). */
export function formatDuration(ms: number): string {
    if (!isFinite(ms) || ms <= 0) {
        return '0s'
    }
    const totalSeconds = Math.round(ms / 1000)
    const units: Array<[number, string]> = [
        [Math.floor(totalSeconds / 86400), 'd'],
        [Math.floor((totalSeconds % 86400) / 3600), 'h'],
        [Math.floor((totalSeconds % 3600) / 60), 'm'],
        [totalSeconds % 60, 's'],
    ]
    const parts = units.filter(([value]) => value > 0).map(([value, unit]) => `${value}${unit}`)
    return parts.slice(0, 2).join(' ') || '0s'
}

// Only format strings that look like ISO dates — `new Date(...)` is permissive enough that
// labels like "Day 1" silently parse to Jan 1 2001, mangling pre-formatted axis labels.
const ISO_DATE_PREFIX = /^\d{4}-\d{2}-\d{2}/

export function formatDate(dateStr: string): string {
    if (!ISO_DATE_PREFIX.test(dateStr)) {
        return dateStr
    }
    const date = new Date(dateStr)
    if (Number.isNaN(date.getTime())) {
        return dateStr
    }
    return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric' })
}

const SUB_DAY_INTERVALS = new Set(['second', 'minute', 'hour'])
const WALL_CLOCK_TIME = /^\d{4}-\d{2}-\d{2}[T ](\d{2}:\d{2})/

export function formatTooltipDate(dateStr: string, interval?: string): string {
    if (!ISO_DATE_PREFIX.test(dateStr)) {
        return dateStr
    }
    const date = new Date(dateStr)
    if (Number.isNaN(date.getTime())) {
        return dateStr
    }
    const day = date.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' })
    const time = interval && SUB_DAY_INTERVALS.has(interval) ? WALL_CLOCK_TIME.exec(dateStr)?.[1] : undefined
    return time ? `${day} ${time}` : day
}

export function getSeriesLabel(item: { label?: string }, index: number): string {
    return item.label || `Series ${index + 1}`
}

export function buildProportionBarSeries(results: TrendsResultItem[], getColor: (index: number) => string): Series[] {
    // One bar has one total, so a previous period saved with compare on is left out.
    return results
        .filter((item) => item.compare_label !== 'previous')
        .map((item, i) => ({
            key: String(i),
            label: getSeriesLabel(item, i),
            data: [item.aggregated_value ?? 0],
            color: getColor(i),
        }))
}

export function normalizeFunnelSteps(results: FunnelResult): Array<{ name: string; count: number; order: number }> {
    if (results.length === 0) {
        return []
    }

    const firstItem = results[0]
    if (Array.isArray(firstItem)) {
        return firstItem.map((step, idx) => ({
            name: step.custom_name || step.name || `Step ${idx + 1}`,
            count: step.count || 0,
            order: step.order ?? idx,
        }))
    }

    return (results as Array<{ name?: string; custom_name?: string; count?: number; order?: number }>).map(
        (step, idx) => ({
            name: step.custom_name || step.name || `Step ${idx + 1}`,
            count: step.count || 0,
            order: step.order ?? idx,
        })
    )
}

// Web stats columns that drive the web analytics UI only, not data.
const HIDDEN_WEB_STATS_COLUMNS = new Set(['ui_fill_fraction', 'cross_sell'])

// Worst band first, so the pages that need work lead the table.
const WEB_VITALS_BANDS = [
    ['poor', 'Poor'],
    ['needs_improvements', 'Needs improvement'],
    ['good', 'Good'],
] as const

function humanizeKey(key: string): string {
    const text = key.replace(/_/g, ' ')
    return text.charAt(0).toUpperCase() + text.slice(1)
}

function formatWebOverviewValue({ kind, value }: WebOverviewItem): string | null {
    if (value === null || value === undefined) {
        return null
    }
    if (kind === 'percentage') {
        return `${value.toFixed(1)}%`
    }
    if (kind === 'duration_s') {
        return formatDuration(value * 1000)
    }
    return formatNumber(value)
}

function webStatsCell(column: string, value: unknown): unknown {
    // Metric cells are `[current, previous]` tuples; multi-part breakdowns (city, region) are tuples too.
    if (Array.isArray(value) && column === 'breakdown_value') {
        return value.filter((part) => part !== null && part !== '').join(', ')
    }
    const current = Array.isArray(value) ? value[0] : value
    return typeof current === 'number' && /rate|percentage/.test(column) ? formatPercent(current) : current
}

/** Maps query results that have no chart of their own into the `columns`/`results` shape of the table. */
export function toTableResult(query: unknown, results: unknown, columns: string[] | undefined): HogQLResult {
    const node = (query ?? {}) as { kind?: unknown; breakdownBy?: unknown }
    if (node.kind === 'WebOverviewQuery' && Array.isArray(results)) {
        return {
            columns: ['Metric', 'Value', 'Change'],
            results: (results as WebOverviewItem[]).map((item) => [
                humanizeKey(item.key),
                formatWebOverviewValue(item),
                typeof item.changeFromPreviousPct === 'number'
                    ? `${item.changeFromPreviousPct > 0 ? '+' : ''}${item.changeFromPreviousPct}%`
                    : null,
            ]),
        }
    }
    if (node.kind === 'WebStatsTableQuery' && Array.isArray(results)) {
        const names = (columns ?? []).map((column) => column.replace(/^context\.columns\./, ''))
        const kept = names.flatMap((name, index) => (HIDDEN_WEB_STATS_COLUMNS.has(name) ? [] : [index]))
        return {
            columns: kept.map((index) =>
                names[index] === 'breakdown_value' && typeof node.breakdownBy === 'string'
                    ? node.breakdownBy
                    : humanizeKey(names[index]!)
            ),
            results: (results as unknown[][]).map((row) =>
                kept.map((index) => webStatsCell(names[index]!, row[index]))
            ),
        }
    }
    if (node.kind === 'WebVitalsPathBreakdownQuery' && Array.isArray(results)) {
        const { metric, percentile } = node as { metric?: string; percentile?: string }
        // The response always holds one breakdown object, keyed by band.
        const bands = (results[0] ?? {}) as Partial<Record<string, Array<{ path: string; value: number }>>>
        return {
            columns: ['Path', `${metric ?? 'Value'} (${percentile ?? 'p75'})`, 'Rating'],
            results: WEB_VITALS_BANDS.flatMap(([band, label]) =>
                (bands[band] ?? []).map(({ path, value }) => [
                    path,
                    metric === 'CLS' ? value.toFixed(2) : `${Math.round(value)} ms`,
                    label,
                ])
            ),
        }
    }
    return results as HogQLResult
}