Search Types & Interfaces

This document provides comprehensive TypeScript interface definitions for the Search management system. These types ensure type safety and consistency across all search-related operations.

Core Search Types

Search Request Types

// Main search request interface
interface SearchProductsRequest {
  locale?: string;
  filters?: SearchFilters;
  pageable?: Pageable;
  includeFacets?: boolean;
}

// Autocomplete request interface
interface AutocompleteProductsRequest {
  input: string;
  locale?: string;
  currency?: string;
  pageable?: Pageable;
  aggregation?: AggregationType;
  productTags?: string[];
}

// Search filters configuration
interface SearchFilters {
  currency?: string;
  locale?: string;
  brand?: string[];
  attributes?: string[];
  productTags?: string[];
  suppliers?: string[];
  aggregation?: AggregationType;
  query?: string;
  categoryIds?: string[];
  priceRange?: PriceRange;
}

Search Response Types

// Main search response interface
interface SearchProductsResponse {
  success: boolean;
  products: ProductsSearchList;
  facets?: Facets;
  includeFacets: boolean;
}

// Autocomplete response (inferred)
interface AutocompleteResponse {
  success: boolean;
  products: ProductSearchContent[];
}

// Paginated products list
interface ProductsSearchList {
  content: ProductSearchContent[];
  pageable: Pageable;
  totalElements: number;
  totalPages: number;
  size: number;
  number: number;
  first: boolean;
  last: boolean;
  empty?: boolean;
}

Product Search Content Types

Core Product Data

// Main search result item
interface ProductSearchContent {
  offerPrice: OfferPriceSearch;
  offer: OfferSearch;
  variant: VariantSearch;
  product: ProductSearch;
  attributes: AttributeSearch[];
  supplier: SupplierSearch;
}

// Basic product information
interface ProductSearch {
  id: string;
  externalId: string;
  sku: string;
  name: string;
  description: string | null;
  brand: string | null;
  mainPictureUrl: string | null;
  tags: ProductTag[];
  unit: string | null;
}

// Product variant details
interface VariantSearch {
  id: string;
  externalId: string;
  sku: string;
  name: string;
  description: string | null;
  pictureUrls: PictureUrl[];
  ean: string;
  mpn: string | null;
}

Pricing and Availability Types

// Offer pricing information
interface OfferPriceSearch {
  unitPrice: number;
  currency: string;
  taxIncluded: boolean;
  discountedPrice?: number;
  discountPercentage?: number;
}

// Offer details and availability
interface OfferSearch {
  id: string;
  externalId: string;
  quantityPerItem: number;
  stock: number;
  currency: string;
  packingType: string | null;
  productUnit: string | null;
  maxOrderQuantity: number | null;
  minOrderQuantity: number;
  minStockAlert: number;
  minShippingPrice: number;
  leadTimeToShip: number | null;
  customFields: CustomField[];
}

// Price range for filtering
interface PriceRange {
  min?: number;
  max?: number;
  currency?: string;
}

Attribute and Supplier Types

// Product attribute information
interface AttributeSearch {
  name: string;
  externalId: string;
  value: string;
  values: string[];
}

// Supplier information
interface SupplierSearch {
  id: string;
  name: string;
  externalId: string;
}

// Product tags
interface ProductTag {
  name: string;
  category?: string;
  id?: string;
}

Faceting and Navigation Types

Facet Structure Types

// Main facets container
interface Facets {
  attributes: AttributeFacet[];
  suppliers?: SupplierFacet[];
  brands?: BrandFacet[];
  productTags?: ProductTagFacet[];
  customFields?: CustomFieldFacet[];
  priceRange?: PriceRangeFacet;
}

// Attribute faceting
interface AttributeFacet {
  id: string;
  name: string;
  values: AttributeValueFacet[];
}

interface AttributeValueFacet {
  value: string;
  count: number;
  selected: boolean;
}

// Brand faceting
interface BrandFacet {
  name: string;
  count: number;
  selected: boolean;
}

// Supplier faceting
interface SupplierFacet {
  id: string;
  name: string;
  count: number;
  selected: boolean;
}

// Product tag faceting
interface ProductTagFacet {
  id: string;
  name: string;
  count: number;
  selected: boolean;
}

Advanced Faceting Types

// Custom field faceting
interface CustomFieldFacet {
  name: string;
  values: CustomFieldValueFacet[];
}

interface CustomFieldValueFacet {
  value: string;
  count: number;
  selected: boolean;
}

// Price range faceting
interface PriceRangeFacet {
  min: number;
  max: number;
  currency: string;
  distribution: PriceDistribution[];
}

