Add `mergeOptions` function

[aleclarson]

Throwing this in here to eventually be added to Radashi. Currently, it depends on Merge from the type-fest npm package, which isn't ideal. We'll have to replace it before this can be added to Radashi.

The return type is pretty spooky, so I think there's value in such a function. Its purpose is to merge two optional objects in a type-safe way.

import type { Merge } from 'type-fest'

type Simplify<T> = {} & { [K in keyof T]: T[K] }

type UndefinedToPartial<T> = undefined extends T
  ? Partial<Exclude<T, undefined>>
  : T

export function mergeOptions<
  const A extends object | undefined,
  const B extends object | undefined,
>(
  a: A,
  b: B
): [A] extends [undefined]
  ? B // If A is always undefined, then B is the result.
  : [B] extends [undefined]
    ? A // If B is always undefined, then A is the result.
    :
        | (B extends object
            ? // Perform an { ...A, ...B } merge.
              Simplify<Merge<UndefinedToPartial<A>, B>>
            : never)
        | (undefined extends B
            ? Simplify<
                A & {
                  // This ensures all properties of B are accessible,
                  // even when B is undefined.
                  [K in B extends object
                    ? Exclude<keyof B, keyof A>
                    : never]?: undefined
                }
              >
            : never)
        | ([undefined, undefined] extends [A, B]
            ? // If both can be undefined, then undefined is possible.
              undefined
            : never)

export function mergeOptions(a: object | undefined, b: object | undefined): any {
  if (a === undefined) {
    return b
  }
  if (b === undefined) {
    return a
  }
  return {
    ...a,
    ...b,
  }
}

[fResult]

Could you give the possible input/output types?

For e.g.,

• mergeOptions({ a: number; }, undefined) => { a: number; }
• mergeOptions(undefined, undefined) => undefined
• mergeOptions({ a: number }, { b: string; }) => { a: number; b: string; }
• mergeOptions({ a: number; }, { a: string; }) => { a: number | string; }
• mergeOptions({ a: number; b: string; } | undefined, undefined) => { a?: number; b?: string; }

It would be nice to cover edge cases.

[aleclarson]

Here are some tests that cover most of the expected behavior:

import { expectTypeOf, test } from 'vitest'

declare function mergeOptions(left: any, right: any): any

// An undefined-only side is basically ignored.
test('mergeOptions undefined-only', () => {
  const r1 = mergeOptions({} as { a: number }, undefined)
  expectTypeOf(r1).toEqualTypeOf<{ a: number }>()

  const r2 = mergeOptions(undefined, {} as { a: number })
  expectTypeOf(r2).toEqualTypeOf<{ a: number }>()

  const r3 = mergeOptions({} as { a?: number }, undefined)
  expectTypeOf(r3).toEqualTypeOf<{ a?: number }>()

  const r4 = mergeOptions(undefined, {} as { a?: number })
  expectTypeOf(r4).toEqualTypeOf<{ a?: number }>()

  const r5 = mergeOptions(undefined, undefined)
  expectTypeOf(r5).toEqualTypeOf<undefined>()
})

// New properties are merged. Optionality is preserved.
test('mergeOptions new properties', () => {
  const r1 = mergeOptions({} as { a: number }, {} as { b: number; c?: number })
  expectTypeOf(r1).toEqualTypeOf<{ a: number; b: number; c?: number }>()

  const r2 = mergeOptions({} as { a?: number }, {} as { b: number })
  expectTypeOf(r2).toEqualTypeOf<{ a?: number; b: number }>()
})

// Right-hand properties overwrite left-hand properties.
test('mergeOptions overwrite', () => {
  const r1 = mergeOptions({} as { a: number }, {} as { a: string })
  expectTypeOf(r1).toEqualTypeOf<{ a: string }>()

  // If right-hand property is optional, the types are unioned.
  const r2 = mergeOptions({} as { a: number }, {} as { a?: string })
  expectTypeOf(r2).toEqualTypeOf<{ a: number | string }>()

  // If both sides are optional, the types are unioned.
  const r3 = mergeOptions({} as { a?: number }, {} as { a?: string })
  expectTypeOf(r3).toEqualTypeOf<{ a?: number | string }>()
})

// Conditionally undefined sides can be complex.
test('mergeOptions undefined-maybe', () => {
  // If left-hand side can be undefined, all left-hand properties
  // become optional unless overwritten by a required property on the
  // right-hand side.
  const r1 = mergeOptions(
    {} as { a: number; b: number; c: number } | undefined,
    {} as { c: string; d: string },
  )
  expectTypeOf(r1).toEqualTypeOf<{
    a?: number
    b?: number
    c: string
    d: string
  }>()

  // If right-hand side can be undefined, its new properties are
  // optional, and its conflicting properties inherit their
  // optionality from the left-hand side.
  const r2 = mergeOptions(
    {} as { a: number; b: number; c?: number },
    {} as { b: string; c: string; d: string } | undefined,
  )
  expectTypeOf(r2).toEqualTypeOf<{
    a: number
    b: number | string
    c?: number | string
    d?: string
  }>()

  // Both sides potentially undefined.
  const r3 = mergeOptions(
    {} as { a: number; b: number } | undefined,
    {} as { b: string; c: string } | undefined,
  )
  expectTypeOf(r3).toEqualTypeOf<{
    a?: number
    b?: number | string
    c?: string
  }>()
})