type-fest 3.6.0 → 3.7.0

package/index.d.ts

@@ -7,6 +7,7 @@ export * from './source/observable-like';
 // Utilities
 export type {EmptyObject, IsEmptyObject} from './source/empty-object';
 export type {Except} from './source/except';
+export type {TaggedUnion} from './source/tagged-union';
 export type {Writable} from './source/writable';
 export type {WritableDeep} from './source/writable-deep';
 export type {Merge} from './source/merge';
@@ -76,6 +77,13 @@ export type {HasRequiredKeys} from './source/has-required-keys';
 export type {Spread} from './source/spread';
 export type {TupleToUnion} from './source/tuple-to-union';
 export type {IsEqual} from './source/is-equal';
+export type {
+	IsLiteral,
+	IsStringLiteral,
+	IsNumericLiteral,
+	IsBooleanLiteral,
+	IsSymbolLiteral,
+} from './source/is-literal';
 
 // Template literal types
 export type {CamelCase} from './source/camel-case';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "3.6.0",
+	"version": "3.7.0",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -36,8 +36,8 @@
 	"devDependencies": {
 		"@sindresorhus/tsconfig": "~0.7.0",
 		"expect-type": "^0.15.0",
-		"tsd": "^0.24.1",
-		"typescript": "^4.9.3",
+		"tsd": "^0.28.0",
+		"typescript": "^5.0.2",
 		"xo": "^0.53.1"
 	},
 	"xo": {
@@ -49,5 +49,10 @@
 			"@typescript-eslint/no-redeclare": "off",
 			"@typescript-eslint/no-confusing-void-expression": "off"
 		}
+	},
+	"tsd": {
+		"compilerOptions": {
+			"noUnusedLocals": false
+		}
 	}
 }

package/readme.md

