type-fest 2.12.2 → 2.13.0

package/source/kebab-cased-properties.d.ts

@@ -1,4 +1,4 @@
-import {DelimiterCasedProperties} from './delimiter-cased-properties';
+import type {DelimiterCasedProperties} from './delimiter-cased-properties';
 
 /**
 Convert object properties to kebab case but not recursively.
@@ -10,6 +10,8 @@ This can be useful when, for example, converting some API types from a different
 
 @example
 ```
+import type {KebabCasedProperties} from 'type-fest';
+
 interface User {
 	userId: number;
 	userName: string;

package/source/last-array-element.d.ts

@@ -5,7 +5,7 @@ Use-case: Defining the return type of functions that extract the last element of
 
 @example
 ```
-import {LastArrayElement} from 'type-fest';
+import type {LastArrayElement} from 'type-fest';
 
 declare function lastOf<V extends readonly any[]>(array: V): LastArrayElement<V>;
 

package/source/literal-to-primitive.d.ts

@@ -5,7 +5,7 @@ Use-case: Working with generic types that may be literal types.
 
 @example
 ```
-import {LiteralToPrimitive} from 'type-fest';
+import type {LiteralToPrimitive} from 'type-fest';
 
 // No overloads needed to get the correct return type
 function plus<T extends number | bigint | string>(x: T, y: T): LiteralToPrimitive<T> {

package/source/literal-union.d.ts

@@ -1,4 +1,4 @@
-import {Primitive} from './primitive';
+import type {Primitive} from './primitive';
 
 /**
 Allows creating a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
@@ -9,7 +9,7 @@ This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Mi
 
 @example
 ```
-import {LiteralUnion} from 'type-fest';
+import type {LiteralUnion} from 'type-fest';
 
 // Before
 

package/source/merge-exclusive.d.ts

@@ -10,7 +10,7 @@ This type works with a helper type, called `Without`. `Without<FirstType, Second
 
 @example
 ```
-import {MergeExclusive} from 'type-fest';
+import type {MergeExclusive} from 'type-fest';
 
 interface ExclusiveVariation1 {
 	exclusive1: boolean;

package/source/merge.d.ts

@@ -1,5 +1,5 @@
-import {Except} from './except';
-import {Simplify} from './simplify';
+import type {Except} from './except';
+import type {Simplify} from './simplify';
 
 type Merge_<FirstType, SecondType> = Except<FirstType, Extract<keyof FirstType, keyof SecondType>> & SecondType;
 
@@ -8,7 +8,7 @@ Merge two types into a new type. Keys of the second type overrides keys of the f
 
 @example
 ```
-import {Merge} from 'type-fest';
+import type {Merge} from 'type-fest';
 
 type Foo = {
 	a: number;

package/source/multidimensional-array.d.ts

@@ -1,4 +1,4 @@
-import {IsEqual, Subtract} from './internal';
+import type {IsEqual, Subtract} from './internal';
 
 type Recursive<T> = Array<Recursive<T>>;
 
@@ -13,7 +13,7 @@ Use-cases:
 
 @example
 ```
-import {MultidimensionalArray} from 'type-fest';
+import type {MultidimensionalArray} from 'type-fest';
 
 function emptyMatrix<T extends number>(dimensions: T): MultidimensionalArray<unknown, T> {
 	const matrix: unknown[] = [];

package/source/multidimensional-readonly-array.d.ts

@@ -1,4 +1,4 @@
-import {IsEqual, Subtract} from './internal';
+import type {IsEqual, Subtract} from './internal';
 
 type Recursive<T> = ReadonlyArray<Recursive<T>>;
 
@@ -13,7 +13,7 @@ Use-cases:
 
 @example
 ```
-import {MultidimensionalReadonlyArray} from 'type-fest';
+import type {MultidimensionalReadonlyArray} from 'type-fest';
 
 function emptyMatrix<T extends number>(dimensions: T): MultidimensionalReadonlyArray<unknown, T> {
 	const matrix: unknown[] = [];

package/source/mutable.d.ts

@@ -1,40 +1,5 @@
-import {Except} from './except';
-import {Simplify} from './simplify';
+import type {Writable} from './writable';
 
-/**
-Create a type that strips `readonly` from all or some of an object's keys. Inverse of `Readonly<T>`.
-
-This can be used to [store and mutate options within a class](https://github.com/sindresorhus/pageres/blob/4a5d05fca19a5fbd2f53842cbf3eb7b1b63bddd2/source/index.ts#L72), [edit `readonly` objects within tests](https://stackoverflow.com/questions/50703834), [construct a `readonly` object within a function](https://github.com/Microsoft/TypeScript/issues/24509), or to define a single model where the only thing that changes is whether or not some of the keys are mutable.
-
-@example
-```
-import {Mutable} from 'type-fest';
-
-type Foo = {
-	readonly a: number;
-	readonly b: readonly string[]; // To show that only the mutability status of the properties, not their values, are affected.
-	readonly c: boolean;
-};
-
-const mutableFoo: Mutable<Foo> = {a: 1, b: ['2'], c: true};
-mutableFoo.a = 3;
-mutableFoo.b[0] = 'new value'; // Will still fail as the value of property "b" is still a readonly type.
-mutableFoo.b = ['something']; // Will work as the "b" property itself is no longer readonly.
-
-type SomeMutable = Mutable<Foo, 'b' | 'c'>;
-// type SomeMutable = {
-// 	readonly a: number;
-// 	b: readonly string[]; // It's now mutable. The type of the property remains unaffected.
-// 	c: boolean; // It's now mutable.
-// }
-```
-
-@category Object
-*/
+/** @deprecated @see Writable */
 export type Mutable<BaseType, Keys extends keyof BaseType = keyof BaseType> =
