type-fest 4.32.0 → 4.33.0

package/package.json

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

package/readme.md

@@ -370,6 +370,7 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 - `SetEntry` - See [`IterableElement`](source/iterable-element.d.ts)
 - `SetValues` - See [`IterableElement`](source/iterable-element.d.ts)
 - `PickByTypes` - See [`ConditionalPick`](source/conditional-pick.d.ts)
+- `HomomorphicOmit` - See [`Except`](source/except.d.ts)
 
 ## Tips
 

package/source/except.d.ts

@@ -69,6 +69,26 @@ type FooWithoutB = Except<Foo, 'b', {requireExactProps: true}>;
 
 const fooWithoutB: FooWithoutB = {a: 1, b: '2'};
 //=> errors at 'b': Type 'string' is not assignable to type 'undefined'.
+
+// The `Omit` utility type doesn't work when omitting specific keys from objects containing index signatures.
+
+// Consider the following example:
+
+type UserData = {
+	[metadata: string]: string;
+	email: string;
+	name: string;
+	role: 'admin' | 'user';
+};
+
+// `Omit` clearly doesn't behave as expected in this case:
+type PostPayload = Omit<UserData, 'email'>;
+//=> type PostPayload = { [x: string]: string; [x: number]: string; }
+
+// In situations like this, `Except` works better.
+// It simply removes the `email` key while preserving all the other keys.
+type PostPayload = Except<UserData, 'email'>;
+//=> type PostPayload = { [x: string]: string; name: string; role: 'admin' | 'user'; }
 ```
 
 @category Object

package/source/get.d.ts

@@ -205,6 +205,6 @@ export type Get<
 	BaseType,
 	Path extends
 	| readonly string[]
-	| LiteralStringUnion<ToString<Paths<BaseType, {bracketNotation: false}> | Paths<BaseType, {bracketNotation: true}>>>,
+	| LiteralStringUnion<ToString<Paths<BaseType, {bracketNotation: false; maxRecursionDepth: 2}> | Paths<BaseType, {bracketNotation: true; maxRecursionDepth: 2}>>>,
 	Options extends GetOptions = {}> =
 		GetWithPath<BaseType, Path extends string ? ToPath<Path> : Path, Options>;

package/source/internal/tuple.d.ts

@@ -37,9 +37,11 @@ If `<Fill>` is not provided, it will default to `unknown`.
 
 @link https://itnext.io/implementing-arithmetic-within-typescripts-type-system-a1ef140a6f6f
 */
-export type BuildTuple<L extends number, Fill = unknown, T extends readonly unknown[] = []> = T['length'] extends L
-	? T
-	: BuildTuple<L, Fill, [...T, Fill]>;
+export type BuildTuple<L extends number, Fill = unknown, T extends readonly unknown[] = []> = number extends L
+	? Fill[]
+	: L extends T['length']
+		? T
+		: BuildTuple<L, Fill, [...T, Fill]>;
 
 /**
 Returns the maximum value from a tuple of integers.

package/source/is-literal.d.ts

@@ -2,6 +2,7 @@ import type {Primitive} from './primitive';
 import type {Numeric} from './numeric';
 import type {IsNotFalse, IsPrimitive} from './internal';
 import type {IsNever} from './is-never';
+import type {IfNever} from './if-never';
 
 /**
 Returns a boolean for whether the given type `T` is the specified `LiteralType`.
@@ -65,6 +66,8 @@ Useful for:
 	- constraining strings to be a string literal
 	- type utilities, such as when constructing parsers and ASTs
 
+The implementation of this type is inspired by the trick mentioned in this [StackOverflow answer](https://stackoverflow.com/a/68261113/420747).
+
 @example
 ```
 import type {IsStringLiteral} from 'type-fest';