@@ -120,6 +120,8 @@ Click the type names for complete docs.
 - [`Primitive`](source/primitive.d.ts) - Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
 - [`Class`](source/basic.d.ts) - Matches a [`class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
 - [`Constructor`](source/basic.d.ts) - Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
+- [`AbstractClass`](source/basic.d.ts) - Matches an [`abstract class`](https://www.typescriptlang.org/docs/handbook/classes.html#abstract-classes).
+- [`AbstractConstructor`](source/basic.d.ts) - Matches an [`abstract class`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-2.html#abstract-construct-signatures) constructor.
 - [`TypedArray`](source/typed-array.d.ts) - Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
 - [`ObservableLike`](source/observable-like.d.ts) - Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
 
@@ -171,6 +173,12 @@ Click the type names for complete docs.
 - [`HasRequiredKeys`](source/has-required-keys.d.ts) - Create a `true`/`false` type depending on whether the given type has any required fields.
 - [`Spread`](source/spread.d.ts) - Mimic the type inferred by TypeScript when merging two objects or two arrays/tuples using the spread syntax.
 - [`IsEqual`](source/is-equal.d.ts) - Returns a boolean for whether the two given types are equal.
+- [`IsLiteral`](source/is-literal.d.ts) - Returns a boolean for whether the given type is a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+- [`IsStringLiteral`](source/is-literal.d.ts) - Returns a boolean for whether the given type is a `string` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+- [`IsNumericLiteral`](source/is-literal.d.ts) - 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).
+- [`IsBooleanLiteral`](source/is-literal.d.ts) - Returns a boolean for whether the given type is a `true` or `false` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+- [`IsSymbolLiteral`](source/is-literal.d.ts) - Returns a boolean for whether the given type is a `symbol` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+- [`TaggedUnion`](source/tagged-union.d.ts) - Create a union of types that share a common discriminant property.
 
 ### JSON
 

package/source/basic.d.ts

@@ -12,6 +12,20 @@ Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/Jav
 */
 export type Constructor<T, Arguments extends unknown[] = any[]> = new(...arguments_: Arguments) => T;
 
+/**
+Matches an [`abstract class`](https://www.typescriptlang.org/docs/handbook/classes.html#abstract-classes).
+
+@category Class
+*/
+export type AbstractClass<T, Arguments extends unknown[] = any[]> = AbstractConstructor<T, Arguments> & {prototype: T};
+
+/**
+Matches an [`abstract class`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-2.html#abstract-construct-signatures) constructor.
+
+@category Class
+*/
+export type AbstractConstructor<T, Arguments extends unknown[] = any[]> = abstract new(...arguments_: Arguments) => T;
+
 /**
 Matches a JSON object.
 

package/source/except.d.ts

@@ -29,9 +29,22 @@ type Filtered = Filter<'bar', 'foo'>;
 */
 type Filter<KeyType, ExcludeType> = IsEqual<KeyType, ExcludeType> extends true ? never : (KeyType extends ExcludeType ? never : KeyType);
 
+type ExceptOptions = {
+	/**
+	Disallow assigning non-specified properties.
+
+	Note that any omitted properties in the resulting type will be present in autocomplete as `undefined`.
+
+	@default false
+	*/
+	requireExactProps?: boolean;
+};
+
 /**
 Create a type from an object type without certain keys.
 
+We recommend setting the `requireExactProps` option to `true`.
+
 This type is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-5.html#the-omit-helper-type). The `Omit` type does not restrict the omitted keys to be keys present on the given type, while `Except` does. The benefits of a stricter type are avoiding typos and allowing the compiler to pick up on rename refactors automatically.
 
 This type was proposed to the TypeScript team, which declined it, saying they prefer that libraries implement stricter versions of the built-in types ([microsoft/TypeScript#30825](https://github.com/microsoft/TypeScript/issues/30825#issuecomment-523668235)).
@@ -43,15 +56,25 @@ import type {Except} from 'type-fest';
 type Foo = {
 	a: number;
 	b: string;
-	c: boolean;
 };
 
-type FooWithoutA = Except<Foo, 'a' | 'c'>;
-//=> {b: string};
+type FooWithoutA = Except<Foo, 'a'>;
+//=> {b: string}
+
+const fooWithoutA: FooWithoutA = {a: 1, b: '2'};
+//=> errors: 'a' does not exist in type '{ b: string; }'
+
+type FooWithoutB = Except<Foo, 'b', {requireExactProps: true}>;
+//=> {a: number} & Partial<Record<"b", never>>
+
+const fooWithoutB: FooWithoutB = {a: 1, b: '2'};
+//=> errors at 'b': Type 'string' is not assignable to type 'undefined'.
 ```
 
 @category Object
 */
-export type Except<ObjectType, KeysType extends keyof ObjectType> = {
+export type Except<ObjectType, KeysType extends keyof ObjectType, Options extends ExceptOptions = {requireExactProps: false}> = {
 	[KeyType in keyof ObjectType as Filter<KeyType, KeysType>]: ObjectType[KeyType];
-};
+} & (Options['requireExactProps'] extends true
+	? Partial<Record<KeysType, never>>
+	: {});

package/source/internal.d.ts

@@ -257,3 +257,8 @@ export type HasMultipleCallSignatures<T extends (...arguments: any[]) => unknown
 			? false
 			: true
 		: false;
+
+/**
+Returns a boolean for whether the given `boolean` is not `false`.
+*/
+export type IsNotFalse<T extends boolean> = [T] extends [false] ? false : true;

package/source/is-literal.d.ts

@@ -0,0 +1,252 @@
+import type {Primitive} from './primitive';
+import type {Numeric} from './numeric';
+import type {IsNever, IsNotFalse} from './internal';
+
+/**
+Returns a boolean for whether the given type `T` is the specified `LiteralType`.
+
+@link https://stackoverflow.com/a/52806744/10292952
+
+@example
+```
+LiteralCheck<1, number>
+//=> true
+
+LiteralCheck<number, number>
+//=> false
+
+LiteralCheck<1, string>
+//=> false
+```
+*/
+type LiteralCheck<T, LiteralType extends Primitive> = (
+	IsNever<T> extends false // Must be wider than `never`
+		? [T] extends [LiteralType] // Must be narrower than `LiteralType`
+			? [LiteralType] extends [T] // Cannot be wider than `LiteralType`
+				? false
+				: true
+			: false
+		: false
+);
+
+/**
+Returns a boolean for whether the given type `T` is one of the specified literal types in `LiteralUnionType`.
+
+@example
+```
+LiteralChecks<1, Numeric>
+//=> true
+
+LiteralChecks<1n, Numeric>
+//=> true
+
+LiteralChecks<bigint, Numeric>
+//=> false
+```
+*/
+type LiteralChecks<T, LiteralUnionType> = (
+	// Conditional type to force union distribution.
+	// If `T` is none of the literal types in the union `LiteralUnionType`, then `LiteralCheck<T, LiteralType>` will evaluate to `false` for the whole union.
+	// If `T` is one of the literal types in the union, it will evaluate to `boolean` (i.e. `true | false`)
+	IsNotFalse<LiteralUnionType extends Primitive
+		? LiteralCheck<T, LiteralUnionType>
+		: never
+	>
+);
+
+/**
+Returns a boolean for whether the given type is a `string` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+
+Useful for:
+	- providing strongly-typed string manipulation functions
+	- constraining strings to be a string literal
+	- type utilities, such as when constructing parsers and ASTs
+
+@example
+```
+import type {IsStringLiteral} from 'type-fest';
+
+type CapitalizedString<T extends string> = IsStringLiteral<T> extends true ? Capitalize<T> : string;
+
+// https://github.com/yankeeinlondon/native-dash/blob/master/src/capitalize.ts
+function capitalize<T extends Readonly<string>>(input: T): CapitalizedString<T> {
+	return (input.slice(0, 1).toUpperCase() + input.slice(1)) as CapitalizedString<T>;
+}
+
+const output = capitalize('hello, world!');
+//=> 'Hello, world!'
+```
+
+@category Utilities
+@category Type Guard
+*/
+export type IsStringLiteral<T> = LiteralCheck<T, string>;
+
+/**
+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).
+
+Useful for:
+	- providing strongly-typed functions when given literal arguments
+	- type utilities, such as when constructing parsers and ASTs
+
+@example
+```
+import type {IsNumericLiteral} from 'type-fest';
+
+// https://github.com/inocan-group/inferred-types/blob/master/src/types/boolean-logic/EndsWith.ts
+type EndsWith<TValue, TEndsWith extends string> =
+	TValue extends string
+		? IsStringLiteral<TEndsWith> extends true
+			? IsStringLiteral<TValue> extends true
+				? TValue extends `${string}${TEndsWith}`
+					? true
+					: false
+				: boolean
+			: boolean
+		: TValue extends number
+			? IsNumericLiteral<TValue> extends true
+				? EndsWith<`${TValue}`, TEndsWith>
+				: false
+			: false;
+
+function endsWith<Input extends string | number, End extends string>(input: Input, end: End) {
+	return `${input}`.endsWith(end) as EndsWith<Input, End>;
+}
+
+endsWith('abc', 'c');
+//=> true
+
+endsWith(123456, '456');
+//=> true
+
+const end = '123' as string;
+
+endsWith('abc123', end);
+//=> boolean
+```
+
+@category Utilities
+@category Type Guard
+*/
+export type IsNumericLiteral<T> = LiteralChecks<T, Numeric>;
+
+/**
+Returns a boolean for whether the given type is a `true` or `false` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+
+Useful for:
+	- providing strongly-typed functions when given literal arguments
+	- type utilities, such as when constructing parsers and ASTs
+
+@example
+```
+import type {IsBooleanLiteral} from 'type-fest';
+
+const id = 123;
+
+type GetId<AsString extends boolean> =
+	IsBooleanLiteral<AsString> extends true
+		? AsString extends true
+			? `${typeof id}`
+			: typeof id
+		: number | string;
+
+function getId<AsString extends boolean = false>(options?: {asString: AsString}) {
+	return (options?.asString ? `${id}` : id) as GetId<AsString>;
+}
+
+const numberId = getId();
+//=> 123
+
+const stringId = getId({asString: true});
+//=> '123'
+
+declare const runtimeBoolean: boolean;
+const eitherId = getId({asString: runtimeBoolean});
+//=> number | string
+```
+
+@category Utilities
+@category Type Guard
+*/
+export type IsBooleanLiteral<T> = LiteralCheck<T, boolean>;
+
+/**
+Returns a boolean for whether the given type is a `symbol` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+
+Useful for:
+	- providing strongly-typed functions when given literal arguments
+	- type utilities, such as when constructing parsers and ASTs
+
+@example
+```
+import type {IsSymbolLiteral} from 'type-fest';
+
+type Get<Obj extends Record<symbol, number>, Key extends keyof Obj> =
+	IsSymbolLiteral<Key> extends true
+		? Obj[Key]
+		: number;
+
+function get<Obj extends Record<symbol, number>, Key extends keyof Obj>(o: Obj, key: Key) {
+	return o[key] as Get<Obj, Key>;
+}
+
+const symbolLiteral = Symbol('literal');
+const symbolValue: symbol = Symbol('value');
+
+get({[symbolLiteral]: 1} as const, symbolLiteral);
+//=> 1
+
+get({[symbolValue]: 1} as const, symbolValue);
+//=> number
+```
+
+@category Utilities
+@category Type Guard
+*/
+export type IsSymbolLiteral<T> = LiteralCheck<T, symbol>;
+
+/** Helper type for `IsLiteral`. */
+type IsLiteralUnion<T> =
+	| IsStringLiteral<T>
+	| IsNumericLiteral<T>
+	| IsBooleanLiteral<T>
+	| IsSymbolLiteral<T>;
+
+/**
+Returns a boolean for whether the given type is a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+
+Useful for:
+	- providing strongly-typed functions when given literal arguments
+	- type utilities, such as when constructing parsers and ASTs
+
+@example
+```
+import type {IsLiteral} from 'type-fest';
+
+// https://github.com/inocan-group/inferred-types/blob/master/src/types/string-literals/StripLeading.ts
+export type StripLeading<A, B> =
+	A extends string
+		? B extends string
+			? IsLiteral<A> extends true
+				? string extends B ? never : A extends `${B & string}${infer After}` ? After : A
+				: string
+			: A
+		: A;
+
+function stripLeading<Input extends string, Strip extends string>(input: Input, strip: Strip) {
+	return input.replace(`^${strip}`, '') as StripLeading<Input, Strip>;
+}
+
+stripLeading('abc123', 'abc');
+//=> '123'
+
+const str = 'abc123' as string;
+
+stripLeading(str, 'abc');
+//=> string
+```
+
+@category Utilities
+@category Type Guard
+*/
+export type IsLiteral<T extends Primitive> = IsNotFalse<IsLiteralUnion<T>>;

package/source/join.d.ts

@@ -21,15 +21,15 @@ const path: Join<[1, 2, 3], '.'> = [1, 2, 3].join('.');
 @category Template literal
 */
 export type Join<
-	Strings extends Readonly<Array<string | number>>,
+	Strings extends ReadonlyArray<string | number>,
 	Delimiter extends string,
 > = Strings extends []
 	? ''
-	: Strings extends [string | number]
+	: Strings extends readonly [string | number]
 		? `${Strings[0]}`
 		: Strings extends readonly [
 			string | number,
-			...infer Rest extends Array<string | number>,
+			...infer Rest extends ReadonlyArray<string | number>,
 		]
 			? `${Strings[0]}${Delimiter}${Join<Rest, Delimiter>}`
 			: string;

package/source/tagged-union.d.ts

@@ -0,0 +1,51 @@
+/**
+Create a union of types that share a common discriminant property.
+
+Use-case: A shorter way to declare tagged unions with multiple members.
+
+@example
+```
+import type {TaggedUnion} from 'type-fest';
+
+type Tagged<Fields extends Record<string, unknown> = TaggedUnion<'type', Fields>
+
+// The TaggedUnion utility reduces the amount of boilerplate needed to create a tagged union with multiple members, making the code more concise.
+type EventMessage = Tagged<{
+	OpenExternalUrl: {
+		url: string;
+		id: number;
+		language: string;
+	};
+	ToggleBackButtonVisibility: {
+		visible: boolean;
+	};
+	PurchaseButtonPressed: {
+		price: number;
+		time: Date;
+	};
+	NavigationStateChanged: {
+		navigation?: string;
+	};
+}>;
+
+// Here is the same type created without this utility.
+type EventMessage =
+	| {
+		type: 'OpenExternalUrl';
+		url: string;
+		id: number;
+		language: string;
+	}
+	| {type: 'ToggleBackButtonVisibility'; visible: boolean}
+	| {type: 'PurchaseButtonPressed'; price: number; time: Date}
+	| {type: 'NavigationStateChanged'; navigation?: string};
+```
+
+@category Utilities
+*/
+export type TaggedUnion<
+	TagKey extends string,
+	UnionMembers extends Record<string, Record<string, unknown>>,
+> = {
+	[Name in keyof UnionMembers]: {[Key in TagKey]: Name} & UnionMembers[Name];
+}[keyof UnionMembers];

package/source/tsconfig-json.d.ts

@@ -225,18 +225,24 @@ declare namespace TsConfigJson {
 		export type ModuleResolution =
 			| 'classic'
 			| 'node'
+			| 'node10'
 			| 'node16'
 			| 'nodenext'
+			| 'bundler'
 			// Pascal-cased alternatives
 			| 'Classic'
 			| 'Node'
+			| 'Node10'
 			| 'Node16'
-			| 'NodeNext';
+			| 'NodeNext'
+			| 'Bundler';
 
 		export type ModuleDetection =
 			| 'auto'
 			| 'legacy'
 			| 'force';
+
+		export type IgnoreDeprecations = '5.0';
 	}
 
 	export type CompilerOptions = {
@@ -244,6 +250,7 @@ declare namespace TsConfigJson {
 		The character set of the input files.
 
 		@default 'utf8'
+		@deprecated This option will be removed in TypeScript 5.5.
 		*/
 		charset?: string;
 
@@ -402,7 +409,7 @@ declare namespace TsConfigJson {
 		/**
 		Specifies the end of line sequence to be used when emitting files: 'crlf' (Windows) or 'lf' (Unix).
 
-		Default: Platform specific
+		@default 'LF'
 		*/
 		newLine?: CompilerOptions.NewLine;
 
@@ -473,6 +480,7 @@ declare namespace TsConfigJson {
 		Disable strict checking of generic signatures in function types.
 
 		@default false
+		@deprecated This option will be removed in TypeScript 5.5.
 		*/
 		noStrictGenericChecks?: boolean;
 
@@ -563,6 +571,7 @@ declare namespace TsConfigJson {
 		Suppress excess property checks for object literals.
 
 		@default false
+		@deprecated This option will be removed in TypeScript 5.5.
 		*/
 		suppressExcessPropertyErrors?: boolean;
 
@@ -570,6 +579,7 @@ declare namespace TsConfigJson {
 		Suppress noImplicitAny errors for indexing objects lacking index signatures.
 
 		@default false
+		@deprecated This option will be removed in TypeScript 5.5.
 		*/
 		suppressImplicitAnyIndexErrors?: boolean;
 
@@ -682,7 +692,7 @@ declare namespace TsConfigJson {
 		/**
 		Disallow inconsistently-cased references to the same file.
 
-		@default false
+		@default true
 		*/
 		forceConsistentCasingInFileNames?: boolean;
 
@@ -755,6 +765,7 @@ declare namespace TsConfigJson {
 		Do not emit `'use strict'` directives in module output.
 
 		@default false
+		@deprecated This option will be removed in TypeScript 5.5.
 		*/
 		noImplicitUseStrict?: boolean;
 
@@ -802,6 +813,7 @@ declare namespace TsConfigJson {
 		Specify emit/checking behavior for imports that are only used for types.
 
 		@default 'remove'
+		@deprecated Use `verbatimModuleSyntax` instead.
 		*/
 		importsNotUsedAsValues?: CompilerOptions.ImportsNotUsedAsValues;
 
@@ -872,6 +884,7 @@ declare namespace TsConfigJson {
 		Resolve `keyof` to string valued property names only (no numbers or symbols).
 
 		@default false
+		@deprecated This option will be removed in TypeScript 5.5.
 		*/
 		keyofStringsOnly?: boolean;
 
@@ -942,6 +955,7 @@ declare namespace TsConfigJson {
 		Preserve unused imported values in the JavaScript output that would otherwise be removed.
 
 		@default true
+		@deprecated Use `verbatimModuleSyntax` instead.
 		*/
 		preserveValueImports?: boolean;
 
@@ -956,6 +970,51 @@ declare namespace TsConfigJson {
 		@default 'auto'
 		*/
 		moduleDetection?: CompilerOptions.ModuleDetection;
+
+		/**
+		Allows TypeScript files to import each other with a TypeScript-specific extension like .ts, .mts, or .tsx.
+
+		@default false
+		*/
+		allowImportingTsExtensions?: boolean;
+
+		/**
+		Forces TypeScript to consult the exports field of package.json files if it ever reads from a package in node_modules.
+
+		@default false
+		*/
+		resolvePackageJsonExports?: boolean;
+
+		/**
+		Forces TypeScript to consult the imports field of package.json files when performing a lookup that starts with # from a file whose ancestor directory contains a package.json.
+
+		@default false
+		*/
+		resolvePackageJsonImports?: boolean;
+
+		/**
+		Suppress errors for file formats that TypeScript does not understand.
+
+		@default false
+		*/
+		allowArbitraryExtensions?: boolean;
+
+		/**
+		List of additional conditions that should succeed when TypeScript resolves from package.json.
+		*/
+		customConditions?: string[];
+
+		/**
+		Anything that uses the type modifier is dropped entirely.
+
+		@default false
+		*/
+		verbatimModuleSyntax?: boolean;
+
+		/**
+		Suppress deprecation warnings
+		*/
+		ignoreDeprecations?: CompilerOptions.IgnoreDeprecations;
 	};
 
 	namespace WatchOptions {
@@ -1052,6 +1111,7 @@ declare namespace TsConfigJson {
 		True if the output of this reference should be prepended to the output of this project.
 
 		Only valid for `--outFile` compilations.
+		@deprecated This option will be removed in TypeScript 5.5.
 		*/
 		prepend?: boolean;
 
@@ -1091,7 +1151,7 @@ export type TsConfigJson = {
 	/**
 	Path to base configuration file to inherit from.
 	*/
-	extends?: string;
+	extends?: string | string[];
 
 	/**
 	If no `files` or `include` property is present in a `tsconfig.json`, the compiler defaults to including all files in the containing directory and subdirectories except those specified by `exclude`. When a `files` property is specified, only those files and those specified by `include` are included.