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.

18.4 KB
Raw Blame
export type FilterKey = 'is' | 'createdBy' | 'in' | 'name'

export interface FilterDefinition {
    key: FilterKey
    aliases: string[]
    description: string
    /** Field name the file system search endpoint understands. */
    backendField: 'type' | 'user' | 'path' | 'name'
    /** Whether a value that matches no suggestion is still a valid filter. */
    freeTextValues: boolean
}

export const FILTER_DEFINITIONS: FilterDefinition[] = [
    {
        key: 'is',
        aliases: ['type'],
        description: 'Type, such as dashboard or feature flag',
        backendField: 'type',
        freeTextValues: false,
    },
    {
        key: 'createdBy',
        aliases: ['by', 'author', 'user'],
        description: 'Who created it',
        backendField: 'user',
        freeTextValues: true,
    },
    {
        key: 'in',
        aliases: ['path', 'folder'],
        description: 'Folder it lives in',
        backendField: 'path',
        freeTextValues: true,
    },
    {
        key: 'name',
        aliases: ['title'],
        description: 'Name only, not description',
        backendField: 'name',
        freeTextValues: true,
    },
]

export const MAX_FILTER_KEY_ROWS = 3

export interface ValueOption {
    value: string
    label: string
    /** Extra words a person can type to reach this option, matched by prefix. */
    aliases?: string[]
    /** Icon type for the row, such as a file system type. */
    iconType?: string
}

export interface QueryChip {
    key: FilterKey
    value: string
    label: string
    negated: boolean
}

export interface QueryToken {
    raw: string
    start: number
    end: number
}

export interface ParsedToken {
    negated: boolean
    /** Set only when the token is `key:` with a known key or alias. */
    filter: FilterDefinition | null
    /** Text before the colon, or the whole token without its `-` when there is no colon. */
    keyText: string
    hasColon: boolean
    /** Value after the colon, with surrounding quotes removed. */
    value: string
}

export type CursorContext =
    | { kind: 'empty' }
    | { kind: 'key'; token: QueryToken; partial: string; negated: boolean; matches: FilterDefinition[] }
    | { kind: 'value'; token: QueryToken; filter: FilterDefinition; partial: string; negated: boolean }
    | { kind: 'text'; token: QueryToken | null }

const lower = (value: string): string => value.toLowerCase()

/** Splits on whitespace outside double quotes. An unclosed quote runs to the end of the text. */
export function tokenize(text: string): QueryToken[] {
    const tokens: QueryToken[] = []
    let start = -1
    let inQuote = false
    for (let i = 0; i <= text.length; i++) {
        const char = text[i]
        const atEnd = i === text.length
        if (!atEnd && char === '"') {
            inQuote = !inQuote
        }
        const isBoundary = atEnd || (!inQuote && /\s/.test(char))
        if (isBoundary) {
            if (start !== -1) {
                tokens.push({ raw: text.slice(start, i), start, end: i })
                start = -1
            }
        } else if (start === -1) {
            start = i
        }
    }
    return tokens
}

export function resolveFilterKey(name: string): FilterDefinition | null {
    const needle = lower(name)
    return (
        FILTER_DEFINITIONS.find(
            (definition) => lower(definition.key) === needle || definition.aliases.some((alias) => alias === needle)
        ) ?? null
    )
}

export function unquote(value: string): string {
    let result = value
    if (result.startsWith('"')) {
        result = result.slice(1)
    }
    if (result.endsWith('"')) {
        result = result.slice(0, -1)
    }
    return result
}

export function parseToken(raw: string): ParsedToken {
    const negated = raw.length > 1 && raw.startsWith('-')
    const body = negated ? raw.slice(1) : raw
    const colonIndex = body.indexOf(':')
    if (colonIndex === -1) {
        return { negated, filter: null, keyText: body, hasColon: false, value: '' }
    }
    const keyText = body.slice(0, colonIndex)
    return {
        negated,
        filter: resolveFilterKey(keyText),
        keyText,
        hasColon: true,
        value: unquote(body.slice(colonIndex + 1)),
    }
}

/** Filter definitions whose key or alias starts with the partial text, at most `MAX_FILTER_KEY_ROWS`. */
export function matchFilterKeys(partial: string): FilterDefinition[] {
    const needle = lower(partial)
    if (!needle) {
        return []
    }
    return FILTER_DEFINITIONS.filter(
        (definition) =>
            lower(definition.key).startsWith(needle) || definition.aliases.some((alias) => alias.startsWith(needle))
    ).slice(0, MAX_FILTER_KEY_ROWS)
}

