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.3 KB
Raw Blame
import api from 'lib/api'

import { FileSystemEntry } from '~/queries/schema/schema-general'

import { ANALYTICS_TYPES, AnalyticsItem, AnalyticsType, fileSystemEntryToAnalytics } from './analyticsUtils'

export const ANALYTICS_FEED_PAGE_SIZE = 20

const ANALYTICS_ORDER_BYS = ['-created_at', 'created_at', '-last_viewed_at', 'last_viewed_at'] as const

/** A column of the list, with a leading `-` for descending, as the file system API takes it. */
export type AnalyticsOrderBy = (typeof ANALYTICS_ORDER_BYS)[number]

export function isAnalyticsOrderBy(value: unknown): value is AnalyticsOrderBy {
    return ANALYTICS_ORDER_BYS.includes(value as AnalyticsOrderBy)
}

export function parseAnalyticsOrderBy(orderBy: AnalyticsOrderBy): { id: string; desc: boolean } {
    return { id: orderBy.replace('-', ''), desc: orderBy.startsWith('-') }
}

/** The order for a sorted column, or undefined for a column the list cannot sort on. */
export function analyticsOrderByOfColumn({ id, desc }: { id: string; desc: boolean }): AnalyticsOrderBy | undefined {
    const orderBy = `${desc ? '-' : ''}${id}`
    return isAnalyticsOrderBy(orderBy) ? orderBy : undefined
}

export interface AnalyticsFeedQuery {
    /** The types to list; empty means every type. */
    types: AnalyticsType[]
    orderBy?: AnalyticsOrderBy
    search: string
    /** Creators' uuids; empty means anyone. The file system cannot filter on a uuid, so the rows are narrowed on the client. */
    createdBy: string[]
    /** True when the only creator is the current person, so the file system narrows the rows itself with `user:me`. */
    createdByMe: boolean
    /** Tag names a row must all carry. Like the creator, narrowed on the client. */
    tags: string[]
    /** Leaves insights out of the list of every type. Picking the insight type still shows them. */
    hideInsights?: boolean
}

export const EMPTY_ANALYTICS_FEED_QUERY: AnalyticsFeedQuery = {
    types: [],
    search: '',
    createdBy: [],
    createdByMe: false,
    tags: [],
}

export interface AnalyticsSourcePage {
    items: AnalyticsItem[]
    /** Rows the API returned, before any client-side filtering, so the next offset stays right. */
    fetched: number
    hasMore: boolean
}

export interface AnalyticsSourceState {
    projectId: string
    query: AnalyticsFeedQuery
    type: AnalyticsType
    items: AnalyticsItem[]
    offset: number
    hasMore: boolean
    initialized: boolean
    refreshing: boolean
    loading: boolean
    failed: boolean
    generation: number
}

export interface AnalyticsFeed {
    items: AnalyticsItem[]
    initialized: boolean
    loading: boolean
    hasMore: boolean
    failedTypes: AnalyticsType[]
    loadFailed: boolean
}

// Only dashboards and insights carry tags, so a tag filter leaves the other types out of the read.
const TAGGABLE_ANALYTICS_TYPES: ReadonlySet<AnalyticsType> = new Set<AnalyticsType>(['dashboard', 'insight'])

export function analyticsFeedTypes(query: AnalyticsFeedQuery): AnalyticsType[] {
    const types = query.types.length
        ? query.types
        : ANALYTICS_TYPES.map((info) => info.type).filter((type) => !query.hideInsights || type !== 'insight')
    return query.tags.length ? types.filter((type) => TAGGABLE_ANALYTICS_TYPES.has(type)) : types
}

export function analyticsSourceKey(projectId: string, query: AnalyticsFeedQuery, type: AnalyticsType): string {
    return JSON.stringify([
        projectId,
        query.search.trim(),
        query.createdBy,
        [...query.tags].sort(),
        type,
        query.orderBy ?? '-created_at',
    ])
}

/** Keeps the rows a source's API could not filter itself. */
export function matchesAnalyticsQuery(item: AnalyticsItem, query: AnalyticsFeedQuery): boolean {
    return (
        (!query.createdBy.length || (!!item.createdBy && query.createdBy.includes(item.createdBy.uuid))) &&
        query.tags.every((tag) => item.tags.includes(tag))
    )
}

