@dcupl/common 2.0.0-beta.5 → 2.0.0-beta.7

package/dist/esm/getFacets.d.ts

@@ -1,3 +1,26 @@
 import { ListItem, DcuplFilterOptions, InverseIndexReferenceMap, DcuplGlobalQueryOptions, DcuplFacet } from './types/index.js';
 import { QueryManager } from './queryData.js';
+/**
+ * Build facet entries for `attribute`.
+ *
+ * Pipeline order — IMPORTANT, do not shuffle:
+ *
+ *   Fast path (options.sort omitted, default):
+ *     1. walk validFacetKeys in insertion order
+ *     2. for each key: compute entry (binary size if calculateFacets is false)
+ *     3. skip if excludeZeros && size === 0 (does NOT advance count)
+ *     4. early-return when filterItemEntries.length === count
+ *     5. push and continue
+ *
+ *   Sort path (options.sort set):
+ *     1. walk ALL validFacetKeys (ignore count for early-return)
+ *     2. for each key: compute entry with FULL size (override calculateFacets: false)
+ *     3. push every entry
+ *     4. drop zeros if excludeZeros
+ *     5. sort by chosen mode (size sorts tie-break on value asc, undefined last)
+ *     6. truncate to count
+ *
+ * The sort path is opt-in because it forfeits both early-return optimizations.
+ * Most call sites only need a partial answer and stay on the fast path.
+ */
 export declare function getFacets<ListType extends ListItem = ListItem>(modelData: Map<string, ListType>, remoteModelData: Map<string, ListType>, options: DcuplFilterOptions, query: DcuplGlobalQueryOptions<any>, attribute: string, modelIndexMap: InverseIndexReferenceMap, queryManager: QueryManager): DcuplFacet[];