-	Simplify<
-		// Pick just the keys that are not mutable from the base type.
-		Except<BaseType, Keys> &
-		// Pick the keys that should be mutable from the base type and make them mutable by removing the `readonly` modifier from the key.
-		{-readonly [KeyType in keyof Pick<BaseType, Keys>]: Pick<BaseType, Keys>[KeyType]}
-	>;
+	Writable<BaseType, Keys>;

package/source/numeric.d.ts

@@ -36,7 +36,7 @@ Use-case: Validating and documenting parameters.
 
 @example
 ```
-import {Finite} from 'type-fest';
+import type {Finite} from 'type-fest';
 
 declare function setScore<T extends number>(length: Finite<T>): void;
 ```
@@ -53,7 +53,7 @@ Use-case: Validating and documenting parameters.
 
 @example
 ```
-import {Integer} from 'type-fest';
+import type {Integer} from 'type-fest';
 
 declare function setYear<T extends number>(length: Integer<T>): void;
 ```
@@ -75,7 +75,7 @@ Use-case: Validating and documenting parameters.
 
 @example
 ```
-import {Float} from 'type-fest';
+import type {Float} from 'type-fest';
 
 declare function setPercentage<T extends number>(length: Float<T>): void;
 ```
@@ -136,7 +136,7 @@ Use-case: Validating and documenting parameters.
 
 @example
 ```
-import {NonNegative} from 'type-fest';
+import type {NonNegative} from 'type-fest';
 
 declare function setLength<T extends number>(length: NonNegative<T>): void;
 ```
@@ -158,7 +158,7 @@ Use-case: Validating and documenting parameters.
 
 @example
 ```
-import {NonNegativeInteger} from 'type-fest';
+import type {NonNegativeInteger} from 'type-fest';
 
 declare function setLength<T extends number>(length: NonNegativeInteger<T>): void;
 ```

package/source/opaque.d.ts