@@ -80,10 +83,45 @@ const output = capitalize('hello, world!');
 //=> 'Hello, world!'
 ```
 
+@example
+```
+// String types with infinite set of possible values return `false`.
+
+import type {IsStringLiteral} from 'type-fest';
+
+type AllUppercaseStrings = IsStringLiteral<Uppercase<string>>;
+//=> false
+
+type StringsStartingWithOn = IsStringLiteral<`on${string}`>;
+//=> false
+
+// This behaviour is particularly useful in string manipulation utilities, as infinite string types often require separate handling.
+
+type Length<S extends string, Counter extends never[] = []> =
+	IsStringLiteral<S> extends false
+		? number // return `number` for infinite string types
+		: S extends `${string}${infer Tail}`
+			? Length<Tail, [...Counter, never]>
+			: Counter['length'];
+
+type L1 = Length<Lowercase<string>>;
+//=> number
+
+type L2 = Length<`${number}`>;
+//=> number
+```
+
 @category Type Guard
 @category Utilities
 */
-export type IsStringLiteral<T> = LiteralCheck<T, string>;
+export type IsStringLiteral<T> = IfNever<T, false,
+// If `T` is an infinite string type (e.g., `on${string}`), `Record<T, never>` produces an index signature,
+// and since `{}` extends index signatures, the result becomes `false`.
+T extends string
+	? {} extends Record<T, never>
+		? false
+		: true
+	: false>;
 
 /**
 Returns a boolean for whether the given type is a `number` or `bigint` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).

package/source/keys-of-union.d.ts

@@ -1,3 +1,5 @@
+import type {UnionToIntersection} from './union-to-intersection';
+
 /**
 Create a union of all keys from a given type, even those exclusive to specific union members.
 
@@ -35,6 +37,6 @@ type AllKeys = KeysOfUnion<Union>;
 
 @category Object
 */
-export type KeysOfUnion<ObjectType> = ObjectType extends unknown
-	? keyof ObjectType
-	: never;
+export type KeysOfUnion<ObjectType> =
+  // Hack to fix https://github.com/sindresorhus/type-fest/issues/1008
+  keyof UnionToIntersection<ObjectType extends unknown ? Record<keyof ObjectType, never> : never>;

package/source/omit-index-signature.d.ts

@@ -61,18 +61,6 @@ type OmitIndexSignature<ObjectType> = {
 
 If `{}` is assignable, it means that `KeyType` is an index signature and we want to remove it. If it is not assignable, `KeyType` is a "real" key and we want to keep it.
 
-```
-import type {OmitIndexSignature} from 'type-fest';
-
-type OmitIndexSignature<ObjectType> = {
-	[KeyType in keyof ObjectType
-		as {} extends Record<KeyType, unknown>
-			? never // => Remove this `KeyType`.
-			: KeyType // => Keep this `KeyType` as it is.
-	]: ObjectType[KeyType];
-};
-```
-
 @example
 ```
 import type {OmitIndexSignature} from 'type-fest';

package/source/pick-index-signature.d.ts

@@ -3,8 +3,6 @@ Pick only index signatures from the given object type, leaving out all explicitl
 
 This is the counterpart of `OmitIndexSignature`.
 
-When you use a type that will iterate through an object that has indexed keys and explicitly defined keys you end up with a type where only the indexed keys are kept. This is because `keyof` of an indexed type always returns `string | number | symbol`, because every key is possible in that object. With this type, you can save the indexed keys and reinject them later, like in the second example below.
-
 @example
 ```
 import type {PickIndexSignature} from 'type-fest';
@@ -23,7 +21,7 @@ type Example = {
 	[x: `embedded-${number}`]: string;
 
 	// These explicitly defined keys will be removed.
-	['snake-case-key']: string;
+	['kebab-case-key']: string;
 	[symbolKey]: string;
 	foo: 'bar';
 	qux?: 'baz';
@@ -42,56 +40,6 @@ type ExampleIndexSignature = PickIndexSignature<Example>;
 // }
 ```
 
