@dcupl/common 2.0.0-beta.2 → 2.0.0-beta.21

package/dist/esm/indices.controller.d.ts

@@ -1,4 +1,4 @@
-import { InverseIndexValuesMap, InverseIndexDataValuesMap, ListItem } from './types';
+import { InverseIndexValuesMap, InverseIndexDataValuesMap, ListItem } from './types/index.js';
 /**
  * Statistics about indices for monitoring
  */
@@ -15,6 +15,12 @@ export declare class IndicesController {
     private indexMetadata;
     constructor();
     reset(attributeKey?: string): void;
+    /**
+     * Removes every index the predicate selects. Used to drop indices that
+     * were built from now-stale data; the next read lazily rebuilds them via
+     * {@link getOrCreateIndex}.
+     */
+    resetIndicesWhere(predicate: (indexKey: string) => boolean): void;
     fillDataMap(attributeKey: string, attributeValue: Array<string | undefined | ListItem>): void;
     fillInverseIndex(attributeKey: string, originKey: string, foreignKeys: Array<string | undefined | ListItem>): void;
     getIndex(attributeKey: string, context?: any): InverseIndexValuesMap | undefined;

package/dist/esm/logger/index.d.ts

@@ -1,2 +1,2 @@
-export { Logger, logger } from './logger';
-export type { LogLevel, LoggerConfig, LogEntry, TrackedErrorEntry } from './logger';
+export { Logger, logger } from './logger.js';
+export type { LogLevel, LoggerConfig, LogEntry, TrackedErrorEntry } from './logger.js';

package/dist/esm/pivot.d.ts

@@ -1,5 +1,5 @@
-import { IndicesController } from './indices.controller';
-import { ListItem, Aggregation, AggregationOptions } from './types';
+import { IndicesController } from './indices.controller.js';
+import { ListItem, Aggregation, AggregationOptions } from './types/index.js';
 type PivotRowOption = {
     attribute: string;
     calculateTotals?: boolean;

package/dist/esm/property-parser.d.ts

@@ -1,5 +1,30 @@
-import { Property, PropertyType } from './types';
-export declare const getPropertiesForData: (data: any[], deep: boolean) => Property[];
+import { Property, PropertyType } from './types/index.js';
+export declare const coerceStringType: (value: string) => PropertyType;
+export declare const looksDateLike: (value: string) => boolean;
+export type GetPropertiesForDataOptions = {
+    deep?: boolean;
+    sampleSize?: number;
+    /** @deprecated No longer honored — empty values are always skipped for type
+     * inference and counted toward ColumnDiagnostic.emptyRate. */
+    ignoreEmpty?: boolean;
+};
+export type ColumnDiagnostic = {
+    column: string;
+    inferredType: PropertyType;
+    observedTypes: PropertyType[];
+    emptyRate: number;
+    conflict: boolean;
+    hint?: string;
+};
+export type InferModelOptions = GetPropertiesForDataOptions & {
+    coerceStrings?: boolean;
+};
+export type InferModelResult = {
+    properties: Property[];
+    diagnostics: ColumnDiagnostic[];
+};
+export declare const inferModel: (data: any[], options?: InferModelOptions) => InferModelResult;
+export declare const getPropertiesForData: (data: any[], deepOrOptions?: boolean | GetPropertiesForDataOptions) => Property[];
 export declare const isInt: (n: any) => boolean;
 export declare const isFloat: (n: any) => boolean;
 export declare const getDcuplPropertyTypeForNativeType: (value: any) => PropertyType;

package/dist/esm/query-builder.d.ts

@@ -1,5 +1,5 @@
-import { DcuplGlobalQueryOptions, DcuplItemsOptions, DcuplQuery, DcuplQueryGroup } from './types';
-import { DeepQueryService } from './deep-query.service';
+import { DcuplGlobalQueryOptions, DcuplItemsOptions, DcuplQuery, DcuplQueryGroup } from './types/index.js';
+import { DeepQueryService } from './deep-query.service.js';
 export type QueryAttributeEntry = {
     attribute: string;
     reference?: string;
@@ -69,7 +69,8 @@ export declare class DcuplQueryBuilder {
      * - {@link replaceQuery} - Replace complete query
      *
      * @param queryToApply - Query, condition, or array to apply
-     * @param options - Mode: 'add' (default) or 'set' (replace)
+     * @param options - Mode: 'add' (default) or 'set' (replace). In 'add' mode a group
+     * without `groupKey` is always appended as a new group, never merged into another.
      * @param relevantQuery - Target query (defaults to current)
      * @returns Updated query
      */
@@ -187,7 +188,10 @@ export declare class DcuplQueryBuilder {
     /**
      * Add query condition(s) to the current query.
      * Accepts single condition or array of conditions.
-     * Each condition is added to its respective attribute group.
+     * Each condition is added to its respective attribute group (the group whose
+     * groupKey equals the condition's attribute; created as an `'or'` group if missing).
+     * To combine conditions in an unkeyed group, use {@link addGroup} — unkeyed groups
+     * are always appended as new groups and never merged.
      *
      * Clearer alternative to `applyQuery(condition, { mode: 'add' })`.
      *
@@ -209,7 +213,13 @@ export declare class DcuplQueryBuilder {
     addCondition(condition: DcuplQuery | DcuplQuery[]): DcuplGlobalQueryOptions<any>;
     /**
      * Add a query group to the current query.
-     * If a group with the same groupKey exists, extends it; otherwise creates new group.
+     * - Keyed group (`groupKey` set): if a group with the same groupKey exists, its queries
+     *   are extended and its groupType is replaced by the given one (if set); otherwise a new
+     *   group is created.
+     * - Unkeyed group (no `groupKey`): always appended as a new group; it is never merged
+     *   into another group, so each unkeyed group keeps its own groupType.
+     *
+     * A newly created group without `groupType` is stored as `'or'`.
      *
      * @param group - Query group to add
      * @returns Updated query

package/dist/esm/query.helper.d.ts

@@ -1,4 +1,4 @@
-import { BooleanFilterItem, BooleanFilterOptions, DateFilterItem, DateFilterOptions, DcuplQueryGroup, DcuplQueryStatement, NumberFilterItem, NumberFilterOptions, ReferenceFilterItem, ReferenceFilterOptions, TextFilterItem, TextFilterOptions } from './types';
+import { BooleanFilterItem, BooleanFilterOptions, DateFilterItem, DateFilterOptions, DcuplQueryGroup, DcuplQueryStatement, NumberFilterItem, NumberFilterOptions, ReferenceFilterItem, ReferenceFilterOptions, TextFilterItem, TextFilterOptions } from './types/index.js';
 export declare const generateTextQuery: (options: TextFilterOptions, filterItem?: TextFilterItem) => DcuplQueryGroup;
 export declare const generateBooleanQuery: (options: BooleanFilterOptions, filterItem?: BooleanFilterItem) => DcuplQueryGroup;
 export declare const generateNumberAndDateQuery: (options: NumberFilterOptions | DateFilterOptions, filterItem?: NumberFilterItem | DateFilterItem) => DcuplQueryGroup;

package/dist/esm/queryData.d.ts

@@ -1,5 +1,5 @@
-import { ListItem, InverseIndexReferenceMap, DcuplQueryTransformOptions, CustomOperatorFn, DcuplGlobalQueryOptions } from './types';
-import { ScriptController } from './script.controller';
+import { ListItem, InverseIndexReferenceMap, DcuplQueryTransformOptions, CustomOperatorFn, DcuplGlobalQueryOptions } from './types/index.js';
+import { ScriptController } from './script.controller.js';
 import { ModelParser } from '@dcupl/core/model-parser';
 import { ItemService } from '@dcupl/core/catalog';
 export declare class QueryManager {
@@ -12,9 +12,59 @@ export declare class QueryManager {
     registerCustomOperator(operator: string, fn: CustomOperatorFn): void;
     transformValue(value: any, transformers: DcuplQueryTransformOptions[]): any;
     private evaluateQuery;
+    /** A missing value never compares — in JS `null >= 0` is true. */
+    private compareValue;
+    /**
+     * The value a condition compares against. A dotted path that runs through a
+     * list (a multi-valued reference, e.g. `memberships.role`) fans out into the
+     * list of leaf values, the same values the attribute's inverse index holds —
+     * `lodash.get` cannot step into an array and would answer `undefined`. An
+     * index (`tags.0`) or `length` still reads the list itself, as with `get`.
+     */
+    private getAttributeValue;
+    /**
+     * Applies `predicate` to a single value, or to each value of a list per
+     * `arrayValueHandling`. `every` needs at least one value: an empty list
+     * matches nothing (and so matches under `invert`).
+     */
+    private matchValues;
+    /**
+     * `eq` against a list compares each value, as the inverse index does; a
+     * query value that is itself a list still compares the whole list.
+     */
+    private queryEq;
+    /**
+     * `in`: a value matches if it equals (as `eq` compares) any listed value; a
+     * list of values matches per `arrayValueHandling`. An empty list matches nothing.
+     */
+    private queryIn;
+    /**
+     * The inverse-index key a query value looks up: a string, or the key of a
+     * `{ key }` object. Anything else has no key and is compared by a scan.
+     */
+    private getIndexKey;
+    /**
+     * Equality the way the inverse index keys values: a string (or `{ key }`)
+     * query value matches a reference by its key and a date by its ISO string.
+     */
+    private equalsQueryValue;
+    /**
+     * An inverse index answers `eq` as "some value equals", untransformed — only
+     * use it when that is the question.
+     */
+    private canUseIndex;
     private evaluateEqOperator;
+    /**
+     * `in` from the inverse index when it can answer: the union of the index
+     * sets of the listed values. A value the index cannot look up (not a string
+     * or `{ key }`, or not in the index) is answered by a scan of the rest, so
+     * the result equals the scan's.
+     */
+    private evaluateInOperator;
+    /** Evaluates `query` on each item, resolving a deep path's references first. */
+    private scanDataset;
     private equalRegexFn;
-    queryFind(entryValue: any | any[], queryValue: any, arrayValueHandling: 'some' | 'every'): boolean;
+    queryFind(entryValue: any | any[], queryValue: any, arrayValueHandling: 'some' | 'every', regexFlags?: string): boolean;
     private validateQuery;
     private getEvaluatedQueryDataset;
     private handleArrayStarQuery;

package/dist/esm/redact-url.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `url` with the values of secret query parameters replaced by `<redacted>`.
+ *
+ * For error messages and log lines only — the request itself keeps the real values. The app
+ * loader appends the project `api-key` to every dcupl CDN request, and a failed fetch used to
+ * carry that URL verbatim into the log output and the quality error. Works on the raw string so
+ * nothing else is re-encoded or reordered. Same parameter set as console-api's `redactUrl`.
+ */
+export declare function redactUrl(url: string): string;

package/dist/esm/resource-id.d.ts

@@ -0,0 +1,43 @@
+/** Authored `resource.key` values are namespaced so they can never collide with a derived hash. */
+export declare const AUTHORED_RESOURCE_ID_PREFIX = "k:";
+export declare const DERIVED_RESOURCE_ID_PREFIX = "h:";
+/**
+ * The fields a resource identity is derived from.
+ *
+ * Structural rather than `AppLoaderConfiguration.Resource` so the same function serves a raw config
+ * entry and a runtime progress item — `model` only exists on data resources, `rawUrl` only at runtime.
+ */
+export type ResourceIdentityInput = {
+    key?: string;
+    type: string;
+    url: string;
+    rawUrl?: string;
+    model?: string;
+};
+/**
+ * A stable id for one resource.
+ *
+ * An authored `key` wins and is used verbatim — that id survives a url edit, which is the reason to
+ * author keys at all. Otherwise the id is a hash of the RAW url plus type/model. Deriving from the
+ * raw url (never the resolved one) is what makes the id identical on both sides of the config↔runtime
+ * boundary, since `${variable}` substitution happens only on the runtime side.
+ *
+ * A derived id therefore changes when the url, type or model changes. That is the accepted limit:
+ * it is stable across runs, not across edits.
+ *
+ * `occurrence` disambiguates config entries that are identical in type/url/model. Prefer
+ * `resolveResourceIds` for a list — it assigns occurrences in document order, so reordering the
+ * config does not churn ids.
+ */
+export declare function resolveResourceId(resource: ResourceIdentityInput, occurrence?: number): string;
+/**
+ * Ids for a resource list, positionally aligned with the input, guaranteed unique.
+ *
+ * Uniqueness is enforced on the OUTPUT, not just on the (type, url, model) basis, because two other
+ * things can collide: two entries authored with the same `key` (nothing in the config validates key
+ * uniqueness — `loader.resources.get()` simply returns the first match), and a hash collision, which
+ * `generateObjectHash` admits by construction since it is a 32-bit rolling hash. Random collisions
+ * are vanishingly rare at realistic config sizes, but a duplicate id silently merges two nodes in a
+ * consumer's graph, so it is worth ruling out rather than reasoning about.
+ */
+export declare function resolveResourceIds(resources: readonly ResourceIdentityInput[]): string[];

package/dist/esm/scheduling.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Yields control back to the event loop as a macrotask WITHOUT going through `setTimeout`.
+ *
+ * Browsers throttle DOM timers on hidden/background tabs: Chrome aligns chained timers to
+ * ~1 s wake-ups (and to 1 min after five minutes hidden). A loop that awaited
+ * `setTimeout(resolve, 0)` per iteration therefore stalled ~1 s per iteration whenever the
+ * tab was not in the foreground, turning a sub-second `dcupl.init()` into minutes.
+ * `scheduler.yield()`, `setImmediate` and `MessageChannel` tasks are not throttled that way,
+ * while still letting rendering and input events run between iterations.
+ *
+ * Resolution order:
+ * 1. `scheduler.yield()` — browsers with the Prioritized Task Scheduling API (Chrome 129+)
+ * 2. `setImmediate` — Node.js
+ * 3. `MessageChannel` — every other browser
+ * 4. `setTimeout(0)` — last resort
+ */
+export declare function yieldToEventLoop(): Promise<void>;

package/dist/esm/types/app-loader.types.d.ts

@@ -1,4 +1,5 @@
-import { DataContainerType } from './';
+import { AutoGeneratePropertiesOption, DataContainerType } from './index.js';
+import { KeyPropertySpec } from './key-property.types.js';
 export declare namespace AppLoaderConfiguration {
     /**
      * The base structure for configuration file contains all resources, evnironments and headers
@@ -55,7 +56,7 @@ export declare namespace AppLoaderConfiguration {
         defaultDataContainerUpdateType?: DataContainerType;
         csvParserOptions?: CsvParserOptions;
         missingModelHandling?: {
-            autoGenerateProperties?: boolean;
+            autoGenerateProperties?: AutoGeneratePropertiesOption;
         };
     };
     export type CsvParserOptions = {
@@ -181,9 +182,25 @@ export declare namespace AppLoaderConfiguration {
     };
     export type DataResourceOptions = {
         updateType?: DataContainerType;
-        keyProperty?: string;
+        /**
+         * Property name(s) on each row that uniquely identify it.
+         *
+         * Pass a single string for a simple key (`keyProperty: 'ID'`) or a
+         * non-empty array for a composite key (`keyProperty: ['ID', 'Language']`).
+         * Composite parts are joined into the internal `.key` using
+         * `keyPropertySeparator` (default `::`). Order is preserved literally.
+         *
+         * Each part is stringified via `String(value)`, so `null`, `undefined`,
+         * and `''` produce distinct keys (`'null'`, `'undefined'`, `''`).
+         */
+        keyProperty?: KeyPropertySpec;
+        /**
+         * Separator joining composite `keyProperty` parts. Default `'::'`.
+         * Ignored when `keyProperty` is a string or a single-element array.
+         */
+        keyPropertySeparator?: string;
         autoGenerateKey?: boolean;
-        autoGenerateProperties?: boolean;
+        autoGenerateProperties?: AutoGeneratePropertiesOption;
         csvParserOptions?: CsvParserOptions;
     };
     export type Resource = ModelResource | DataResource | TransformerResource | CustomOperatorResource | CustomScriptResource;
@@ -191,6 +208,45 @@ export declare namespace AppLoaderConfiguration {
         key: string;
         value: string;
     };
+    /** Why a declared resource was not scheduled for a run. */
+    export type SkipReason = 
+    /** The run filters by resourceTags, and the resource carries no tags at all. */
+    'no-tags'
+    /** The run filters by resourceTags, and none of them matched the resource's tags. */
+     | 'tag-mismatch';
+    export type SkippedResource = {
+        resource: Resource;
+        reason: SkipReason;
+        /**
+         * The same identity a scheduled item would carry — see `AppLoaderProgress.ResourceItem.id`.
+         *
+         * Assigned here rather than left to the consumer because ids are allotted over the FULL declared
+         * list: recomputing one in isolation cannot know its occurrence index, so duplicate entries would
+         * come out with a different id than the SDK gave them.
+         */
+        id?: string;
+    };
+    /**
+     * The outcome of resolving a configuration against process options, WITHOUT fetching anything.
+     *
+     * `scheduled` is what a `process()` call would actually load (tag-filtered, urls resolved);
+     * `skipped` is every declared resource that dropped out, with the reason. Together they cover
+     * `config.resources` exactly, which is what lets a consumer show "declared but not in this app"
+     * without re-implementing the filter.
+     */
+    export type ResourcePlan = {
+        scheduled: AppLoaderProgress.ResourceItem[];
+        skipped: SkippedResource[];
+        /** The variables the scheduled urls were resolved with. */
+        variables: EnvironmentVariableAsObject;
+        /** The process options the plan was built for. */
+        run: RunContext;
+    };
+    export type RunContext = {
+        applicationKey?: string;
+        resourceTags?: StringOrStringArray;
+        environmentKeys?: string[];
+    };
     export {};
 }
 export type FilesApiStatusResponse = {
@@ -205,6 +261,30 @@ export declare namespace AppLoaderProgress {
     type ResourceItem = AppLoaderConfiguration.Resource & {
         success?: boolean;
         status?: number;
+        /**
+         * Stable identity for this resource, derived once at plan time.
+         *
+         * Authored `resource.key` wins (`k:<key>`); otherwise a deterministic hash of the resource's
+         * RAW url plus type/model (`h:<hash>`). Because it is derived from the raw url it is the same
+         * value a consumer computes from the config file, which is what makes declared↔runtime joins
+         * possible without url matching. See `resolveResourceId`.
+         */
+        id?: string;
+        /**
+         * The url as authored in the config, BEFORE `${variable}` substitution.
+         *
+         * `url` is overwritten with the resolved value at plan time; without this the template — and
+         * therefore the link back to the config entry — would be unrecoverable at runtime.
+         */
+        rawUrl?: string;
+        /**
+         * Variables referenced by `rawUrl` that had no value at resolve time.
+         *
+         * `evaluateTemplate` substitutes an unknown variable with an empty string, so an unset
+         * `${baseUrl}` silently yields a mangled url and a download failure that looks like a missing
+         * file. A non-empty array here is the difference between "file is gone" and "config is wrong".
+         */
+        unresolvedVariables?: string[];
     };
     type ProgressItem = {
         total: number;
@@ -213,11 +293,21 @@ export declare namespace AppLoaderProgress {
         progress: number;
         context: string;
         currentItem: ResourceItem;
+        /** The resources SCHEDULED for this run — already tag-filtered and url-resolved. */
         totalItems: ResourceItem[];
         processedItems: ResourceItem[];
         downloadedItems: ResourceItem[];
         failedItems: ResourceItem[];
         remainingItems: ResourceItem[];
+        /**
+         * Declared resources that this run never scheduled, with the reason.
+         *
+         * `totalItems` covers only what the run's resourceTags selected, so on its own it cannot
+         * distinguish "loaded everything" from "loaded everything it was allowed to see".
+         */
+        skippedItems?: AppLoaderConfiguration.SkippedResource[];
+        /** The application/tags/environments this run resolved against. */
+        run?: AppLoaderConfiguration.RunContext;
     };
     type CallbackFunction = (item: ProgressItem) => void;
 }

package/dist/esm/types/data.types.d.ts

@@ -1,3 +1,5 @@
+import { AutoGeneratePropertiesOption } from './model.types.js';
+import { KeyPropertySpec } from './key-property.types.js';
 export type RawItem = any;
 export type ListItem = {
     key: string;
@@ -7,15 +9,17 @@ export type DataContainer<ListType extends RawItem | ListItem = ListItem, ModelN
     model: ModelNames;
     type?: DataContainerType;
     data: ListType[];
-    keyProperty?: string;
+    keyProperty?: KeyPropertySpec;
+    keyPropertySeparator?: string;
     autoGenerateKey?: boolean;
-    autoGenerateProperties?: boolean;
+    autoGenerateProperties?: AutoGeneratePropertiesOption;
     placeholderUid?: string;
 };
 export type DataContainerType = 'upsert' | 'update' | 'set' | 'remove';
 export type ReferenceDataTypes<ListType extends ListItem = ListItem> = string | string[] | ListType | ListType[];
 export type DataOptions<ModelNames extends string = string> = {
     model: ModelNames;
-    keyProperty?: string;
+    keyProperty?: KeyPropertySpec;
+    keyPropertySeparator?: string;
     autoGenerateKey?: boolean;
 };

package/dist/esm/types/dcupl.types.d.ts

@@ -1,12 +1,12 @@
-import { DcuplUpdateMessage } from '../changeDetection';
-import { PivotOptions } from '../pivot';
-import { AggregationOptions } from './aggregation.types';
-import { DcuplFacetOptions } from './facets.types';
-import { DcuplGroupByOptions } from './group-by.types';
-import { DcuplItemsOptions } from './list.types';
-import { DcuplGlobalQueryOptions } from './query.types';
-import { SuggestionOptions } from './suggestion.types';
-import { LogLevel, LogEntry } from '../logger';
+import { DcuplUpdateMessage } from '../changeDetection.js';
+import { PivotOptions } from '../pivot.js';
+import { AggregationOptions } from './aggregation.types.js';
+import { DcuplFacetOptions } from './facets.types.js';
+import { DcuplGroupByOptions } from './group-by.types.js';
+import { DcuplItemsOptions } from './list.types.js';
+import { DcuplGlobalQueryOptions } from './query.types.js';
+import { SuggestionOptions } from './suggestion.types.js';
+import { LogLevel, LogEntry } from '../logger/index.js';
 export type DcuplInitOptions = {
     config?: DcuplInitConfig;
     /**
@@ -85,9 +85,9 @@ export type DcuplPartialUpdateConfig = {
      */
     itemRatioThreshold?: number;
     /**
-     * Threshold for cache invalidation (0-1). If more than this percentage of models are affected,
-     * the entire cache will be cleared instead of selective invalidation.
-     * Default: 0.7 (70%)
+     * @deprecated No effect since 2.0.0-beta.14 and ignored. It gated a global
+     * query cache that was never populated; query/facet caches live per list and
+     * are invalidated lazily on every update (#245). Will be removed in 2.0.0.
      */
     cacheInvalidationThreshold?: number;
     /**
@@ -98,6 +98,20 @@ export type DcuplPartialUpdateConfig = {
 };
 export type DcuplInitQualityConfig = {
     enabled: boolean;
+    /**
+     * Maximum number of stored error objects per (model, property, errorType)
+     * group. Quality errors are still counted exactly beyond this limit and are
+     * reachable via `dcupl.quality.errors.summary()` or the
+     * `$DcuplErrorTrackingSummary` model; only the retained error objects (and
+     * the `$DcuplErrorTrackingErrors` model) are bounded. Retained records of a
+     * capped group carry `truncated: true` and `groupTotal`. Default: 1000.
+     *
+     * Note: for error groups whose true count exceeds `maxErrorsPerGroup`,
+     * partial-update cleanup may cause the totals to slightly
+     * over-report, since over-cap occurrences are counted but never stored as
+     * error objects and therefore cannot be decremented on removal.
+     */
+    maxErrorsPerGroup?: number;
 };
 export type DcuplInitErrorTrackingConfig = {
     enabled: boolean;

package/dist/esm/types/facets.types.d.ts

@@ -1,4 +1,4 @@
-import { ListItem } from './data.types';
+import { ListItem } from './data.types.js';
 export type DcuplFacetOptions = {
     attribute: string;
     count?: number;
@@ -6,6 +6,19 @@ export type DcuplFacetOptions = {
     excludeUndefineds?: boolean;
     excludeUnresolved?: boolean;
     calculateResults?: boolean;
+    /**
+     * Opt-in deterministic ordering. See `DcuplFilterOptions.sort` for full semantics.
+     * When omitted the fast (insertion-order) path is preserved.
+     */
+    sort?: 'size-desc' | 'size-asc' | 'value-asc' | 'value-desc';
+    /**
+     * Key of the query group to leave out when counting (disjunctive facets):
+     * each facet value is counted under every other group of the current query,
+     * so selecting one value does not collapse its siblings.
+     * Defaults to the group keyed by `attribute`. A key that matches no group
+     * leaves nothing out. `selected` reflects this group's conditions on `attribute`.
+     */
+    excludeGroup?: string;
 };
 export type DcuplFacet = {
     key: string;

package/dist/esm/types/filter.types.d.ts

@@ -1,6 +1,6 @@
-import { DcuplQueryGroup, ListItem } from '.';
-import { CatalogApiOptions } from './list.types';
-import { FilterComparisonType } from './model.types';
+import { DcuplQueryGroup, ListItem } from './index.js';
+import { CatalogApiOptions } from './list.types.js';
+import { FilterComparisonType } from './model.types.js';
 export type NumberConstraintOperators = {
     gt?: number;
     lt?: number;

package/dist/esm/types/group-by.types.d.ts

@@ -1,5 +1,5 @@
-import { AggregationOptions } from './aggregation.types';
-import { DcuplItemsOptions } from './list.types';
+import { AggregationOptions } from './aggregation.types.js';
+import { DcuplItemsOptions } from './list.types.js';
 export type DcuplSectionItemOption<T> = DcuplItemsOptions<T> & {
     key: string;
 };

package/dist/esm/types/index.d.ts

@@ -1,16 +1,17 @@
-export * from './aggregation.types';
-export * from './app-loader.types';
-export * from './data.types';
-export * from './dcupl.types';
-export * from './facets.types';
-export * from './filter.types';
-export * from './group-by.types';
-export * from './internal.types';
-export * from './list.types';
-export * from './model.types';
-export * from './projection.types';
-export * from './quality.types';
-export * from './query.types';
-export * from './section.types';
-export * from './suggestion.types';
-export * from './testing.types';
+export * from './aggregation.types.js';
+export * from './app-loader.types.js';
+export * from './key-property.types.js';
+export * from './data.types.js';
+export * from './dcupl.types.js';
+export * from './facets.types.js';
+export * from './filter.types.js';
+export * from './group-by.types.js';
+export * from './internal.types.js';
+export * from './list.types.js';
+export * from './model.types.js';
+export * from './projection.types.js';
+export * from './quality.types.js';
+export * from './query.types.js';
+export * from './section.types.js';
+export * from './suggestion.types.js';
+export * from './testing.types.js';

package/dist/esm/types/internal.types.d.ts

@@ -1,4 +1,4 @@
-import { ListItem } from './data.types';
+import { ListItem } from './data.types.js';
 export type InverseIndexReferenceMap = Map<string, InverseIndexValuesMap>;
 export type InverseIndexValuesMap = Map<string, Set<string>>;
 export type InverseIndexDataMap = Map<string, InverseIndexDataValuesMap>;

package/dist/esm/types/key-property.types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Specifies the property (or properties) on a row that uniquely identifies it.
+ *
+ * - A single string names one property: `keyProperty: 'id'`.
+ * - A non-empty array of strings produces a composite key by joining the
+ *   stringified values of each property with the configured separator
+ *   (default `::`): `keyProperty: ['ID', 'Language']` → `.key === 'A1::en'`.
+ *
+ * The order of array entries is significant and preserved verbatim.
+ */
+export type KeyPropertySpec = string | readonly string[];

package/dist/esm/types/list.types.d.ts

@@ -1,7 +1,7 @@
-import { DcuplGlobalQueryOptions } from './query.types';
-import { ViewDefinition, ModelAttribute } from './model.types';
-import { Projection, SortingProjection } from './projection.types';
-import { ListItem } from './data.types';
+import { DcuplGlobalQueryOptions } from './query.types.js';
+import { ViewDefinition, ModelAttribute } from './model.types.js';
+import { Projection, SortingProjection } from './projection.types.js';
+import { ListItem } from './data.types.js';
 export type DcuplItemsOptions<T> = {
     start?: number;
     count?: number;
@@ -22,6 +22,27 @@ export type DcuplFilterOptions = CatalogApiOptions & {
     excludeUndefineds?: boolean;
     excludeUnresolved?: boolean;
     count?: number;
+    /**
+     * Opt-in deterministic ordering for facet results.
+     *
+     * When omitted (default), results are returned in inverse-index iteration
+     * order and `count` truncation is applied mid-iteration. This is the
+     * fast path and matches all existing call sites.
+     *
+     * When set, `getFacets` walks all facet keys, computes real sizes
+     * (overriding `calculateFacets: false`), applies the chosen sort with
+     * deterministic tie-break, and truncates to `count` after sorting.
+     * This is the slow but correct path — opt in when ordering matters.
+     *
+     * Tie-break for size sorts is always `value` ascending with `undefined`
+     * last. `value-desc` keeps `undefined` last as well.
+     */
+    sort?: 'size-desc' | 'size-asc' | 'value-asc' | 'value-desc';
+    /**
+     * Key of the query group left out when counting facet entries.
+     * Defaults to the group keyed by the faceted attribute. See `DcuplFacetOptions.excludeGroup`.
+     */
+    excludeGroup?: string;
 };
 export type DcuplFiltersOptions = DcuplFilterOptions & {
     filterKeys?: string[];