@@ -18,7 +18,7 @@ There have been several discussions about adding this feature to TypeScript via
 
 @example
 ```
-import {Opaque} from 'type-fest';
+import type {Opaque} from 'type-fest';
 
 type AccountNumber = Opaque<number, 'AccountNumber'>;
 type AccountBalance = Opaque<number, 'AccountBalance'>;

package/source/package-json.d.ts

@@ -1,4 +1,4 @@
-import {LiteralUnion} from './literal-union';
+import type {LiteralUnion} from './literal-union';
 
 declare namespace PackageJson {
 	/**
@@ -200,12 +200,12 @@ declare namespace PackageJson {
 		Run with the `npm restart` command, after `restart`. Note: `npm restart` will run the `stop` and `start` scripts if no `restart` script is provided.
 		*/
 		postrestart?: string;
-	} & Record<string, string>;
+	} & Partial<Record<string, string>>;
 
 	/**
 	Dependencies of the package. The version range is a string which has one or more space-separated descriptors. Dependencies can also be identified with a tarball or Git URL.
 	*/
-	export type Dependency = Record<string, string>;
+	export type Dependency = Partial<Record<string, string>>;
 
 	/**
 	Conditions which provide a way to resolve a package entry point based on the environment.
@@ -262,7 +262,7 @@ declare namespace PackageJson {
 		*/
 		browser?:
 		| string
-		| Record<string, string | false>;
+		| Partial<Record<string, string | false>>;
 
 		/**
 		Denote which files in your project are "pure" and therefore safe for Webpack to prune if unused.
@@ -281,7 +281,7 @@ declare namespace PackageJson {
 		/**
 		Version selection map of TypeScript.
 		*/
-		typesVersions?: Record<string, Record<string, string[]>>;
+		typesVersions?: Partial<Record<string, Partial<Record<string, string[]>>>>;
 
 		/**
 		Location of the bundled TypeScript declaration file. Alias of `types`.
@@ -442,7 +442,7 @@ declare namespace PackageJson {
 		*/
 		bin?:
 		| string
-		| Record<string, string>;
+		| Partial<Record<string, string>>;
 
 		/**
 		Filenames to put in place for the `man` program to find.
@@ -504,7 +504,7 @@ declare namespace PackageJson {
 		/**
 		Indicate peer dependencies that are optional.
 		*/
-		peerDependenciesMeta?: Record<string, {optional: true}>;
+		peerDependenciesMeta?: Partial<Record<string, {optional: true}>>;
 
 		/**
 		Package names that are bundled when the package is published.
@@ -520,7 +520,7 @@ declare namespace PackageJson {
 		Engines that this package runs on.
 		*/
 		engines?: {
-			[EngineName in 'npm' | 'node' | string]: string;
+			[EngineName in 'npm' | 'node' | string]?: string;
 		};
 
 		/**

package/source/partial-deep.d.ts

@@ -1,4 +1,4 @@
-import {BuiltIns} from './internal';
+import type {BuiltIns} from './internal';
 
 /**
 Create a type from another type with all keys and nested keys set to optional.
@@ -9,7 +9,7 @@ Use-cases:
 
 @example
 ```