-@example
-```
-import type {OmitIndexSignature, PickIndexSignature, Simplify} from 'type-fest';
-
-type Foo = {
-	[x: string]: string;
-	foo: string;
-	bar: number;
-};
-
-// Imagine that you want a new type `Bar` that comes from `Foo`.
-// => {
-// 	[x: string]: string;
-// 	bar: number;
-// };
-
-type Bar = Omit<Foo, 'foo'>;
-// This is not working because `Omit` returns only indexed keys.
-// => {
-// 	[x: string]: string;
-// 	[x: number]: string;
-// }
-
-// One solution is to save the indexed signatures to new type.
-type FooIndexSignature = PickIndexSignature<Foo>;
-// => {
-// 	[x: string]: string;
-// }
-
-// Get a new type without index signatures.
-type FooWithoutIndexSignature = OmitIndexSignature<Foo>;
-// => {
-// 	foo: string;
-// 	bar: number;
-// }
-
-// At this point we can use Omit to get our new type.
-type BarWithoutIndexSignature = Omit<FooWithoutIndexSignature, 'foo'>;
-// => {
-// 	bar: number;
-// }
-
-// And finally we can merge back the indexed signatures.
-type BarWithIndexSignature = Simplify<BarWithoutIndexSignature & FooIndexSignature>;
-// => {
-// 	[x: string]: string;
-// 	bar: number;
-// }
-```
-
 @see OmitIndexSignature
 @category Object
 */

package/source/replace.d.ts