// Insights file as `insight` or under a subtype such as `insight/trends`, so they match on the prefix.
export function fileSystemTypeParams(type: AnalyticsType): { type?: string; type__startswith?: string } {
    return type === 'insight' ? { type__startswith: 'insight' } : { type }
}

/** One page of a type's rows from the project file system, in the requested order, with the row's space. */
export async function fetchAnalyticsSourcePage(
    _projectId: string,
    type: AnalyticsType,
    query: AnalyticsFeedQuery,
    offset: number
): Promise<AnalyticsSourcePage> {
    const limit = ANALYTICS_FEED_PAGE_SIZE
    // Without the server filter, a person's rows hide among everyone else's and each page brings few of them.
    const search = [query.createdByMe ? 'user:me' : '', query.search.trim()].filter(Boolean).join(' ')
    const result = await api.fileSystem.list({
        ...fileSystemTypeParams(type),
        search: search || undefined,
        orderBy: query.orderBy ?? '-created_at',
        includeTags: true,
        limit,
        offset,
    })
    const items = result.results.flatMap((entry: FileSystemEntry) => {
        const item = fileSystemEntryToAnalytics(entry, result.users ?? [])
        if (!item || !matchesAnalyticsQuery(item, query)) {
            return []
        }
        if (query.orderBy && parseAnalyticsOrderBy(query.orderBy).id === 'last_viewed_at') {
            item.timestamp = entry.last_viewed_at ?? null
        }
        return [item]
    })
    return { items, fetched: result.results.length, hasMore: !!result.next && result.results.length > 0 }
}

export function analyticsTime(item: AnalyticsItem, orderBy?: AnalyticsFeedQuery['orderBy']): number {
    if (!item.timestamp) {
        return -Infinity
    }
    const time = new Date(item.timestamp).getTime()
    return orderBy && !parseAnalyticsOrderBy(orderBy).desc ? -time : time
}

function analyticsItemComesFirst(
    first: AnalyticsItem,
    second: AnalyticsItem,
    orderBy?: AnalyticsFeedQuery['orderBy']
): boolean {
    const firstTime = analyticsTime(first, orderBy)
    const secondTime = analyticsTime(second, orderBy)
    if (firstTime !== secondTime) {
        return firstTime > secondTime
    }
    return new Date(first.createdAt ?? 0).getTime() > new Date(second.createdAt ?? 0).getTime()
}

export function mergeAnalyticsSources(sources: (AnalyticsSourceState | undefined)[]): {
    items: AnalyticsItem[]
    blocking: AnalyticsSourceState[]
} {
    const states = sources.map(
        (source) => source ?? ({ items: [], hasMore: true, initialized: false } as unknown as AnalyticsSourceState)
    )
    const positions = states.map(() => 0)
    const items: AnalyticsItem[] = []
    for (;;) {
        const blocking = states.filter(
            (state, index) => positions[index] >= state.items.length && (state.hasMore || !state.initialized)
        )
        if (blocking.length) {
            return { items, blocking: blocking.filter((state) => sources.includes(state)) }
        }
        let best = -1
        for (let index = 0; index < states.length; index++) {
            if (
                positions[index] < states[index].items.length &&
                (best === -1 ||
                    analyticsItemComesFirst(
                        states[index].items[positions[index]],
                        states[best].items[positions[best]],
                        states[index].query?.orderBy
                    ))
            ) {
                best = index
            }
        }
        if (best === -1) {
            return { items, blocking: [] }
        }
        items.push(states[best].items[positions[best]++])
    }
}

export function analyticsFeedFromSources(sources: (AnalyticsSourceState | undefined)[]): AnalyticsFeed {
    const { items, blocking } = mergeAnalyticsSources(sources)
    const initialized = sources.every((source) => source?.initialized)
    const failed = sources.filter((source): source is AnalyticsSourceState => !!source?.failed)
    return {
        items: initialized ? items : [],
        initialized,
        loading: sources.some((source) => !source || source.loading || source.refreshing),
        hasMore: blocking.length > 0,
        failedTypes: failed.map((source) => source.type),
        // A tag filter on untaggable types leaves no sources at all, which is an empty list and not a failure.
        loadFailed: initialized && sources.length > 0 && failed.length === sources.length && items.length === 0,
    }
}