@dcupl/common 2.0.0-beta.20 → 2.0.0-beta.22

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

@@ -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/queryData.d.ts

@@ -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/types/facets.types.d.ts

@@ -11,6 +11,14 @@ export type DcuplFacetOptions = {
      * 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/list.types.d.ts

@@ -38,6 +38,11 @@ export type DcuplFilterOptions = CatalogApiOptions & {
      * 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[];

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

@@ -7,12 +7,13 @@ import { Projection, SortingProjection } from './projection.types.js';
  * - `removeWhitespace`: Remove all whitespace characters
  */
 export type DcuplQueryTransformOptions = 'lowercase' | 'trim' | 'removeWhitespace';
-export declare const DcuplQueryOperatorsAsArray: readonly ["eq", "find", "gt", "gte", "lt", "lte", "typeof", "isTruthy", "size"];
+export declare const DcuplQueryOperatorsAsArray: readonly ["eq", "in", "find", "gt", "gte", "lt", "lte", "typeof", "isTruthy", "size"];
 /**
  * Query operators for filtering data.
  *
  * Available operators:
  * - `eq`: Equality check - matches exact values
+ * - `in`: Membership check - matches if the value equals any value of a list (`eq`'s equality)
  * - `find`: Regex / exact / object match - bare string is exact-equality, `/regex/` for substring/pattern, object for property match
  * - `gt`: Greater than - numeric/date comparison (exclusive)
  * - `gte`: Greater than or equal - numeric/date comparison (inclusive)
@@ -27,6 +28,9 @@ export declare const DcuplQueryOperatorsAsArray: readonly ["eq", "find", "gt", "
  * // Equality
  * { operator: 'eq', attribute: 'status', value: 'active' }
  *
+ * // Any of several values
+ * { operator: 'in', attribute: 'status', value: ['active', 'pending'] }
+ *
  * // Numeric comparison
  * { operator: 'gte', attribute: 'price', value: 100 }
  *
@@ -79,7 +83,13 @@ type DcuplQueryBase = {
          */
         transform?: DcuplQueryTransformOptions[];
         /**
-         * Invert the query result (NOT operation).
+         * Invert the query result (NOT operation). Applies to every built-in operator.
+         * A missing (`undefined`/`null`) value matches neither way, except for `eq`,
+         * `in`, `typeof` and `isTruthy`, which compare against it. A list of values (an
+         * `Array<…>` property or a dotted path through a multi-valued reference) is
+         * checked per value instead: an empty list, or a `null` in it, simply does not
+         * match, so `invert` does match it (`memberships.user.daysInactive gte 60`
+         * inverted includes items with no memberships).
          * @example
          * ```typescript
          * // Find items where status is NOT 'active'
@@ -88,9 +98,14 @@ type DcuplQueryBase = {
          */
         invert?: boolean;
         /**
-         * When querying array values, determines match behavior.
+         * When querying array values, determines match behavior. Array values are
+         * `Array<…>` properties and dotted paths through a multi-valued reference
+         * (`memberships.role` compares the `role` of every membership).
          * - `some`: Match if at least one array element matches (default)
-         * - `every`: Match only if all array elements match
+         * - `every`: Match only if all array elements match — and there is at least
+         *   one: an empty array (or a reference with no items) never matches
+         *
+         * On a reference path, leaves that are `undefined` are skipped.
          *
          * @example
          * ```typescript
@@ -127,14 +142,58 @@ type DcuplQueryEq = DcuplQueryBase & {
      */
     value: any;
 };
+/**
+ * Membership query - matches if the attribute's value equals **any** value of
+ * the list, using the same equality as `eq`: a string (or `{ key }`) matches a
+ * reference by its key and a date by its ISO string. It answers like an `or`
+ * group of one `eq` condition per listed value.
+ *
+ * - On an `Array<…>` property or a dotted path through a multi-valued
+ *   reference, `arrayValueHandling: 'some'` (default) matches if at least one
+ *   value is listed; `'every'` if every value is listed (and there is at least one).
+ * - `options.invert` is NOT IN; like `eq`, a missing value then matches.
+ * - `options.transform` applies to the attribute value and to every listed value.
+ * - `null` in the list matches `null`, like `eq` with `null`.
+ * - An empty list matches nothing (and everything under `invert`).
+ * - `value` must be an array; anything else throws. (`eq` with an array value
+ *   compares the whole array instead.)
+ *
+ * @example
+ * ```typescript
+ * // Items whose status is 'active' or 'pending'
+ * { operator: 'in', attribute: 'status', value: ['active', 'pending'] }
+ *
+ * // Through references (2 hops)
+ * { operator: 'in', attribute: 'customer.address.city', value: ['Vienna', 'Graz'] }
+ *
+ * // Reference keys, as strings or { key }
+ * { operator: 'in', attribute: 'category', value: ['cat-1', { key: 'cat-2' }] }
+ *
+ * // Every tag is one of the listed ones
+ * { operator: 'in', attribute: 'tags', value: ['sale', 'new'], options: { arrayValueHandling: 'every' } }
+ *
+ * // NOT IN
+ * { operator: 'in', attribute: 'status', value: ['archived', 'deleted'], options: { invert: true } }
+ * ```
+ */
+type DcuplQueryIn = DcuplQueryBase & {
+    operator: 'in';
+    /**
+     * The values to match; any one of them matching is enough.
+     * Note: For indexed search optimization, use string or { key: string } values.
+     */
+    value: unknown[];
+};
 /**
  * Find query - regex / exact / object match.
  *
  * Matching depends on the shape of `value`:
  * - **Bare string** (e.g. `'search'`) — exact-equality against the *whole* field
  *   value, NOT a substring. `find` with `'Ball'` does not match `'Soccer Ball'`.
- * - **Slash-delimited regex** (e.g. `'/search/'`, `'/^foo/i'`) — JS regex literal;
- *   use this for substring and pattern matching.
+ * - **Slash-delimited regex** (e.g. `'/search/'`, `'/^foo/'`) — the text between the
+ *   slashes is a JS regex; use this for substring and pattern matching. Flags go in
+ *   `options.regexFlags` (`'/^foo/'` + `regexFlags: 'i'`), not after the closing
+ *   slash: `'/^foo/i'` is a bare string and matches exactly.
  * - **Object** (e.g. `{ key: 'value' }`) — property matching against the field.
  *
  * @example
@@ -142,6 +201,9 @@ type DcuplQueryEq = DcuplQueryBase & {
  * // Substring search — slash-delimited regex (bare string would be exact-match)
  * { operator: 'find', attribute: 'description', value: '/search/' }
  *
+ * // Case-insensitive substring search
+ * { operator: 'find', attribute: 'description', value: '/search/', options: { regexFlags: 'i' } }
+ *
  * // Exact-match the whole field value
  * { operator: 'find', attribute: 'status', value: 'active' }
  *
@@ -155,6 +217,13 @@ type DcuplQueryFind = DcuplQueryBase & {
      * Bare string (exact-match), `/regex/` (substring/pattern), or object (property match).
      */
     value: Record<string, unknown> | string;
+    options?: {
+        /**
+         * Flags for a `/regex/` value, e.g. `'i'` for case-insensitive. Ignored for any
+         * other value; invalid flags match nothing.
+         */
+        regexFlags?: string;
+    };
 };
 /**
  * Numeric/date comparison queries.
@@ -260,7 +329,7 @@ type DcuplQuerySize = DcuplQueryBase & {
  * };
  * ```
  */
