type-fest 0.18.1 → 0.20.2

package/base.d.ts

@@ -0,0 +1,38 @@
+// Types that are compatible with all supported TypeScript versions.
+// It's shared between all TypeScript version-specific definitions.
+
+// Basic
+export * from './source/basic';
+
+// Utilities
+export {Except} from './source/except';
+export {Mutable} from './source/mutable';
+export {Merge} from './source/merge';
+export {MergeExclusive} from './source/merge-exclusive';
+export {RequireAtLeastOne} from './source/require-at-least-one';
+export {RequireExactlyOne} from './source/require-exactly-one';
+export {PartialDeep} from './source/partial-deep';
+export {ReadonlyDeep} from './source/readonly-deep';
+export {LiteralUnion} from './source/literal-union';
+export {Promisable} from './source/promisable';
+export {Opaque} from './source/opaque';
+export {SetOptional} from './source/set-optional';
+export {SetRequired} from './source/set-required';
+export {ValueOf} from './source/value-of';
+export {PromiseValue} from './source/promise-value';
+export {AsyncReturnType} from './source/async-return-type';
+export {ConditionalExcept} from './source/conditional-except';
+export {ConditionalKeys} from './source/conditional-keys';
+export {ConditionalPick} from './source/conditional-pick';
+export {UnionToIntersection} from './source/union-to-intersection';
+export {Stringified} from './source/stringified';
+export {FixedLengthArray} from './source/fixed-length-array';
+export {IterableElement} from './source/iterable-element';
+export {Entry} from './source/entry';
+export {Entries} from './source/entries';
+export {SetReturnType} from './source/set-return-type';
+export {Asyncify} from './source/asyncify';
+
+// Miscellaneous
+export {PackageJson} from './source/package-json';
+export {TsConfigJson} from './source/tsconfig-json';

package/index.d.ts

@@ -1,35 +1,2 @@
-// Basic
-export * from './source/basic';
-
-// Utilities
-export {Except} from './source/except';
-export {Mutable} from './source/mutable';
-export {Merge} from './source/merge';
-export {MergeExclusive} from './source/merge-exclusive';
-export {RequireAtLeastOne} from './source/require-at-least-one';
-export {RequireExactlyOne} from './source/require-exactly-one';
-export {PartialDeep} from './source/partial-deep';
-export {ReadonlyDeep} from './source/readonly-deep';
-export {LiteralUnion} from './source/literal-union';
-export {Promisable} from './source/promisable';
-export {Opaque} from './source/opaque';
-export {SetOptional} from './source/set-optional';
-export {SetRequired} from './source/set-required';
-export {ValueOf} from './source/value-of';
-export {PromiseValue} from './source/promise-value';
-export {AsyncReturnType} from './source/async-return-type';
-export {ConditionalExcept} from './source/conditional-except';
-export {ConditionalKeys} from './source/conditional-keys';
-export {ConditionalPick} from './source/conditional-pick';
-export {UnionToIntersection} from './source/union-to-intersection';
-export {Stringified} from './source/stringified';
-export {FixedLengthArray} from './source/fixed-length-array';
-export {IterableElement} from './source/iterable-element';
-export {Entry} from './source/entry';
-export {Entries} from './source/entries';
-export {SetReturnType} from './source/set-return-type';
-export {Asyncify} from './source/asyncify';
-
-// Miscellaneous
-export {PackageJson} from './source/package-json';
-export {TsConfigJson} from './source/tsconfig-json';
+// These are all the basic types that's compatible with all supported TypeScript versions.
+export * from './base';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "0.18.1",
+	"version": "0.20.2",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -14,11 +14,14 @@
 		"node": ">=10"
 	},
 	"scripts": {
-		"test": "xo && tsd"
+		"//test": "xo && tsd && tsc",
+		"test": "xo && tsc"
 	},
 	"files": [
 		"index.d.ts",
-		"source"
+		"base.d.ts",
+		"source",
+		"ts41"
 	],
 	"keywords": [
 		"typescript",
@@ -32,14 +35,24 @@
 		"json"
 	],
 	"devDependencies": {
+		"@sindresorhus/tsconfig": "~0.7.0",
 		"tsd": "^0.13.1",
-		"xo": "^0.28.2"
+		"typescript": "^4.1.2",
+		"xo": "^0.35.0"
+	},
+	"types": "./index.d.ts",
+	"typesVersions": {
+		">=4.1": {
+			"*": [
+				"ts41/*"
+			]
+		}
 	},