interface PriceDistribution {
  range: string;
  count: number;
  min?: number;
  max?: number;
}

Utility and Configuration Types

Pagination Types

// Pagination configuration
interface Pageable {
  page?: number;
  size?: number;
  sort?: string[];
}

// Sort direction enum
enum SortDirection {
  ASC = "ASC",
  DESC = "DESC",
}

// Sort field configuration
interface SortField {
  field: string;
  direction: SortDirection;
}

Media and Content Types

// Picture URL information
interface PictureUrl {
  url: string;
  width?: number;
  height?: number;
  alt?: string;
}

// Custom field definition
interface CustomField {
  id: string;
  name: string;
  value: any;
  type: CustomFieldType;
}

enum CustomFieldType {
  TEXT = "TEXT",
  NUMBER = "NUMBER",
  BOOLEAN = "BOOLEAN",
  DATE = "DATE",
  LIST = "LIST",
}

Enums and Constants

Search Configuration Enums

// Aggregation type for search results
enum AggregationType {
  PRODUCT = "PRODUCT",
  VARIANT = "VARIANT",
  OFFER = "OFFER",
}

// Search sort fields
enum SearchSortField {
  RELEVANCE = "relevance",
  NAME = "name",
  PRICE = "price",
  BRAND = "brand",
  STOCK = "stock",
  CREATED_DATE = "createdDate",
  UPDATED_DATE = "updatedDate",
}

// Search filter types
enum FilterType {
  TEXT = "TEXT",
  ATTRIBUTE = "ATTRIBUTE",
  BRAND = "BRAND",
  SUPPLIER = "SUPPLIER",
  TAG = "TAG",
  PRICE_RANGE = "PRICE_RANGE",
  CATEGORY = "CATEGORY",
}

Composable Types

Search Composable Interface

// Main useSearchProduct interface
interface UseSearchProduct {
  // API functions
  autoCompleteSearchProducts: (
    params: AutocompleteProductsRequest
  ) => Promise<ProductSearchContent[]>;
  getProductsList: (
    params: SearchProductsRequest
  ) => Promise<SearchProductsResponse>;

  // Getter functions
  getOfferPrice: (product: ProductSearchContent) => OfferPriceSearch;
  getOffer: (product: ProductSearchContent) => OfferSearch;
  getVariant: (product: ProductSearchContent) => VariantSearch;
  getProductDetails: (product: ProductSearchContent) => ProductSearch;
  getSupplier: (product: ProductSearchContent) => SupplierSearch;
  getAttributes: (product: ProductSearchContent) => AttributeSearch[];
  getPictureUrls: (product: ProductSearchContent) => PictureUrl[];
  getMainPictureUrl: (product: ProductSearchContent) => PictureUrl[];
  getProductId: (product: ProductSearchContent) => string;
  getProductSku: (product: ProductSearchContent) => string;
  getProductExternalId: (product: ProductSearchContent) => string;
  getProductName: (product: ProductSearchContent) => string;
  getProductDescription: (product: ProductSearchContent) => string | null;
  getProductBrand: (product: ProductSearchContent) => string | null;
  getProductTags: (product: ProductSearchContent) => any[];
  getMainProductPictureUrl: (product: ProductSearchContent) => string | null;
  getProductVariantName: (product: ProductSearchContent) => string;
  getProductsPaginated: (
    searchResponse: SearchProductsResponse
  ) => ProductsSearchList;
  getProductsContent: (
    searchResponse: SearchProductsResponse
  ) => ProductSearchContent[];
  getOfferUnitPrice: (product: ProductSearchContent) => number;
  getOfferMinQuantity: (product: ProductSearchContent) => number;
  getOfferMaxQuantity: (product: ProductSearchContent) => number;
  getOfferStock: (product: ProductSearchContent) => number;
  getOfferQuantityPerPack: (product: ProductSearchContent) => number;

  // Helper functions
  getAttributeValueByName: (
    product: ProductSearchContent,
    attributeName: string
  ) => unknown;
  getAttributeValuesByExternalId: (
    product: ProductSearchContent,
    attributeExternalId: string
  ) => unknown;
  getFacets: (searchResponse: SearchProductsResponse) => unknown;
  getOfferCustomFieldValueByExternalId: (
    product: ProductSearchContent,
    externalId: string
  ) => unknown;
}

Component Helper Types

// Search API interface
interface SearchProductApi {
  autoCompleteSearchProducts: (
    params: AutocompleteProductsRequest
  ) => Promise<ProductSearchContent[]>;
  getProductsList: (
    params: SearchProductsRequest
  ) => Promise<SearchProductsResponse>;
}

