@helpers4/object 2.0.0-beta.0 → 2.0.0

package/meta/api.json

@@ -1,6 +1,6 @@
 {
   "category": "object",
-  "version": "2.0.0-beta.0",
+  "version": "2.0.0",
   "functions": [
     {
       "name": "compact",
@@ -110,54 +110,6 @@
       ],
       "sourceFile": "deepClone.ts"
     },
-    {
-      "name": "deepCompare",
-      "kind": "function",
-      "description": "Deep comparison of two objects that returns detailed information about differences.",
-      "since": "2.0.0",
-      "signatures": [
-        {
-          "signature": "deepCompare(objA: object | null | undefined, objB: object | null | undefined): boolean | DeepCompareResult",
-          "description": "Deep comparison of two objects that returns detailed information about differences.",
-          "params": [
-            {
-              "name": "objA",
-              "type": "object | null | undefined",
-              "description": "First object to compare (can be object, undefined, or null)"
-            },
-            {
-              "name": "objB",
-              "type": "object | null | undefined",
-              "description": "Second object to compare (can be object, undefined, or null)"
-            }
-          ],
-          "returns": {
-            "type": "boolean | DeepCompareResult",
-            "description": "`true` if objects are identical, `false` if incompatible types, or a `DeepCompareResult` object detailing differences"
-          }
-        }
-      ],
-      "examples": [
-        {
-          "title": "Compare nested objects",
-          "description": "Deeply compares two objects, returning true when they are structurally equal.",
-          "code": "deepCompare({ a: { b: 1 } }, { a: { b: 1 } })\n// => true"
-        },
-        {
-          "title": "Detect deep differences",
-          "description": "Returns a detailed diff object when nested values differ.",
-          "code": "deepCompare({ a: { b: 1 } }, { a: { b: 2 } })\n// => { a: { b: false } }"
-        }
-      ],
-      "sourceFile": "deepCompare.ts",
-      "relatedTypes": [
-        {
-          "name": "DeepCompareResult",
-          "description": "Result type for deep comparison when objects are not identical",
-          "typeDefinition": "interface DeepCompareResult {}"
-        }
-      ]
-    },
     {
       "name": "deepMerge",
       "kind": "function",
@@ -240,6 +192,142 @@
       ],
       "sourceFile": "deepMerge.ts"
     },
