@ls-stack/utils 3.26.1 → 3.27.0

package/lib/testUtils.cjs

@@ -59,6 +59,30 @@ function filterAndMap(array, mapFilter) {
   }
   return result;
 }
+function sortBy(arr, sortByValue, props = "asc") {
+  const order = Array.isArray(props) || typeof props === "string" ? props : props.order ?? "asc";
+  return [...arr].sort((a, b) => {
+    const _aPriority = sortByValue(a);
+    const _bPriority = sortByValue(b);
+    const aPriority = Array.isArray(_aPriority) ? _aPriority : [_aPriority];
+    const bPriority = Array.isArray(_bPriority) ? _bPriority : [_bPriority];
+    for (let i = 0; i < aPriority.length; i++) {
+      const levelOrder = typeof order === "string" ? order : order[i] ?? "asc";
+      const aP = aPriority[i] ?? 0;
+      const bP = bPriority[i] ?? 0;
+      if (aP === bP) {
+        continue;
+      }
+      if (bP === Infinity || aP === -Infinity || aP < bP) {
+        return levelOrder === "asc" ? -1 : 1;
+      }
+      if (aP === Infinity || bP === -Infinity || aP > bP) {
+        return levelOrder === "asc" ? 1 : -1;
+      }
+    }
+    return 0;
+  });
+}
 function arrayWithPrevAndIndex(array) {
   return array.map((item, i) => ({
     item,
@@ -135,8 +159,57 @@ function deepEqual(foo, bar, maxDepth = 20) {
 function filterObjectOrArrayKeys(objOrArray, {
   filterKeys,
   rejectKeys,
-  rejectEmptyObjectsInArray = true
+  rejectEmptyObjectsInArray = true,
+  sortKeys = "simpleValuesFirst",
+  sortPatterns
 }) {
+  function getNestedValue(obj, path) {
+    const parts = path.split(".");
+    let current = obj;
+    for (const part of parts) {
+      if (current == null || typeof current !== "object") {
+        return void 0;
+      }
+      current = current[part];
+    }
+    return current;
+  }
+  function evaluateCondition(item, condition) {
+    const value = getNestedValue(item, condition.property);
+    let valueStr = String(value);
+    if (condition.caseInsensitive) {
+      valueStr = valueStr.toLowerCase();
+    }
+    const processValue = (v) => condition.caseInsensitive ? v.toLowerCase() : v;
+    switch (condition.operator) {
+      case "=":
+        return condition.values.some((v) => valueStr === processValue(v));
+      case "!=":
+        return condition.values.every((v) => valueStr !== processValue(v));
+      case "*=":
+        return condition.values.some((v) => valueStr.includes(processValue(v)));
+      case "!*=":
+        return condition.values.every(
+          (v) => !valueStr.includes(processValue(v))
+        );
+      case "^=":
+        return condition.values.some(
+          (v) => valueStr.startsWith(processValue(v))
+        );
+      case "!^=":
+        return condition.values.every(
+          (v) => !valueStr.startsWith(processValue(v))
+        );
+      case "$=":
+        return condition.values.some((v) => valueStr.endsWith(processValue(v)));
+      case "!$=":
+        return condition.values.every(
+          (v) => !valueStr.endsWith(processValue(v))
+        );
+      default:
+        return false;
+    }
+  }
   const toArray = (v) => v === void 0 ? [] : Array.isArray(v) ? v : [v];
   const filterPatternsRaw = toArray(filterKeys);
   const rejectPatternsRaw = toArray(rejectKeys);
@@ -144,9 +217,46 @@ function filterObjectOrArrayKeys(objOrArray, {
   const hasRejects = rejectPatternsRaw.length > 0;
   const expandedFilterPatterns = filterPatternsRaw.flatMap(expandPatterns);
   const expandedRejectPatterns = rejectPatternsRaw.flatMap(expandPatterns);
-  const filterPatterns = expandedFilterPatterns.map(parsePattern);
+  const { filterOnlyPatterns, combinedPatterns } = separateFilterPatterns(
+    expandedFilterPatterns
+  );
+  const filterPatterns = filterOnlyPatterns.map(parsePattern);
   const rejectPatterns = expandedRejectPatterns.map(parsePattern);
-  function matchPath(path, pattern) {
+  const sortPatternsRaw = toArray(sortPatterns);
+  const expandedSortPatterns = sortPatternsRaw.flatMap(expandPatterns);
+  const sortPatternsParsed = expandedSortPatterns.map(parsePattern);
+  let dataToProcess = objOrArray;
+  if (combinedPatterns.length > 0) {
+    const groupedByFilter = /* @__PURE__ */ new Map();
+    for (const { filterPart, fieldPart } of combinedPatterns) {
+      if (!groupedByFilter.has(filterPart)) {
+        groupedByFilter.set(filterPart, []);
+      }
+      groupedByFilter.get(filterPart).push(fieldPart);
+    }
+    const combinedResult = Array.isArray(objOrArray) ? [] : {};
+    for (const [filterPart, fieldParts] of groupedByFilter) {
+      const filteredResult = filterObjectOrArrayKeys(objOrArray, {
+        filterKeys: [filterPart],
+        rejectKeys,
+        rejectEmptyObjectsInArray
+      });
+      const fieldSelectedResult = filterObjectOrArrayKeys(filteredResult, {
+        filterKeys: fieldParts,
+        rejectEmptyObjectsInArray
+      });
+      if (Array.isArray(combinedResult) && Array.isArray(fieldSelectedResult)) {
+        combinedResult.push(...fieldSelectedResult);
+      } else if (!Array.isArray(combinedResult) && !Array.isArray(fieldSelectedResult)) {
+        Object.assign(combinedResult, fieldSelectedResult);
+      }
+    }
+    if (filterOnlyPatterns.length === 0) {
+      return combinedResult;
+    }
+    dataToProcess = combinedResult;
+  }
+  function matchPath(path, pattern, value) {
     function rec(pi, pti) {
       if (pti >= pattern.length) return pi === path.length;
       const pt = pattern[pti];
@@ -187,12 +297,91 @@ function filterObjectOrArrayKeys(objOrArray, {
             if (okLower && okUpper) return rec(pi + 1, pti + 1);
           }
           return false;
+        case "INDEX_FILTER":
+          if (ct.type === "INDEX" && value !== void 0) {
+            const results = pt.conditions.map(
+              (cond) => evaluateCondition(value, cond)
+            );
+            const matches = pt.logic === "AND" ? results.every((r) => r) : results.some((r) => r);
+            if (matches) return rec(pi + 1, pti + 1);
+          }
+          return false;
       }
     }
     return rec(0, 0);
   }
-  const matchesAnyFilter = (path) => filterPatterns.some((p) => matchPath(path, p));
-  const matchesAnyReject = (path) => rejectPatterns.some((p) => matchPath(path, p));
+  const matchesAnyFilter = (path, value) => filterPatterns.some((p) => matchPath(path, p, value));
+  const matchesAnyReject = (path, value) => rejectPatterns.some((p) => matchPath(path, p, value));
+  function getSortPriority(path) {
+    for (let i = 0; i < sortPatternsParsed.length; i++) {
+      if (matchPath(path, sortPatternsParsed[i])) {
+        return i;
+      }
+    }
+    return sortPatternsParsed.length;
+  }
+  function applySortKeys(keys, obj, sortOrder) {
+    if (sortOrder === "asc") {
+      return [...keys].sort();
+    }
+    if (sortOrder === "desc") {
+      return [...keys].sort().reverse();
+    }
+    return sortBy(
+      sortBy(keys, (k) => k),
+      (key) => {
+        const value = obj[key];
+        if (value !== void 0 && value !== null) {
+          if (Array.isArray(value) && value.length === 0) return 0;
+          if (isPlainObject(value)) {
+            const objLength = Object.keys(value).length;
+            return 1.99 + objLength * -1e-3;
+          }
+          if (Array.isArray(value)) {
+            const allItemsArePrimitives = value.every(
+              (item) => typeof item === "string" || typeof item === "number" || typeof item === "boolean" || item === null || item === void 0
+            );
+            if (allItemsArePrimitives) {
+              return 1.9 + value.length * -1e-3;
+            } else {
+              return 1.5 + value.length * -0.01;
+            }
+          }
+          if (typeof value === "boolean") return 4;
+          if (typeof value === "number") return 3.5;
+          if (typeof value === "string" && value.length < 20) return 3;
+          return 2;
+        }
+        return 0;
+      },
+      "desc"
+    );
+  }
+  function sortKeysWithPatterns(keys, obj, currentPath) {
+    if (!sortKeys && sortPatternsParsed.length === 0) {
+      return keys;
+    }
+    if (sortPatternsParsed.length === 0) {
+      return sortKeys ? applySortKeys(keys, obj, sortKeys) : keys;
+    }
+    const sortedKeys = [...keys].sort((a, b) => {
+      const pathA = currentPath.concat({ type: "KEY", name: a });
+      const pathB = currentPath.concat({ type: "KEY", name: b });
+      const priorityA = getSortPriority(pathA);
+      const priorityB = getSortPriority(pathB);
+      if (priorityA !== priorityB) {
+        return priorityA - priorityB;
+      }
+      if (sortKeys === "desc") {
+        return b.localeCompare(a);
+      }
+      if (sortKeys === "asc") {
+        return a.localeCompare(b);
+      }
+      return 0;
+    });
+    return sortedKeys;
+  }
   const build = (value, path, allowedByFilter, stack2, isRoot, parentIsArray) => {
     if (Array.isArray(value)) {
       if (stack2.has(value)) {
@@ -203,9 +392,9 @@ function filterObjectOrArrayKeys(objOrArray, {
       const includeAllChildren = allowedByFilter || !hasFilters;
       for (let index = 0; index < value.length; index += 1) {
         const childPath = path.concat({ type: "INDEX", index });
-        if (hasRejects && matchesAnyReject(childPath)) continue;
         const child = value[index];
-        const directInclude = hasFilters ? matchesAnyFilter(childPath) : true;
+        if (hasRejects && matchesAnyReject(childPath, child)) continue;
+        const directInclude = hasFilters ? matchesAnyFilter(childPath, child) : true;
         const childAllowed = includeAllChildren || directInclude;
         if (isPlainObject(child) || Array.isArray(child)) {
           const builtChild = build(
@@ -240,7 +429,8 @@ function filterObjectOrArrayKeys(objOrArray, {
       stack2.add(value);
       const result = {};
       const includeAllChildren = allowedByFilter || !hasFilters;
-      for (const key of Object.keys(value)) {
+      const sortedKeys = sortKeysWithPatterns(Object.keys(value), value, path);
+      for (const key of sortedKeys) {
         const childPath = path.concat({ type: "KEY", name: key });
         if (hasRejects && matchesAnyReject(childPath)) continue;
         const val = value[key];
@@ -286,16 +476,123 @@ function filterObjectOrArrayKeys(objOrArray, {
   const initialAllowed = !hasFilters;
   const stack = /* @__PURE__ */ new WeakSet();
   const built = build(
-    objOrArray,
+    dataToProcess,
     startPath,
     initialAllowed,
     stack,
     true,
     false
   );
-  if (built === void 0) return Array.isArray(objOrArray) ? [] : {};
+  if (built === void 0) return Array.isArray(dataToProcess) ? [] : {};
   return built;
 }
+function parseFilterConditions(filterContent) {
+  const conditions = [];
+  let logic = "AND";
+  const caseInsensitive = filterContent.startsWith("i");
+  const content = caseInsensitive ? filterContent.slice(1) : filterContent;
+  const hasAnd = content.includes("&&");
+  const hasOr = content.includes(" || ");
+  if (hasAnd && hasOr) {
+    throw new Error(
+      "Mixing && and || operators in the same filter is not supported. Use separate filter patterns instead."
+    );
+  }
+  const andGroups = content.split("&&").map((s) => s.trim());
+  for (const andGroup of andGroups) {
+    if (andGroup.includes(" || ")) {
+      logic = "OR";
+      const orConditions = andGroup.split(" || ").map((s) => s.trim());
+      for (const orCondition of orConditions) {
+        const parsed = parseSingleCondition(orCondition, caseInsensitive);
+        if (parsed) {
+          conditions.push(parsed);
+        }
+      }
+    } else {
+      const parsed = parseSingleCondition(andGroup, caseInsensitive);
+      if (parsed) {
+        conditions.push(parsed);
+      }
+    }
+  }
+  if (conditions.length === 0) {
+    return null;
+  }
+  return {
+    type: "INDEX_FILTER",
+    conditions,
+    logic
+  };
+}
+function parseSingleCondition(condition, caseInsensitive = false) {
+  const cleanCondition = condition.startsWith("%") ? condition.slice(1) : condition;
+  let operator = null;
+  let operatorIndex = -1;
+  let operatorLength = 0;
+  const operators = [
+    ["!*=", "!*="],
+    ["!^=", "!^="],
+    ["!$=", "!$="],
+    ["!=", "!="],
+    ["*=", "*="],
+    ["^=", "^="],
+    ["$=", "$="],
+    ["=", "="]
+  ];
+  for (const [op, opType] of operators) {
+    const index = cleanCondition.indexOf(op);
+    if (index !== -1) {
+      operator = opType;
+      operatorIndex = index;
+      operatorLength = op.length;
+      break;
+    }
+  }
+  if (operator === null || operatorIndex === -1) {
+    return null;
+  }
+  const property = cleanCondition.slice(0, operatorIndex).trim();
+  const valueStr = cleanCondition.slice(operatorIndex + operatorLength).trim();
+  const values = [];
+  if (valueStr.includes(" | ")) {
+    const parts = valueStr.split(" | ");
+    for (const part of parts) {
+      const trimmed = part.trim();
+      const value = trimmed.startsWith('"') && trimmed.endsWith('"') ? trimmed.slice(1, -1) : trimmed;
+      values.push(value);
+    }
+  } else {
+    const trimmed = valueStr.trim();
+    const value = trimmed.startsWith('"') && trimmed.endsWith('"') ? trimmed.slice(1, -1) : trimmed;
+    values.push(value);
+  }
+  return {
+    property,
+    operator,
+    values,
+    caseInsensitive
+  };
+}
+function separateFilterPatterns(patterns) {
+  const filterOnlyPatterns = [];
+  const combinedPatterns = [];
+  for (const pattern of patterns) {
+    const filterMatch = pattern.match(/^(.+\[[i%][^[\]]*\])\.(.+)$/);
+    if (filterMatch?.[1] && filterMatch[2]) {
+      const filterPart = filterMatch[1];
+      const fieldPart = filterMatch[2];
+      const baseArrayPath = filterPart.replace(/\[[i%][^[\]]*\]/, "[*]");
+      combinedPatterns.push({
+        filterPart,
+        fieldPart: `${baseArrayPath}.${fieldPart}`
+      });
+    } else {
+      filterOnlyPatterns.push(pattern);
+    }
+  }
+  return { filterOnlyPatterns, combinedPatterns };
+}
 function expandPatterns(pattern) {
   function expandSingle(str) {
     const start = str.indexOf("(");
@@ -339,7 +636,20 @@ function parsePattern(pattern) {
     if (ch === "[") {
       const end = pattern.indexOf("]", i + 1);
       const inside = end === -1 ? pattern.slice(i + 1) : pattern.slice(i + 1, end);
-      if (inside === "*") {
+      if (inside.startsWith("%") || inside.startsWith("i%")) {
+        let filterContent;
+        if (inside.startsWith("i%")) {
+          filterContent = `i${inside.slice(2)}`;
+        } else if (inside.startsWith("%")) {
+          filterContent = inside.slice(1);
+        } else {
+          filterContent = inside;
+        }
+        const filterToken = parseFilterConditions(filterContent);
+        if (filterToken) {
+          tokens.push(filterToken);
+        }
+      } else if (inside === "*") {
         tokens.push({ type: "INDEX_ANY" });
       } else if (inside.includes("-")) {
         const parts = inside.split("-");
@@ -1035,6 +1345,8 @@ function compactSnapshot(value, {
   showBooleansAs = true,
   rejectKeys,
   filterKeys,
+  sortKeys,
+  sortPatterns,
   ...options
 } = {}) {
   let processedValue = value;
@@ -1042,7 +1354,9 @@ function compactSnapshot(value, {
     if (isPlainObject(processedValue) || Array.isArray(processedValue)) {
       processedValue = filterObjectOrArrayKeys(processedValue, {
         rejectKeys,
-        filterKeys
+        filterKeys,
+        sortKeys,
+        sortPatterns
       });
     }
   }

package/lib/testUtils.d.cts

@@ -71,6 +71,13 @@ declare function waitController(): {
  *   - `'[4-*]'` - All items of the array from the fourth index to the end
  * - Expanding the patterns with parentheses:
  *   - `'prop.test.(prop1|prop2|prop3.prop4)'` - Will produce `prop.test.prop1`, `prop.test.prop2`, and `prop.test.prop3.prop4`
+ * - Array filtering by value:
+ *   - `'users[%name="John"]'` - Filters the `users` with the `name` property equal to `John`
+ *   - `'users[%name="John" | "Jane"]'` - Filters the `users` with the `name` property equal to `John` or `Jane`
+ *   - `'users[%name="John" | "Jane" && %age=20]'` - AND and OR are supported by using `&&` and `||`, nesting logical operators is not supported yet
+ *   - `'users[%config.name="John" | "Jane"]'` - Dot notation is supported
+ *
+ * Check more supported patterns in {@link filterObjectOrArrayKeys} docs.
  *
  * @param value - The value to snapshot.
  * @param options - The options for the snapshot.
@@ -81,9 +88,11 @@ declare function waitController(): {
  * @param options.rejectKeys - The keys to reject.
  * @param options.filterKeys - The keys to filter.
  * @param options.ignoreProps - The props to ignore.
+ * @param options.sortKeys - Sort all keys by a specific order (default: `simpleValuesFirst`).
+ * @param options.sortPatterns - Sort specific keys by pattern. Use to control the order of specific properties. The same patterns as `filterKeys` are supported.
  * @returns The compact snapshot of the value.
  */
-declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLength, showUndefined, showBooleansAs, rejectKeys, filterKeys, ...options }?: YamlStringifyOptions & {
+declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLength, showUndefined, showBooleansAs, rejectKeys, filterKeys, sortKeys, sortPatterns, ...options }?: YamlStringifyOptions & {
     showBooleansAs?: boolean | {
         props?: Record<string, {
             trueText?: string;
@@ -93,47 +102,10 @@ declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLengt
         trueText?: string;
         falseText?: string;
     };
-    /**
-     * Reject (exclude) keys from the snapshot using pattern matching.
-     *
-     * **Examples:**
-     * ```typescript
-     * // Reject root-level 'secret' only
-     * rejectKeys: ['secret']
-     *
-     * // Reject nested 'password' properties only
-     * rejectKeys: ['*.password']
-     *
-     * // Reject any 'apiKey' property at any level
-     * rejectKeys: ['*apiKey']
-     *
-     * // Reject specific nested path
-     * rejectKeys: ['user.settings.theme']
-     * ```
-     */
     rejectKeys?: string[] | string;
-    /**
-     * Filter (include only) keys that match the specified patterns.
-     *
-     * **Examples:**
-     * ```typescript
-     * // Include only root-level 'user'
-     * filterKeys: ['user']
-     *
-     * // Include all 'name' properties at any level
-     * filterKeys: ['*name']
-     *
-     * // Include only nested 'id' properties
-     * filterKeys: ['*.id']
-     *
-     * // Include specific nested paths
-     * filterKeys: ['user.profile.email', 'settings.theme']
-     * ```
-     *
-     * **Note:** When filtering, parent paths are automatically included if needed
-     * to preserve the structure for nested matches.
-     */
     filterKeys?: string[] | string;
+    sortKeys?: 'asc' | 'desc' | 'simpleValuesFirst' | false;
+    sortPatterns?: string[];
 }): string;
 
 export { compactSnapshot, createLoggerStore, getResultFn, waitController };

package/lib/testUtils.d.ts

@@ -71,6 +71,13 @@ declare function waitController(): {
  *   - `'[4-*]'` - All items of the array from the fourth index to the end
  * - Expanding the patterns with parentheses:
  *   - `'prop.test.(prop1|prop2|prop3.prop4)'` - Will produce `prop.test.prop1`, `prop.test.prop2`, and `prop.test.prop3.prop4`
+ * - Array filtering by value:
+ *   - `'users[%name="John"]'` - Filters the `users` with the `name` property equal to `John`
+ *   - `'users[%name="John" | "Jane"]'` - Filters the `users` with the `name` property equal to `John` or `Jane`
+ *   - `'users[%name="John" | "Jane" && %age=20]'` - AND and OR are supported by using `&&` and `||`, nesting logical operators is not supported yet
+ *   - `'users[%config.name="John" | "Jane"]'` - Dot notation is supported
+ *
+ * Check more supported patterns in {@link filterObjectOrArrayKeys} docs.
  *
  * @param value - The value to snapshot.
  * @param options - The options for the snapshot.
@@ -81,9 +88,11 @@ declare function waitController(): {
  * @param options.rejectKeys - The keys to reject.
  * @param options.filterKeys - The keys to filter.
  * @param options.ignoreProps - The props to ignore.
+ * @param options.sortKeys - Sort all keys by a specific order (default: `simpleValuesFirst`).
+ * @param options.sortPatterns - Sort specific keys by pattern. Use to control the order of specific properties. The same patterns as `filterKeys` are supported.
  * @returns The compact snapshot of the value.
  */
-declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLength, showUndefined, showBooleansAs, rejectKeys, filterKeys, ...options }?: YamlStringifyOptions & {
+declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLength, showUndefined, showBooleansAs, rejectKeys, filterKeys, sortKeys, sortPatterns, ...options }?: YamlStringifyOptions & {
     showBooleansAs?: boolean | {
         props?: Record<string, {
             trueText?: string;
@@ -93,47 +102,10 @@ declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLengt
         trueText?: string;
         falseText?: string;
     };
-    /**
-     * Reject (exclude) keys from the snapshot using pattern matching.
-     *
-     * **Examples:**
-     * ```typescript
-     * // Reject root-level 'secret' only
-     * rejectKeys: ['secret']
-     *
-     * // Reject nested 'password' properties only
-     * rejectKeys: ['*.password']
-     *
-     * // Reject any 'apiKey' property at any level
-     * rejectKeys: ['*apiKey']
-     *
-     * // Reject specific nested path
-     * rejectKeys: ['user.settings.theme']
-     * ```
-     */
     rejectKeys?: string[] | string;
-    /**
-     * Filter (include only) keys that match the specified patterns.
-     *
-     * **Examples:**
-     * ```typescript
-     * // Include only root-level 'user'
-     * filterKeys: ['user']
-     *
-     * // Include all 'name' properties at any level
-     * filterKeys: ['*name']
-     *
-     * // Include only nested 'id' properties
-     * filterKeys: ['*.id']
-     *
-     * // Include specific nested paths
-     * filterKeys: ['user.profile.email', 'settings.theme']
-     * ```
-     *
-     * **Note:** When filtering, parent paths are automatically included if needed
-     * to preserve the structure for nested matches.
-     */
     filterKeys?: string[] | string;
+    sortKeys?: 'asc' | 'desc' | 'simpleValuesFirst' | false;
+    sortPatterns?: string[];
 }): string;
 
 export { compactSnapshot, createLoggerStore, getResultFn, waitController };

package/lib/testUtils.js

@@ -11,7 +11,7 @@ import {
 } from "./chunk-JQFUKJU5.js";
 import {
   filterObjectOrArrayKeys
-} from "./chunk-2WZGT4NA.js";
+} from "./chunk-MVN6FKX7.js";
 import {
   defer
 } from "./chunk-DFXNVEH6.js";
@@ -263,6 +263,8 @@ function compactSnapshot(value, {
   showBooleansAs = true,
   rejectKeys,
   filterKeys,
+  sortKeys,
+  sortPatterns,
   ...options
 } = {}) {
   let processedValue = value;
@@ -270,7 +272,9 @@ function compactSnapshot(value, {
     if (isPlainObject(processedValue) || Array.isArray(processedValue)) {
       processedValue = filterObjectOrArrayKeys(processedValue, {
         rejectKeys,
-        filterKeys
+        filterKeys,
+        sortKeys,
+        sortPatterns
       });
     }
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ls-stack/utils",
   "description": "Universal TypeScript utilities for browser and Node.js",
-  "version": "3.26.1",
+  "version": "3.27.0",
   "license": "MIT",
   "files": [
     "lib",