@ls-stack/utils 3.26.1 → 3.27.0

package/docs/filterObjectOrArrayKeys.md

@@ -14,7 +14,7 @@
 function filterObjectOrArrayKeys(objOrArray, options): Record<string, any> | Record<string, any>[];
 ```
 
-Defined in: [packages/utils/src/filterObjectOrArrayKeys.ts:42](https://github.com/lucasols/utils/blob/main/packages/utils/src/filterObjectOrArrayKeys.ts#L42)
+Defined in: [packages/utils/src/filterObjectOrArrayKeys.ts:58](https://github.com/lucasols/utils/blob/main/packages/utils/src/filterObjectOrArrayKeys.ts#L58)
 
 Filters the keys of an object based on the provided patterns.
 
@@ -46,6 +46,19 @@ Filtering patterns in `rejectKeys` and `filterKeys`:
   - `'prop.test.(prop1|prop2|prop3)'` - Expands to `prop.test.prop1`, `prop.test.prop2`, and `prop.test.prop3`
   - `'components[*].(table_id|columns|filters[*].value)'` - Expands to `components[*].table_id`, `components[*].columns`, and `components[*].filters[*].value`
   - `'(users|admins)[*].name'` - Expands to `users[*].name` and `admins[*].name`
+- Array filtering by value:
+  - `'users[%name="John"]'` - Filters the `users` with the `name` property equal to `John`
+  - `'users[%name="John" | "Jane"]'` - Value-level OR using `|` for multiple values of same property
+  - `'users[%name="Alice" || %age=35]'` - Property-level OR using `||` for different properties
+  - `'users[%age=30 && %role="admin"]'` - Property-level AND using `&&` for different properties
+  - Note: Mixing `&&` and `||` in the same filter is not supported - use separate filter patterns instead
+  - `'users[%config.name="John" | "Jane"]'` - Dot notation is supported
+  - `'users[%name*="oh"]'` - Contains operator (*=) - filters users where name contains "oh"
+  - `'users[%name^="Jo"]'` - Starts with operator (^=) - filters users where name starts with "Jo"
+  - `'users[%name$="hn"]'` - Ends with operator ($=) - filters users where name ends with "hn"
+  - `'users[%name!="John"]'` - Not equal operator (!=) - filters users where name is not "John"
+  - `'users[%name!*="admin"]'` - Not contains operator (!*=) - filters users where name doesn't contain "admin"
+  - `'users[i%name="john"]'` - Case-insensitive matching (i% prefix) - matches "John", "JOHN", "john", etc.
 
 #### Parameters
 
@@ -77,6 +90,18 @@ Whether to reject empty objects in arrays (default: true).
 
 The keys to reject.
 
+###### sortKeys?
+
+`false` \| `"asc"` \| `"simpleValuesFirst"` \| `"desc"` = `'simpleValuesFirst'`
+
+Sort all keys by a specific order (optional, preserves original order when not specified).
+
+###### sortPatterns?
+
+`string`[]
+
+Sort specific keys by pattern. Use to control the order of specific properties. The same patterns as `filterKeys` are supported.
+
 #### Returns
 
 `Record`\<`string`, `any`\> \| `Record`\<`string`, `any`\>[]

package/docs/testUtils.md

@@ -14,7 +14,7 @@
 function compactSnapshot(value, options): string;
 ```
 
-Defined in: [packages/utils/src/testUtils.ts:354](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L354)
+Defined in: [packages/utils/src/testUtils.ts:363](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L363)
 
 Produces a more compact and readable snapshot of a value using yaml.
 By default booleans are shown as `✅` and `❌`, use `showBooleansAs` to disable/configure this.
