@internetarchive/collection-browser 3.3.2 → 3.3.4-alpha-webdev7761.0

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

@@ -0,0 +1,418 @@
+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 { TVChannelMaps, 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;
+    /**
+     * How many consecutive pages should be batched together on the initial page fetch.
+     * Defaults to 2 pages.
+     */
+    private numInitialPages;
+    /**
+     * 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
+     */
+    histogramAggregation?: Aggregation;
+    /**
+     * @inheritdoc
+     */
+    collectionTitles: Map<string, string>;
+    /**
+     * @inheritdoc
+     */
+    tvChannelMaps: TVChannelMaps;
+    /**
+     * @inheritdoc
+     */
+    tvChannelAliases: 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 promise for any current TV channel maps fetch.
+     */
+    private _tvMapsPromise?;
+    /**
+     * 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
+     */
+    resetPages(): 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
+     */
+    setNumInitialPages(numPages: number): void;
+    /**
+     * @inheritdoc
+     */
+    setTotalResultCount(count: number): void;
+    /**
+     * @inheritdoc
+     */
+    setFetchesSuppressed(suppressed: boolean): void;
+    /**
+     * @inheritdoc
+     */
+    setEndOfDataReached(reached: 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>;
+    /**
+     * Returns the type of request that produced the current set of hits,
+     * based on the presence of a search query or profile/collection target
+     * on the host.
+     */
+    private get hitRequestSource();
+    /**
+     * 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;
+    /**
+     * @inheritdoc
+     */
+    populateTVChannelMaps(): Promise<TVChannelMaps>;
+    /**
+     * Internal function implementing the actual fetches for TV channel mappings.
+     * This should only called by the public populateTVChannelMaps method, which is guarded so
+     * that we do not make extra requests for these rather large mappings.
+     */
+    private _fetchTVChannelMaps;
+}