-import {PartialDeep} from 'type-fest';
+import type {PartialDeep} from 'type-fest';
 
 const settings: Settings = {
 	textEditor: {

package/source/pascal-case.d.ts

@@ -1,11 +1,11 @@
-import {CamelCase} from './camel-case';
+import type {CamelCase} from './camel-case';
 
 /**
 Converts a string literal to pascal-case.
 
 @example
 ```
-import {PascalCase} from 'type-fest';
+import type {PascalCase} from 'type-fest';
 
 // Simple
 

package/source/pascal-cased-properties-deep.d.ts

@@ -1,4 +1,4 @@
-import {PascalCase} from './pascal-case';
+import type {PascalCase} from './pascal-case';
 
 /**
 Convert object properties to pascal case recursively.
@@ -10,6 +10,8 @@ This can be useful when, for example, converting some API types from a different
 
 @example
 ```
+import type {PascalCasedPropertiesDeep} from 'type-fest';
+
 interface User {
 	userId: number;
 	userName: string;

package/source/pascal-cased-properties.d.ts

@@ -1,4 +1,4 @@
-import {PascalCase} from './pascal-case';
+import type {PascalCase} from './pascal-case';
 
 /**
 Convert object properties to pascal case but not recursively.
@@ -10,6 +10,8 @@ This can be useful when, for example, converting some API types from a different
 
 @example
 ```
+import type {PascalCasedProperties} from 'type-fest';
+
 interface User {
 	userId: number;
 	userName: string;

package/source/promisable.d.ts

@@ -9,7 +9,7 @@ Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/31394)
 
 @example
 ```
-import {Promisable} from 'type-fest';
+import type {Promisable} from 'type-fest';
 
 async function logger(getLogEntry: () => Promisable<string>): Promise<void> {
 	const entry = await getLogEntry();

package/source/promise-value.d.ts

@@ -7,10 +7,10 @@ If the type is not a `Promise`, the type itself is returned.
 
 @example
 ```
-import {PromiseValue} from 'type-fest';
+import type {PromiseValue} from 'type-fest';
 
 type AsyncData = Promise<string>;
-let asyncData: PromiseValue<AsyncData> = Promise.resolve('ABC');
+let asyncData: AsyncData = Promise.resolve('ABC');
 
 type Data = PromiseValue<AsyncData>;
 let data: Data = await asyncData;
@@ -20,8 +20,8 @@ type SyncData = PromiseValue<string>;
 let syncData: SyncData = getSyncData();
 
 // Here's an example that shows how this type reacts to recursive Promise types.
-type RecursiveAsyncData = Promise<Promise<string> >;
-let recursiveAsyncData: PromiseValue<RecursiveAsyncData> = Promise.resolve(Promise.resolve('ABC'));
+type RecursiveAsyncData = Promise<Promise<string>>;
+let recursiveAsyncData: PromiseValue<RecursiveAsyncData> = await Promise.resolve(Promise.resolve('ABC'));
 ```
 
 @category Async

package/source/readonly-deep.d.ts

@@ -1,4 +1,4 @@
-import {BuiltIns} from './internal';
+import type {BuiltIns} from './internal';
 
 /**
 Convert `object`s, `Map`s, `Set`s, and `Array`s and all of their keys/elements into immutable structures recursively.
@@ -15,7 +15,7 @@ Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/13923)
 }
 
 // main.ts
-import {ReadonlyDeep} from 'type-fest';
+import type {ReadonlyDeep} from 'type-fest';
 import dataJson = require('./data.json');
 
 const data: ReadonlyDeep<typeof dataJson> = dataJson;

package/source/readonly-tuple.d.ts

@@ -0,0 +1,41 @@
+/**
+Creates a read-only tuple of type `Element` and with the length of `Length`.
+
+@private
+@see `ReadonlyTuple` which is safer because it tests if `Length` is a specific finite number.
+*/
+type BuildTupleHelper<Element, Length extends number, Rest extends Element[]> =
+	Rest['length'] extends Length ?
+		readonly [...Rest] : // Terminate with readonly array (aka tuple)
+		BuildTupleHelper<Element, Length, [Element, ...Rest]>;
+
+/**
+Create a type that represents a read-only tuple of the given type and length.
+
+Use-cases:
+- Declaring fixed-length tuples with a large number of items.
+- Creating a range union (for example, `0 | 1 | 2 | 3 | 4` from the keys of such a type) without having to resort to recursive types.
+- Creating a tuple of coordinates with a static length, for example, length of 3 for a 3D vector.
+
+@example
+```
+import {ReadonlyTuple} from 'type-fest';
+
+type FencingTeam = ReadonlyTuple<string, 3>;
+
+const guestFencingTeam: FencingTeam = ['Josh', 'Michael', 'Robert'];
+
+const homeFencingTeam: FencingTeam = ['George', 'John'];
+//=> error TS2322: Type string[] is not assignable to type 'FencingTeam'
+
+guestFencingTeam.push('Sam');
+//=> error TS2339: Property 'push' does not exist on type 'FencingTeam'
+```
+
+@category Utilities
+*/
+export type ReadonlyTuple<Element, Length extends number> =
+	number extends Length
+		// Because `Length extends number` and `number extends Length`, then `Length` is not a specific finite number.
+		? readonly Element[] // It's not fixed length.
+		: BuildTupleHelper<Element, Length, []>; // Otherwise it is a fixed length tuple.

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

@@ -34,15 +34,19 @@ type Keyed = {} extends Record<'foo' | 'bar', unknown>
 Using a [mapped type](https://www.typescriptlang.org/docs/handbook/2/mapped-types.html#further-exploration), you can then check for each `KeyType` of `ObjectType`...
 
 ```
+import type {RemoveIndexSignature} from 'type-fest';
+
 type RemoveIndexSignature<ObjectType> = {
 	[KeyType in keyof ObjectType // Map each key of `ObjectType`...
-  ]: ObjectType[KeyType]; // ...to its original value, i.e. `RemoveIndexSignature<Foo> == Foo`.
+	]: ObjectType[KeyType]; // ...to its original value, i.e. `RemoveIndexSignature<Foo> == Foo`.
 };
 ```
 
 ...whether an empty object (`{}`) would be assignable to an object with that `KeyType` (`Record<KeyType, unknown>`)...
 
 ```
+import type {RemoveIndexSignature} from 'type-fest';
+
 type RemoveIndexSignature<ObjectType> = {
 	[KeyType in keyof ObjectType
 		// Is `{}` assignable to `Record<KeyType, unknown>`?
@@ -56,6 +60,8 @@ type RemoveIndexSignature<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 {RemoveIndexSignature} from 'type-fest';
+
 type RemoveIndexSignature<ObjectType> = {
 	[KeyType in keyof ObjectType
 		as {} extends Record<KeyType, unknown>
@@ -67,7 +73,7 @@ type RemoveIndexSignature<ObjectType> = {
 
 @example
 ```
-import {RemoveIndexSignature} from 'type-fest';
+import type {RemoveIndexSignature} from 'type-fest';
 
 interface Example {
 	// These index signatures will be removed.

package/source/replace.d.ts

@@ -0,0 +1,67 @@
+type ReplaceOptions = {
+	all?: boolean;
+};
+
+/**
+Represents a string with some or all matches replaced by a replacement.
+
+Use-case:
+- `snake-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
+
+@example
+```
+import {Replace} from 'type-fest';
+
+declare function replace<
+	Input extends string,
+	Search extends string,
+	Replacement extends string
+>(
+	input: Input,
+	search: Search,
+	replacement: Replacement
+): Replace<Input, Search, Replacement>;
+
+declare function replaceAll<
+	Input extends string,
+	Search extends string,
+	Replacement extends string
+>(
+	input: Input,
+	search: Search,
+	replacement: Replacement
+): Replace<Input, Search, Replacement, {all: true}>;
+
+// The return type is the exact string literal, not just `string`.
+
+replace('hello ?', '?', '🦄');
+//=> 'hello 🦄'
+
+replace('hello ??', '?', '❓');
+//=> 'hello ❓?'
+
+replaceAll('10:42:00', ':', '-');
+//=> '10-42-00'
+
+replaceAll('__userName__', '__', '');
+//=> 'userName'
+
+replaceAll('My Cool Title', ' ', '');
+//=> 'MyCoolTitle'
+```
+
+@category String
+@category Template literal
+*/
+export type Replace<
+	Input extends string,
+	Search extends string,
+	Replacement extends string,
+	Options extends ReplaceOptions = {},
+> = Input extends `${infer Head}${Search}${infer Tail}`
+	? Options['all'] extends true
+		? Replace<`${Head}${Replacement}${Tail}`, Search, Replacement, Options>
+		: `${Head}${Replacement}${Tail}`
+	: Input;

package/source/require-all-or-none.d.ts

@@ -8,7 +8,7 @@ The caveat with `RequireAllOrNone` is that TypeScript doesn't always know at com
 
 @example
 ```
-import {RequireAllOrNone} from 'type-fest';
+import type {RequireAllOrNone} from 'type-fest';
 
 type Responder = {
 	text?: () => string;

package/source/require-at-least-one.d.ts

@@ -1,11 +1,11 @@
-import {Except} from './except';
+import type {Except} from './except';
 
 /**
 Create a type that requires at least one of the given keys. The remaining keys are kept as is.
 
 @example
 ```
-import {RequireAtLeastOne} from 'type-fest';
+import type {RequireAtLeastOne} from 'type-fest';
 
 type Responder = {
 	text?: () => string;

package/source/require-exactly-one.d.ts

@@ -9,7 +9,7 @@ The caveat with `RequireExactlyOne` is that TypeScript doesn't always know at co
 
 @example
 ```
-import {RequireExactlyOne} from 'type-fest';
+import type {RequireExactlyOne} from 'type-fest';
 
 type Responder = {
 	text: () => string;

package/source/schema.d.ts

@@ -8,7 +8,7 @@ Use-cases:
 
 @example
 ```
-import {Schema} from 'type-fest';
+import type {Schema} from 'type-fest';
 
 interface User {
 	id: string;

package/source/screaming-snake-case.d.ts

@@ -1,6 +1,6 @@
-import {SplitIncludingDelimiters} from './delimiter-case';
-import {SnakeCase} from './snake-case';
-import {Includes} from './includes';
+import type {SplitIncludingDelimiters} from './delimiter-case';
+import type {SnakeCase} from './snake-case';
+import type {Includes} from './includes';
 
 /**
 Returns a boolean for whether the string is screaming snake case.
@@ -18,7 +18,7 @@ This can be useful when, for example, converting a camel-cased object property t
 
 @example
 ```
-import {ScreamingSnakeCase} from 'type-fest';
+import type {ScreamingSnakeCase} from 'type-fest';
 
 const someVariable: ScreamingSnakeCase<'fooBar'> = 'FOO_BAR';
 ```

package/source/set-optional.d.ts

@@ -1,5 +1,5 @@
-import {Except} from './except';
-import {Simplify} from './simplify';
+import type {Except} from './except';
+import type {Simplify} from './simplify';
 
 /**
 Create a type that makes the given keys optional. The remaining keys are kept as is. The sister of the `SetRequired` type.
@@ -8,7 +8,7 @@ Use-case: You want to define a single model where the only thing that changes is
 
 @example
 ```
-import {SetOptional} from 'type-fest';
+import type {SetOptional} from 'type-fest';
 
 type Foo = {
 	a: number;

package/source/set-required.d.ts

@@ -1,5 +1,5 @@
-import {Except} from './except';
-import {Simplify} from './simplify';
+import type {Except} from './except';
+import type {Simplify} from './simplify';
 
 /**
 Create a type that makes the given keys required. The remaining keys are kept as is. The sister of the `SetOptional` type.
@@ -8,7 +8,7 @@ Use-case: You want to define a single model where the only thing that changes is
 
 @example
 ```
-import {SetRequired} from 'type-fest';
+import type {SetRequired} from 'type-fest';
 
 type Foo = {
 	a?: number;

package/source/set-return-type.d.ts

@@ -9,7 +9,7 @@ Use-case: You want to define a wrapped function that returns something different
 
 @example
 ```
-import {SetReturnType} from 'type-fest';
+import type {SetReturnType} from 'type-fest';
 
 type MyFunctionThatCanThrow = (foo: SomeType, bar: unknown) => SomeOtherType;
 

package/source/simplify.d.ts

@@ -3,7 +3,7 @@ Useful to flatten the type output to improve type hints shown in editors. And al
 
 @example
 ```
-import {Simplify} from 'type-fest';
+import type {Simplify} from 'type-fest';
 
 type PositionProps = {
 	top: number;
@@ -25,7 +25,7 @@ If the type definition must be an interface (perhaps it was defined in a third-p
 
 @example
 ```
-import {Simplify} from 'type-fest';
+import type {Simplify} from 'type-fest';
 
 interface SomeInterface {
 	foo: number;