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
Product or content result from search
Facet definition with filters for refining search results
Individual filter option within a facet
Promotional banner in search results
Promoted result with special positioning
Query suggestion for autocomplete
Historical search query with metadata
URL redirection for specific queries
Request Types
Request parameters for search queries
Request parameters for recommendations
Request parameters for related tags
Response Types
Complete search response with results, facets, and metadata
Recommendations response with suggested items
Facets and filters response
Utility Types
Base interface for entities with an ID
Interface for entities with name and model name
Interface for items that can show preview results
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
Metadata for AI-powered queries
Response format for AI features
Tagging Models
Request format for tracking events
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