Skip to content

Fix: Browse and Search types #410

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
esezen merged 4 commits into from
Jan 26, 2026
Merged

Fix: Browse and Search types #410

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
079ce32
Fix browse types based on empirical testing
xkr47 Oct 17, 2025
09bcbaa
Fix search types based on empirical testing
xkr47 Oct 17, 2025
f0114e5
Fix types in browse and search tests
Alexey-Pavlov Dec 29, 2025
cd8b3f5
Fix typo
esezen Jan 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 37 additions & 23 deletions src/types/browse.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import {
BrowseFacet,
Collection,
ConstructorClientOptions,
Facet,
Expand Down Expand Up @@ -31,7 +32,7 @@ export interface IBrowseParameters {
hiddenFacets?: string[];
variationsMap?: VariationsMap;
qsParam?: Record<string, any>;
filterMatchTypes?: Record<string, 'all'| 'any' | 'none'>
filterMatchTypes?: Record<string, 'all' | 'any' | 'none'>;
}

declare class Browse {
Expand Down Expand Up @@ -77,40 +78,52 @@ declare class Browse {
/** *********
* Browse results returned from server
********** */
export interface BrowseResponse<ResponseType> extends Record<string, any> {
request?: Partial<BrowseRequestType>;
response?: Partial<ResponseType>;
result_id?: string;
export interface BrowseResponse<ResponseType, OmittedRequestFields extends keyof BrowseRequestType>
extends Record<string, any> {

request: Omit<BrowseRequestType, OmittedRequestFields>;
Comment on lines +81 to +84
Copy link
Contributor Author

@xkr47 xkr47 Oct 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I know the documentation says the format of the request object should not be programmatically relied on.. but otoh you have declared a type for the fields here, so I improved them at least a little bit..

response: ResponseType;
result_id: string;
ad_based?: boolean;
}

export type GetBrowseResultsResponse =
BrowseResponse<GetBrowseResultsResponseData>;
BrowseResponse<GetBrowseResultsResponseData, 'facet_name'>;
export type GetBrowseResultsForItemIdsResponse =
BrowseResponse<GetBrowseResultsResponseData>;
BrowseResponse<GetBrowseResultsResponseData, 'facet_name'>;
export type GetBrowseGroupsResponse = BrowseResponse<
Pick<
GetBrowseResultsResponseData,
'result_sources' | 'groups' | 'refined_content'
>
>,
'browse_filter_name' | 'browse_filter_value' | 'searchandized_items' | 'facet_name'
>;
export type GetBrowseFacetsResponse = BrowseResponse<
Pick<GetBrowseResultsResponseData, 'facets' | 'total_num_results'>
GetBrowseFacetsResultsResponseData,
Comment on lines -98 to +102
Copy link
Contributor Author

@xkr47 xkr47 Oct 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The facets response actually returns a lighter version of the facet data and therefore I made a separate interface for it.

'browse_filter_name' | 'browse_filter_value' | 'searchandized_items' | 'facet_name'
>;
export type GetBrowseFacetOptionsResponse = BrowseResponse<
Pick<GetBrowseResultsResponseData, 'facets'>
Pick<GetBrowseResultsResponseData, 'facets' | 'total_num_results'>,
Copy link
Contributor Author

@xkr47 xkr47 Oct 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The total_num_results is indeed included here as well

'browse_filter_name' | 'browse_filter_value' | 'searchandized_items'
>;

export interface GetBrowseResultsResponseData extends Record<string, any> {
result_sources: Partial<ResultSources>;
facets: Partial<Facet>[];
groups: Partial<Group>[];
results: Partial<BrowseResultData>[];
sort_options: Partial<SortOption>[];
result_sources: ResultSources;
facets: Facet[];
groups: Group[];
results: BrowseResultData[];
sort_options: SortOption[];
refined_content: Record<string, any>[];
total_num_results: number;
features: Partial<Feature>[];
collection: Partial<Collection>;
features: Feature[];
collection?: Partial<Collection>;
related_searches?: Record<string, any>[];
related_browse_pages?: Record<string, any>[];
}

export interface GetBrowseFacetsResultsResponseData extends Record<string, any> {
facets: BrowseFacet[];
Copy link
Contributor Author

@xkr47 xkr47 Oct 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I defined the light-weight BrowseFacet in index.d.ts, thought it was more in-context there even though it is a browse-specific type..

total_num_results: number;
}

export interface BrowseResultData extends Record<string, any> {
Expand All @@ -122,23 +135,24 @@ export interface BrowseResultData extends Record<string, any> {
value: string;
is_slotted: false;
labels: Record<string, any>;
variations: Record<string, any>[];
variations_map: Record<string, any> | Record<string, any>[];
variations?: Record<string, any>[];
variations_map?: Record<string, any> | Record<string, any>[];
}

export interface BrowseRequestType extends Record<string, any> {
browse_filter_name: string;
browse_filter_value: string;
filter_match_types: Record<string, any>;
filters: Record<string, any>;
fmt_options: Record<string, any>;
filter_match_types?: Record<string, any>;
filters?: Record<string, any>;
fmt_options: FmtOptions;
facet_name: string;
Copy link
Contributor Author

@xkr47 xkr47 Oct 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

facet_name comes from /browse/facet_options endpoint

num_results_per_page: number;
page: number;
section: string;
sort_by: string;
sort_order: string;
term: string;
query: string;
query?: string;
features: Partial<RequestFeature>;
feature_variants: Partial<RequestFeatureVariant>;
searchandized_items: Record<string, any>;
Expand Down
36 changes: 26 additions & 10 deletions src/types/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,7 @@ export interface SortOption extends Record<string, any> {
display_name: string;
sort_order: string;
status: string;
hidden: boolean;
}

export interface Feature extends Record<string, any> {
Expand All @@ -107,44 +108,59 @@ export interface Feature extends Record<string, any> {
} | null;
}

export type Facet = RangeFacet | OptionFacet;
export type Facet = RangeFacet | OptionFacet | HierarchicalOptionFacet;

export type BrowseFacet = Pick<Facet, keyof BaseFacet | 'type'>;

export interface BaseFacet extends Record<string, any> {
data: Record<string, any>;
status: Record<string, any>;
display_name: string;
name: string;
hidden: boolean;
}

export interface RangeFacet extends BaseFacet, Record<string, any> {
max: number;
min: number;
status?: { min: RangeMin, max: RangeMax };
max: RangeMax;
min: RangeMin;
type: 'range';
}

export interface OptionFacet extends BaseFacet, Record<string, any> {
options: FacetOption[];
type: 'multiple' | 'single' | 'hierarchical';
type: 'multiple' | 'single';
}

export interface HierarchicalOptionFacet extends BaseFacet, Record<string, any> {
options: HierarchicalFacetOption[];
type: 'hierarchical';
}

export interface FacetOption extends Record<string, any> {
count: number;
display_name: string;
value: string;
options?: FacetOption[];
range?: ['-inf' | number, 'inf' | number];
range?: [RangeMin, RangeMax];
status: string;
data: Record<string, any>;
}

export interface HierarchicalFacetOption extends FacetOption {
options?: HierarchicalFacetOption[];
}

export type RangeMin = '-inf' | number;
export type RangeMax = '+inf' | 'inf' | number

export interface Group extends BaseGroup, Record<string, any> {
count?: number;
count: number;
data?: Record<string, any>;
parents?: BaseGroup[];
children?: Group[];
parents: BaseGroup[];
children: Group[];
}

export interface Collection extends Record<string, any> {
// documentation says this field is called `id`
collection_id: string;
display_name: string;
data: Record<string, any>;
Expand Down
34 changes: 13 additions & 21 deletions src/types/search.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import {
BrowseResultData,
ConstructorClientOptions,
Facet,
Feature,
Expand Down Expand Up @@ -56,27 +57,29 @@ declare class Search {
* search results returned from server
********** */
export interface SearchResponse {
request: Partial<SearchRequestType>;
response: Partial<SearchResponseType | Redirect>;
request: SearchRequestType;
response: SearchResponseType | Redirect;
result_id: string;
}

export interface SearchResponseType extends Record<string, any> {
result_sources: Partial<ResultSources>;
facets: Partial<Facet>[];
groups: Partial<Group>[];
results: Partial<Result>[];
sort_options: Partial<SortOption>[];
result_sources: ResultSources;
facets: Facet[];
groups: Group[];
results: Result[];
sort_options: SortOption[];
refined_content: Record<string, any>[];
total_num_results: number;
features: Partial<Feature>[];
features: Feature[];
related_searches?: Record<string, any>[];
related_browse_pages?: Record<string, any>[];
}

export interface SearchRequestType extends Record<string, any> {
page: number;
num_results_per_page: number;
section: string;
blacklist_rules: boolean;
blacklist_rules?: boolean;
term: string;
fmt_options: FmtOptions;
sort_by: string;
Expand All @@ -89,18 +92,7 @@ export interface SearchRequestType extends Record<string, any> {
pre_filter_expression?: FilterExpression;
}

export interface Result extends Record<string, any> {
matched_terms: string[];
data: {
id: string;
[key: string]: any;
};
value: string;
is_slotted: false;
labels: Record<string, any>;
variations: Record<string, any>[];
variations_map: Record<string, any> | Record<string, any>[];
}
export type Result = BrowseResultData;
Copy link
Contributor Author

@xkr47 xkr47 Oct 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Result was identical so I thought we could just alias it here.


export interface Redirect extends Record<string, any> {
redirect: {
Expand Down
2 changes: 2 additions & 0 deletions src/types/tests/browse.test-d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ expectAssignable<GetBrowseResultsResponse>({
data: {},
},
],
groups: [],
results: [
{
matched_terms: [],
Expand Down Expand Up @@ -62,6 +63,7 @@ expectAssignable<GetBrowseResultsResponse>({
display_name: 'A - Z',
sort_order: 'descending',
status: '',
hidden: false,
},
],
refined_content: [],
Expand Down
Loading