@ls-stack/utils 3.24.1 → 3.25.0

package/docs/testUtils.md

@@ -11,10 +11,38 @@
 ### compactSnapshot()
 
 ```ts
-function compactSnapshot(value, __namedParameters): string;
+function compactSnapshot(value, options): string;
 ```
 
-Defined in: [packages/utils/src/testUtils.ts:487](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L487)
+Defined in: [packages/utils/src/testUtils.ts:352](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L352)
+
+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.
+
+Filtering patterns in `rejectKeys` and `filterKeys`:
+- `'prop'` - Only root-level properties named 'prop'
+- `'**prop'` - Any property named exactly 'prop' at any level (root or nested)
+- `'*.prop'` - Any nested property named 'prop' at second level (excludes root-level matches)
+- `'test.*.prop'` - Any property named 'prop' at second level of 'test'
+- `'test.*.test.**prop'` - Any property named 'prop' inside of 'test.*.test'
+- `'prop.nested'` - Exact nested property paths like `obj.prop.nested`
+- `'prop.**nested'` - All nested properties inside root `prop` with name `nested`
+- `'prop[0]'` - The first item of the `prop` array
+- `'prop[*]'` - All items of the `prop` array
+- `'prop[0].nested'` - `nested` prop of the first item of the `prop` array
+- `'prop[*].nested'` - `nested` prop of all items of the `prop` array
+- `'prop[*]**nested'` - all `nested` props of all items of the `prop` array
+- `'prop[0-2]'` - The first three items of the `prop` array
+- `'prop[4-*]'` - All items of the `prop` array from the fourth index to the end
+- `'prop[0-2].nested.**prop'` - Combining multiple nested patterns is supported
+- Root array:
+  - `'[0]'` - The first item of the root array
+  - `'[*]'` - All items of the array
+  - `'[0].nested'` - `nested` prop of the first item of the array
+  - `'[*].nested'` - `nested` prop of all items of the array
+  - `'[*]**nested'` - all `nested` props of all items of the array
+  - `'[0-2]'` - The first three items of the array
+  - `'[4-*]'` - All items of the array from the fourth index to the end
 
 #### Parameters
 