-	"types": "index.d.ts",
 	"xo": {
 		"rules": {
+			"@typescript-eslint/ban-types": "off",
 			"@typescript-eslint/indent": "off",
-			"func-call-spacing": "off"
+			"node/no-unsupported-features/es-builtins": "off"
 		}
 	}
 }

package/readme.md

@@ -11,7 +11,6 @@
 <br>
 <br>
 
-[![Build Status](https://github.com/sindresorhus/type-fest/workflows/CI/badge.svg?branch=master)](https://github.com/sindresorhus/type-fest/actions?query=branch%3Amaster+workflow%3ACI)
 [![](https://img.shields.io/badge/unicorn-approved-ff69b4.svg)](https://giphy.com/gifs/illustration-rainbow-unicorn-26AHG5KGFxSkUWw1i)
 <!-- Commented out until they actually show anything
 [![npm dependents](https://badgen.net/npm/dependents/type-fest)](https://www.npmjs.com/package/type-fest?activeTab=dependents) [![npm downloads](https://badgen.net/npm/dt/type-fest)](https://www.npmjs.com/package/type-fest)
@@ -29,7 +28,7 @@ PR welcome for additional commonly needed types and docs improvements. Read the
 $ npm install type-fest
 ```
 
-*Requires TypeScript >=3.2*
+*Requires TypeScript >=3.4*
 
 ## Usage
 
@@ -89,6 +88,16 @@ Click the type names for complete docs.
 - [`SetReturnType`](source/set-return-type.d.ts) - Create a function type with a return type of your choice and the same parameters as the given function type.
 - [`Asyncify`](source/asyncify.d.ts) - Create an async version of the given function type.
 
+### Template literal types
+
+*Note:* These require [TypeScript 4.1 or newer](https://devblogs.microsoft.com/typescript/announcing-typescript-4-1/#template-literal-types).
+
+- [`CamelCase`](ts41/camel-case.d.ts) – Convert a string literal to camel-case (`fooBar`).
+- [`KebabCase`](ts41/kebab-case.d.ts) – Convert a string literal to kebab-case (`foo-bar`).
+- [`PascalCase`](ts41/pascal-case.d.ts) – Converts a string literal to pascal-case (`FooBar`)
+- [`SnakeCase`](ts41/snake-case.d.ts) – Convert a string literal to snake-case (`foo_bar`).
+- [`DelimiterCase`](ts41/delimiter-case.d.ts) – Convert a string literal to a custom string delimiter casing.
+
 ### Miscellaneous
 
 - [`PackageJson`](source/package-json.d.ts) - Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file).
@@ -630,6 +639,7 @@ You can find some examples in the [TypeScript docs](https://www.typescriptlang.o
 - [Sindre Sorhus](https://github.com/sindresorhus)
 - [Jarek Radosz](https://github.com/CvX)
 - [Dimitri Benin](https://github.com/BendingBender)
+- [Pelle Wessman](https://github.com/voxpelli)
 
 ## License
 

package/source/package-json.d.ts

@@ -200,16 +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;
-	} & {
-		[scriptName: string]: string;
-	};
+	} & 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 interface Dependency {
-		[packageName: string]: string;
-	}
+	export type Dependency = Record<string, string>;
 
 	/**
 	Conditions which provide a way to resolve a package entry point based on the environment.
@@ -232,7 +228,7 @@ declare namespace PackageJson {
 	export type Exports =
 	| string
 	| {[key in ExportCondition]: Exports}
-	| {[key: string]: Exports};
+	| {[key: string]: Exports}; // eslint-disable-line @typescript-eslint/consistent-indexed-object-style
 
 	export interface NonStandardEntryPoints {
 		/**
@@ -256,9 +252,7 @@ declare namespace PackageJson {
 		*/
 		browser?:
 		| string
-		| {
-			[moduleName: string]: string | false;
-		};
+		| Record<string, string | false>;
 
 		/**
 		Denote which files in your project are "pure" and therefore safe for Webpack to prune if unused.
@@ -426,9 +420,7 @@ declare namespace PackageJson {
 		*/
 		bin?:
 		| string
-		| {
-			[binary: string]: string;
-		};
+		| Record<string, string>;
 
 		/**
 		Filenames to put in place for the `man` program to find.
@@ -465,9 +457,7 @@ declare namespace PackageJson {
 		/**
 		Is used to set configuration parameters used in package scripts that persist across upgrades.
 		*/
-		config?: {
-			[configKey: string]: unknown;
-		};
+		config?: Record<string, unknown>;
 
 		/**
 		The dependencies of the package.
@@ -492,11 +482,7 @@ declare namespace PackageJson {
 		/**
 		Indicate peer dependencies that are optional.
 		*/
-		peerDependenciesMeta?: {
-			[packageName: string]: {
-				optional: true;
-			};
-		};
+		peerDependenciesMeta?: Record<string, {optional: true}>;
 
 		/**
 		Package names that are bundled when the package is published.
@@ -585,9 +571,7 @@ declare namespace PackageJson {
 		/**
 		A set of config values that will be used at publish-time. It's especially handy to set the tag, registry or access, to ensure that a given package is not tagged with 'latest', published to the global public registry or that a scoped module is private by default.
 		*/
-		publishConfig?: {
-			[config: string]: unknown;
-		};
+		publishConfig?: Record<string, unknown>;
 
 		/**
 		Describes and notifies consumers of a package's monetary support information.

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

@@ -20,13 +20,14 @@ const responder: RequireAtLeastOne<Responder, 'text' | 'json'> = {
 };
 ```
 */
-export type RequireAtLeastOne<ObjectType, KeysType extends keyof ObjectType = keyof ObjectType> =
-	{
-		// For each Key in KeysType make a mapped type
-		[Key in KeysType]: (
-			// …by picking that Key's type and making it required
-			Required<Pick<ObjectType, Key>>
-		)
-	}[KeysType]
-	// …then, make intersection types by adding the remaining keys to each mapped type.
-	& Except<ObjectType, KeysType>;
+export type RequireAtLeastOne<
+	ObjectType,
+	KeysType extends keyof ObjectType = keyof ObjectType
+> = {
+	// For each `Key` in `KeysType` make a mapped type:
+	[Key in KeysType]-?: Required<Pick<ObjectType, Key>> & // 1. Make `Key`'s type required
+		// 2. Make all other keys in `KeysType` optional
+		Partial<Pick<ObjectType, Exclude<KeysType, Key>>>;
+}[KeysType] &
+	// 3. Add the remaining keys not in `KeysType`
+	Except<ObjectType, KeysType>;

package/source/tsconfig-json.d.ts

@@ -532,9 +532,7 @@ declare namespace TsConfigJson {
 		/**
 		Specify path mapping to be computed relative to baseUrl option.
 		*/
-		paths?: {
-			[key: string]: string[];
-		};
+		paths?: Record<string, string[]>;
 
 		/**
 		List of TypeScript language server plugins to load.

package/source/utilities.d.ts

@@ -0,0 +1,3 @@
+export type UpperCaseCharacters = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
+
+export type WordSeparators = '-' | '_' | ' ';

package/ts41/camel-case.d.ts

@@ -0,0 +1,72 @@
+import {WordSeparators} from '../source/utilities';
+
+/**
+Recursively split a string literal into two parts on the first occurence of the given string, returning an array literal of all the separate parts.
+*/
+export type Split<S extends string, D extends string> =
+	string extends S ? string[] :
+	S extends '' ? [] :
+	S extends `${infer T}${D}${infer U}` ? [T, ...Split<U, D>] :
+	[S];
+
+/**
+Step by step takes the first item in an array literal, formats it and adds it to a string literal, and then recursively appends the remainder.
+
+Only to be used by `CamelCaseStringArray<>`.
+
+@see CamelCaseStringArray
+*/
+type InnerCamelCaseStringArray<Parts extends any[], PreviousPart> =
+	Parts extends [`${infer FirstPart}`, ...infer RemainingParts]
+		? FirstPart extends undefined
+			? ''
+			: FirstPart extends ''
+					? InnerCamelCaseStringArray<RemainingParts, PreviousPart>
+					: `${PreviousPart extends '' ? FirstPart : Capitalize<FirstPart>}${InnerCamelCaseStringArray<RemainingParts, FirstPart>}`
+		: '';
+
+/**
+Starts fusing the output of `Split<>`, an array literal of strings, into a camel-cased string literal.
+
+It's separate from `InnerCamelCaseStringArray<>` to keep a clean API outwards to the rest of the code.
+
+@see Split
+*/
+type CamelCaseStringArray<Parts extends string[]> =
+	Parts extends [`${infer FirstPart}`, ...infer RemainingParts]
+		? Uncapitalize<`${FirstPart}${InnerCamelCaseStringArray<RemainingParts, FirstPart>}`>
+		: never;
+
+/**
+Convert a string literal to camel-case.
+
+This can be useful when, for example, converting some kebab-cased command-line flags or a snake-cased database result.
+
+@example
+```
+import {CamelCase} from 'type-fest';
+
+// Simple
+
+const someVariable: CamelCase<'foo-bar'> = 'fooBar';
+
+// Advanced
+
+type CamelCasedProps<T> = {
+	[K in keyof T as CamelCase<K>]: T[K]
+};
+
+interface RawOptions {
+	'dry-run': boolean;
+	'full_family_name': string;
+	foo: number;
+}
+
+const dbResult: CamelCasedProps<ModelProps> = {
+	dryRun: true,
+	fullFamilyName: 'bar.js',
+	foo: 123
+};
+```
+*/
+export type CamelCase<K> = K extends string ? CamelCaseStringArray<Split<K, WordSeparators>> : K;

package/ts41/delimiter-case.d.ts

@@ -0,0 +1,85 @@
+import {UpperCaseCharacters, WordSeparators} from '../source/utilities';
+
+/**
+Unlike a simpler split, this one includes the delimiter splitted on in the resulting array literal. This is to enable splitting on, for example, upper-case characters.
+*/
+export type SplitIncludingDelimiters<Source extends string, Delimiter extends string> =
+	Source extends '' ? [] :
+	Source extends `${infer FirstPart}${Delimiter}${infer SecondPart}` ?
+	(
+		Source extends `${FirstPart}${infer UsedDelimiter}${SecondPart}`
+			? UsedDelimiter extends Delimiter
+				? Source extends `${infer FirstPart}${UsedDelimiter}${infer SecondPart}`
+					? [...SplitIncludingDelimiters<FirstPart, Delimiter>, UsedDelimiter, ...SplitIncludingDelimiters<SecondPart, Delimiter>]
+					: never
+				: never
+			: never
+	) :
+	[Source];
+
+/**
+Format a specific part of the splitted string literal that `StringArrayToDelimiterCase<>` fuses together, ensuring desired casing.
+
+@see StringArrayToDelimiterCase
+*/
+type StringPartToDelimiterCase<StringPart extends string, UsedWordSeparators extends string, UsedUpperCaseCharacters extends string, Delimiter extends string> =
+	StringPart extends UsedWordSeparators ? Delimiter :
+	StringPart extends UsedUpperCaseCharacters ? `${Delimiter}${Lowercase<StringPart>}` :
+	StringPart;
+
+/**
+Takes the result of a splitted string literal and recursively concatenates it together into the desired casing.
+
+It receives `UsedWordSeparators` and `UsedUpperCaseCharacters` as input to ensure it's fully encapsulated.
+
+@see SplitIncludingDelimiters
+*/
+type StringArrayToDelimiterCase<Parts extends any[], UsedWordSeparators extends string, UsedUpperCaseCharacters extends string, Delimiter extends string> =
+	Parts extends [`${infer FirstPart}`, ...infer RemainingParts]
+		? `${StringPartToDelimiterCase<FirstPart, UsedWordSeparators, UsedUpperCaseCharacters, Delimiter>}${StringArrayToDelimiterCase<RemainingParts, UsedWordSeparators, UsedUpperCaseCharacters, Delimiter>}`
+		: '';
+
+/**
+Convert a string literal to a custom string delimiter casing.
+
+This can be useful when, for example, converting a camel-cased object property to an oddly cased one.
+
+@see KebabCase
+@see SnakeCase
+
+@example
+```
+import {DelimiterCase} from 'type-fest';
+
+// Simple
+
+const someVariable: DelimiterCase<'fooBar', '#'> = 'foo#bar';
+
+// Advanced
+
+type OddlyCasedProps<T> = {
+	[K in keyof T as DelimiterCase<K, '#'>]: T[K]
+};
+
+interface SomeOptions {
+	dryRun: boolean;
+	includeFile: string;
+	foo: number;
+}
+
+const rawCliOptions: OddlyCasedProps<SomeOptions> = {
+	'dry#run': true,
+	'include#file': 'bar.js',
+	foo: 123
+};
+```
+*/
+
+export type DelimiterCase<Value, Delimiter extends string> = Value extends string
+	? StringArrayToDelimiterCase<
+		SplitIncludingDelimiters<Value, WordSeparators | UpperCaseCharacters>,
+		WordSeparators,
+		UpperCaseCharacters,
+		Delimiter
+	>
+	: Value;

package/ts41/index.d.ts

@@ -0,0 +1,9 @@
+// These are all the basic types that's compatible with all supported TypeScript versions.
+export * from '../base';
+
+// These are special types that require at least TypeScript 4.1.
+export {CamelCase} from './camel-case';
+export {KebabCase} from './kebab-case';
+export {PascalCase} from './pascal-case';
+export {SnakeCase} from './snake-case';
+export {DelimiterCase} from './delimiter-case';

package/ts41/kebab-case.d.ts

@@ -0,0 +1,36 @@
+import {DelimiterCase} from './delimiter-case';
+
+/**
+Convert a string literal to kebab-case.
+
+This can be useful when, for example, converting a camel-cased object property to a kebab-cased CSS class name or a command-line flag.
+
+@example
+```
+import {KebabCase} from 'type-fest';
+
+// Simple
+
+const someVariable: KebabCase<'fooBar'> = 'foo-bar';
+
+// Advanced
+
+type KebabCasedProps<T> = {
+	[K in keyof T as KebabCase<K>]: T[K]
+};
+
+interface CliOptions {
+	dryRun: boolean;
+	includeFile: string;
+	foo: number;
+}
+
+const rawCliOptions: KebabCasedProps<CliOptions> = {
+	'dry-run': true,
+	'include-file': 'bar.js',
+	foo: 123
+};
+```
+*/
+
+export type KebabCase<Value> = DelimiterCase<Value, '-'>;

package/ts41/pascal-case.d.ts

@@ -0,0 +1,36 @@
+import {CamelCase} from './camel-case';
+
+/**
+Converts a string literal to pascal-case.
+
+@example
+```
+import {PascalCase} from 'type-fest';
+
+// Simple
+
+const someVariable: PascalCase<'foo-bar'> = 'FooBar';
+
+// Advanced
+
+type PascalCaseProps<T> = {
+	[K in keyof T as PascalCase<K>]: T[K]
+};
+
+interface RawOptions {
+	'dry-run': boolean;
+	'full_family_name': string;
+	foo: number;
+}
+
+const dbResult: CamelCasedProps<ModelProps> = {
+	DryRun: true,
+	FullFamilyName: 'bar.js',
+	Foo: 123
+};
+```
+*/
+
+export type PascalCase<Value> = CamelCase<Value> extends string
+	? Capitalize<CamelCase<Value>>
+	: CamelCase<Value>;

package/ts41/snake-case.d.ts

@@ -0,0 +1,35 @@
+import {DelimiterCase} from './delimiter-case';
+
+/**
+Convert a string literal to snake-case.
+
+This can be useful when, for example, converting a camel-cased object property to a snake-cased SQL column name.
+
+@example
+```
+import {SnakeCase} from 'type-fest';
+
+// Simple
+
+const someVariable: SnakeCase<'fooBar'> = 'foo_bar';
+
+// Advanced
+
+type SnakeCasedProps<T> = {
+	[K in keyof T as SnakeCase<K>]: T[K]
+};
+
+interface ModelProps {
+	isHappy: boolean;
+	fullFamilyName: string;
+	foo: number;
+}
+
+const dbResult: SnakeCasedProps<ModelProps> = {
+	'is_happy': true,
+	'full_family_name': 'Carla Smith',
+	foo: 123
+};
+```
+*/
+export type SnakeCase<Value> = DelimiterCase<Value, '_'>;