-export type DcuplQuery = DcuplQueryEq | DcuplQueryNumbers | DcuplQueryTypeOf | DcuplQueryIsTruthy | DcuplQuerySize | DcuplQueryFind;
+export type DcuplQuery = DcuplQueryEq | DcuplQueryIn | DcuplQueryNumbers | DcuplQueryTypeOf | DcuplQueryIsTruthy | DcuplQuerySize | DcuplQueryFind;
 /**
  * Query group - combines multiple conditions with AND/OR logic.
  * Groups can be nested to create complex filter expressions.
@@ -311,13 +380,24 @@ export type DcuplQueryGroup<ChildQuery extends DcuplQuery | DcuplQueryGroup = an
      */
     __type?: 'group';
     /**
-     * Combination logic for conditions in this group.
-     * Defaults to 'and' if not specified.
+     * Combination logic for conditions in this group. Set it explicitly; when omitted,
+     * the effective behaviour depends on where the group ends up:
+     * - Groups created by the query builder (`addGroup` / `setGroup` / `apply(group)` for a
+     *   group not yet present) are stored as `'or'`. When `addGroup` extends an existing keyed
+     *   group, that group keeps its current groupType.
+     * - The root query (`groupKey: 'root'`) is evaluated as `'and'`.
+     * - A nested group that reaches evaluation without a groupType (e.g. passed inside a full
+     *   query via `apply({ groupKey: 'root', ... })`, `init` or `execute`, or stored by
+     *   `setGroup` replacing an existing group) is intersected like `'and'`, with one
+     *   difference: if the running intersection becomes empty, the matches of the next
+     *   condition replace it instead of the result staying empty.
      */
     groupType?: DcuplQueryType;
     /**
      * Optional identifier for this group.
-     * Useful for tracking or removing specific query groups.
+     * Useful for tracking or removing specific query groups. Adding a group with an
+     * existing groupKey extends that group; a group without groupKey is always added
+     * as a new group.
      */
     groupKey?: string;
     /**
@@ -412,7 +492,10 @@ export type DcuplGlobalManyItemOptions<T> = {
 };
 /**
  * Options for executing queries on a list instance.
- * Combines query conditions with data retrieval options.
+ * Combines optional query conditions with data retrieval options.
+ *
+ * `queries` is optional: without it the list's own (live) query is used, so
+ * item options alone (`projection`, `start`, `count`, `sort`) are valid.
  *
  * @see ListQueryOptions - Type alias with clearer naming
  *
@@ -426,9 +509,12 @@ export type DcuplGlobalManyItemOptions<T> = {
  *   count: 10
  * };
  * const results = list.catalog.query.execute(options);
+ *
+ * // The list's own query, projected
+ * const projected = list.catalog.query.execute({ projection: { $: false, name: true } });
  * ```
  */
-export type DcuplListQueryOptions<T> = DcuplItemOptions<T> & DcuplQueryGroup;
+export type DcuplListQueryOptions<T> = DcuplItemOptions<T> & Partial<DcuplQueryGroup>;
 /**
  * Options for retrieving a specific item from a list instance.
  */

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

@@ -7,6 +7,11 @@ type SuggestionOptionsBase = {
     excludeUndefineds?: boolean;
     excludeNulls?: boolean;
     transform?: DcuplQueryTransformOptions[];
+    /**
+     * Flags for a `/pattern/` value, e.g. `'i'` for case-insensitive. Ignored for any
+     * other value; invalid flags suggest nothing.
+     */
+    regexFlags?: string;
 };
 type SuggestionOptionsFiltered = SuggestionOptionsBase & {
     relevantData?: 'filtered';