@@ -22,14 +50,20 @@ Defined in: [packages/utils/src/testUtils.ts:487](https://github.com/lucasols/ut
 
 `unknown`
 
-##### \_\_namedParameters
+The value to snapshot.
+
+##### options
 
 [`YamlStringifyOptions`](yamlStringify.md#yamlstringifyoptions) & `object` = `{}`
 
+The options for the snapshot.
+
 #### Returns
 
 `string`
 
+The compact snapshot of the value.
+
 ***
 
 ### createLoggerStore()
@@ -38,7 +72,7 @@ Defined in: [packages/utils/src/testUtils.ts:487](https://github.com/lucasols/ut
 function createLoggerStore(__namedParameters): object;
 ```
 
-Defined in: [packages/utils/src/testUtils.ts:10](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L10)
+Defined in: [packages/utils/src/testUtils.ts:11](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L11)
 
 #### Parameters
 
@@ -270,7 +304,7 @@ get snapshotFromLast(): string;
 function getResultFn<T>(fnGetter, wrapper?): T;
 ```
 
-Defined in: [packages/utils/src/testUtils.ts:276](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L276)
+Defined in: [packages/utils/src/testUtils.ts:277](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L277)
 
 #### Type Parameters
 
@@ -300,7 +334,7 @@ Defined in: [packages/utils/src/testUtils.ts:276](https://github.com/lucasols/ut
 function waitController(): object;
 ```
 
-Defined in: [packages/utils/src/testUtils.ts:291](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L291)
+Defined in: [packages/utils/src/testUtils.ts:292](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L292)
 
 #### Returns
 

package/docs/time.md

@@ -243,7 +243,7 @@ Defined in: [packages/utils/src/time.ts:29](https://github.com/lucasols/utils/bl
 
 ##### format
 
-`"seconds"` | `"minutes"` | `"milliseconds"`
+`"minutes"` | `"seconds"` | `"milliseconds"`
 
 ##### hoursMinLength
 

package/docs/tsResult/README.md

@@ -18,7 +18,7 @@
 type GetTypedResult<R> = TypedResult<R extends Result<infer T, any> ? T : never, R extends Result<any, infer E> ? E : never>;
 ```
 
-Defined in: [packages/utils/src/tsResult.ts:328](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L328)
+Defined in: [packages/utils/src/tsResult.ts:355](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L355)
 
 #### Type Parameters
 
@@ -83,7 +83,7 @@ Use `t-result` library instead.
 type TypedResult<T, E> = object;
 ```
 
-Defined in: [packages/utils/src/tsResult.ts:318](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L318)
+Defined in: [packages/utils/src/tsResult.ts:345](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L345)
 
 #### Deprecated
 
@@ -107,7 +107,7 @@ Use `t-result` library instead.
 _type: Result<T, E>;
 ```
 
-Defined in: [packages/utils/src/tsResult.ts:324](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L324)
+Defined in: [packages/utils/src/tsResult.ts:351](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L351)
 
 ###### Deprecated
 
@@ -119,7 +119,7 @@ Use `t-result` library instead.
 err: (error) => Err<E>;
 ```
 
-Defined in: [packages/utils/src/tsResult.ts:322](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L322)
+Defined in: [packages/utils/src/tsResult.ts:349](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L349)
 
 ###### Parameters
 
@@ -141,7 +141,7 @@ Use `t-result` library instead.
 ok: (value) => Ok<T>;
 ```
 
-Defined in: [packages/utils/src/tsResult.ts:320](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L320)
+Defined in: [packages/utils/src/tsResult.ts:347](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L347)
 
 ###### Parameters
 
@@ -477,7 +477,7 @@ Use `t-result` library instead.
 function err<E>(error): Err<E>;
 ```
 
-Defined in: [packages/utils/src/tsResult.ts:149](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L149)
+Defined in: [packages/utils/src/tsResult.ts:158](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L158)
 
 #### Type Parameters
 
@@ -503,6 +503,8 @@ Use `t-result` library instead.
 
 ### ~~ok()~~
 
+#### Param
+
 #### Deprecated
 
 Use `t-result` library instead.
@@ -519,6 +521,8 @@ Defined in: [packages/utils/src/tsResult.ts:124](https://github.com/lucasols/uti
 
 [`Ok`](-internal-.md#ok)\<`void`\>
 
+##### Param
+
 ##### Deprecated
 
 Use `t-result` library instead.
@@ -533,7 +537,7 @@ Use `t-result` library instead.
 function ok<T>(value): Ok<T>;
 ```
 
-Defined in: [packages/utils/src/tsResult.ts:126](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L126)
+Defined in: [packages/utils/src/tsResult.ts:129](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L129)
 
 ##### Type Parameters
 
@@ -551,6 +555,8 @@ Defined in: [packages/utils/src/tsResult.ts:126](https://github.com/lucasols/uti
 
 [`Ok`](-internal-.md#ok)\<`T`\>
 
+##### Param
+
 ##### Deprecated
 
 Use `t-result` library instead.
@@ -569,7 +575,7 @@ Use `t-result` library instead.
 function resultify<T, E>(fn, errorNormalizer?): Result<T, E>;
 ```
 
-Defined in: [packages/utils/src/tsResult.ts:238](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L238)
+Defined in: [packages/utils/src/tsResult.ts:254](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L254)
 
 ##### Type Parameters
 
@@ -605,7 +611,7 @@ Use `t-result` library instead.
 function resultify<T, E>(fn, errorNormalizer?): Promise<Result<Awaited<T>, E>>;
 ```
 
-Defined in: [packages/utils/src/tsResult.ts:243](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L243)
+Defined in: [packages/utils/src/tsResult.ts:263](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L263)
 
 ##### Type Parameters
 
@@ -641,7 +647,7 @@ Use `t-result` library instead.
 function resultify<T, E>(fn, errorNormalizer?): Promise<Result<T, E>>;
 ```
 
-Defined in: [packages/utils/src/tsResult.ts:248](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L248)
+Defined in: [packages/utils/src/tsResult.ts:272](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L272)
 
 ##### Type Parameters
 
@@ -679,7 +685,7 @@ Use `t-result` library instead.
 function unknownToError(error): Error;
 ```
 
-Defined in: [packages/utils/src/tsResult.ts:296](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L296)
+Defined in: [packages/utils/src/tsResult.ts:323](https://github.com/lucasols/utils/blob/main/packages/utils/src/tsResult.ts#L323)
 
 #### Parameters
 

package/docs/typingFnUtils/-internal-.md

@@ -14,7 +14,7 @@
 type UnionDiff<T, U> = [T] extends [U] ? [U] extends [T] ? null : object : [U] extends [T] ? object : object;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:77](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L77)
+Defined in: [packages/utils/src/typingFnUtils.ts:92](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L92)
 
 #### Type Parameters
 

package/docs/typingFnUtils/README.md

@@ -18,7 +18,7 @@
 const isSubTypeOf: <BaseType, SubType>() => unknown = typeOnRightExtendsLeftType;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:65](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L65)
+Defined in: [packages/utils/src/typingFnUtils.ts:78](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L78)
 
 Type helper to check if a type is a subtype of another type.
 
@@ -80,7 +80,7 @@ Defined in: [packages/utils/src/typingFnUtils.ts:3](https://github.com/lucasols/
 function asType<T>(value): T;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:28](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L28)
+Defined in: [packages/utils/src/typingFnUtils.ts:37](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L37)
 
 a safe way to cast types, use to substitute the `as Type`
 
@@ -108,7 +108,7 @@ a safe way to cast types, use to substitute the `as Type`
 function isObjKey<T>(key, obj): key is keyof T;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:70](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L70)
+Defined in: [packages/utils/src/typingFnUtils.ts:85](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L85)
 
 Type helper to narrow a string to a key of an object.
 
@@ -140,7 +140,7 @@ Type helper to narrow a string to a key of an object.
 function narrowStringToUnion<T>(key, union): undefined | T;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:33](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L33)
+Defined in: [packages/utils/src/typingFnUtils.ts:46](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L46)
 
 narrow a string to a union of strings
 
@@ -172,7 +172,7 @@ narrow a string to a union of strings
 function typedObjectEntries<T>(obj): NonNullable<{ [K in string | number | symbol]: [K, T[K]] }[keyof T]>[];
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:10](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L10)
+Defined in: [packages/utils/src/typingFnUtils.ts:13](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L13)
 
 a wrapper to Object.entries with a better typing inference
 
@@ -200,7 +200,7 @@ a wrapper to Object.entries with a better typing inference
 function typedObjectKeys<T>(obj): keyof T[];
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:21](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L21)
+Defined in: [packages/utils/src/typingFnUtils.ts:27](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L27)
 
 a wrapper to Object.keys with a better typing inference
 
@@ -228,7 +228,7 @@ keyof `T`[]
 function typeOnRightExtendsLeftType<BaseType, SubType>(): unknown;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:57](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L57)