// Search getters interface
interface SearchProductGetters {
  getOfferPrice: (product: ProductSearchContent) => OfferPriceSearch;
  getOffer: (product: ProductSearchContent) => OfferSearch;
  getVariant: (product: ProductSearchContent) => VariantSearch;
  getProductDetails: (product: ProductSearchContent) => ProductSearch;
  getSupplier: (product: ProductSearchContent) => SupplierSearch;
  getAttributes: (product: ProductSearchContent) => AttributeSearch[];
  getPictureUrls: (product: ProductSearchContent) => PictureUrl[];
  getMainPictureUrl: (product: ProductSearchContent) => PictureUrl[];
  getProductId: (product: ProductSearchContent) => string;
  getProductSku: (product: ProductSearchContent) => string;
  getProductExternalId: (product: ProductSearchContent) => string;
  getProductName: (product: ProductSearchContent) => string;
  getProductDescription: (product: ProductSearchContent) => string | null;
  getProductBrand: (product: ProductSearchContent) => string | null;
  getProductTags: (product: ProductSearchContent) => any[];
  getMainProductPictureUrl: (product: ProductSearchContent) => string | null;
  getProductVariantName: (product: ProductSearchContent) => string;
  getProductsPaginated: (
    searchResponse: SearchProductsResponse
  ) => ProductsSearchList;
  getProductsContent: (
    searchResponse: SearchProductsResponse
  ) => ProductSearchContent[];
  getOfferUnitPrice: (product: ProductSearchContent) => number;
  getOfferMinQuantity: (product: ProductSearchContent) => number;
  getOfferMaxQuantity: (product: ProductSearchContent) => number;
  getOfferStock: (product: ProductSearchContent) => number;
  getOfferQuantityPerPack: (product: ProductSearchContent) => number;
}

// Search helpers interface
interface SearchProductHelper {
  getAttributeValueByName: (
    product: ProductSearchContent,
    attributeName: string
  ) => unknown;
  getAttributeValuesByExternalId: (
    product: ProductSearchContent,
    attributeExternalId: string
  ) => unknown;
  getFacets: (searchResponse: SearchProductsResponse) => unknown;
  getOfferCustomFieldValueByExternalId: (
    product: ProductSearchContent,
    externalId: string
  ) => unknown;
}

Error and State Types

Error Handling Types

// Search error types
interface SearchError {
  code: string;
  message: string;
  details?: any;
  timestamp: string;
}

// API error response
interface SearchApiError {
  statusCode: number;
  error: string;
  message: string;
  path: string;
  timestamp: string;
}

// Search state types
interface SearchState {
  isLoading: boolean;
  results: ProductSearchContent[];
  facets: Facets | null;
  totalResults: number;
  currentPage: number;
  error: SearchError | null;
  lastQuery: string;
}

Default Values and Constants

Default Search Configuration

// Default pagination settings
const DEFAULT_PAGEABLE: Pageable = {
  page: 0,
  size: 20,
  sort: ["name|ASC"],
};

// Default search filters
const DEFAULT_FILTERS: SearchFilters = {
  currency: "EUR",
  locale: "en-GB",
  brand: [],
  attributes: [],
  productTags: [],
  suppliers: [],
  aggregation: AggregationType.PRODUCT,
};

// Search limits and constraints
const SEARCH_CONSTRAINTS = {
  MAX_QUERY_LENGTH: 200,
  MIN_AUTOCOMPLETE_LENGTH: 2,
  MAX_PAGE_SIZE: 100,
  DEFAULT_AUTOCOMPLETE_SIZE: 10,
  DEBOUNCE_DELAY: 300,
} as const;

Type Guards and Utilities

Type Checking Utilities

// Type guard functions
function isProductSearchContent(item: any): item is ProductSearchContent {
  return (
    item &&
    typeof item.product === "object" &&
    typeof item.variant === "object" &&
    typeof item.offer === "object" &&
    typeof item.offerPrice === "object"
  );
}

function isValidSearchResponse(
  response: any
): response is SearchProductsResponse {
  return (
    response &&
    typeof response.success === "boolean" &&
    response.products &&
    Array.isArray(response.products.content)
  );
}

function isValidAutocompleteResponse(
  response: any
): response is ProductSearchContent[] {
  return (
    Array.isArray(response) &&
    response.every((item) => isProductSearchContent(item))
  );
}

// Utility type for search parameter validation
type SearchRequestValidator = {
  [K in keyof SearchProductsRequest]: (
    value: SearchProductsRequest[K]
  ) => boolean;
};

These TypeScript interfaces provide complete type safety for the Search management system, ensuring consistency across all search operations, faceted navigation, and result processing within the Nuxt 3 e-commerce application.