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.1 KB
Raw Blame
import { TaxonomicFilterGroupType } from 'lib/components/TaxonomicFilter/types'
import { surveyQuestionLabelsLogic } from 'scenes/surveys/surveyQuestionLabelsLogic'

import { CoreFilterDefinition, PropertyDefinition, PropertyType } from '~/types'

import { CORE_FILTER_DEFINITIONS_BY_GROUP, CoreFilterDefinitionsGroup } from './taxonomy'

/** Return whether a given filter key is part of PostHog's core (marked by the PostHog logo). */

const hasCoreFilterDefinitionsForGroup = (
    type: TaxonomicFilterGroupType
): Record<string, CoreFilterDefinition> | null =>
    type in CORE_FILTER_DEFINITIONS_BY_GROUP
        ? CORE_FILTER_DEFINITIONS_BY_GROUP[type as CoreFilterDefinitionsGroup]
        : null

export function isCoreFilter(key: string): boolean {
    return Object.values(CORE_FILTER_DEFINITIONS_BY_GROUP).some((mapping) => Object.keys(mapping).includes(key))
}

export type PropertyKey = string | null | undefined

export function getCoreFilterDefinition(
    value: string | null | undefined,
    type: TaxonomicFilterGroupType
): CoreFilterDefinition | null {
    if (value == undefined) {
        return null
    }

    value = value.toString()
    const isGroupTaxonomicFilterType = type.startsWith('groups_')
    const groupDefinitions = hasCoreFilterDefinitionsForGroup(type)
    if (groupDefinitions && value in groupDefinitions) {
        return { ...groupDefinitions[value] }
    } else if (
        isGroupTaxonomicFilterType &&
        value in CORE_FILTER_DEFINITIONS_BY_GROUP[TaxonomicFilterGroupType.GroupsPrefix]
    ) {
        return { ...CORE_FILTER_DEFINITIONS_BY_GROUP[TaxonomicFilterGroupType.GroupsPrefix][value] }
    } else if (value.startsWith('$survey_responded/')) {
        const surveyId = value.replace(/^\$survey_responded\//, '')
        if (surveyId) {
            return {
                label: `Survey Responded: ${surveyId}`,
                description: `Whether the user responded to survey with ID: "${surveyId}".`,
            }
        }
    } else if (value.startsWith('$survey_dismissed/')) {
        const surveyId = value.replace(/^\$survey_dismissed\//, '')
        if (surveyId) {
            return {
                label: `Survey Dismissed: ${surveyId}`,
                description: `Whether the user dismissed survey with ID: "${surveyId}".`,
            }
        }
    } else if (value.startsWith('$survey_response_')) {
        const suffix = value.replace(/^\$survey_response_/, '')
        if (suffix) {
            // If `surveyQuestionLabelsLogic` is mounted (a `PropertyKeyInfo` for any
            // survey response key triggers the mount, which auto-loads the slim labels
            // endpoint), prefer the actual question text. This branch covers every
            // call site — `PropertyKeyInfo`, the property definitions popover, chart
            // legends, breakdown labels, the admin definitions page — so all of them
            // benefit once the labels have loaded.
            const resolved = surveyQuestionLabelsLogic.findMounted()?.values.surveyQuestionLabels?.[suffix]
            if (resolved) {
                return {
                    label: `${resolved.questionText} · ${resolved.surveyName}`,
                    description: `Response to "${resolved.questionText}" in survey "${resolved.surveyName}".`,
                }
            }
            const parsedIndex = Number(suffix)
            if (Number.isInteger(parsedIndex) && parsedIndex >= 0) {
                const index = parsedIndex + 1
                const ordinal = index === 1 ? 'st' : index === 2 ? 'nd' : index === 3 ? 'rd' : 'th'
                return {
                    label: `Survey response for ${index}${ordinal} question`,
                    description: `The response value for the ${index}${ordinal} question in the survey.`,
                }
            }
            // Modern format `$survey_response_<question-uuid>`, but the labels haven't
            // loaded yet (or this consumer doesn't subscribe so it won't re-render
            // when they do). Emit a generic short-ID label as a placeholder.
            const shortId = suffix.slice(0, 8)
            return {
                label: `Survey response (${shortId}…)`,
                description: `Response for survey question with ID "${suffix}".`,
            }
        }
    } else if (value.startsWith('$feature/')) {
        const featureFlagKey = value.replace(/^\$feature\//, '')
        if (featureFlagKey) {
            return {
                label: `Feature: ${featureFlagKey}`,
                description: `Value for the feature flag "${featureFlagKey}" when this event was sent.`,
                examples: ['true', 'variant-1a'],
            }
        }
    } else if (value.startsWith('$feature_enrollment/')) {
        const featureFlagKey = value.replace(/^\$feature_enrollment\//, '')
        if (featureFlagKey) {
            return {
                label: `Feature Enrollment: ${featureFlagKey}`,
                description: `Whether the user has opted into the "${featureFlagKey}" beta program.`,
                examples: ['true', 'false'],
            }
        }
    } else if (value.startsWith('$feature_interaction/')) {
        const featureFlagKey = value.replace(/^\$feature_interaction\//, '')
        if (featureFlagKey) {
            return {
                label: `Feature Interaction: ${featureFlagKey}`,
                description: `Whether the user has interacted with "${featureFlagKey}".`,
                examples: ['true', 'false'],
            }
        }
    }
    return null
}

/** Prefix of the synthetic ids the property definitions API gives virtual (query-time computed) properties. */
export const VIRTUAL_PROPERTY_DEFINITION_ID_PREFIX = '$builtin_'

const VIRTUAL_PROPERTY_DEFINITION_GROUPS = [
    TaxonomicFilterGroupType.EventProperties,
    TaxonomicFilterGroupType.PersonProperties,
    TaxonomicFilterGroupType.GroupsPrefix,
]

export interface VirtualPropertyDefinitionMatch {
    definition: PropertyDefinition
    /** The taxonomy group the definition was resolved from; use it for label/description lookups so they can't disagree. */
    group: TaxonomicFilterGroupType
}

/** Virtual properties have no database row, so their definition is built from the taxonomy. */
export function getVirtualPropertyDefinition(id: string): VirtualPropertyDefinitionMatch | null {
    if (!id.startsWith(VIRTUAL_PROPERTY_DEFINITION_ID_PREFIX)) {
        return null
    }
    const name = id.slice(VIRTUAL_PROPERTY_DEFINITION_ID_PREFIX.length)
    for (const group of VIRTUAL_PROPERTY_DEFINITION_GROUPS) {
        const coreDefinition = getCoreFilterDefinition(name, group)
        if (coreDefinition?.virtual) {
            return {
                definition: {
                    id,
                    name,
                    description:
                        typeof coreDefinition.description === 'string' ? coreDefinition.description : undefined,
                    is_numerical: coreDefinition.type === PropertyType.Numeric,
                    property_type: coreDefinition.type,
                    verified: false,
                    hidden: false,
                    virtual: true,
                },
                group,
            }
        }
    }
    return null
}

export function getFirstFilterTypeFor(propertyKey: string): TaxonomicFilterGroupType | null {
    for (const type of Object.keys(CORE_FILTER_DEFINITIONS_BY_GROUP) as CoreFilterDefinitionsGroup[]) {
        if (propertyKey in CORE_FILTER_DEFINITIONS_BY_GROUP[type]) {
            return type as TaxonomicFilterGroupType
        }
    }
    return null
}

export function getFilterLabel(key: PropertyKey, type: TaxonomicFilterGroupType): string {
    const data = getCoreFilterDefinition(key, type)
    return (data ? data.label : key)?.trim() ?? '(empty string)'
}

export function getPropertyKey(value: string, type: TaxonomicFilterGroupType): string {
    // Find the key by looking through the mapping
    const group = hasCoreFilterDefinitionsForGroup(type)
    if (group) {
        const foundKey = Object.entries(group).find(([_, def]) => (def as any).label === value || _ === value)?.[0]
        return foundKey || value
    }
    return value
}