@ls-stack/utils 3.24.1 → 3.26.0

package/lib/runShellCmd.d.ts

@@ -13,6 +13,14 @@ type RunCmdOptions = {
     noCiColorForce?: boolean;
 };
 /**
+ * @param label
+ * @param command
+ * @param root0
+ * @param root0.mock
+ * @param root0.silent
+ * @param root0.throwOnError
+ * @param root0.cwd
+ * @param root0.noCiColorForce
  * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
  * ```
  * // Old (deprecated)
@@ -24,6 +32,9 @@ type RunCmdOptions = {
  */
 declare function runCmd(label: string | null, command: string | string[], { mock, silent, throwOnError, cwd, noCiColorForce, }?: RunCmdOptions): Promise<CmdResult>;
 /**
+ * @param label
+ * @param cmd
+ * @param onResult
  * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
  * ```
  * // Old (deprecated)
@@ -35,6 +46,10 @@ declare function runCmd(label: string | null, command: string | string[], { mock
  */
 declare function concurrentCmd(label: string, cmd: string | string[], onResult: (result: CmdResult) => void): Promise<() => void>;
 /**
+ * @param label
+ * @param command
+ * @param root0
+ * @param root0.silent
  * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
  * ```
  * // Old (deprecated)
@@ -48,6 +63,7 @@ declare function runCmdUnwrap(label: string | null, command: string | string[],
     silent?: boolean | 'timeOnly';
 }): Promise<string>;
 /**
+ * @param command
  * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
  * ```
  * // Old (deprecated)
@@ -59,6 +75,7 @@ declare function runCmdUnwrap(label: string | null, command: string | string[],
  */
 declare function runCmdSilent(command: string | string[]): Promise<CmdResult>;
 /**
+ * @param command
  * @deprecated This utility has been moved to @ls-stack/node-utils. Please update your imports:
  * ```
  * // Old (deprecated)

package/lib/safeJson.d.cts

@@ -1,6 +1,12 @@
-/** JSON.stringify can throw if the value is circular or contains functions, this function catches those errors and returns undefined */
+/**
+ * JSON.stringify can throw if the value is circular or contains functions, this function catches those errors and returns undefined
+ * @param value
+ */
 declare function safeJsonStringify(value: unknown): string | undefined;
-/** JSON.parse can throw if the value is not valid JSON, this function catches those errors and returns undefined */
+/**
+ * JSON.parse can throw if the value is not valid JSON, this function catches those errors and returns undefined
+ * @param value
+ */
 declare function safeJsonParse(value: string): unknown;
 
 export { safeJsonParse, safeJsonStringify };

package/lib/safeJson.d.ts

@@ -1,6 +1,12 @@
-/** JSON.stringify can throw if the value is circular or contains functions, this function catches those errors and returns undefined */
+/**
+ * JSON.stringify can throw if the value is circular or contains functions, this function catches those errors and returns undefined
+ * @param value
+ */
 declare function safeJsonStringify(value: unknown): string | undefined;
-/** JSON.parse can throw if the value is not valid JSON, this function catches those errors and returns undefined */
+/**
+ * JSON.parse can throw if the value is not valid JSON, this function catches those errors and returns undefined
+ * @param value
+ */
 declare function safeJsonParse(value: string): unknown;
 
 export { safeJsonParse, safeJsonStringify };

package/lib/saferTyping.d.cts

@@ -8,12 +8,14 @@ type EmptyObject = Record<string, never>;
 /**
  * Cast a value to `any` type. Use this when you have legit usage of `any` casting.
  *
+ * @param value
  * @template V (optional) - When used enforces that the casted value is assignable to the type V, use it for safer casts
  */
 declare function __LEGIT_ANY_CAST__<V = unknown>(value: V): __LEGIT_ANY__;
 /**
  * Cast a value to a specific type T. Use this when you have legit usage of type assertion.
  *
+ * @param value
  * @template T - The type to cast to
  * @template V (optional) - When used enforces that the casted value is assignable to the type V, use it for safer casts
  */
@@ -21,6 +23,7 @@ declare function __LEGIT_CAST__<T, V = unknown>(value: V): T;
 /**
  * Refine a value to a specific type T. Use this when you have legit usage of type assertion.
  *
+ * @param value
  * @template T - The type to cast to
  * @template V (optional) - When used enforces that the casted value is assignable to the type V, use it for safer casts
  */

