@pfeiferio/object-utils 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pascal Pfeifer <pascal@pfeifer.zone>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# @pfeiferio/object-utils
+
+Small, predictable utility functions for working with plain JavaScript objects.
+
+This package provides a minimal set of helpers for **object inspection and deep merging** with strict, explicit behavior and zero dependencies.
+
+---
+
+## Installation
+
+```bash
+npm install @pfeiferio/object-utils
+````
+
+---
+
+## Usage
+
+```ts
+import {
+  isObject,
+  isPlainObject,
+  mergeObjects
+} from '@pfeiferio/object-utils'
+```
+
+---
+
+## `isObject(value)`
+
+Checks whether a value is a **non-null object**, excluding arrays.
+
+```ts
+isObject({})        // true
+isObject([])        // false
+isObject(null)      // false
+isObject('string')  // false
+```
+
+This is a safe alternative to `typeof value === 'object'`.
+
+---
+
+## `isPlainObject(value)`
+
+Checks whether a value is a **plain object**.
+
+A plain object is defined as:
+
+* created via object literal (`{}`)
+* or `Object.create(null)`
+
+```ts
+isPlainObject({})                  // true
+isPlainObject(Object.create(null)) // true
+
+isPlainObject([])                  // false
+isPlainObject(new Date())          // false
+isPlainObject(null)                // false
+```
+
+Useful for merge logic and configuration handling.
+
+---
+
+## `mergeObjects(a, b)`
+
+Deeply merges two values.
+
+* **Only plain objects** are merged recursively
+* All other values **overwrite**
+* Inputs are **never mutated**
+
+```ts
+mergeObjects(
+  { server: { host: 'example.com' } },
+  { server: { port: 80 } }
+)
+// → { server: { host: 'example.com', port: 80 } }
+```
+
+### Overwrite behavior
+
+```ts
+mergeObjects(
+  { a: { b: 1 } },
+  { a: 2 }
+)
+// → { a: 2 }
+```
+
+```ts
+mergeObjects(
+  { list: [1, 2] },
+  { list: [3] }
+)
+// → { list: [3] }
+```
+
+### Non-plain values always win
+
+```ts
+mergeObjects(
+  { a: { b: 1 } },
+  null
+)
+// → null
+```
+
+---
+
+## Design Principles
+
+* Explicit semantics
+* No array merging
+* No mutation
+* Predictable results
+* Suitable for configuration and business logic
+
+This package intentionally avoids:
+
+* implicit deep cloning
+* class instance merging
+* array merging heuristics
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { isPlainObject } from "./isPlainObject.js";
+export { isObject } from "./isObject.js";
+export { mergeObjects } from "./mergeObjects.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAC,QAAQ,EAAC,MAAM,eAAe,CAAC;AACvC,OAAO,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { isPlainObject } from "./isPlainObject.js";
+export { isObject } from "./isObject.js";
+export { mergeObjects } from "./mergeObjects.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAC,QAAQ,EAAC,MAAM,eAAe,CAAC;AACvC,OAAO,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAC"}

package/dist/isObject.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Checks whether a value is a non-null object excluding arrays.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export declare const isObject: (value: unknown) => value is object;
+//# sourceMappingURL=isObject.d.ts.map

package/dist/isObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isObject.d.ts","sourceRoot":"","sources":["../src/isObject.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAMlD,CAAA"}

package/dist/isObject.js

@@ -0,0 +1,11 @@
+/**
+ * Checks whether a value is a non-null object excluding arrays.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export const isObject = (value) => {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value));
+};
+//# sourceMappingURL=isObject.js.map

package/dist/isObject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isObject.js","sourceRoot":"","sources":["../src/isObject.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAmB,EAAE;IAC1D,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CACtB,CAAA;AACH,CAAC,CAAA"}

package/dist/isPlainObject.d.ts

@@ -0,0 +1,17 @@
+type PlainObject = Record<string, unknown>;
+/**
+ * Checks whether a value is a plain object.
+ *
+ * A plain object is defined as an object created via object literal
+ * notation or `Object` constructor. Arrays, null, and all other
+ * non-object types are explicitly excluded.
+ *
+ * @param {*} value
+ *   The value to check.
+ *
+ * @returns {boolean}
+ *   `true` if the value is a plain object, otherwise `false`.
+ */
+export declare const isPlainObject: (value: unknown) => value is PlainObject;
+export {};
+//# sourceMappingURL=isPlainObject.d.ts.map

package/dist/isPlainObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isPlainObject.d.ts","sourceRoot":"","sources":["../src/isPlainObject.ts"],"names":[],"mappings":"AAEA,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE1C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,WAQvD,CAAA"}

package/dist/isPlainObject.js

@@ -0,0 +1,22 @@
+import { isObject } from "./isObject.js";
+/**
+ * Checks whether a value is a plain object.
+ *
+ * A plain object is defined as an object created via object literal
+ * notation or `Object` constructor. Arrays, null, and all other
+ * non-object types are explicitly excluded.
+ *
+ * @param {*} value
+ *   The value to check.
+ *
+ * @returns {boolean}
+ *   `true` if the value is a plain object, otherwise `false`.
+ */
+export const isPlainObject = (value) => {
+    if (!isObject(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+};
+//# sourceMappingURL=isPlainObject.js.map

package/dist/isPlainObject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isPlainObject.js","sourceRoot":"","sources":["../src/isPlainObject.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAC,MAAM,eAAe,CAAC;AAIvC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAc,EAAwB,EAAE;IAEpE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAA;IAC1C,OAAO,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,CAAA;AACrD,CAAC,CAAA"}

package/dist/mergeObjects.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Deeply merges two objects.
+ *
+ * Plain objects are merged recursively. For all other value types
+ * (arrays, primitives, null, or differing types), the value from
+ * the second object overrides the first one.
+ *
+ * This function does not mutate either input object.
+ *
+ * @param {Object} a
+ *   Base object.
+ *
+ * @param {Object} b
+ *   object whose values take precedence.
+ *
+ * @returns {Object}
+ *   A new object containing the merged result.
+ *
+ * @example
+ * mergeObjects(
+ *   { server: { host: 'example.com' } },
+ *   { server: { port: 80 } }
+ * )
+ * // → { server: { host: 'example.com', port: 80 } }
+ */
+/**
+ * @param a
+ * @param b
+ */
+export declare const mergeObjects: (a: unknown, b: unknown) => unknown;
+//# sourceMappingURL=mergeObjects.d.ts.map

package/dist/mergeObjects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mergeObjects.d.ts","sourceRoot":"","sources":["../src/mergeObjects.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,OAAO,EAAE,GAAG,OAAO,KAAG,OAmBrD,CAAA"}

package/dist/mergeObjects.js

@@ -0,0 +1,48 @@
+import { isPlainObject } from "./isPlainObject.js";
+/**
+ * Deeply merges two objects.
+ *
+ * Plain objects are merged recursively. For all other value types
+ * (arrays, primitives, null, or differing types), the value from
+ * the second object overrides the first one.
+ *
+ * This function does not mutate either input object.
+ *
+ * @param {Object} a
+ *   Base object.
+ *
+ * @param {Object} b
+ *   object whose values take precedence.
+ *
+ * @returns {Object}
+ *   A new object containing the merged result.
+ *
+ * @example
+ * mergeObjects(
+ *   { server: { host: 'example.com' } },
+ *   { server: { port: 80 } }
+ * )
+ * // → { server: { host: 'example.com', port: 80 } }
+ */
+/**
+ * @param a
+ * @param b
+ */
+export const mergeObjects = (a, b) => {
+    // if b is not a plain object, it always wins
+    if (!isPlainObject(a) || !isPlainObject(b)) {
+        return b;
+    }
+    const result = { ...a };
+    for (const [key, valueB] of Object.entries(b)) {
+        const valueA = a[key];
+        if (isPlainObject(valueA) && isPlainObject(valueB)) {
+            result[key] = mergeObjects(valueA, valueB);
+        }
+        else {
+            result[key] = valueB;
+        }
+    }
+    return result;
+};
+//# sourceMappingURL=mergeObjects.js.map

package/dist/mergeObjects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mergeObjects.js","sourceRoot":"","sources":["../src/mergeObjects.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,oBAAoB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAU,EAAE,CAAU,EAAW,EAAE;IAC9D,6CAA6C;IAC7C,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,OAAO,CAAC,CAAA;IACV,CAAC;IAED,MAAM,MAAM,GAA4B,EAAC,GAAG,CAAC,EAAC,CAAA;IAE9C,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAA;QAErB,IAAI,aAAa,CAAC,MAAM,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;YACnD,MAAM,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC5C,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAA;QACtB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@pfeiferio/object-utils",
+  "version": "1.0.0",
+  "description": "Small, predictable utilities for working with plain JavaScript objects",
+  "license": "MIT",
+  "author": "Pascal Pfeifer <pascal@pfeifer.zone>",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "object",
+    "utils",
+    "merge",
+    "plain-object",
+    "deep-merge",
+    "utility",
+    "configuration"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pfeiferio/utils-object.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pfeiferio/utils-object/issues"
+  },
+  "homepage": "https://github.com/pfeiferio/utils-object#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test",
+    "test:coverage": "npm run build && node --test --experimental-test-coverage",
+    "test:watch": "node --test --watch",
+    "prepublishOnly": "npm run clean && npm test",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.9",
+    "typescript": "^5.9.3"
+  }
+}