fix: preserve required properties when using onlyDefinedProperties

types/index.d.ts

@@ -1,6 +1,13 @@
 type DeepMergeFn = <T1, T2>(target: T1, source: T2) => DeepMerge<T1, T2>
 type DeepMergeAllFn = <T extends Array<any>>(...targets: T) => DeepMergeAll<{}, T>
 
+/**
+ * Merge function that preserves required properties from target when source may have undefined.
+ * Used when onlyDefinedProperties: true - undefined values in source don't override target.
+ */
+type DeepMergeDefinedFn = <T1, T2>(target: T1, source: T2) => DeepMergeDefined<T1, T2>
+type DeepMergeAllDefinedFn = <T extends Array<any>>(...targets: T) => DeepMergeAllDefined<{}, T>
+
 type Primitive =
   | null
   | undefined
@@ -31,7 +38,7 @@ type DeepMergeHelper<
   T,
   U,
   T0 = DifferenceKeys<T, U>
-  & { [K in keyof IntersectionKeys<T, U>]: DeepMerge<T[K], U[K]> },
+  & { [K in keyof IntersectionKeys<T, U>]: DeepMerge<K extends keyof T ? T[K] : never, K extends keyof U ? U[K] : never> },
   T1 = { [K in keyof T0]: T0[K] }
   > = T1
 
@@ -44,6 +51,90 @@ type DeepMerge<T, U> =
             ? DeepMergeHelper<T, U>
             : U
 
+/**
+ * For onlyDefinedProperties: true mode.
+ * When merging, if source value could be undefined, preserve target's type.
+ * This ensures that merging Partial<T> into T returns T, not Partial<T>.
+ */
+type ExcludeUndefined<T> = T extends undefined ? never : T
+
+/**
+ * Check if a type is a mergeable object (not array, not primitive, not builtin, not function)
+ * Using 'object' check which works with Partial types (unlike index signatures)
+ */
+type IsMergeableObject<T> = T extends BuiltIns
+  ? false
+  : T extends readonly any[]
+    ? false
+    : T extends (...args: any[]) => any
+      ? false
+      : T extends object
+        ? true
+        : false
+
+/**
+ * Get keys that exist in both T and U
+ */
+type CommonKeys<T, U> = keyof T & keyof U
+
+/**
+ * Get keys only in T (not in U)
+ */
+type OnlyTKeys<T, U> = Exclude<keyof T, keyof U>
+
+/**
+ * Get keys only in U (not in T)
+ */
+type OnlyUKeys<T, U> = Exclude<keyof U, keyof T>
+
+/**
+ * Merge a single property with onlyDefinedProperties semantics:
+ * - If source could be undefined, recursively merge but preserve target's definedness
+ * - If source cannot be undefined, normal merge applies
+ */
+type DeepMergeDefinedProperty<T, U> =
+  // If U could be undefined
+  [undefined] extends [U]
+    // Both T and ExcludeUndefined<U> are mergeable objects - merge them
+    ? [IsMergeableObject<T>, IsMergeableObject<ExcludeUndefined<U>>] extends [true, true]
+        ? DeepMergeDefinedHelper<T, ExcludeUndefined<U>>
+      // Otherwise use target's type (preserving non-undefined)
+        : T
+    // U cannot be undefined - normal deep merge
+    : DeepMergeDefined<T, U>
+
+/**
+ * Helper for onlyDefinedProperties mode.
+ * For intersection keys: preserve required-ness from target when source may be undefined.
+ */
+type DeepMergeDefinedHelper<T, U> = {
+  // Keys only in T: preserve from target
+  [K in OnlyTKeys<T, U>]: T[K]
+} & {
+  // Keys in both: merge with defined-property semantics
+  [K in CommonKeys<T, U>]: DeepMergeDefinedProperty<T[K], U[K]>
+} & {
+  // Keys only in U: include only if not potentially undefined
+  [K in OnlyUKeys<T, U> as [undefined] extends [U[K]] ? never : K]: U[K]
+} extends infer O ? { [K in keyof O]: O[K] } : never
+
+type DeepMergeDefined<T, U> =
+  U extends BuiltIns
+    ? [undefined] extends [U]
+        ? [undefined] extends [T] ? T : ExcludeUndefined<U> | T
+        : U
+    : [T, U] extends [readonly any[], readonly any[]]
+        ? MergeArrays<T, U>
+        : [IsMergeableObject<T>, IsMergeableObject<U>] extends [true, true]
+            ? DeepMergeDefinedHelper<T, U>
+            : [undefined] extends [U]
+                ? [undefined] extends [T] ? T : ExcludeUndefined<U> | T
+                : U
+
+type DeepMergeAllDefined<R, T> = First<T> extends never
+  ? R
+  : DeepMergeAllDefined<DeepMergeDefined<R, First<T>>, Rest<T>>
+
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 type First<T> = T extends [infer _I, ...infer _Rest] ? _I : never
 