package/lib/saferTyping.d.ts

@@ -8,12 +8,14 @@ type EmptyObject = Record<string, never>;
 /**
  * Cast a value to `any` type. Use this when you have legit usage of `any` casting.
  *
+ * @param value
  * @template V (optional) - When used enforces that the casted value is assignable to the type V, use it for safer casts
  */
 declare function __LEGIT_ANY_CAST__<V = unknown>(value: V): __LEGIT_ANY__;
 /**
  * Cast a value to a specific type T. Use this when you have legit usage of type assertion.
  *
+ * @param value
  * @template T - The type to cast to
  * @template V (optional) - When used enforces that the casted value is assignable to the type V, use it for safer casts
  */
@@ -21,6 +23,7 @@ declare function __LEGIT_CAST__<T, V = unknown>(value: V): T;
 /**
  * Refine a value to a specific type T. Use this when you have legit usage of type assertion.
  *
+ * @param value
  * @template T - The type to cast to
  * @template V (optional) - When used enforces that the casted value is assignable to the type V, use it for safer casts
  */

package/lib/stringUtils.d.cts

@@ -2,6 +2,7 @@ type Arg = string | false | undefined | null;
 /**
  * A util to create more legible conditional concatenated strings
  *
+ * @param args
  * @example
  * joinStrings('a', 'b', 'c') // 'abc'
  * joinStrings('a', false, 'c') // 'ac'

package/lib/stringUtils.d.ts

@@ -2,6 +2,7 @@ type Arg = string | false | undefined | null;
 /**
  * A util to create more legible conditional concatenated strings
  *
+ * @param args
  * @example
  * joinStrings('a', 'b', 'c') // 'abc'
  * joinStrings('a', false, 'c') // 'ac'

package/lib/testUtils.cjs

@@ -131,6 +131,256 @@ function deepEqual(foo, bar, maxDepth = 20) {
   return foo !== foo && bar !== bar;
 }
 
+// src/filterObjectOrArrayKeys.ts
+function filterObjectOrArrayKeys(objOrArray, {
+  filterKeys,
+  rejectKeys,
+  rejectEmptyObjectsInArray = true
+}) {
+  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 filterPatterns = filterPatternsRaw.map(parsePattern);
+  const rejectPatterns = rejectPatternsRaw.map(parsePattern);
+  function matchPath(path, pattern) {
+    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 "MULTI_KEY":
+          if (ct.type === "KEY" && pt.names.includes(ct.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;
+      }
+    }
+    return rec(0, 0);
+  }
+  const matchesAnyFilter = (path) => filterPatterns.some((p) => matchPath(path, p));
+  const matchesAnyReject = (path) => rejectPatterns.some((p) => matchPath(path, p));
+  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 });
+        if (hasRejects && matchesAnyReject(childPath)) continue;
+        const child = value[index];
+        const directInclude = hasFilters ? matchesAnyFilter(childPath) : 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;
+      for (const key of Object.keys(value)) {
+        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(
+    objOrArray,
+    startPath,
+    initialAllowed,
+    stack,
+    true,
+    false
+  );
+  if (built === void 0) return Array.isArray(objOrArray) ? [] : {};
+  return built;
+}
+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 === "*") {
+        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 === "(") {
+      const end = pattern.indexOf(")", i + 1);
+      const inside = end === -1 ? pattern.slice(i + 1) : pattern.slice(i + 1, end);
+      if (inside.includes("|") && inside.trim().length > 0) {
+        const names = inside.split("|").filter((name) => name.length > 0);
+        if (names.length > 0) {
+          tokens.push({ type: "MULTI_KEY", names });
+        }
+      }
+      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;
+}
+
 // src/mathUtils.ts
 function clampMin(value, min) {
   return value < min ? min : value;
@@ -197,12 +447,12 @@ function yamlStringify(obj, {
   addRootObjSpaces = "beforeAndAfter"
 } = {}) {
   if (isObject(obj) || Array.isArray(obj) || typeof obj === "function") {
-    return `${stringifyValue(obj, "", maxLineLength, !!showUndefined, maxDepth, 0, collapseObjects, addRootObjSpaces)}
+    return `${stringifyValue(obj, "", maxLineLength, !!showUndefined, maxDepth, 0, collapseObjects, addRootObjSpaces, false)}
 `;
   }
   return JSON.stringify(obj) || "undefined";
 }
-function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, depth, collapseObjects, addObjSpaces) {
+function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, depth, collapseObjects, addObjSpaces, isArrayItem) {
   let result = "";
   const childIndent = `${indent}  `;
   if (isPlainObject(value)) {
@@ -221,7 +471,8 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
           return typeof val === "number" || typeof val === "boolean" || val === null || val === void 0;
         }
       );
-      if (isSimpleObject && entries.length > 0) {
+      const shouldCollapse = isArrayItem ? entries.length > 1 : entries.length > 0;
+      if (isSimpleObject && shouldCollapse) {
         let line = "{ ";
         line += entries.map(([key, val]) => {
           let valueStr;
@@ -268,20 +519,29 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
         maxDepth,
         depth + 1,
         collapseObjects,
-        addObjSpaces
+        addObjSpaces,
+        false
       );
-      const willBeCollapsed = isObject(objVal) && (Object.keys(objVal).length === 0 || collapseObjects && depth + 1 > 0 && Object.entries(objVal).filter(([, val]) => val !== void 0 || showUndefined).every(([, val]) => {
-        if (typeof val === "string") {
-          return !val.includes("'") && !val.includes('"') && !val.includes("\\");
-        }
-        return typeof val === "number" || typeof val === "boolean" || val === null || val === void 0;
-      }));
-      const prevWasCollapsed = prevValue && isObject(prevValue) && (Object.keys(prevValue).length === 0 || collapseObjects && depth + 1 > 0 && Object.entries(prevValue).filter(([, val]) => val !== void 0 || showUndefined).every(([, val]) => {
-        if (typeof val === "string") {
-          return !val.includes("'") && !val.includes('"') && !val.includes("\\");
-        }
-        return typeof val === "number" || typeof val === "boolean" || val === null || val === void 0;
-      }));
+      const willBeCollapsed = isObject(objVal) && (Object.keys(objVal).length === 0 || collapseObjects && depth + 1 > 0 && (() => {
+        const filteredEntries = Object.entries(objVal).filter(([, val]) => val !== void 0 || showUndefined);
+        const shouldCollapseThis = isArrayItem ? filteredEntries.length > 1 : filteredEntries.length > 0;
+        return shouldCollapseThis && filteredEntries.every(([, val]) => {
+          if (typeof val === "string") {
+            return !val.includes("'") && !val.includes('"') && !val.includes("\\");
+          }
+          return typeof val === "number" || typeof val === "boolean" || val === null || val === void 0;
+        });
+      })());
+      const prevWasCollapsed = prevValue && isObject(prevValue) && (Object.keys(prevValue).length === 0 || collapseObjects && depth + 1 > 0 && (() => {
+        const filteredEntries = Object.entries(prevValue).filter(([, val]) => val !== void 0 || showUndefined);
+        const shouldCollapseThis = isArrayItem ? filteredEntries.length > 1 : filteredEntries.length > 0;
+        return shouldCollapseThis && filteredEntries.every(([, val]) => {
+          if (typeof val === "string") {
+            return !val.includes("'") && !val.includes('"') && !val.includes("\\");
+          }
+          return typeof val === "number" || typeof val === "boolean" || val === null || val === void 0;
+        });
+      })());
       if (!afterSpaceWasAdded && indent === "" && isObject(objVal) && !willBeCollapsed && prevValue && !prevWasCollapsed && (addObjSpaces === "before" || addObjSpaces === "beforeAndAfter")) {
         result += "\n";
       }
@@ -344,7 +604,8 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
           maxDepth,
           depth + 1,
           collapseObjects,
-          addObjSpaces
+          addObjSpaces,
+          true
         );
       }).join(", ");
       line += "]";
@@ -368,7 +629,8 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
             maxDepth,
             depth + 1,
             collapseObjects,
-            addObjSpaces
+            addObjSpaces,
+            true
           );
           arrayString = arrayString.trimStart();
           result += arrayString;
@@ -381,7 +643,8 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
             maxDepth,
             depth + 1,
             collapseObjects,
-            addObjSpaces
+            addObjSpaces,
+            true
           );
         }
         result += "\n";
@@ -435,7 +698,8 @@ ${indent}${line}
       maxDepth,
       depth + 1,
       collapseObjects,
-      addObjSpaces
+      addObjSpaces,
+      false
     );
   }
   return JSON.stringify(value);
@@ -753,126 +1017,6 @@ function waitController() {
     }
   };
 }
-function matchesKeyPattern(fullPath, key, pattern, currentPath) {
-  if (fullPath === pattern) {
-    return true;
-  }
-  if (pattern.startsWith("*.")) {
-    const propName = pattern.slice(2);
-    return currentPath !== "" && key === propName;
-  }
-  if (pattern.startsWith("*") && !pattern.startsWith("*.")) {
-    const propName = pattern.slice(1);
-    return key === propName;
-  }
-  if (!pattern.includes("*")) {
-    return currentPath === "" && key === pattern;
-  }
-  return false;
-}
-function isParentOfPattern(path, pattern) {
-  if (pattern.includes("*")) {
-    const patternParts = pattern.split(".");
-    const pathParts = path.split(".");
-    if (pathParts.length >= patternParts.length) {
-      return false;
-    }
-    for (let i = 0; i < pathParts.length; i++) {
-      const pathPart = pathParts[i];
-      const patternPart = patternParts[i];
-      if (patternPart === "*") {
-        continue;
-      }
-      if (pathPart !== patternPart) {
-        return false;
-      }
-    }
-    return true;
-  } else {
-    return pattern.startsWith(`${path}.`);
-  }
-}
-function applyKeyFiltering(value, { rejectKeys, filterKeys }, currentPath = "", visited = /* @__PURE__ */ new Set()) {
-  if (!isPlainObject(value) && !Array.isArray(value)) {
-    return value;
-  }
-  if (Array.isArray(value)) {
-    if (visited.has(value)) {
-      throw new Error(
-        "Circular reference detected in array during key filtering"
-      );
-    }
-    visited.add(value);
-    try {
-      return value.map(
-        (item, index) => applyKeyFiltering(
-          item,
-          { rejectKeys, filterKeys },
-          currentPath ? `${currentPath}[${index}]` : `[${index}]`,
-          visited
-        )
-      );
-    } finally {
-      visited.delete(value);
-    }
-  }
-  if (isPlainObject(value)) {
-    if (visited.has(value)) {
-      throw new Error(
-        "Circular reference detected in object during key filtering"
-      );
-    }
-    visited.add(value);
-    try {
-      const result = {};
-      for (const [key, itemValue] of Object.entries(value)) {
-        const fullPath = currentPath ? `${currentPath}.${key}` : key;
-        if (rejectKeys?.some(
-          (rejectPath) => matchesKeyPattern(fullPath, key, rejectPath, currentPath)
-        )) {
-          continue;
-        }
-        if (filterKeys) {
-          const exactMatch = filterKeys.some(
-            (filterPath) => matchesKeyPattern(fullPath, key, filterPath, currentPath)
-          );
-          const isParent = filterKeys.some(
-            (filterPath) => isParentOfPattern(fullPath, filterPath)
-          );
-          if (!exactMatch && !isParent) {
-            continue;
-          }
-          if (exactMatch) {
-            result[key] = applyKeyFiltering(
-              itemValue,
-              { rejectKeys },
-              fullPath,
-              visited
-            );
-          } else {
-            result[key] = applyKeyFiltering(
-              itemValue,
-              { rejectKeys, filterKeys },
-              fullPath,
-              visited
-            );
-          }
-        } else {
-          result[key] = applyKeyFiltering(
-            itemValue,
-            { rejectKeys, filterKeys },
-            fullPath,
-            visited
-          );
-        }
-      }
-      return result;
-    } finally {
-      visited.delete(value);
-    }
-  }
-  return value;
-}
 function compactSnapshot(value, {
   collapseObjects = true,
   maxLineLength = 100,
@@ -884,10 +1028,12 @@ function compactSnapshot(value, {
 } = {}) {
   let processedValue = value;
   if (rejectKeys || filterKeys) {
-    processedValue = applyKeyFiltering(processedValue, {
-      rejectKeys: Array.isArray(rejectKeys) ? rejectKeys : rejectKeys ? [rejectKeys] : void 0,
-      filterKeys: Array.isArray(filterKeys) ? filterKeys : filterKeys ? [filterKeys] : void 0
-    });
+    if (isPlainObject(processedValue) || Array.isArray(processedValue)) {
+      processedValue = filterObjectOrArrayKeys(processedValue, {
+        rejectKeys,
+        filterKeys
+      });
+    }
   }
   processedValue = showBooleansAs ? replaceBooleansWithEmoji(processedValue, showBooleansAs) : processedValue;
   return `