type-fest 3.8.0 → 3.9.0

package/index.d.ts

@@ -72,6 +72,7 @@ export type {StringKeyOf} from './source/string-key-of';
 export type {Exact} from './source/exact';
 export type {ReadonlyTuple} from './source/readonly-tuple';
 export type {OptionalKeysOf} from './source/optional-keys-of';
+export type {OverrideProperties} from './source/override-properties';
 export type {HasOptionalKeys} from './source/has-optional-keys';
 export type {RequiredKeysOf} from './source/required-keys-of';
 export type {HasRequiredKeys} from './source/has-required-keys';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "3.8.0",
+	"version": "3.9.0",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",

package/readme.md

@@ -135,6 +135,7 @@ Click the type names for complete docs.
 - [`Merge`](source/merge.d.ts) - Merge two types into a new type. Keys of the second type overrides keys of the first type.
 - [`MergeDeep`](source/merge-deep.d.ts) - Merge two objects or two arrays/tuples recursively into a new type.
 - [`MergeExclusive`](source/merge-exclusive.d.ts) - Create a type that has mutually exclusive keys.
+- [`OverrideProperties`](source/override-properties.d.ts) - Override only existing properties of the given type. Similar to `Merge`, but enforces that the original type has the properties you want to override.
 - [`RequireAtLeastOne`](source/require-at-least-one.d.ts) - Create a type that requires at least one of the given keys.
 - [`RequireExactlyOne`](source/require-exactly-one.d.ts) - Create a type that requires exactly a single key of the given keys and disallows more.
 - [`RequireAllOrNone`](source/require-all-or-none.d.ts) - Create a type that requires all of the given keys or none of the given keys.

package/source/join.d.ts

@@ -1,3 +1,13 @@
+// The builtin `join` method supports all these natively in the same way that typescript handles them so we can safely accept all of them.
+type JoinableItem = string | number | bigint | boolean | undefined | null;
+
+// `null` and `undefined` are treated uniquely in the built-in join method, in a way that differs from the default `toString` that would result in the type `${undefined}`. That's why we need to handle it specifically with this helper.
+// @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join#description
+type NullishCoalesce<
+	Value extends JoinableItem,
+	Fallback extends string,
+> = Value extends undefined | null ? NonNullable<Value> | Fallback : Value;
+
 /**
 Join an array of strings and/or numbers using the given string as a delimiter.
 
@@ -15,21 +25,44 @@ const path: Join<['foo', 'bar', 'baz'], '.'> = ['foo', 'bar', 'baz'].join('.');
 
 // Only number items; result is: '1.2.3'
 const path: Join<[1, 2, 3], '.'> = [1, 2, 3].join('.');
+
+// Only bigint items; result is '1.2.3'
+const path: Join<[1n, 2n, 3n], '.'> = [1n, 2n, 3n].join('.');
+
+// Only boolean items; result is: 'true.false.true'
+const path: Join<[true, false, true], '.'> = [true, false, true].join('.');
+
+// Contains nullish items; result is: 'foo..baz..xyz'
+const path: Join<['foo', undefined, 'baz', null, 'xyz'], '.'> = ['foo', undefined, 'baz', null, 'xyz'].join('.');
+
+// Partial tuple shapes (rest param last); result is: `prefix.${string}`
+const path: Join<['prefix', ...string[]], '.'> = ['prefix'].join('.');
+
+// Partial tuple shapes (rest param first); result is: `${string}.suffix`
+const path: Join<[...string[], 'suffix'], '.'> = ['suffix'].join('.');
+
+// Tuples items with nullish unions; result is '.' | 'hello.' | '.world' | 'hello.world'
+const path: Join<['hello' | undefined, 'world' | null], '.'> = ['hello', 'world'].join('.');
 ```
 
 @category Array
 @category Template literal
 */
 export type Join<
-	Strings extends ReadonlyArray<string | number>,
+	Items extends readonly JoinableItem[],
 	Delimiter extends string,
-> = Strings extends []
+> = Items extends []
 	? ''
-	: Strings extends readonly [string | number]
-		? `${Strings[0]}`
-		: Strings extends readonly [
-			string | number,
-			...infer Rest extends ReadonlyArray<string | number>,
+	: Items extends readonly [JoinableItem?]
+		? `${NullishCoalesce<Items[0], ''>}`
+		: Items extends readonly [
+			infer First extends JoinableItem,
+			...infer Tail extends readonly JoinableItem[],
 		]
-			? `${Strings[0]}${Delimiter}${Join<Rest, Delimiter>}`
-			: string;
+			? `${NullishCoalesce<First, ''>}${Delimiter}${Join<Tail, Delimiter>}`
+			: Items extends readonly [
+				...infer Head extends readonly JoinableItem[],
+				infer Last extends JoinableItem,
+			]
+				? `${Join<Head, Delimiter>}${Delimiter}${NullishCoalesce<Last, ''>}`
+				: string;

package/source/override-properties.d.ts

@@ -0,0 +1,26 @@
+import type {Merge} from './merge';
+
+/**
+Override existing properties of the given type. Similar to `Merge`, but enforces that the original type has the properties you want to override.
+
+This is useful when you want to override existing properties with a different type and make sure that these properties really exist in the original.
+
+@example
+```
+type Foo = {
+	a: string
+	b: string
+}
+type Bar = OverrideProperties<Foo, {b: number}>
+//=> {a: string, b: number}
+
+type Baz = OverrideProperties<Foo, {c: number}>
+// error TS2559: Type '{c: number}' has no properties in common with type 'Partial{a: unknown; b: unknown}>'.
+```
+
+@category Object
+*/
+export type OverrideProperties<
+	TOriginal,
+	TOverride extends Partial<{[key in keyof TOriginal]: unknown}>,
+> = Merge<TOriginal, TOverride>;