@@ -6,7 +6,7 @@ type ReplaceOptions = {
 Represents a string with some or all matches replaced by a replacement.
 
 Use-case:
-- `snake-case-path` to `dotted.path.notation`
+- `kebab-case-path` to `dotted.path.notation`
 - Changing date/time format: `01-08-2042` → `01/08/2042`
 - Manipulation of type properties, for example, removal of prefixes
 

package/source/set-optional.d.ts

@@ -34,6 +34,6 @@ export type SetOptional<BaseType, Keys extends keyof BaseType> =
 		// Pick just the keys that are readonly from the base type.
 		Except<BaseType, Keys> &
 		// Pick the keys that should be mutable from the base type and make them mutable.
-		Partial<HomomorphicPick<BaseType, Keys & KeysOfUnion<BaseType>>>
+		Partial<HomomorphicPick<BaseType, Keys>>
 		>
 		: never;

package/source/set-readonly.d.ts

@@ -35,6 +35,6 @@ export type SetReadonly<BaseType, Keys extends keyof BaseType> =
 	BaseType extends unknown
 		? Simplify<
 		Except<BaseType, Keys> &
-		Readonly<HomomorphicPick<BaseType, Keys & KeysOfUnion<BaseType>>>
+		Readonly<HomomorphicPick<BaseType, Keys>>
 		>
 		: never;

package/source/set-required-deep.d.ts

@@ -1,6 +1,10 @@
+import type {IsAny} from './is-any';
 import type {NonRecursiveType, StringToNumber} from './internal';
 import type {Paths} from './paths';
+import type {SetRequired} from './set-required';
 import type {SimplifyDeep} from './simplify-deep';
+import type {UnionToTuple} from './union-to-tuple';
+import type {RequiredDeep} from './required-deep';
 import type {UnknownArray} from './unknown-array';
 
 /**
@@ -28,19 +32,37 @@ type SomeRequiredDeep = SetRequiredDeep<Foo, 'a' | `c.${number}.d`>;
 // 		d: number // Is now required
 // 	}[]
 // }
+
+// Set specific indices in an array to be required.
+type ArrayExample = SetRequiredDeep<{a: [number?, number?, number?]}, 'a.0' | 'a.1'>;
+//=> {a: [number, number, number?]}
 ```
 
 @category Object
 */
-export type SetRequiredDeep<BaseType, KeyPaths extends Paths<BaseType>> =
-BaseType extends NonRecursiveType
+export type SetRequiredDeep<BaseType, KeyPaths extends Paths<BaseType>> = IsAny<KeyPaths> extends true
+	? SimplifyDeep<RequiredDeep<BaseType>>
+	: SetRequiredDeepHelper<BaseType, UnionToTuple<KeyPaths>>;
+
+/**
+Internal helper for {@link SetRequiredDeep}.
+
+Recursively transforms the `BaseType` by applying {@link SetRequiredDeepSinglePath} for each path in `KeyPathsTuple`.
+*/
+type SetRequiredDeepHelper<BaseType, KeyPathsTuple extends UnknownArray> =
+	KeyPathsTuple extends [infer KeyPath, ...infer RestPaths]
+		? SetRequiredDeepHelper<SetRequiredDeepSinglePath<BaseType, KeyPath>, RestPaths>
+		: BaseType;
+
+/**
+Makes a single path required in `BaseType`.
+*/
+type SetRequiredDeepSinglePath<BaseType, KeyPath> = BaseType extends NonRecursiveType
 	? BaseType
-	: SimplifyDeep<(
-		BaseType extends UnknownArray
-			? {}
-			: {[K in keyof BaseType as K extends (KeyPaths | StringToNumber<KeyPaths & string>) ? K : never]-?: BaseType[K]}
-	) & {
-		[K in keyof BaseType]: Extract<KeyPaths, `${K & (string | number)}.${string}`> extends never
-			? BaseType[K]
-			: SetRequiredDeep<BaseType[K], KeyPaths extends `${K & (string | number)}.${infer Rest extends Paths<BaseType[K]>}` ? Rest : never>
-	}>;
+	: KeyPath extends `${infer Property}.${infer RestPath}`
+		? {
+			[Key in keyof BaseType]: Property extends `${Key & (string | number)}`
+				? SetRequiredDeepSinglePath<BaseType[Key], RestPath>
+				: BaseType[Key];
+		}
+		: SetRequired<BaseType, (KeyPath | StringToNumber<KeyPath & string>) & keyof BaseType>;

package/source/set-required.d.ts

@@ -43,7 +43,7 @@ export type SetRequired<BaseType, Keys extends keyof BaseType> =
 		// Pick just the keys that are optional from the base type.
 		Except<BaseType, Keys> &
 		// Pick the keys that should be required from the base type and make them required.
-		Required<HomomorphicPick<BaseType, Keys & KeysOfUnion<BaseType>>>
+		Required<HomomorphicPick<BaseType, Keys>>
 		>;
 
 /**

package/source/split.d.ts

@@ -22,8 +22,14 @@ array = split(items, ',');
 export type Split<
 	S extends string,
 	Delimiter extends string,
+> = SplitHelper<S, Delimiter>;
+
+type SplitHelper<
+	S extends string,
+	Delimiter extends string,
+	Accumulator extends string[] = [],
 > = S extends `${infer Head}${Delimiter}${infer Tail}`
-	? [Head, ...Split<Tail, Delimiter>]
-	: S extends Delimiter
-		? []
-		: [S];
+	? SplitHelper<Tail, Delimiter, [...Accumulator, Head]>
+	: Delimiter extends ''
+		? Accumulator
+		: [...Accumulator, S];

package/source/string-repeat.d.ts

@@ -1,5 +1,5 @@
+import type {IsNumericLiteral} from './is-literal';
 import type {IsNegative} from './numeric';
-import type {Subtract} from './subtract';
 
 /**
 Returns a new string which contains the specified number of copies of a given string, just like `String#repeat()`.
@@ -28,16 +28,20 @@ stringRepeat('=', 3);
 export type StringRepeat<
 	Input extends string,
 	Count extends number,
-> = number extends Count
-	? Input extends ''
-		? ''
-		: string
-	: IsNegative<Count> extends true
+> = StringRepeatHelper<Input, Count>;
+
+type StringRepeatHelper<
+	Input extends string,
+	Count extends number,
+	Counter extends never[] = [],
+	Accumulator extends string = '',
+> =
+	IsNegative<Count> extends true
 		? never
-		: Count extends 0
+		: Input extends ''
 			? ''
-			: string extends Input
-				? string
-				: StringRepeat<Input, Subtract<Count, 1>> extends infer R extends string
-					? `${Input}${R}`
-					: never;
+			: Count extends Counter['length']
+				? Accumulator
+				: IsNumericLiteral<Count> extends false
+					? string
+					: StringRepeatHelper<Input, Count, [...Counter, never], `${Accumulator}${Input}`>;

package/source/string-slice.d.ts

@@ -31,7 +31,7 @@ export type StringSlice<
 	Start extends number = 0,
 	End extends number = StringToArray<S>['length'],
 > = string extends S
-	? string[]
+	? string
 	: ArraySlice<StringToArray<S>, Start, End> extends infer R extends readonly string[]
 		? Join<R, ''>
 		: never;