export function tokenAtCursor(text: string, cursor: number): QueryToken | null {
    return tokenize(text).find((token) => token.start <= cursor && cursor <= token.end) ?? null
}

export function getCursorContext(text: string, cursor: number, chips: QueryChip[]): CursorContext {
    if (text.trim() === '' && chips.length === 0) {
        return { kind: 'empty' }
    }
    const token = tokenAtCursor(text, cursor)
    if (!token) {
        return { kind: 'text', token: null }
    }
    const parsed = parseToken(token.raw)
    if (parsed.filter) {
        return { kind: 'value', token, filter: parsed.filter, partial: parsed.value, negated: parsed.negated }
    }
    if (!parsed.hasColon) {
        const matches = matchFilterKeys(parsed.keyText)
        if (matches.length > 0) {
            return { kind: 'key', token, partial: parsed.keyText, negated: parsed.negated, matches }
        }
    }
    return { kind: 'text', token }
}

/** Prefix matches on the label, value, or an alias first, then matches inside a word when allowed. */
export function matchValueOptions(
    options: ValueOption[],
    partial: string,
    { allowSubstring }: { allowSubstring: boolean }
): ValueOption[] {
    const needle = lower(partial)
    if (!needle) {
        return options
    }
    const prefix: ValueOption[] = []
    const substring: ValueOption[] = []
    for (const option of options) {
        const starts = [option.label, option.value, ...(option.aliases ?? [])].map(lower)
        if (starts.some((word) => word.startsWith(needle))) {
            prefix.push(option)
        } else if (allowSubstring && starts.some((word) => word.includes(needle))) {
            substring.push(option)
        }
    }
    return [...prefix, ...substring]
}

/** The exact option a typed value names, if any. */
export function findExactOption(options: ValueOption[], value: string): ValueOption | null {
    const needle = lower(value)
    return (
        options.find(
            (option) =>
                lower(option.value) === needle ||
                lower(option.label) === needle ||
                (option.aliases ?? []).some((alias) => lower(alias) === needle)
        ) ?? null
    )
}

/**
 * The option a fully typed value commits to without a Space: it names the option exactly and no
 * other option starts with it, so typing more could not mean something else.
 */
export function unambiguousOption(options: ValueOption[], value: string): ValueOption | null {
    const exact = findExactOption(options, value)
    if (!exact) {
        return null
    }
    const needle = lower(value)
    const othersStartWith = options.some(
        (option) =>
            option !== exact &&
            [option.label, option.value, ...(option.aliases ?? [])].some((word) => lower(word).startsWith(needle))
    )
    return othersStartWith ? null : exact
}

/** Turns a typed `key:value` into a chip, or returns null when the value is not valid for that key. */
export function resolveChip(
    filter: FilterDefinition,
    value: string,
    negated: boolean,
    options: ValueOption[]
): QueryChip | null {
    const trimmed = value.trim()
    if (!trimmed) {
        return null
    }
    const exact = findExactOption(options, trimmed)
    if (exact) {
        return { key: filter.key, value: exact.value, label: exact.label, negated }
    }
    if (filter.freeTextValues) {
        return { key: filter.key, value: trimmed, label: trimmed, negated }
    }
    return null
}

export function chipId(chip: Pick<QueryChip, 'key' | 'value' | 'negated'>): string {
    return `${chip.negated ? '-' : ''}${chip.key}:${chip.value}`
}

/** Each key holds one chip. A new value for a key replaces the old chip in place. */
export function addChip(chips: QueryChip[], chip: QueryChip): QueryChip[] {
    const index = chips.findIndex((existing) => existing.key === chip.key)
    if (index === -1) {
        return [...chips, chip]
    }
    return chips.map((existing, i) => (i === index ? chip : existing))
}

const quoteIfNeeded = (value: string): string => (/\s/.test(value) ? `"${value}"` : value)

/** The editable text a chip turns back into. */
export function chipToText(chip: QueryChip): string {
    return `${chip.negated ? '-' : ''}${chip.key}:${quoteIfNeeded(chip.value)}`
}

export function filterDefinition(key: FilterKey): FilterDefinition {
    return FILTER_DEFINITIONS.find((definition) => definition.key === key) as FilterDefinition
}

const backendToken = (key: FilterKey, value: string, negated: boolean): string =>
    `${negated ? '-' : ''}${filterDefinition(key).backendField}:${quoteIfNeeded(value)}`

