generic merge object function

src/lib/util.ts

@@ -143,3 +143,55 @@ export const trimEdges = (str: string, char: string, trimStart?: boolean, trimEn
 
 	return str.substring(start, end);
 };
+
+// helper: only treat plain objects as mergeable
+const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+	typeof v === 'object' &&
+	v !== null &&
+	!Array.isArray(v) &&
+	Object.getPrototypeOf(v) === Object.prototype;
+
+/** Merge two plain object maps. No `any` used. */
+function mergePlainObjects(
+	baseObj: Record<string, unknown>,
+	overrideObj: Record<string, unknown>
+): Record<string, unknown> {
+	const res: Record<string, unknown> = { ...baseObj };
+
+	for (const k of Object.keys(overrideObj)) {
+		const v = overrideObj[k];
+		if (v === undefined) continue; // undefined preserves base
+		const b = res[k];
+
+		if (isPlainObject(v) && isPlainObject(b)) {
+			res[k] = mergePlainObjects(b as Record<string, unknown>, v as Record<string, unknown>);
+		} else {
+			// primitives, null, arrays, non-plain objects replace base
+			res[k] = v;
+		}
+	}
+
+	return res;
+}
+
+/**
+ * Merge `base` with `override`.
+ * - `null` in `override` replaces (kept as valid override)
+ * - `undefined` in `override` is ignored (keeps base)
+ * - Only plain objects are deep-merged
+ * - If `override` is null/undefined we return a shallow copy of `base`
+ */
+export const mergeOverrideObject = <T extends Record<string, unknown>>(
+	base: T,
+	override?: Partial<T> | null
+): T => {
+	if (override == null) return { ...base } as T;
+
+	// Use plain maps internally to avoid explicit any
+	const baseMap = { ...base } as Record<string, unknown>;
+	const overrideMap = override as Record<string, unknown>;
+
+	const merged = mergePlainObjects(baseMap, overrideMap);
+
+	return merged as T;
+};