@@ -45,6 +45,13 @@ Filtering patterns in `rejectKeys` and `filterKeys`:
   - `'[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 [filterObjectOrArrayKeys](filterObjectOrArrayKeys.md#filterobjectorarraykeys) docs.
 
 #### Parameters
 

package/lib/chunk-MVN6FKX7.js

@@ -0,0 +1,557 @@
+import {
+  sortBy
+} from "./chunk-SRVMMYSW.js";
+import {
+  isPlainObject
+} from "./chunk-JF2MDHOJ.js";
+
+// src/filterObjectOrArrayKeys.ts
+function filterObjectOrArrayKeys(objOrArray, {
+  filterKeys,
+  rejectKeys,
+  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);
+  const hasFilters = filterPatternsRaw.length > 0;
+  const hasRejects = rejectPatternsRaw.length > 0;
+  const expandedFilterPatterns = filterPatternsRaw.flatMap(expandPatterns);
+  const expandedRejectPatterns = rejectPatternsRaw.flatMap(expandPatterns);
+  const { filterOnlyPatterns, combinedPatterns } = separateFilterPatterns(
+    expandedFilterPatterns
+  );
+  const filterPatterns = filterOnlyPatterns.map(parsePattern);
+  const rejectPatterns = expandedRejectPatterns.map(parsePattern);
+  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];
+      if (pt.type === "WILDCARD_ANY") {
+        if (rec(pi, pti + 1)) return true;
+        if (pi < path.length) return rec(pi + 1, pti);
+        return false;
+      }
+      if (pt.type === "WILDCARD_ONE") {
+        let j = pi;
+        let sawKey = false;
+        while (j < path.length) {
+          if (path[j].type === "KEY") sawKey = true;
+          if (sawKey && rec(j, pti + 1)) return true;
+          j += 1;
+        }
+        return false;
+      }
+      if (pi >= path.length) return false;
+      const ct = path[pi];
+      switch (pt.type) {
+        case "KEY":
+          if (ct.type === "KEY" && ct.name === pt.name)
+            return rec(pi + 1, pti + 1);
+          if (ct.type === "INDEX") return rec(pi + 1, pti);
+          return false;
+        case "INDEX":
+          if (ct.type === "INDEX" && ct.index === pt.index)
+            return rec(pi + 1, pti + 1);
+          return false;
+        case "INDEX_ANY":
+          if (ct.type === "INDEX") return rec(pi + 1, pti + 1);
+          return false;
+        case "INDEX_RANGE":
+          if (ct.type === "INDEX") {
+            const okLower = ct.index >= pt.start;
+            const okUpper = pt.end === null ? true : ct.index <= pt.end;
+            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, 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)) {
+        throw new TypeError("Circular references are not supported");
+      }
+      stack2.add(value);
+      const out = [];
+      const includeAllChildren = allowedByFilter || !hasFilters;
+      for (let index = 0; index < value.length; index += 1) {
+        const childPath = path.concat({ type: "INDEX", index });
+        const child = value[index];
+        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(
+            child,
+            childPath,
+            childAllowed,
+            stack2,
+            false,
+            true
+          );
+          if (builtChild !== void 0) {
+            out.push(builtChild);
+          }
+        } else {
+          if (childAllowed) {
+            out.push(child);
+          }
+        }
+      }
+      stack2.delete(value);
+      const filteredOut = rejectEmptyObjectsInArray ? out.filter(
+        (item) => !(isPlainObject(item) && Object.keys(item).length === 0)
+      ) : out;
+      if (filteredOut.length === 0 && !allowedByFilter && !isRoot)
+        return void 0;
+      return filteredOut;
+    }
+    if (isPlainObject(value)) {
+      if (stack2.has(value)) {
+        throw new TypeError("Circular references are not supported");
+      }
+      stack2.add(value);
+      const result = {};
+      const includeAllChildren = allowedByFilter || !hasFilters;
+      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];
+        const directInclude = hasFilters ? matchesAnyFilter(childPath) : true;
+        const childAllowed = includeAllChildren || directInclude;
+        if (isPlainObject(val) || Array.isArray(val)) {
+          const builtChild = build(
+            val,
+            childPath,
+            childAllowed,
+            stack2,
+            false,
+            false
+          );
+          if (builtChild === void 0) {
+            continue;
+          }
+          if (Array.isArray(builtChild) && builtChild.length === 0 && !childAllowed) {
+            continue;
+          }
+          if (isPlainObject(builtChild) && Object.keys(builtChild).length === 0 && !childAllowed) {
+            continue;
+          }
+          result[key] = builtChild;
+        } else {
+          if (childAllowed) {
+            result[key] = val;
+          }
+        }
+      }
+      stack2.delete(value);
+      if (Object.keys(result).length === 0 && !allowedByFilter && !isRoot) {
+        if (parentIsArray && !rejectEmptyObjectsInArray) {
+          return {};
+        }
+        return void 0;
+      }
+      return result;
+    }
+    return allowedByFilter || !hasFilters ? value : void 0;
+  };
+  const startPath = [];
+  const initialAllowed = !hasFilters;
+  const stack = /* @__PURE__ */ new WeakSet();
+  const built = build(
+    dataToProcess,
+    startPath,
+    initialAllowed,
+    stack,
+    true,
+    false
+  );
+  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("(");
+    if (start === -1) {
+      return [str];
+    }
+    const end = str.indexOf(")", start);
+    if (end === -1) {
+      return [str];
+    }
+    const before = str.slice(0, start);
+    const inside = str.slice(start + 1, end);
+    const after = str.slice(end + 1);
+    if (!inside.includes("|")) {
+      return expandSingle(before + inside + after);
+    }
+    const options = inside.split("|").filter((option) => option.trim().length > 0);
+    const results = [];
+    for (const option of options) {
+      const newStr = before + option + after;
+      results.push(...expandSingle(newStr));
+    }
+    return results;
+  }
+  return expandSingle(pattern);
+}
+function parsePattern(pattern) {
+  const tokens = [];
+  let i = 0;
+  const n = pattern.length;
+  const pushKey = (name) => {
+    if (name.length === 0) return;
+    tokens.push({ type: "KEY", name });
+  };
+  while (i < n) {
+    const ch = pattern[i];
+    if (ch === ".") {
+      i += 1;
+      continue;
+    }
+    if (ch === "[") {
+      const end = pattern.indexOf("]", i + 1);
+      const inside = end === -1 ? pattern.slice(i + 1) : pattern.slice(i + 1, end);
+      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("-");
+        const startStr = parts[0] ?? "";
+        const endStr = parts[1] ?? "";
+        const start = parseInt(startStr, 10);
+        const endNum = endStr === "*" ? null : parseInt(endStr, 10);
+        tokens.push({
+          type: "INDEX_RANGE",
+          start,
+          end: endNum === null || Number.isFinite(endNum) ? endNum : null
+        });
+      } else if (inside.length > 0) {
+        const idx = parseInt(inside, 10);
+        tokens.push({ type: "INDEX", index: idx });
+      }
+      i = end === -1 ? n : end + 1;
+      continue;
+    }
+    if (ch === "*") {
+      if (pattern[i + 1] === "*") {
+        tokens.push({ type: "WILDCARD_ANY" });
+        i += 2;
+        let j2 = i;
+        while (j2 < n) {
+          const c = pattern[j2];
+          if (c === "." || c === "[") break;
+          j2 += 1;
+        }
+        if (j2 > i) {
+          pushKey(pattern.slice(i, j2));
+          i = j2;
+        }
+        continue;
+      } else {
+        tokens.push({ type: "WILDCARD_ONE" });
+        i += 1;
+        continue;
+      }
+    }
+    let j = i;
+    while (j < n) {
+      const c = pattern[j];
+      if (c === "." || c === "[") break;
+      j += 1;
+    }
+    pushKey(pattern.slice(i, j));
+    i = j;
+  }
+  return tokens;
+}
+
+export {
+  filterObjectOrArrayKeys
+};