@internetarchive/collection-browser 2.3.0 → 2.4.0

package/dist/src/data-source/collection-browser-data-source.d.ts

@@ -1,378 +1,378 @@
-import type { ReactiveControllerHost } from 'lit';
-import { AccountExtraInfo, Aggregation, CollectionExtraInfo, FilterMap, PageElementMap, SearchParams, SearchResponseSessionContext } from '@internetarchive/search-service';
-import { type PrefixFilterType, TileModel, PrefixFilterCounts, RequestKind } from '../models';
-import { type PageSpecifierParams } from './models';
-import type { CollectionBrowserDataSourceInterface } from './collection-browser-data-source-interface';
-import type { CollectionBrowserSearchInterface } from './collection-browser-query-state';
-export declare class CollectionBrowserDataSource implements CollectionBrowserDataSourceInterface {
-    /** The host element to which this controller should attach listeners */
-    private readonly host;
-    /** Default size of result pages */
-    private pageSize;
-    /**
-     * All pages of tile models that have been fetched so far, indexed by their page
-     * number (with the first being page 1).
-     */
-    private pages;
-    /**
-     * Tile offset to apply when looking up tiles in the pages, in order to maintain
-     * page alignment after tiles are removed.
-     */
-    private offset;
-    /**
-     * Total number of tile models stored in this data source's pages
-     */
-    private numTileModels;
-    /**
-     * A set of fetch IDs that are valid for the current query state
-     */
-    private fetchesInProgress;
-    /**
-     * A record of the query key used for the last search.
-     * If this changes, we need to load new results.
-     */
-    private previousQueryKey;
-    /**
-     * Whether the initial page of search results for the current query state
-     * is presently being fetched.
-     */
-    private searchResultsLoading;
-    /**
-     * Whether the facets (aggregations) for the current query state are
-     * presently being fetched.
-     */
-    private facetsLoading;
-    /**
-     * Whether the facets are actually visible -- if not, then we can delay any facet
-     * fetches until they become visible.
-     */
-    private facetsReadyToLoad;
-    /**
-     * Whether further query changes should be ignored and not trigger fetches
-     */
-    private suppressFetches;
-    /**
-     * @inheritdoc
-     */
-    totalResults: number;
-    /**
-     * @inheritdoc
-     */
-    endOfDataReached: boolean;
-    /**
-     * @inheritdoc
-     */
-    queryInitialized: boolean;
-    /**
-     * @inheritdoc
-     */
-    aggregations?: Record<string, Aggregation>;
-    /**
-     * @inheritdoc
-     */
-    yearHistogramAggregation?: Aggregation;
-    /**
-     * @inheritdoc
-     */
-    collectionTitles: Map<string, string>;
-    /**
-     * @inheritdoc
-     */
-    collectionExtraInfo?: CollectionExtraInfo;
-    /**
-     * @inheritdoc
-     */
-    accountExtraInfo?: AccountExtraInfo;
-    /**
-     * @inheritdoc
-     */
-    sessionContext?: SearchResponseSessionContext;
-    /**
-     * @inheritdoc
-     */
-    pageElements?: PageElementMap;
-    /**
-     * @inheritdoc
-     */
-    parentCollections?: string[];
-    /**
-     * @inheritdoc
-     */
-    prefixFilterCountMap: Partial<Record<PrefixFilterType, PrefixFilterCounts>>;
-    /**
-     * @inheritdoc
-     */
-    queryErrorMessage?: string;
-    /**
-     * Internal property to store the `resolve` function for the most recent
-     * `initialSearchComplete` promise, allowing us to resolve it at the appropriate time.
-     */
-    private _initialSearchCompleteResolver;
-    /**
-     * Internal property to store the private value backing the `initialSearchComplete` getter.
-     */
-    private _initialSearchCompletePromise;
-    /**
-     * @inheritdoc
-     */
-    get initialSearchComplete(): Promise<boolean>;
-    constructor(
-    /** The host element to which this controller should attach listeners */
-    host: ReactiveControllerHost & CollectionBrowserSearchInterface, 
-    /** Default size of result pages */
-    pageSize?: number);
-    hostConnected(): void;
-    hostUpdate(): void;
-    /**
-     * Returns whether this data source is the one currently installed on the host component.
-     */
-    private get activeOnHost();
-    /**
-     * @inheritdoc
-     */
-    get size(): number;
-    /**
-     * @inheritdoc
-     */
-    reset(): void;
-    /**
-     * @inheritdoc
-     */
-    addPage(pageNum: number, pageTiles: TileModel[]): void;
-    /**
-     * @inheritdoc
-     */
-    addMultiplePages(firstPageNum: number, tiles: TileModel[]): void;
-    /**
-     * @inheritdoc
-     */
-    getPage(pageNum: number): TileModel[];
-    /**
-     * @inheritdoc
-     */
-    getAllPages(): Record<string, TileModel[]>;
-    /**
-     * @inheritdoc
-     */
-    hasPage(pageNum: number): boolean;
-    /**
-     * @inheritdoc
-     */
-    getTileModelAt(index: number): TileModel | undefined;
-    /**
-     * @inheritdoc
-     */
-    indexOf(tile: TileModel): number;
-    /**
-     * @inheritdoc
-     */
-    getPageSize(): number;
-    /**
-     * @inheritdoc
-     */
-    setPageSize(pageSize: number): void;
-    /**
-     * @inheritdoc
-     */
-    setTotalResultCount(count: number): void;
-    /**
-     * @inheritdoc
-     */
-    setFetchesSuppressed(suppressed: boolean): void;
-    /**
-     * @inheritdoc
-     */
-    handleQueryChange(): Promise<void>;
-    /**
-     * @inheritdoc
-     */
-    handleFacetReadinessChange(ready: boolean): Promise<void>;
-    /**
-     * Whether the data source & its host are in a state where a facet request should be fired.
-     * (i.e., they aren't suppressed or already loading, etc.)
-     */
-    private get canFetchFacets();
-    /**
-     * @inheritdoc
-     */
-    map(callback: (model: TileModel, index: number, array: TileModel[]) => TileModel): void;
-    /**
-     * @inheritdoc
-     */
-    checkAllTiles: () => void;
-    /**
-     * @inheritdoc
-     */
-    uncheckAllTiles: () => void;
-    /**
-     * @inheritdoc
-     */
-    removeCheckedTiles: () => void;
-    /**
-     * @inheritdoc
-     */
-    get checkedTileModels(): TileModel[];
-    /**
-     * @inheritdoc
-     */
-    get uncheckedTileModels(): TileModel[];
-    /**
-     * Returns a flattened, filtered array of all the tile models in the data source
-     * for which the given predicate returns a truthy value.
-     *
-     * @param predicate A callback function to apply on each tile model, as with Array.filter
-     * @returns A filtered array of tile models satisfying the predicate
-     */
-    private getFilteredTileModels;
-    /**
-     * @inheritdoc
-     */
-    get canPerformSearch(): boolean;
-    /**
-     * Sets the state for whether the initial set of search results for the
-     * current query is loading
-     */
-    private setSearchResultsLoading;
-    /**
-     * Sets the state for whether the facets for a query is loading
-     */
-    private setFacetsLoading;
-    /**
-     * Requests that the host perform an update, provided this data
-     * source is actively installed on it.
-     */
-    private requestHostUpdate;
-    /**
-     * Requests that the host refresh its visible tiles, provided this
-     * data source is actively installed on it.
-     */
-    private refreshVisibleResults;
-    /**
-     * The query key is a string that uniquely identifies the current search.
-     * It consists of:
-     *  - The current base query
-     *  - The current collection/profile target & page element
-     *  - The current search type
-     *  - Any currently-applied facets
-     *  - Any currently-applied date range
-     *  - Any currently-applied prefix filters
-     *  - The current sort options
-     *
-     * This lets us internally keep track of queries so we don't persist data that's
-     * no longer relevant. Not meant to be human-readable.
-     */
-    get pageFetchQueryKey(): string;
-    /**
-     * Similar to `pageFetchQueryKey` above, but excludes sort fields since they
-     * are not relevant in determining aggregation queries.
-     */
-    get facetFetchQueryKey(): string;
-    /**
-     * Constructs a search service FilterMap object from the combination of
-     * all the currently-applied filters. This includes any facets, letter
-     * filters, and date range.
-     */
-    get filterMap(): FilterMap;
-    /**
-     * Produces a compact unique ID for a search request that can help with debugging
-     * on the backend by making related requests easier to trace through different services.
-     * (e.g., tying the hits/aggregations requests for the same page back to a single hash).
-     *
-     * @param params The search service parameters for the request
-     * @param kind The kind of request (hits-only, aggregations-only, or both)
-     * @returns A Promise resolving to the uid to apply to the request
-     */
-    requestUID(params: SearchParams, kind: RequestKind): Promise<string>;
-    /**
-     * @inheritdoc
-     */
-    get pageSpecifierParams(): PageSpecifierParams | null;
-    /**
-     * The full query, including year facets and date range clauses
-     */
-    private get fullQuery();
-    /**
-     * Generates a query string representing the current set of applied facets
-     *
-     * Example: `mediatype:("collection" OR "audio" OR -"etree") AND year:("2000" OR "2001")`
-     */
-    private get facetQuery();
-    private get dateRangeQueryClause();
-    private get sortFilterQueries();
-    /**
-     * Returns a query clause identifying the currently selected title filter,
-     * e.g., `firstTitle:X`.
-     */
-    private get titleQuery();
-    /**
-     * Returns a query clause identifying the currently selected creator filter,
-     * e.g., `firstCreator:X`.
-     */
-    private get creatorQuery();
-    /**
-     * Builds an OR-joined facet clause for the given facet name and values.
-     *
-     * E.g., for name `subject` and values
-     * `{ foo: { state: 'selected' }, bar: { state: 'hidden' } }`
-     * this will produce the clause
-     * `subject:("foo" OR -"bar")`.
-     *
-     * @param facetName The facet type (e.g., 'collection')
-     * @param facetValues The facet buckets, mapped by their keys
-     */
-    private buildFacetClause;
-    /**
-     * Handles some special pre-request normalization steps for certain facet types
-     * that require them.
-     *
-     * @param facetName The name of the facet type (e.g., 'language')
-     * @param facetValues An array of values for that facet type
-     */
-    private prepareFacetForFetch;
-    /**
-     * Takes an array of facet clauses, and combines them into a
-     * full AND-joined facet query string. Empty clauses are ignored.
-     */
-    private joinFacetClauses;
-    /**
-     * Fires a backend request to fetch a set of aggregations (representing UI facets) for
-     * the current search state.
-     */
-    private fetchFacets;
-    /**
-     * Performs the initial page fetch(es) for the current search state.
-     */
-    private doInitialPageFetch;
-    /**
-     * Fetches one or more pages of results and updates the data source.
-     *
-     * @param pageNumber The page number to fetch
-     * @param numInitialPages If this is an initial page fetch (`pageNumber = 1`),
-     *  specifies how many pages to batch together in one request. Ignored
-     *  if `pageNumber != 1`, defaulting to a single page.
-     */
-    fetchPage(pageNumber: number, numInitialPages?: number): Promise<void>;
-    /**
-     * Update the datasource from the fetch response
-     *
-     * @param pageNumber
-     * @param results
-     */
-    private addFetchedResultsToDataSource;
-    /**
-     * Fetches the aggregation buckets for the given prefix filter type.
-     */
-    private fetchPrefixFilterBuckets;
-    /**
-     * Fetches and caches the prefix filter counts for the given filter type.
-     */
-    updatePrefixFilterCounts(filterType: PrefixFilterType): Promise<void>;
-    /**
-     * @inheritdoc
-     */
-    updatePrefixFiltersForCurrentSort(): Promise<void>;
-    /**
-     * @inheritdoc
-     */
-    refreshLetterCounts(): void;
-}
+import type { ReactiveControllerHost } from 'lit';
+import { AccountExtraInfo, Aggregation, CollectionExtraInfo, FilterMap, PageElementMap, SearchParams, SearchResponseSessionContext } from '@internetarchive/search-service';
+import { type PrefixFilterType, TileModel, PrefixFilterCounts, RequestKind } from '../models';
+import { type PageSpecifierParams } from './models';
+import type { CollectionBrowserDataSourceInterface } from './collection-browser-data-source-interface';
+import type { CollectionBrowserSearchInterface } from './collection-browser-query-state';
+export declare class CollectionBrowserDataSource implements CollectionBrowserDataSourceInterface {
+    /** The host element to which this controller should attach listeners */
+    private readonly host;
+    /** Default size of result pages */
+    private pageSize;
+    /**
+     * All pages of tile models that have been fetched so far, indexed by their page
+     * number (with the first being page 1).
+     */
+    private pages;
+    /**
+     * Tile offset to apply when looking up tiles in the pages, in order to maintain
+     * page alignment after tiles are removed.
+     */
+    private offset;
+    /**
+     * Total number of tile models stored in this data source's pages
+     */
+    private numTileModels;
+    /**
+     * A set of fetch IDs that are valid for the current query state
+     */
+    private fetchesInProgress;
+    /**
+     * A record of the query key used for the last search.
+     * If this changes, we need to load new results.
+     */
+    private previousQueryKey;
+    /**
+     * Whether the initial page of search results for the current query state
+     * is presently being fetched.
+     */
+    private searchResultsLoading;
+    /**
+     * Whether the facets (aggregations) for the current query state are
+     * presently being fetched.
+     */
+    private facetsLoading;
+    /**
+     * Whether the facets are actually visible -- if not, then we can delay any facet
+     * fetches until they become visible.
+     */
+    private facetsReadyToLoad;
+    /**
+     * Whether further query changes should be ignored and not trigger fetches
+     */
+    private suppressFetches;
+    /**
+     * @inheritdoc
+     */
+    totalResults: number;
+    /**
+     * @inheritdoc
+     */
+    endOfDataReached: boolean;
+    /**
+     * @inheritdoc
+     */
+    queryInitialized: boolean;
+    /**
+     * @inheritdoc
+     */
+    aggregations?: Record<string, Aggregation>;
+    /**
+     * @inheritdoc
+     */
+    yearHistogramAggregation?: Aggregation;
+    /**
+     * @inheritdoc
+     */
+    collectionTitles: Map<string, string>;
+    /**
+     * @inheritdoc
+     */
+    collectionExtraInfo?: CollectionExtraInfo;
+    /**
+     * @inheritdoc
+     */
+    accountExtraInfo?: AccountExtraInfo;
+    /**
+     * @inheritdoc
+     */
+    sessionContext?: SearchResponseSessionContext;
+    /**
+     * @inheritdoc
+     */
+    pageElements?: PageElementMap;
+    /**
+     * @inheritdoc
+     */
+    parentCollections?: string[];
+    /**
+     * @inheritdoc
+     */
+    prefixFilterCountMap: Partial<Record<PrefixFilterType, PrefixFilterCounts>>;
+    /**
+     * @inheritdoc
+     */
+    queryErrorMessage?: string;
+    /**
+     * Internal property to store the `resolve` function for the most recent
+     * `initialSearchComplete` promise, allowing us to resolve it at the appropriate time.
+     */
+    private _initialSearchCompleteResolver;
+    /**
+     * Internal property to store the private value backing the `initialSearchComplete` getter.
+     */
+    private _initialSearchCompletePromise;
+    /**
+     * @inheritdoc
+     */
+    get initialSearchComplete(): Promise<boolean>;
+    constructor(
+    /** The host element to which this controller should attach listeners */
+    host: ReactiveControllerHost & CollectionBrowserSearchInterface, 
+    /** Default size of result pages */
+    pageSize?: number);
+    hostConnected(): void;
+    hostUpdate(): void;
+    /**
+     * Returns whether this data source is the one currently installed on the host component.
+     */
+    private get activeOnHost();
+    /**
+     * @inheritdoc
+     */
+    get size(): number;
+    /**
+     * @inheritdoc
+     */
+    reset(): void;
+    /**
+     * @inheritdoc
+     */
+    addPage(pageNum: number, pageTiles: TileModel[]): void;
+    /**
+     * @inheritdoc
+     */
+    addMultiplePages(firstPageNum: number, tiles: TileModel[]): void;
+    /**
+     * @inheritdoc
+     */
+    getPage(pageNum: number): TileModel[];
+    /**
+     * @inheritdoc
+     */
+    getAllPages(): Record<string, TileModel[]>;
+    /**
+     * @inheritdoc
+     */
+    hasPage(pageNum: number): boolean;
+    /**
+     * @inheritdoc
+     */
+    getTileModelAt(index: number): TileModel | undefined;
+    /**
+     * @inheritdoc
+     */
+    indexOf(tile: TileModel): number;
+    /**
+     * @inheritdoc
+     */
+    getPageSize(): number;
+    /**
+     * @inheritdoc
+     */
+    setPageSize(pageSize: number): void;
+    /**
+     * @inheritdoc
+     */
+    setTotalResultCount(count: number): void;
+    /**
+     * @inheritdoc
+     */
+    setFetchesSuppressed(suppressed: boolean): void;
+    /**
+     * @inheritdoc
+     */
+    handleQueryChange(): Promise<void>;
+    /**
+     * @inheritdoc
+     */
+    handleFacetReadinessChange(ready: boolean): Promise<void>;
+    /**
+     * Whether the data source & its host are in a state where a facet request should be fired.
+     * (i.e., they aren't suppressed or already loading, etc.)
+     */
+    private get canFetchFacets();
+    /**
+     * @inheritdoc
+     */
+    map(callback: (model: TileModel, index: number, array: TileModel[]) => TileModel): void;
+    /**
+     * @inheritdoc
+     */
+    checkAllTiles: () => void;
+    /**
+     * @inheritdoc
+     */
+    uncheckAllTiles: () => void;
+    /**
+     * @inheritdoc
+     */
+    removeCheckedTiles: () => void;
+    /**
+     * @inheritdoc
+     */
+    get checkedTileModels(): TileModel[];
+    /**
+     * @inheritdoc
+     */
+    get uncheckedTileModels(): TileModel[];
+    /**
+     * Returns a flattened, filtered array of all the tile models in the data source
+     * for which the given predicate returns a truthy value.
+     *
+     * @param predicate A callback function to apply on each tile model, as with Array.filter
+     * @returns A filtered array of tile models satisfying the predicate
+     */
+    private getFilteredTileModels;
+    /**
+     * @inheritdoc
+     */
+    get canPerformSearch(): boolean;
+    /**
+     * Sets the state for whether the initial set of search results for the
+     * current query is loading
+     */
+    private setSearchResultsLoading;
+    /**
+     * Sets the state for whether the facets for a query is loading
+     */
+    private setFacetsLoading;
+    /**
+     * Requests that the host perform an update, provided this data
+     * source is actively installed on it.
+     */
+    private requestHostUpdate;
+    /**
+     * Requests that the host refresh its visible tiles, provided this
+     * data source is actively installed on it.
+     */
+    private refreshVisibleResults;
+    /**
+     * The query key is a string that uniquely identifies the current search.
+     * It consists of:
+     *  - The current base query
+     *  - The current collection/profile target & page element
+     *  - The current search type
+     *  - Any currently-applied facets
+     *  - Any currently-applied date range
+     *  - Any currently-applied prefix filters
+     *  - The current sort options
+     *
+     * This lets us internally keep track of queries so we don't persist data that's
+     * no longer relevant. Not meant to be human-readable.
+     */
+    get pageFetchQueryKey(): string;
+    /**
+     * Similar to `pageFetchQueryKey` above, but excludes sort fields since they
+     * are not relevant in determining aggregation queries.
+     */
+    get facetFetchQueryKey(): string;
+    /**
+     * Constructs a search service FilterMap object from the combination of
+     * all the currently-applied filters. This includes any facets, letter
+     * filters, and date range.
+     */
+    get filterMap(): FilterMap;
+    /**
+     * Produces a compact unique ID for a search request that can help with debugging
+     * on the backend by making related requests easier to trace through different services.
+     * (e.g., tying the hits/aggregations requests for the same page back to a single hash).
+     *
+     * @param params The search service parameters for the request
+     * @param kind The kind of request (hits-only, aggregations-only, or both)
+     * @returns A Promise resolving to the uid to apply to the request
+     */
+    requestUID(params: SearchParams, kind: RequestKind): Promise<string>;
+    /**
+     * @inheritdoc
+     */
+    get pageSpecifierParams(): PageSpecifierParams | null;
+    /**
+     * The full query, including year facets and date range clauses
+     */
+    private get fullQuery();
+    /**
+     * Generates a query string representing the current set of applied facets
+     *
+     * Example: `mediatype:("collection" OR "audio" OR -"etree") AND year:("2000" OR "2001")`
+     */
+    private get facetQuery();
+    private get dateRangeQueryClause();
+    private get sortFilterQueries();
+    /**
+     * Returns a query clause identifying the currently selected title filter,
+     * e.g., `firstTitle:X`.
+     */
+    private get titleQuery();
+    /**
+     * Returns a query clause identifying the currently selected creator filter,
+     * e.g., `firstCreator:X`.
+     */
+    private get creatorQuery();
+    /**
+     * Builds an OR-joined facet clause for the given facet name and values.
+     *
+     * E.g., for name `subject` and values
+     * `{ foo: { state: 'selected' }, bar: { state: 'hidden' } }`
+     * this will produce the clause
+     * `subject:("foo" OR -"bar")`.
+     *
+     * @param facetName The facet type (e.g., 'collection')
+     * @param facetValues The facet buckets, mapped by their keys
+     */
+    private buildFacetClause;
+    /**
+     * Handles some special pre-request normalization steps for certain facet types
+     * that require them.
+     *
+     * @param facetName The name of the facet type (e.g., 'language')
+     * @param facetValues An array of values for that facet type
+     */
+    private prepareFacetForFetch;
+    /**
+     * Takes an array of facet clauses, and combines them into a
+     * full AND-joined facet query string. Empty clauses are ignored.
+     */
+    private joinFacetClauses;
+    /**
+     * Fires a backend request to fetch a set of aggregations (representing UI facets) for
+     * the current search state.
+     */
+    private fetchFacets;
+    /**
+     * Performs the initial page fetch(es) for the current search state.
+     */
+    private doInitialPageFetch;
+    /**
+     * Fetches one or more pages of results and updates the data source.
+     *
+     * @param pageNumber The page number to fetch
+     * @param numInitialPages If this is an initial page fetch (`pageNumber = 1`),
+     *  specifies how many pages to batch together in one request. Ignored
+     *  if `pageNumber != 1`, defaulting to a single page.
+     */
+    fetchPage(pageNumber: number, numInitialPages?: number): Promise<void>;
+    /**
+     * Update the datasource from the fetch response
+     *
+     * @param pageNumber
+     * @param results
+     */
+    private addFetchedResultsToDataSource;
+    /**
+     * Fetches the aggregation buckets for the given prefix filter type.
+     */
+    private fetchPrefixFilterBuckets;
+    /**
+     * Fetches and caches the prefix filter counts for the given filter type.
+     */
+    updatePrefixFilterCounts(filterType: PrefixFilterType): Promise<void>;
+    /**
+     * @inheritdoc
+     */
+    updatePrefixFiltersForCurrentSort(): Promise<void>;
+    /**
+     * @inheritdoc
+     */
+    refreshLetterCounts(): void;
+}