/** Removes a token from the text and returns the new text and where the cursor lands. */
export function removeToken(text: string, token: QueryToken): { text: string; cursor: number } {
    const before = text.slice(0, token.start).replace(/\s+$/, '')
    const after = text.slice(token.end).replace(/^\s+/, '')
    const joined = before && after ? `${before} ${after}` : before || after
    const cursor = before ? before.length + (after ? 1 : 0) : 0
    return { text: joined, cursor }
}

/** Replaces a token with new text and puts the cursor at the end of the replacement. */
export function replaceToken(text: string, token: QueryToken, replacement: string): { text: string; cursor: number } {
    return {
        text: text.slice(0, token.start) + replacement + text.slice(token.end),
        cursor: token.start + replacement.length,
    }
}

/** The values each filter key can suggest. Free-text keys may have none. */
export type FilterOptions = Record<FilterKey, ValueOption[]>

/** Moves every complete, valid filter token in the text into chips. Used for pasted queries. */
export function extractChips(
    text: string,
    chips: QueryChip[],
    options: FilterOptions
): { text: string; chips: QueryChip[] } {
    let nextChips = chips
    const remaining: string[] = []
    for (const token of tokenize(text)) {
        const parsed = parseToken(token.raw)
        const chip = parsed.filter
            ? resolveChip(parsed.filter, parsed.value, parsed.negated, options[parsed.filter.key])
            : null
        if (chip) {
            nextChips = addChip(nextChips, chip)
        } else {
            remaining.push(token.raw)
        }
    }
    return { text: remaining.join(' '), chips: nextChips }
}

export interface ResolvedQuery {
    /** The filters in effect: the chips, with a valid `key:value` still in the text standing in for that key's chip. */
    filters: QueryChip[]
    /** The text that is not a filter token. */
    freeText: string
    /** The `search` string for the file system endpoint. */
    backendSearch: string
}

function shellWords(text: string, quotes: string): string[] | null {
    const words: string[] = []
    let word: string | null = null
    let quote: string | null = null
    for (let i = 0; i < text.length; i++) {
        const char = text[i]
        if (quote) {
            if (char === quote) {
                quote = null
            } else if (char === '\\' && quote === '"' && (text[i + 1] === '"' || text[i + 1] === '\\')) {
                word += text[++i]
            } else {
                word += char
            }
        } else if (/\s/.test(char)) {
            if (word !== null) {
                words.push(word)
                word = null
            }
        } else if (quotes.includes(char)) {
            word ??= ''
            quote = char
        } else if (char === '\\') {
            if (i + 1 === text.length) {
                return null
            }
            word = (word ?? '') + text[++i]
        } else {
            word = (word ?? '') + char
        }
    }
    if (quote) {
        return null
    }
    if (word !== null) {
        words.push(word)
    }
    return words
}

// Mirrors `tokenize_search` in posthog/api/file_system/file_system.py, which reads every `'` as a letter once one is unmatched.
function tokenizeSearch(text: string): string[] {
    return shellWords(text, `"'`) ?? shellWords(text, '"') ?? text.split(/\s+/).filter(Boolean)
}

/**
 * Resolves the input once per change, so every consumer agrees on what applies. A typed value
 * previews what committing it would do, so `createdBy:Ca` narrows results before it is committed.
 * Filters come first in `backendSearch`, sorted, so the same query typed in another order hits the
 * same cache entry.
 */
export function resolveQuery(text: string, chips: QueryChip[], options: FilterOptions): ResolvedQuery {
    const filters = new Map<FilterKey, QueryChip>(chips.map((chip) => [chip.key, chip]))
    const freeTokens: string[] = []
    for (const token of tokenize(text)) {
        const parsed = parseToken(token.raw)
        if (!parsed.filter) {
            freeTokens.push(token.raw)
            continue
        }
        const chip = resolveChip(parsed.filter, parsed.value, parsed.negated, options[parsed.filter.key])
        if (chip) {
            filters.set(chip.key, chip)
        }
    }
    const filterTokens = [...filters.values()].map((chip) => backendToken(chip.key, chip.value, chip.negated)).sort()
    return {
        filters: [...filters.values()],
        freeText: freeTokens.join(' '),
        backendSearch: [...filterTokens, ...freeTokens].join(' '),
    }
}

const isQuotedBy = (text: string, quote: string): boolean => text.startsWith(quote) && text.endsWith(quote)
const stripQuotes = (text: string): string =>
    isQuotedBy(text, '"') || isQuotedBy(text, "'") ? text.slice(1, -1) : text

