fix: Fix includeKeys return type when passing a union of objects

[gmaclennan]

Similar to #34, this uses a distributive conditional type that returns the correct type when using includeKeys on a union type.

I'm not sure if there is a strange edge-case that means this does not work as-expected for includeKeys, I don't want to break types for regular use.

[sindresorhus]

AI review:

---

Problems in the PR:

1. DistributivePick as written still requires the key to exist on every union arm. It needs Extract to narrow keys per arm. The diff doesn’t show any Extract<IncludedKeys, keyof Value>. ([GitHub][1])
2. No parity check for excludeKeys. It already distributes, but you should also use Extract there for symmetry and clearer intent (even though Omit tolerates non-existent keys).
3. Tests don’t cover the real edge: passing keys that exist only on some union members. The added includeKeys(object2, ['type', propertySymbol, 'qux']) uses keys present on both members (one is qux: string, the other qux: undefined), so it doesn’t catch the failure mode. ([GitHub][1])

Minimal fix (types only):

// Internal helpers
type DistributivePick<Value, Key extends PropertyKey> =
	Value extends unknown ? Pick<Value, Extract<Key, keyof Value>> : never;

type DistributiveOmit<Value, Key extends PropertyKey> =
	Value extends unknown ? Omit<Value, Extract<Key, keyof Value>> : never;

// includeKeys
export function includeKeys<
	ObjectType extends Record<PropertyKey, unknown>,
	IncludedKeys extends PropertyKey
>(
	object: ObjectType,
	keys: readonly IncludedKeys[] | ReadonlySet<IncludedKeys>
): DistributivePick<ObjectType, IncludedKeys>;

// excludeKeys
export function excludeKeys<
	ObjectType extends Record<PropertyKey, unknown>,
	ExcludedKeys extends PropertyKey
>(
	object: ObjectType,
	keys: readonly ExcludedKeys[] | ReadonlySet<ExcludedKeys>
): DistributiveOmit<ObjectType, ExcludedKeys>;

Add tests that actually fail without Extract:

type U =
	| { kind: 'a'; a: number }
	| { kind: 'b'; b: boolean }
	| { kind: 'c'; c: bigint };

declare const u: U;

// include keys present on some arms only
expectType<{ a: number } | {} | {}>(includeKeys(u, ['a'] as const));
expectType<{ b: boolean } | {} | {}>(includeKeys(u, ['b'] as const));
expectType<{ a: number } | { b: boolean } | {}>(includeKeys(u, ['a', 'b'] as const));

// parity for exclude
expectType<{ kind: 'a' } | { b: boolean; kind: 'b' } | { c: bigint; kind: 'c' }>(
	excludeKeys(
		({ kind: 'a', a: 1 } as U),
		['a', 'nonExistent'] as const
	)
);