Skip to main content

Overview

@empathyco/x-types provides comprehensive TypeScript type definitions and interfaces for building search experiences with Interface X. It includes models for requests, responses, facets, results, and all search-related entities.

Installation

npm install @empathyco/x-types

Main Exports

Core Models

Result
interface
Product or content result from search
Facet
interface
Facet definition with filters for refining search results
Filter
interface
Individual filter option within a facet
Banner
interface
Promotional banner in search results
Promoted
interface
Promoted result with special positioning
Suggestion
interface
Query suggestion for autocomplete
HistoryQuery
interface
Historical search query with metadata
Redirection
interface
URL redirection for specific queries

Request Types

SearchRequest
interface
Request parameters for search queries
RecommendationsRequest
interface
Request parameters for recommendations
Request parameters for related tags

Response Types

SearchResponse
interface
Complete search response with results, facets, and metadata
RecommendationsResponse
interface
Recommendations response with suggested items
FacetsResponse
interface
Facets and filters response

Utility Types

Identifiable
interface
Base interface for entities with an ID
NamedModel
interface
Interface for entities with name and model name
Previewable
interface
Interface for items that can show preview results
PartialResult
interface
Partial search result information

Common Type Examples

Result Interface

import type { Result } from '@empathyco/x-types'

interface Result extends Identifiable {
  id: string
  modelName: 'Result'
  name?: string
  description?: string
  images?: string[]
  url?: string
  price?: {
    value: number
    currency?: string
  }
  rating?: {
    value: number
  }
  isWishlisted?: boolean
  // Additional custom fields
  [key: string]: unknown
}

Facet Interface

import type { Facet, Filter } from '@empathyco/x-types'

interface Facet extends Identifiable {
  id: string
  modelName: 'Facet'
  label?: string
  filters: Filter[]
}

interface Filter extends Identifiable {
  id: string
  modelName: string
  facetId: string
  label?: string
  totalResults?: number
  selected: boolean
}

Search Request

import type { SearchRequest } from '@empathyco/x-types'

interface SearchRequest {
  query: string
  rows?: number
  start?: number
  filters?: Record<string, string[]>
  sort?: string
  extraParams?: Record<string, unknown>
}

Search Response

import type { SearchResponse, Result, Facet, Banner } from '@empathyco/x-types'

interface SearchResponse {
  results: Result[]
  facets: Facet[]
  totalResults: number
  banners?: Banner[]
  promoteds?: Result[]
  partialResults?: Result[]
  redirections?: Redirection[]
  spellcheck?: string
  queryTagging?: TaggingInfo
  displayTagging?: TaggingInfo
}

Type Guards

The package includes type guard functions:
import { isFacetFilter, isHierarchicalFilter } from '@empathyco/x-types'

if (isFacetFilter(filter)) {
  // TypeScript knows filter has facetId property
  console.log(filter.facetId)
}

if (isHierarchicalFilter(filter)) {
  // TypeScript knows filter has children property
  console.log(filter.children)
}

AI Models

AIQueryMetadata
interface
Metadata for AI-powered queries
AIResponse
interface
Response format for AI features

Tagging Models

TaggingRequest
interface
Request format for tracking events
TaggingInfo
interface
Tagging information included in responses

User Info

import type { UserInfo } from '@empathyco/x-types'

interface UserInfo {
  userId?: string
  sessionId?: string
  [key: string]: unknown
}

Sort Model

import type { Sort } from '@empathyco/x-types'

type Sort = string

Stats Model

import type { Stats } from '@empathyco/x-types'

interface Stats {
  queryTime?: number
  totalTime?: number
  numFound?: number
}

Using with X Components

import { defineComponent } from 'vue'
import type { Result, Facet } from '@empathyco/x-types'
import type { SearchState } from '@empathyco/x-components'

export default defineComponent({
  computed: {
    results(): Result[] {
      return this.$store.state.x.search.results
    },
    facets(): Facet[] {
      return this.$store.state.x.facets.facets
    }
  }
})

Adapter Integration

import type { SearchRequest, SearchResponse } from '@empathyco/x-types'
import { endpointAdapterFactory } from '@empathyco/x-adapter'

const searchAdapter = endpointAdapterFactory<SearchRequest, SearchResponse>({
  endpoint: '/api/search',
  requestMapper: (request) => ({
    q: request.query,
    size: request.rows || 24,
    filters: request.filters
  }),
  responseMapper: (response) => ({
    results: response.results,
    facets: response.facets,
    totalResults: response.totalResults
  })
})

X Components Adapter

import type { XComponentsAdapter } from '@empathyco/x-types'

interface XComponentsAdapter {
  search: EndpointAdapter<SearchRequest, SearchResponse>
  recommendations: EndpointAdapter<RecommendationsRequest, RecommendationsResponse>
  relatedTags: EndpointAdapter<RelatedTagsRequest, RelatedTagsResponse>
  // ... other endpoints
}

Custom Extensions

Extend types for your use case:
import type { Result } from '@empathyco/x-types'

interface CustomResult extends Result {
  availability: 'in_stock' | 'out_of_stock'
  brand: string
  categories: string[]
  customField: string
}

Dependencies

The package depends on:
  • @empathyco/x-adapter - Adapter interfaces
  • @empathyco/x-utils - Utility types

Resources

GitHub Repository

View source code and type definitions

TypeScript Documentation

Learn more about TypeScript

Build docs developers (and LLMs) love