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

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Fix: Browse and Search types #410

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 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
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 | HierarchialOptionFacet;

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 HierarchialOptionFacet extends BaseFacet, Record<string, any> {
options: HierarchialFacetOption[];
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 HierarchialFacetOption extends FacetOption {
options?: HierarchialFacetOption[];
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.

Can the hierarchial facet option be recursive to to any depth? This typing assumes so. If it only allows two levels deep options, the type here should be replaced with FacetOption.

Also did not test this option so I don't know if it is always present or optional, so left it optional.

}

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
Loading