+Defined in: [packages/utils/src/typingFnUtils.ts:70](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L70)
 
 Type helper to check if a type is a subtype of another type.
 
@@ -260,7 +260,7 @@ Returns undefined, only used for type checking
 function unionsAreTheSame<T, U>(_diff): void;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:93](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L93)
+Defined in: [packages/utils/src/typingFnUtils.ts:107](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L107)
 
 Type helper to compare two union types and determine their relationship.
 
@@ -289,5 +289,3 @@ null if unions are identical, or an object describing the errors
 #### Returns
 
 `void`
-
-void - This function is only used for type checking

package/lib/arrayUtils.d.cts

@@ -4,6 +4,8 @@
  * In the `mapFilter` function return `false` to reject the item, or any other
  * value to map it.
  *
+ * @param array
+ * @param mapFilter
  * @example
  * // Filter reject and turn value into `value mapped`
  * const items = ['value', 'value', 'reject', 'reject'];
@@ -26,6 +28,9 @@ type SortOrder = 'desc' | 'asc';
  *
  * Use `Infinity` as as wildcard to absolute max and min values
  *
+ * @param arr
+ * @param sortByValue
+ * @param props
  * @example
  * const items = [1, 3, 2, 4];
  *
@@ -36,7 +41,7 @@ type SortOrder = 'desc' | 'asc';
  *
  * // return a array to sort by multiple values
  * const sortedItems = sortBy(items, (item) => [item.a, item.b]);
- **/
+ */
 declare function sortBy<T>(arr: T[], sortByValue: (item: T) => (number | string)[] | number | string, props?: {
     order?: SortOrder | SortOrder[];
 } | SortOrder | SortOrder[]): T[];

package/lib/arrayUtils.d.ts

@@ -4,6 +4,8 @@
  * In the `mapFilter` function return `false` to reject the item, or any other
  * value to map it.
  *
+ * @param array
+ * @param mapFilter
  * @example
  * // Filter reject and turn value into `value mapped`
  * const items = ['value', 'value', 'reject', 'reject'];
@@ -26,6 +28,9 @@ type SortOrder = 'desc' | 'asc';
  *
  * Use `Infinity` as as wildcard to absolute max and min values
  *
+ * @param arr
+ * @param sortByValue
+ * @param props
  * @example
  * const items = [1, 3, 2, 4];
  *
@@ -36,7 +41,7 @@ type SortOrder = 'desc' | 'asc';
  *
  * // return a array to sort by multiple values
  * const sortedItems = sortBy(items, (item) => [item.a, item.b]);
- **/
+ */
 declare function sortBy<T>(arr: T[], sortByValue: (item: T) => (number | string)[] | number | string, props?: {
     order?: SortOrder | SortOrder[];
 } | SortOrder | SortOrder[]): T[];

package/lib/{chunk-JAPKLFIK.js → chunk-QLD7KG5I.js}

@@ -18,12 +18,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)) {
@@ -42,7 +42,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;
@@ -89,20 +90,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";
       }
@@ -165,7 +175,8 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
           maxDepth,
           depth + 1,
           collapseObjects,
-          addObjSpaces
+          addObjSpaces,
+          true
         );
       }).join(", ");
       line += "]";
@@ -189,7 +200,8 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
             maxDepth,
             depth + 1,
             collapseObjects,
-            addObjSpaces
+            addObjSpaces,
+            true
           );
           arrayString = arrayString.trimStart();
           result += arrayString;
@@ -202,7 +214,8 @@ function stringifyValue(value, indent, maxLineLength, showUndefined, maxDepth, d
             maxDepth,
             depth + 1,
             collapseObjects,
-            addObjSpaces
+            addObjSpaces,
+            true
           );
         }
         result += "\n";
@@ -256,7 +269,8 @@ ${indent}${line}
       maxDepth,
       depth + 1,
       collapseObjects,
-      addObjSpaces
+      addObjSpaces,
+      false
     );
   }
   return JSON.stringify(value);