+    {
+      "name": "diff",
+      "kind": "function",
+      "description": "Structural object diff.\n\nReturns `true` when both inputs are deeply equal, otherwise a\nDiffResult describing the differences key by key.\n\nComparison rules:\n- Same reference \\u2192 `true`.\n- Either side is `null`/`undefined` (and not both) \\u2192 `false`.\n- Both `Date` \\u2192 epoch comparison.\n- Both arrays \\u2192 compared with `array/equalsDeep` (leaf, no diff drill-down).\n- Special objects (Map, Set, RegExp, Promise, class instances\\u2026) \\u2192 reference equality.\n- Plain objects \\u2192 key-by-key, recursing up to `options.depth` levels.\n- Mixed types (e.g. array vs object, Date vs object) \\u2192 `false`.\n\nFor a boolean wrapper see equalsDeep from this category.\nFor a one-level boolean check see equalsShallow from this category.",
+      "since": "2.0.0",
+      "signatures": [
+        {
+          "signature": "diff(objA: object | null | undefined, objB: object | null | undefined, options: DiffOptions): boolean | DiffResult",
+          "description": "Structural object diff.\n\nReturns `true` when both inputs are deeply equal, otherwise a\nDiffResult describing the differences key by key.\n\nComparison rules:\n- Same reference \\u2192 `true`.\n- Either side is `null`/`undefined` (and not both) \\u2192 `false`.\n- Both `Date` \\u2192 epoch comparison.\n- Both arrays \\u2192 compared with `array/equalsDeep` (leaf, no diff drill-down).\n- Special objects (Map, Set, RegExp, Promise, class instances\\u2026) \\u2192 reference equality.\n- Plain objects \\u2192 key-by-key, recursing up to `options.depth` levels.\n- Mixed types (e.g. array vs object, Date vs object) \\u2192 `false`.\n\nFor a boolean wrapper see equalsDeep from this category.\nFor a one-level boolean check see equalsShallow from this category.",
+          "params": [
+            {
+              "name": "objA",
+              "type": "object | null | undefined",
+              "description": "First value (object, `null`, or `undefined`)."
+            },
+            {
+              "name": "objB",
+              "type": "object | null | undefined",
+              "description": "Second value (object, `null`, or `undefined`)."
+            },
+            {
+              "name": "options",
+              "type": "DiffOptions",
+              "description": "See DiffOptions.",
+              "defaultValue": "{}"
+            }
+          ],
+          "returns": {
+            "type": "boolean | DiffResult",
+            "description": "`true` when equal, otherwise a DiffResult, or `false` for incompatible types."
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Compare nested objects",
+          "description": "Deeply compares two objects, returning true when they are structurally equal.",
+          "code": "diff({ a: { b: 1 } }, { a: { b: 1 } })\n// => true"
+        },
+        {
+          "title": "Detect deep differences",
+          "description": "Returns a detailed diff object when nested values differ.",
+          "code": "diff({ a: { b: 1 } }, { a: { b: 2 } })\n// => { a: { b: false } }"
+        }
+      ],
+      "sourceFile": "diff.ts",
+      "relatedTypes": [
+        {
+          "name": "DiffOptions",
+          "description": "Options for diff.",
+          "typeDefinition": "interface DiffOptions {\n  depth?: number;\n}"
+        },
+        {
+          "name": "DiffResult",
+          "description": "Per-key diff result. Each entry tells what differs between the two\nobjects:\n- `\"onlyA\"` \\u2014 the key exists only on the first input.\n- `\"onlyB\"` \\u2014 the key exists only on the second input.\n- `false`  \\u2014 both inputs have the key but the values differ.\n- nested `DiffResult` \\u2014 plain-object values that differ deeper.",
+          "typeDefinition": "interface DiffResult {}"
+        }
+      ]
+    },
+    {
+      "name": "equalsDeep",
+      "kind": "function",
+      "description": "Recursive structural object equality.\n\nBoolean wrapper around diff \\u2014 returns `true` when the two values\nare deeply equal according to the same rules. Use this when you only\nneed a yes/no answer; use diff when you also need to know\n*what* differs.\n\nFor a one-level boolean check use equalsShallow.",
+      "since": "2.0.0",
+      "signatures": [
+        {
+          "signature": "equalsDeep(objA: object | null | undefined, objB: object | null | undefined): boolean",
+          "description": "Recursive structural object equality.\n\nBoolean wrapper around diff \\u2014 returns `true` when the two values\nare deeply equal according to the same rules. Use this when you only\nneed a yes/no answer; use diff when you also need to know\n*what* differs.\n\nFor a one-level boolean check use equalsShallow.",
+          "params": [
+            {
+              "name": "objA",
+              "type": "object | null | undefined",
+              "description": "First value (object, `null`, or `undefined`)."
+            },
+            {
+              "name": "objB",
+              "type": "object | null | undefined",
+              "description": "Second value (object, `null`, or `undefined`)."
+            }
+          ],
+          "returns": {
+            "type": "boolean",
+            "description": "`true` if both inputs are deeply equal, `false` otherwise."
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Compare nested objects",
+          "description": "Recursive structural equality. Returns true when the two values are deeply equal.",
+          "code": "equalsDeep({ a: { b: 1 } }, { a: { b: 1 } })\n// => true"
+        },
+        {
+          "title": "Detect deep differences",
+          "description": "Returns false when nested values differ.",
+          "code": "equalsDeep({ a: { b: 1 } }, { a: { b: 2 } })\n// => false"
+        }
+      ],
+      "sourceFile": "equalsDeep.ts"
+    },
+    {
+      "name": "equalsShallow",
+      "kind": "function",
+      "description": "One-level (shallow) object equality.\n\nTwo objects are equal when they share the exact same set of own\nenumerable string keys and each pair of values satisfies strict equality\n(`===`). No recursion: nested objects/arrays are compared by reference.\n\nFalls back to strict equality when either input is `null`, `undefined`\nor not an object \\u2014 so primitives match if and only if they are `===`.\nArrays are not supported; they always return `false` (unless identical\nreferences). Use `array/equalsShallow` instead.\n\nFor recursive structural comparison use equalsDeep. For a diff\nstructure use diff.",
+      "since": "2.0.0",
+      "signatures": [
+        {
+          "signature": "equalsShallow(objA: unknown, objB: unknown): boolean",
+          "description": "One-level (shallow) object equality.\n\nTwo objects are equal when they share the exact same set of own\nenumerable string keys and each pair of values satisfies strict equality\n(`===`). No recursion: nested objects/arrays are compared by reference.\n\nFalls back to strict equality when either input is `null`, `undefined`\nor not an object \\u2014 so primitives match if and only if they are `===`.\nArrays are not supported; they always return `false` (unless identical\nreferences). Use `array/equalsShallow` instead.\n\nFor recursive structural comparison use equalsDeep. For a diff\nstructure use diff.",
+          "params": [
+            {
+              "name": "objA",
+              "type": "unknown",
+              "description": "First value to compare"
+            },
+            {
+              "name": "objB",
+              "type": "unknown",
+              "description": "Second value to compare"
+            }
+          ],
+          "returns": {
+            "type": "boolean",
+            "description": "`true` if values are shallowly equal, `false` otherwise."
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Compare two equal objects",
+          "description": "Uses JSON.stringify for a fast comparison.",
+          "code": "equalsShallow({ a: 1, b: 2 }, { a: 1, b: 2 })\n// => true"
+        }
+      ],
+      "sourceFile": "equalsShallow.ts"
+    },
     {
       "name": "get",
       "kind": "function",
@@ -293,6 +381,170 @@
       ],
       "sourceFile": "get.ts"
     },
+    {
+      "name": "groupBy",
+      "kind": "function",
+      "description": "Groups an array of items by a key derived from each item.\n\nA thin, typed wrapper around `Object.groupBy` (ES2024) that works on\nolder targets and provides stricter return-type inference.",
+      "since": "2.0.0",
+      "signatures": [
+        {
+          "signature": "groupBy<T, K extends PropertyKey>(items: readonly T[], keyFn: function): Partial<Record<K, T[]>>",
+          "description": "Groups an array of items by a key derived from each item.\n\nA thin, typed wrapper around `Object.groupBy` (ES2024) that works on\nolder targets and provides stricter return-type inference.",
+          "params": [
+            {
+              "name": "items",
+              "type": "readonly T[]",
+              "description": "The array to group"
+            },
+            {
+              "name": "keyFn",
+              "type": "function",
+              "description": "Function that returns the group key for each item"
+            }
+          ],
+          "returns": {
+            "type": "Partial<Record<K, T[]>>",
+            "description": "A record mapping each key to the array of items with that key"
+          },
+          "typeParameters": [
+            {
+              "name": "T"
+            },
+            {
+              "name": "K",
+              "constraint": "PropertyKey"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Group numbers by parity",
+          "description": "Groups elements by the string key returned by the callback.",
+          "code": "groupBy([1, 2, 3, 4], n => n % 2 === 0 ? 'even' : 'odd')\n// => { odd: [1, 3], even: [2, 4] }"
+        },
+        {
+          "title": "Group objects by a property",
+          "description": "Use a property accessor as the grouping key.",
+          "code": "const users = [\n  { name: 'Alice', role: 'admin' },\n  { name: 'Bob',   role: 'user'  },\n  { name: 'Carol', role: 'admin' },\n];\ngroupBy(users, u => u.role)\n// => { admin: [{...Alice}, {...Carol}], user: [{...Bob}] }"
+        }
+      ],
+      "sourceFile": "groupBy.ts"
+    },
+    {
+      "name": "invert",
+      "kind": "function",
+      "description": "Returns a new object with keys and values swapped.\nIf multiple keys share the same value, the last one wins.",
+      "since": "2.0.0",
+      "signatures": [
+        {
+          "signature": "invert<K extends string, V extends PropertyKey>(obj: Record<K, V>): Record<V, K>",
+          "description": "Returns a new object with keys and values swapped.\nIf multiple keys share the same value, the last one wins.",
+          "params": [
+            {
+              "name": "obj",
+              "type": "Record<K, V>",
+              "description": "The object whose keys and values are to be swapped"
+            }
+          ],
+          "returns": {
+            "type": "Record<V, K>",
+            "description": "A new object with values as keys and original keys as values"
+          },
+          "typeParameters": [
+            {
+              "name": "K",
+              "constraint": "string"
+            },
+            {
+              "name": "V",
+              "constraint": "PropertyKey"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Swap keys and values",
+          "description": "Returns a new object with keys and values swapped.",
+          "code": "invert({ a: 'x', b: 'y', c: 'z' })\n// => { x: 'a', y: 'b', z: 'c' }"
+        },
+        {
+          "title": "Build a reverse lookup map",
+          "description": "Useful when you have a code-to-label map and need label-to-code.",
+          "code": "const STATUS_LABELS = { 200: 'OK', 404: 'Not Found', 500: 'Internal Server Error' };\nconst LABEL_TO_CODE = invert(STATUS_LABELS);\n\nLABEL_TO_CODE['OK']; // => '200'"
+        }
+      ],
+      "sourceFile": "invert.ts"
+    },
+    {
+      "name": "map",
+      "kind": "function",
+      "description": "Transforms the values and/or keys of a plain object in a single pass.\n\nBoth callbacks are optional and default to identity (no transformation).\nWhen `mapValue` is omitted the original values are preserved;\nwhen `mapKey` is omitted the original keys are preserved.\n\nNote: if two different keys map to the same output key the last one wins\n(insertion order).",
+      "since": "2.0.0",
+      "signatures": [
+        {
+          "signature": "map<TObj extends Record<string, unknown>, TVal = indexedAccess, TKey extends PropertyKey = keyof TObj>(obj: TObj, mapValue?: function, mapKey?: function): Record<TKey, TVal>",
+          "description": "Transforms the values and/or keys of a plain object in a single pass.\n\nBoth callbacks are optional and default to identity (no transformation).\nWhen `mapValue` is omitted the original values are preserved;\nwhen `mapKey` is omitted the original keys are preserved.\n\nNote: if two different keys map to the same output key the last one wins\n(insertion order).",
+          "params": [
+            {
+              "name": "obj",
+              "type": "TObj",
+              "description": "The source object"
+            },
+            {
+              "name": "mapValue",
+              "type": "function",
+              "description": "Callback called with `(value, key)` for each entry.\n  Defaults to identity.",
+              "optional": true
+            },
+            {
+              "name": "mapKey",
+              "type": "function",
+              "description": "Callback called with `(key, value)` for each entry.\n  Defaults to identity.",
+              "optional": true
+            }
+          ],
+          "returns": {
+            "type": "Record<TKey, TVal>",
+            "description": "A new object with transformed keys and/or values"
+          },
+          "typeParameters": [
+            {
+              "name": "TObj",
+              "constraint": "Record<string, unknown>"
+            },
+            {
+              "name": "TVal",
+              "default": "indexedAccess"
+            },
+            {
+              "name": "TKey",
+              "constraint": "PropertyKey",
+              "default": "keyof TObj"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Transform values",
+          "description": "Maps each value of an object through a transform function.",
+          "code": "map({ a: 1, b: 2 }, v => v * 10)\n// => { a: 10, b: 20 }"
+        },
+        {
+          "title": "Transform keys",
+          "description": "Maps each key of an object through a transform function.",
+          "code": "map({ a: 1, b: 2 }, undefined, k => k.toUpperCase())\n// => { A: 1, B: 2 }"
+        },
+        {
+          "title": "Transform both keys and values in a single pass",
+          "description": "Provide both a value mapper and a key mapper to rewrite the whole object.",
+          "code": "map(\n  { price: 100, discount: 20 },\n  v => v / 100,\n  k => `${k}Ratio`\n)\n// => { priceRatio: 1, discountRatio: 0.2 }"
+        }
+      ],
+      "sourceFile": "map.ts"
+    },
     {
       "name": "omit",
       "kind": "function",
@@ -546,7 +798,7 @@
       "name": "safeJsonParse",
       "kind": "function",
       "description": "Parses a JSON string, returning `null` (or a fallback) on any parse failure.\n\nUnlike `JSON.parse`, this never throws. Invalid JSON strings and other\nparsing edge-cases resolve to `null` or the provided `fallback`.",
-      "since": "next",
+      "since": "2.0.0",
       "signatures": [
         {
           "signature": "safeJsonParse<T>(input: string): T | null",
@@ -653,42 +905,6 @@
         }
       ],
       "sourceFile": "set.ts"
-    },
-    {
-      "name": "shallowEquals",
-      "kind": "function",
-      "description": "Quick comparison of two objects using JSON.stringify.\nThis is a fast but simple comparison that may not work for all edge cases.",
-      "since": "2.0.0",
-      "signatures": [
-        {
-          "signature": "shallowEquals(objA: unknown, objB: unknown): boolean",
-          "description": "Quick comparison of two objects using JSON.stringify.\nThis is a fast but simple comparison that may not work for all edge cases.",
-          "params": [
-            {
-              "name": "objA",
-              "type": "unknown",
-              "description": "First object to compare"
-            },
-            {
-              "name": "objB",
-              "type": "unknown",
-              "description": "Second object to compare"
-            }
-          ],
-          "returns": {
-            "type": "boolean",
-            "description": "`true` if objects are identical according to JSON.stringify, `false` otherwise"
-          }
-        }
-      ],
-      "examples": [
-        {
-          "title": "Compare two equal objects",
-          "description": "Uses JSON.stringify for a fast comparison.",
-          "code": "shallowEquals({ a: 1, b: 2 }, { a: 1, b: 2 })\n// => true"
-        }
-      ],
-      "sourceFile": "shallowEquals.ts"
     }
   ]
 }

package/meta/examples.json

@@ -27,27 +27,52 @@
       ]
     },
     {
-      "name": "deepCompare",
+      "name": "deepMerge",
+      "examples": [
+        {
+          "title": "Merge two objects deeply",
+          "description": "Recursively merges source properties into the target object.",
+          "code": "deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 }, e: 4 })\n// => { a: 1, b: { c: 2, d: 3 }, e: 4 }"
+        }
+      ]
+    },
+    {
+      "name": "diff",
       "examples": [
         {
           "title": "Compare nested objects",
           "description": "Deeply compares two objects, returning true when they are structurally equal.",
-          "code": "deepCompare({ a: { b: 1 } }, { a: { b: 1 } })\n// => true"
+          "code": "diff({ a: { b: 1 } }, { a: { b: 1 } })\n// => true"
         },
         {
           "title": "Detect deep differences",
           "description": "Returns a detailed diff object when nested values differ.",
-          "code": "deepCompare({ a: { b: 1 } }, { a: { b: 2 } })\n// => { a: { b: false } }"
+          "code": "diff({ a: { b: 1 } }, { a: { b: 2 } })\n// => { a: { b: false } }"
         }
       ]
     },
     {
-      "name": "deepMerge",
+      "name": "equalsDeep",
       "examples": [
         {
-          "title": "Merge two objects deeply",
-          "description": "Recursively merges source properties into the target object.",
-          "code": "deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 }, e: 4 })\n// => { a: 1, b: { c: 2, d: 3 }, e: 4 }"
+          "title": "Compare nested objects",
+          "description": "Recursive structural equality. Returns true when the two values are deeply equal.",
+          "code": "equalsDeep({ a: { b: 1 } }, { a: { b: 1 } })\n// => true"
+        },
+        {
+          "title": "Detect deep differences",
+          "description": "Returns false when nested values differ.",
+          "code": "equalsDeep({ a: { b: 1 } }, { a: { b: 2 } })\n// => false"
+        }
+      ]
+    },
+    {
+      "name": "equalsShallow",
+      "examples": [
+        {
+          "title": "Compare two equal objects",
+          "description": "Uses JSON.stringify for a fast comparison.",
+          "code": "equalsShallow({ a: 1, b: 2 }, { a: 1, b: 2 })\n// => true"
         }
       ]
     },
@@ -66,6 +91,56 @@
         }
       ]
     },
+    {
+      "name": "groupBy",
+      "examples": [
+        {
+          "title": "Group numbers by parity",
+          "description": "Groups elements by the string key returned by the callback.",
+          "code": "groupBy([1, 2, 3, 4], n => n % 2 === 0 ? 'even' : 'odd')\n// => { odd: [1, 3], even: [2, 4] }"
+        },
+        {
+          "title": "Group objects by a property",
+          "description": "Use a property accessor as the grouping key.",
+          "code": "const users = [\n  { name: 'Alice', role: 'admin' },\n  { name: 'Bob',   role: 'user'  },\n  { name: 'Carol', role: 'admin' },\n];\ngroupBy(users, u => u.role)\n// => { admin: [{...Alice}, {...Carol}], user: [{...Bob}] }"
+        }
+      ]
+    },
+    {
+      "name": "invert",
+      "examples": [
+        {
+          "title": "Swap keys and values",
+          "description": "Returns a new object with keys and values swapped.",
+          "code": "invert({ a: 'x', b: 'y', c: 'z' })\n// => { x: 'a', y: 'b', z: 'c' }"
+        },
+        {
+          "title": "Build a reverse lookup map",
+          "description": "Useful when you have a code-to-label map and need label-to-code.",
+          "code": "const STATUS_LABELS = { 200: 'OK', 404: 'Not Found', 500: 'Internal Server Error' };\nconst LABEL_TO_CODE = invert(STATUS_LABELS);\n\nLABEL_TO_CODE['OK']; // => '200'"
+        }
+      ]
+    },
+    {
+      "name": "map",
+      "examples": [
+        {
+          "title": "Transform values",
+          "description": "Maps each value of an object through a transform function.",
+          "code": "map({ a: 1, b: 2 }, v => v * 10)\n// => { a: 10, b: 20 }"
+        },
+        {
+          "title": "Transform keys",
+          "description": "Maps each key of an object through a transform function.",
+          "code": "map({ a: 1, b: 2 }, undefined, k => k.toUpperCase())\n// => { A: 1, B: 2 }"
+        },
+        {
+          "title": "Transform both keys and values in a single pass",
+          "description": "Provide both a value mapper and a key mapper to rewrite the whole object.",
+          "code": "map(\n  { price: 100, discount: 20 },\n  v => v / 100,\n  k => `${k}Ratio`\n)\n// => { priceRatio: 1, discountRatio: 0.2 }"
+        }
+      ]
+    },
     {
       "name": "omit",
       "examples": [
@@ -135,16 +210,6 @@
           "code": "set({}, 'a.b.c', 42)\n// => { a: { b: { c: 42 } } }"
         }
       ]
-    },
-    {
-      "name": "shallowEquals",
-      "examples": [
-        {
-          "title": "Compare two equal objects",
-          "description": "Uses JSON.stringify for a fast comparison.",
-          "code": "shallowEquals({ a: 1, b: 2 }, { a: 1, b: 2 })\n// => true"
-        }
-      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpers4/object",
-  "version": "2.0.0-beta.0",
+  "version": "2.0.0",
   "description": "A set of helpers in TS/JS, compatible with tree-shaking, for object.",
   "author": "baxyz <baxy@etik.com>",
   "license": "LGPL-3.0",
@@ -29,15 +29,19 @@
     "object",
     "compact",
     "deepClone",
-    "deepCompare",
     "deepMerge",
+    "diff",
+    "equalsDeep",
+    "equalsShallow",
     "get",
+    "groupBy",
+    "invert",
+    "map",
     "omit",
     "pick",
     "removeUndefinedNull",
     "safeJsonParse",
-    "set",
-    "shallowEquals"
+    "set"
   ],
   "files": [
     "lib/index.js",