@@ -87,13 +178,17 @@ interface Options {
 type DeepmergeConstructor = typeof deepmerge
 
 declare namespace deepmerge {
-  export { Options, DeepMergeFn, DeepMergeAllFn }
+  export { Options, DeepMergeFn, DeepMergeAllFn, DeepMergeDefinedFn, DeepMergeAllDefinedFn }
   export const deepmerge: DeepmergeConstructor
   export { deepmerge as default }
 
   export const isMergeableObject: (value: any) => boolean
 }
 
+declare function deepmerge (options: Options & { all: true; onlyDefinedProperties: true }): DeepMergeAllDefinedFn
+
+declare function deepmerge (options: Options & { onlyDefinedProperties: true }): DeepMergeDefinedFn
+
 declare function deepmerge (options: Options & { all: true }): DeepMergeAllFn
 
 declare function deepmerge (options?: Options): DeepMergeFn

types/index.test-d.ts

@@ -1,5 +1,8 @@
 import { expectAssignable, expectError, expectType } from 'tsd'
-import { deepmerge, type DeepMergeFn, type DeepMergeAllFn } from '.'
+import { deepmerge, type DeepMergeFn, type DeepMergeAllFn, DeepMergeDefinedFn, DeepMergeAllDefinedFn } from '.'
+
+// onlyDefinedProperties: true tests
+// When source has optional properties (Partial), merging into a full type should preserve required-ness
 
 expectAssignable<Function>(deepmerge())
 expectType<DeepMergeFn>(deepmerge())
@@ -84,3 +87,60 @@ deepmerge({
 
 expectType<(value: any) => boolean>(deepmerge.isMergeableObject)
 expectError(deepmerge.isMergeableObject = function () { return false })
+
+expectType<DeepMergeDefinedFn>(deepmerge({ onlyDefinedProperties: true }))
+expectType<DeepMergeAllDefinedFn>(deepmerge({ all: true, onlyDefinedProperties: true }))
+
+// Basic case: merging partial into full type preserves required properties
+interface FullOptions {
+  apiUrl: string
+  timeout: number
+  nested: {
+    enabled: boolean
+    value: string
+  }
+}
+
+type PartialOptions = Partial<FullOptions>
+
+// With onlyDefinedProperties: true, merging Partial<T> into T should return T
+// because undefined values from source are ignored at runtime
+const fullTarget: FullOptions = { apiUrl: 'url', timeout: 100, nested: { enabled: true, value: 'test' } }
+const partialSource: PartialOptions = { timeout: 200 }
+
+const mergedDefined = deepmerge({ onlyDefinedProperties: true })(fullTarget, partialSource)
+expectType<string>(mergedDefined.apiUrl)
+expectType<number>(mergedDefined.timeout)
+expectType<{ enabled: boolean; value: string }>(mergedDefined.nested)
+
+// Result should be assignable to FullOptions (the target type)
+expectAssignable<FullOptions>(mergedDefined)
+
+// Contrast with regular merge (without onlyDefinedProperties) - source undefined could override
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const mergedRegular = deepmerge()(fullTarget, partialSource)
+
+// Deep partial merging
+type DeepPartialOptions = {
+  apiUrl?: string
+  timeout?: number
+  nested?: {
+    enabled?: boolean
+    value?: string
+  }
+}
+
+const deepPartialSource: DeepPartialOptions = { nested: { enabled: false } }
+const mergedDeep = deepmerge({ onlyDefinedProperties: true })(fullTarget, deepPartialSource)
+expectType<string>(mergedDeep.apiUrl)
+expectType<number>(mergedDeep.timeout)
+// Nested properties should also preserve required-ness from target
+expectAssignable<{ enabled: boolean; value: string }>(mergedDeep.nested)
+
+// all mode with onlyDefinedProperties
+const mergedAll = deepmerge({ all: true, onlyDefinedProperties: true })(
+  fullTarget,
+  { timeout: 300 } as PartialOptions,
+  { apiUrl: 'newUrl' } as PartialOptions
+)
+expectAssignable<FullOptions>(mergedAll)