@helpers4/object 2.0.2 → 2.0.4

package/meta/api.json

@@ -1,6 +1,6 @@
 {
   "category": "object",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "functions": [
     {
       "name": "compact",
@@ -113,73 +113,73 @@
     {
       "name": "deepMerge",
       "kind": "function",
-      "description": "Merges two or more objects deeply",
+      "description": "Merges two or more objects deeply.\n\nRecursively merges own enumerable properties — both string and symbol keys.\nPlain objects are merged recursively; all other values (arrays, class instances,\nprimitives, etc.) are replaced by the source value.\n`undefined` source values do not overwrite existing target values.",
       "since": "1.9.0",
       "signatures": [
         {
-          "signature": "deepMerge<T extends Record<string, unknown>>(target: T, sources: Record<string, unknown>[]): T",
-          "description": "Merges two or more objects deeply",
+          "signature": "deepMerge<T extends Record<PropertyKey, unknown>>(target: T, sources: Record<PropertyKey, unknown>[]): T",
+          "description": "Merges two or more objects deeply.\n\nRecursively merges own enumerable properties — both string and symbol keys.\nPlain objects are merged recursively; all other values (arrays, class instances,\nprimitives, etc.) are replaced by the source value.\n`undefined` source values do not overwrite existing target values.",
           "params": [
             {
               "name": "target",
               "type": "T",
-              "description": "The target object"
+              "description": "The target object (mutated in place)"
             },
             {
               "name": "sources",
-              "type": "Record<string, unknown>[]",
-              "description": "The source objects to merge"
+              "type": "Record<PropertyKey, unknown>[]",
+              "description": "One or more source objects to merge into the target"
             }
           ],
           "returns": {
             "type": "T",
-            "description": "The merged object"
+            "description": "The mutated target"
           },
           "typeParameters": [
             {
               "name": "T",
-              "constraint": "Record<string, unknown>"
+              "constraint": "Record<PropertyKey, unknown>"
             }
           ]
         },
         {
-          "signature": "deepMerge(target: undefined, sources: Record<string, unknown>[]): undefined",
-          "description": "Merges two or more objects deeply",
+          "signature": "deepMerge(target: undefined, sources: Record<PropertyKey, unknown>[]): undefined",
+          "description": "Merges two or more objects deeply.\n\nRecursively merges own enumerable properties — both string and symbol keys.\nPlain objects are merged recursively; all other values (arrays, class instances,\nprimitives, etc.) are replaced by the source value.\n`undefined` source values do not overwrite existing target values.",
           "params": [
             {
               "name": "target",
               "type": "undefined",
-              "description": "The target object"
+              "description": "The target object (mutated in place)"
             },
             {
               "name": "sources",
-              "type": "Record<string, unknown>[]",
-              "description": "The source objects to merge"
+              "type": "Record<PropertyKey, unknown>[]",
+              "description": "One or more source objects to merge into the target"
             }
           ],
           "returns": {
             "type": "undefined",
-            "description": "The merged object"
+            "description": "The mutated target"
           }
         },
         {
-          "signature": "deepMerge(target: null, sources: Record<string, unknown>[]): null",
-          "description": "Merges two or more objects deeply",
+          "signature": "deepMerge(target: null, sources: Record<PropertyKey, unknown>[]): null",
+          "description": "Merges two or more objects deeply.\n\nRecursively merges own enumerable properties — both string and symbol keys.\nPlain objects are merged recursively; all other values (arrays, class instances,\nprimitives, etc.) are replaced by the source value.\n`undefined` source values do not overwrite existing target values.",
           "params": [
             {
               "name": "target",
               "type": "null",
-              "description": "The target object"
+              "description": "The target object (mutated in place)"
             },
             {
               "name": "sources",
-              "type": "Record<string, unknown>[]",
-              "description": "The source objects to merge"
+              "type": "Record<PropertyKey, unknown>[]",
+              "description": "One or more source objects to merge into the target"
             }
           ],
           "returns": {
             "type": "null",
-            "description": "The merged object"
+            "description": "The mutated target"
           }
         }
       ],
@@ -331,33 +331,33 @@
     {
       "name": "get",
       "kind": "function",
-      "description": "Gets a value from an object using a dot-notated path",
+      "description": "Gets a value from an object using a dot/bracket-notated path or explicit key array.\n\n**Two path forms are supported:**\n\n1. **String path** — dot notation (`'a.b.c'`) and bracket notation (`'layers[1].name'`)\n   are both accepted and mixed freely. Segments are traversed as string keys; `[n]`\n   indices become numeric keys.\n\n2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables symbol-keyed traversal and compile-time type inference:\n   `get(obj, ['a', 'b'] as const)` infers the return type from the path.",
       "since": "1.9.0",
       "signatures": [
         {
           "signature": "get<T = unknown>(obj: unknown, path: string, defaultValue?: T): T | undefined",
-          "description": "Gets a value from an object using a dot-notated path",
+          "description": "Gets a value from an object using a dot/bracket-notated path or explicit key array.\n\n**Two path forms are supported:**\n\n1. **String path** — dot notation (`'a.b.c'`) and bracket notation (`'layers[1].name'`)\n   are both accepted and mixed freely. Segments are traversed as string keys; `[n]`\n   indices become numeric keys.\n\n2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables symbol-keyed traversal and compile-time type inference:\n   `get(obj, ['a', 'b'] as const)` infers the return type from the path.",
           "params": [
             {
               "name": "obj",
               "type": "unknown",
-              "description": "The object to get value from"
+              "description": "The object to read from"
             },
             {
               "name": "path",
               "type": "string",
-              "description": "The dot-notated path (e.g., 'a.b.c')"
+              "description": "Dot/bracket-notation string or explicit `PropertyKey[]`"
             },
             {
               "name": "defaultValue",
               "type": "T",
-              "description": "Default value if path doesn't exist",
+              "description": "Returned when the path is absent or resolves to `undefined`",
               "optional": true
             }
           ],
           "returns": {
             "type": "T | undefined",
-            "description": "The value at the path or default value"
+            "description": "The value at the path, or `defaultValue`"
           },
           "typeParameters": [
             {
@@ -365,6 +365,42 @@
               "default": "unknown"
             }
           ]
+        },
+        {
+          "signature": "get<T extends object, Path extends readonly PropertyKey[]>(obj: T, path: Path, defaultValue?: DeepGet<T, Path>): DeepGet<T, Path> | undefined",
+          "description": "Gets a value from an object using a dot/bracket-notated path or explicit key array.\n\n**Two path forms are supported:**\n\n1. **String path** — dot notation (`'a.b.c'`) and bracket notation (`'layers[1].name'`)\n   are both accepted and mixed freely. Segments are traversed as string keys; `[n]`\n   indices become numeric keys.\n\n2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables symbol-keyed traversal and compile-time type inference:\n   `get(obj, ['a', 'b'] as const)` infers the return type from the path.",
+          "params": [
+            {
+              "name": "obj",
+              "type": "T",
+              "description": "The object to read from"
+            },
+            {
+              "name": "path",
+              "type": "Path",
+              "description": "Dot/bracket-notation string or explicit `PropertyKey[]`"
+            },
+            {
+              "name": "defaultValue",
+              "type": "DeepGet<T, Path>",
+              "description": "Returned when the path is absent or resolves to `undefined`",
+              "optional": true
+            }
+          ],
+          "returns": {
+            "type": "DeepGet<T, Path> | undefined",
+            "description": "The value at the path, or `defaultValue`"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "constraint": "object"
+            },
+            {
+              "name": "Path",
+              "constraint": "readonly PropertyKey[]"
+            }
+          ]
         }
       ],
       "examples": [
@@ -377,6 +413,11 @@
           "title": "Return default for missing path",
           "description": "Returns the default value when the path does not exist.",
           "code": "get({ a: 1 }, 'b.c', 'default')\n// => 'default'"
+        },
+        {
+          "title": "Get via key array (supports symbols)",
+          "description": "Pass an explicit PropertyKey[] to bypass parsing. Supports string, number, and symbol keys.",
+          "code": "const id = Symbol('id')\nget({ [id]: 'alice' }, [id])\n// => 'alice'"
         }
       ],
       "sourceFile": "get.ts"
@@ -477,6 +518,78 @@
       ],
       "sourceFile": "invert.ts"
     },
+    {
+      "name": "isEmpty",
+      "kind": "function",
+      "description": "Checks if a plain object has no own enumerable string-keyed properties.\n\nSymbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`\nseparately if symbol keys matter for your use case.",
+      "since": "2.0.3",
+      "signatures": [
+        {
+          "signature": "isEmpty(value: Record<PropertyKey, unknown>): boolean",
+          "description": "Checks if a plain object has no own enumerable string-keyed properties.\n\nSymbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`\nseparately if symbol keys matter for your use case.",
+          "params": [
+            {
+              "name": "value",
+              "type": "Record<PropertyKey, unknown>",
+              "description": "The object to check"
+            }
+          ],
+          "returns": {
+            "type": "boolean",
+            "description": "`true` if the object has no own enumerable string-keyed properties"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Check if an object has no own string-keyed properties",
+          "description": "Returns true for `{}`. Symbol-keyed properties are not counted.",
+          "code": "isEmpty({})              // => true\nisEmpty({ a: 1 })        // => false\nisEmpty({ a: undefined }) // => false  (key exists even if value is undefined)"
+        },
+        {
+          "title": "Symbol keys are not counted",
+          "description": "An object with only symbol-keyed properties is considered empty.",
+          "code": "const sym = Symbol('x');\nconst obj = { [sym]: 1 };\nisEmpty(obj) // => true  (only string keys are counted)"
+        }
+      ],
+      "sourceFile": "isEmpty.ts"
+    },
+    {
+      "name": "isNonEmpty",
+      "kind": "function",
+      "description": "Checks if a plain object has at least one own enumerable string-keyed property.\n\nSymbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`\nseparately if symbol keys matter for your use case.",
+      "since": "2.0.3",
+      "signatures": [
+        {
+          "signature": "isNonEmpty(value: Record<PropertyKey, unknown>): boolean",
+          "description": "Checks if a plain object has at least one own enumerable string-keyed property.\n\nSymbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`\nseparately if symbol keys matter for your use case.",
+          "params": [
+            {
+              "name": "value",
+              "type": "Record<PropertyKey, unknown>",
+              "description": "The object to check"
+            }
+          ],
+          "returns": {
+            "type": "boolean",
+            "description": "`true` if the object has at least one own enumerable string-keyed property"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Check if an object has own string-keyed properties",
+          "description": "Returns true when at least one own enumerable string key is present.",
+          "code": "isNonEmpty({ a: 1 })        // => true\nisNonEmpty({ a: undefined }) // => true  (key exists)\nisNonEmpty({})              // => false"
+        },
+        {
+          "title": "Guard before iterating object keys",
+          "description": "Use isNonEmpty before looping to avoid processing empty objects.",
+          "code": "function processConfig(config: Record<string, unknown>): void {\n  if (!isNonEmpty(config)) {\n    console.warn('Config is empty');\n    return;\n  }\n  for (const key of Object.keys(config)) {\n    // process each key\n  }\n}"
+        }
+      ],
+      "sourceFile": "isNonEmpty.ts"
+    },
     {
       "name": "map",
       "kind": "function",
@@ -868,40 +981,89 @@
     {
       "name": "set",
       "kind": "function",
-      "description": "Sets a value in an object using a dot-notated path",
+      "description": "Sets a value in an object at the given path, creating intermediate objects as needed.\n\n**Three path forms are supported:**\n\n1. **Dot notation** (`string`) — segments split on `.` are kept as-is string keys.\n   `\"layers.1.name\"` → keys `[\"layers\", \"1\", \"name\"]` (all strings, including `\"1\"`).\n\n2. **Bracket notation** (`string`) — `[n]` segments are parsed as numeric keys.\n   `\"layers[1].name\"` → keys `[\"layers\", 1, \"name\"]` (index `1` becomes a number).\n   Dot and bracket can be mixed freely: `\"a[0].b[2].c\"`.\n\n3. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables full key-type control, including symbols:\n   `[\"layers\", 1, Symbol('id')]`.\n\nIntermediate nodes that are absent, `null`, or not an object are replaced with `{}`.\nAny path containing a string segment equal to `__proto__`, `constructor`, or `prototype`\nis rejected and the original object is returned unchanged (prototype-pollution guard).",
       "since": "1.9.0",
       "signatures": [
         {
           "signature": "set(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>",
-          "description": "Sets a value in an object using a dot-notated path",
+          "description": "Sets a value in an object at the given path, creating intermediate objects as needed.\n\n**Three path forms are supported:**\n\n1. **Dot notation** (`string`) — segments split on `.` are kept as-is string keys.\n   `\"layers.1.name\"` → keys `[\"layers\", \"1\", \"name\"]` (all strings, including `\"1\"`).\n\n2. **Bracket notation** (`string`) — `[n]` segments are parsed as numeric keys.\n   `\"layers[1].name\"` → keys `[\"layers\", 1, \"name\"]` (index `1` becomes a number).\n   Dot and bracket can be mixed freely: `\"a[0].b[2].c\"`.\n\n3. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables full key-type control, including symbols:\n   `[\"layers\", 1, Symbol('id')]`.\n\nIntermediate nodes that are absent, `null`, or not an object are replaced with `{}`.\nAny path containing a string segment equal to `__proto__`, `constructor`, or `prototype`\nis rejected and the original object is returned unchanged (prototype-pollution guard).",
           "params": [
             {
               "name": "obj",
               "type": "Record<string, unknown>",
-              "description": "The object to set value in"
+              "description": "The object to mutate"
             },
             {
               "name": "path",
               "type": "string",
-              "description": "The dot-notated path (e.g., 'a.b.c')"
+              "description": "Dot/bracket-notation string or explicit `PropertyKey[]`"
             },
             {
               "name": "value",
               "type": "unknown",
-              "description": "The value to set"
+              "description": "Value to assign at the path"
             }
           ],
           "returns": {
             "type": "Record<string, unknown>",
-            "description": "The modified object"
+            "description": "The mutated object (same reference)"
           }
+        },
+        {
+          "signature": "set<T extends object, Path extends readonly PropertyKey[], V extends unknown>(obj: T, path: Path, value: V): DeepSet<T, Path, V>",
+          "description": "Sets a value in an object at the given path, creating intermediate objects as needed.\n\n**Three path forms are supported:**\n\n1. **Dot notation** (`string`) — segments split on `.` are kept as-is string keys.\n   `\"layers.1.name\"` → keys `[\"layers\", \"1\", \"name\"]` (all strings, including `\"1\"`).\n\n2. **Bracket notation** (`string`) — `[n]` segments are parsed as numeric keys.\n   `\"layers[1].name\"` → keys `[\"layers\", 1, \"name\"]` (index `1` becomes a number).\n   Dot and bracket can be mixed freely: `\"a[0].b[2].c\"`.\n\n3. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables full key-type control, including symbols:\n   `[\"layers\", 1, Symbol('id')]`.\n\nIntermediate nodes that are absent, `null`, or not an object are replaced with `{}`.\nAny path containing a string segment equal to `__proto__`, `constructor`, or `prototype`\nis rejected and the original object is returned unchanged (prototype-pollution guard).",
+          "params": [
+            {
+              "name": "obj",
+              "type": "T",
+              "description": "The object to mutate"
+            },
+            {
+              "name": "path",
+              "type": "Path",
+              "description": "Dot/bracket-notation string or explicit `PropertyKey[]`"
+            },
+            {
+              "name": "value",
+              "type": "V",
+              "description": "Value to assign at the path"
+            }
+          ],
+          "returns": {
+            "type": "DeepSet<T, Path, V>",
+            "description": "The mutated object (same reference)"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "constraint": "object"
+            },
+            {
+              "name": "Path",
+              "constraint": "readonly PropertyKey[]"
+            },
+            {
+              "name": "V",
+              "constraint": "unknown"
+            }
+          ]
         }
       ],
       "examples": [
         {
-          "title": "Set a nested property",
-          "description": "Creates intermediate objects as needed along the dot-notated path.",
-          "code": "set({}, 'a.b.c', 42)\n// => { a: { b: { c: 42 } } }"
+          "title": "Set a nested property (dot notation)",
+          "description": "Creates intermediate objects as needed. All segments are string keys — including numeric-looking ones like \"1\".",
+          "code": "set({}, 'a.b.c', 42)\n// => { a: { b: { c: 42 } } }\n\nset({}, 'layers.1.name', 'bg')\n// => { layers: { '1': { name: 'bg' } } }   // '1' is a string key"
+        },
+        {
+          "title": "Set via bracket notation",
+          "description": "Square-bracket indices become numeric keys. Useful when the path targets an array element.",
+          "code": "const obj = { layers: [{}, { name: 'old' }] }\nset(obj, 'layers[1].name', 'new')\n// => { layers: [{}, { name: 'new' }] }"
+        },
+        {
+          "title": "Set via key array (supports symbols)",
+          "description": "Pass an explicit PropertyKey[] to bypass parsing. Supports string, number, and symbol keys.",
+          "code": "const id = Symbol('id')\nset({}, ['user', id], 'alice')\n// => { user: { [id]: 'alice' } }"
         }
       ],
       "sourceFile": "set.ts"

package/meta/examples.json

@@ -88,6 +88,11 @@
           "title": "Return default for missing path",
           "description": "Returns the default value when the path does not exist.",
           "code": "get({ a: 1 }, 'b.c', 'default')\n// => 'default'"
+        },
+        {
+          "title": "Get via key array (supports symbols)",
+          "description": "Pass an explicit PropertyKey[] to bypass parsing. Supports string, number, and symbol keys.",
+          "code": "const id = Symbol('id')\nget({ [id]: 'alice' }, [id])\n// => 'alice'"
         }
       ]
     },
@@ -121,6 +126,36 @@
         }
       ]
     },