const BACKEND_FILTER_FIELDS = new Set(['path', 'name', 'user', 'author', 'type', 'ref'])

// Reads `backendSearch` like the file system search does, so the list searches the words Cmd+K matched.
// List pages match one phrase, which cannot exclude, so excluded words and filters other than `name:` stay out.
interface SearchTerms {
    words: string[]
    freeWords: string[]
    name: string | null
    excludes: boolean
}

function searchTerms(backendSearch: string): SearchTerms {
    const terms: SearchTerms = { words: [], freeWords: [], name: null, excludes: false }
    for (const raw of tokenizeSearch(backendSearch)) {
        if (raw.startsWith('-') || raw.startsWith('!')) {
            terms.excludes ||= raw.length > 1
            continue
        }
        const token = stripQuotes(raw)
        const colonIndex = token.indexOf(':')
        const field = colonIndex === -1 ? null : token.slice(0, colonIndex).toLowerCase()
        if (field === 'name') {
            terms.name = stripQuotes(token.slice(colonIndex + 1).trim())
            terms.words.push(terms.name)
        } else if (field === null || !BACKEND_FILTER_FIELDS.has(field)) {
            terms.words.push(token)
            terms.freeWords.push(token)
        }
    }
    return terms
}

export function listSearchText({ backendSearch }: Pick<ResolvedQuery, 'backendSearch'>): string {
    return searchTerms(backendSearch).words.filter(Boolean).join(' ')
}

export interface TypeSearchTerms {
    text: string
    name: string | null
    freeText: string
    excludes: boolean
}

export function typeSearchTerms({ backendSearch }: Pick<ResolvedQuery, 'backendSearch'>): TypeSearchTerms {
    const { words, freeWords, name, excludes } = searchTerms(backendSearch)
    return {
        text: words.filter(Boolean).join(' '),
        name: name || null,
        freeText: freeWords.filter(Boolean).join(' '),
        excludes,
    }
}

/** The raw query as a person would type it, chips included. Used when copying the input. */
export function queryAsText(text: string, chips: QueryChip[]): string {
    return [...chips.map(chipToText), text.trim()].filter(Boolean).join(' ')
}

export interface InputEdit {
    previousText: string
    previousCursor: number
    text: string
    cursor: number
}

const typedSpaceAt = (edit: InputEdit): boolean =>
    edit.cursor === edit.previousCursor + 1 &&
    edit.text[edit.previousCursor] === ' ' &&
    edit.text.slice(0, edit.previousCursor) + edit.text.slice(edit.cursor) === edit.previousText

/**
 * A space typed at the start or after another space separates nothing. It mostly follows a value
 * that already committed on its last letter, so it is dropped rather than left as stray text.
 */
export function isRedundantSpace(edit: InputEdit): boolean {
    return typedSpaceAt(edit) && (edit.previousCursor === 0 || /\s/.test(edit.previousText[edit.previousCursor - 1]))
}

/**
 * The chip an edit commits, as if its suggestion were picked: a space typed right after a valid
 * `key:value`, or a value that names exactly one option. Returns the token to remove from `text`.
 */
export function chipCommittedByEdit(
    edit: InputEdit,
    chips: QueryChip[],
    options: FilterOptions
): { chip: QueryChip; token: QueryToken; via: 'space' | 'typed' } | null {
    const { previousText, previousCursor, text, cursor } = edit
    const typedSpace = typedSpaceAt(edit)
    const context = typedSpace
        ? getCursorContext(previousText, previousCursor, chips)
        : getCursorContext(text, cursor, chips)
    const end = typedSpace ? previousCursor : cursor
    if (context.kind !== 'value' || context.token.end !== end) {
        return null
    }
    // A value inside an open quote is still being typed, whether the edit is a space or a letter.
    const rawValue = context.token.raw.slice(context.token.raw.indexOf(':') + 1)
    if (rawValue.startsWith('"') && (rawValue.length === 1 || !rawValue.endsWith('"'))) {
        return null
    }
    if (!typedSpace) {
        const option = unambiguousOption(options[context.filter.key], context.partial)
        return option
            ? {
                  chip: { key: context.filter.key, value: option.value, label: option.label, negated: context.negated },
                  token: context.token,
                  via: 'typed',
              }
            : null
    }
    const chip = resolveChip(context.filter, context.partial, context.negated, options[context.filter.key])
    return chip ? { chip, token: context.token, via: 'space' } : null
}