+    {
+      "name": "isEmpty",
+      "examples": [
+        {
+          "title": "Check if an object has no own string-keyed properties",
+          "description": "Returns true for `{}`. Symbol-keyed properties are not counted.",
+          "code": "isEmpty({})              // => true\nisEmpty({ a: 1 })        // => false\nisEmpty({ a: undefined }) // => false  (key exists even if value is undefined)"
+        },
+        {
+          "title": "Symbol keys are not counted",
+          "description": "An object with only symbol-keyed properties is considered empty.",
+          "code": "const sym = Symbol('x');\nconst obj = { [sym]: 1 };\nisEmpty(obj) // => true  (only string keys are counted)"
+        }
+      ]
+    },
+    {
+      "name": "isNonEmpty",
+      "examples": [
+        {
+          "title": "Check if an object has own string-keyed properties",
+          "description": "Returns true when at least one own enumerable string key is present.",
+          "code": "isNonEmpty({ a: 1 })        // => true\nisNonEmpty({ a: undefined }) // => true  (key exists)\nisNonEmpty({})              // => false"
+        },
+        {
+          "title": "Guard before iterating object keys",
+          "description": "Use isNonEmpty before looping to avoid processing empty objects.",
+          "code": "function processConfig(config: Record<string, unknown>): void {\n  if (!isNonEmpty(config)) {\n    console.warn('Config is empty');\n    return;\n  }\n  for (const key of Object.keys(config)) {\n    // process each key\n  }\n}"
+        }
+      ]
+    },
     {
       "name": "map",
       "examples": [
@@ -205,9 +240,19 @@
       "name": "set",
       "examples": [
         {
-          "title": "Set a nested property",
-          "description": "Creates intermediate objects as needed along the dot-notated path.",
-          "code": "set({}, 'a.b.c', 42)\n// => { a: { b: { c: 42 } } }"
+          "title": "Set a nested property (dot notation)",
+          "description": "Creates intermediate objects as needed. All segments are string keys — including numeric-looking ones like \"1\".",
+          "code": "set({}, 'a.b.c', 42)\n// => { a: { b: { c: 42 } } }\n\nset({}, 'layers.1.name', 'bg')\n// => { layers: { '1': { name: 'bg' } } }   // '1' is a string key"
+        },
+        {
+          "title": "Set via bracket notation",
+          "description": "Square-bracket indices become numeric keys. Useful when the path targets an array element.",
+          "code": "const obj = { layers: [{}, { name: 'old' }] }\nset(obj, 'layers[1].name', 'new')\n// => { layers: [{}, { name: 'new' }] }"
+        },
+        {
+          "title": "Set via key array (supports symbols)",
+          "description": "Pass an explicit PropertyKey[] to bypass parsing. Supports string, number, and symbol keys.",
+          "code": "const id = Symbol('id')\nset({}, ['user', id], 'alice')\n// => { user: { [id]: 'alice' } }"
         }
       ]
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpers4/object",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "A set of helpers in TS/JS, compatible with tree-shaking, for object.",
   "author": "baxyz <baxy@etik.com>",
   "license": "LGPL-3.0",
@@ -36,6 +36,8 @@
     "get",
     "groupBy",
     "invert",
+    "isEmpty",
+    "isNonEmpty",
     "map",
     "omit",
     "pick",