type-fest 1.1.0 → 1.2.0

package/package.json

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

package/readme.md

@@ -136,6 +136,7 @@ Click the type names for complete docs.
 - [`SnakeCase`](ts41/snake-case.d.ts) – Convert a string literal to snake-case (`foo_bar`).
 - [`SnakeCasedProperties`](ts41/snake-cased-properties-deep.d.ts) – Convert object properties to snake-case (`foo_bar`).
 - [`SnakeCasedPropertiesDeep`](ts41/snake-cased-properties-deep.d.ts) – Convert object properties to snake-case recursively (`foo_bar`).
+- [`ScreamingSnakeCase`](ts41/screaming-snake-case.d.ts) - Convert a string literal to screaming-snake-case (`FOO_BAR`).
 - [`DelimiterCase`](ts41/delimiter-case.d.ts) – Convert a string literal to a custom string delimiter casing.
 - [`DelimiterCasedProperties`](ts41/delimiter-cased-properties.d.ts) – Convert object properties to a custom string delimiter casing.
 - [`DelimiterCasedPropertiesDeep`](ts41/delimiter-cased-properties-deep.d.ts) – Convert object properties to a custom string delimiter casing recursively.

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

@@ -19,5 +19,7 @@ async function doSomething(value: Value) {}
 
 asyncFunction().then(value => doSomething(value));
 ```
+
+@category Utilities
 */
 export type AsyncReturnType<Target extends AsyncFunction> = PromiseValue<ReturnType<Target>>;

package/source/asyncify.d.ts

@@ -27,5 +27,7 @@ const getFooAsync: AsyncifiedFooGetter = (someArg) => {
 	// …
 }
 ```
+
+@category Utilities
 */
 export type Asyncify<Fn extends (...args: any[]) => any> = SetReturnType<Fn, Promise<PromiseValue<ReturnType<Fn>>>>;

package/source/basic.d.ts

@@ -1,6 +1,8 @@
 // TODO: Remove the `= unknown` sometime  in the future when most users are on TS 3.5 as it's now the default
 /**
 Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
+
+@category Basic
 */
 export type Class<T = unknown, Arguments extends any[] = any[]> = new(...arguments_: Arguments) => T;
 
@@ -8,11 +10,15 @@ export type Class<T = unknown, Arguments extends any[] = any[]> = new(...argumen
 Matches a JSON object.
 
 This type can be useful to enforce some input to be JSON-compatible or as a super-type to be extended from. Don't use this as a direct return type as the user would have to double-cast it: `jsonObject as unknown as CustomResponse`. Instead, you could extend your CustomResponse type from it to ensure your type only uses JSON-compatible types: `interface CustomResponse extends JsonObject { … }`.
+
+@category Basic
 */
 export type JsonObject = {[Key in string]?: JsonValue};
 
 /**
 Matches a JSON array.
+
+@category Basic
 */
 export interface JsonArray extends Array<JsonValue> {}
 // TODO: Make it this when targeting TypeScript 4.1:
@@ -20,5 +26,7 @@ export interface JsonArray extends Array<JsonValue> {}
 
 /**
 Matches any valid JSON value.
+
+@category Basic
 */
 export type JsonValue = string | number | boolean | null | JsonObject | JsonArray;

package/source/conditional-except.d.ts

@@ -36,6 +36,8 @@ interface Example {
 type NonStringKeysOnly = ConditionalExcept<Example, string>;
 //=> {b: string | number; c: () => void; d: {}}
 ```
+
+@category Utilities
 */
 export type ConditionalExcept<Base, Condition> = Except<
 	Base,

package/source/conditional-keys.d.ts

@@ -25,6 +25,8 @@ To support partial types, make sure your `Condition` is a union of undefined (fo
 type StringKeysAndUndefined = ConditionalKeys<Example, string | undefined>;
 //=> 'a' | 'c'
 ```
+
+@category Utilities
 */
 export type ConditionalKeys<Base, Condition> = NonNullable<
 	// Wrap in `NonNullable` to strip away the `undefined` type from the produced union.

package/source/conditional-pick.d.ts

@@ -35,6 +35,8 @@ interface Example {
 type StringKeysOnly = ConditionalPick<Example, string>;
 //=> {a: string}
 ```
+
+@category Utilities
 */
 export type ConditionalPick<Base, Condition> = Pick<
 	Base,

package/source/entries.d.ts

@@ -48,6 +48,8 @@ const mapEntries: Entries<typeof map> = [['a', 1]];
 const setExample = new Set(['a', 1]);
 const setEntries: Entries<typeof setExample> = [['a', 'a'], [1, 1]];
 ```
+
+@category Utilities
 */
 export type Entries<BaseType> =
 	BaseType extends Map<unknown, unknown> ? MapEntries<BaseType>

package/source/entry.d.ts

@@ -51,6 +51,8 @@ const setExample = new Set(['a', 1]);
 const setEntryString: Entry<typeof setExample> = ['a', 'a'];
 const setEntryNumber: Entry<typeof setExample> = [1, 1];
 ```
+
+@category Utilities
 */
 export type Entry<BaseType> =
 	BaseType extends Map<unknown, unknown> ? MapEntry<BaseType>

package/source/except.d.ts

@@ -18,5 +18,7 @@ type Foo = {
 type FooWithoutA = Except<Foo, 'a' | 'c'>;
 //=> {b: string};
 ```
+
+@category Utilities
 */
 export type Except<ObjectType, KeysType extends keyof ObjectType> = Pick<ObjectType, Exclude<keyof ObjectType, KeysType>>;

package/source/fixed-length-array.d.ts

@@ -27,6 +27,8 @@ const homeFencingTeam: FencingTeam = ['George', 'John'];
 guestFencingTeam.push('Sam');
 //=> error TS2339: Property 'push' does not exist on type 'FencingTeam'
 ```
+
+@category Utilities
 */
 export type FixedLengthArray<Element, Length extends number, ArrayPrototype = [Element, ...Element[]]> = Pick<
 	ArrayPrototype,

package/source/iterable-element.d.ts

@@ -37,6 +37,8 @@ An example with an array of strings:
 ```
 type MeString = IterableElement<string[]>
 ```
+
+@category Utilities
 */
 export type IterableElement<TargetIterable> =
 	TargetIterable extends Iterable<infer ElementType> ?

package/source/literal-union.d.ts

@@ -26,6 +26,8 @@ type Pet2 = LiteralUnion<'dog' | 'cat', string>;
 const pet: Pet2 = '';
 // You **will** get auto-completion for `dog` and `cat` literals.
 ```
+
+@category Utilities
  */
 export type LiteralUnion<
 	LiteralType,

package/source/merge-exclusive.d.ts

@@ -31,6 +31,8 @@ exclusiveOptions = {exclusive2: 'hi'};
 exclusiveOptions = {exclusive1: true, exclusive2: 'hi'};
 //=> Error
 ```
+
+@category Utilities
 */
 export type MergeExclusive<FirstType, SecondType> =
 	(FirstType | SecondType) extends object ?

package/source/merge.d.ts

@@ -21,5 +21,7 @@ type Bar = {
 
 const ab: Merge<Foo, Bar> = {a: 1, b: 2};
 ```
+
+@category Utilities
 */
 export type Merge<FirstType, SecondType> = Simplify<Merge_<FirstType, SecondType>>;

package/source/mutable.d.ts

@@ -28,6 +28,8 @@ type SomeMutable = Mutable<Foo, 'b' | 'c'>;
 // 	c: boolean; // It's now mutable.
 // }
 ```
+
+@category Utilities
 */
 export type Mutable<BaseType, Keys extends keyof BaseType = keyof BaseType> =
 	Simplify<

package/source/observable-like.d.ts

@@ -6,6 +6,8 @@ declare global {
 
 /**
 Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
+
+@category Basic
 */
 export interface ObservableLike {
 	subscribe(observer: (value: unknown) => void): void;

package/source/opaque.d.ts

@@ -61,5 +61,7 @@ type Person = {
 	name: string;
 };
 ```
+
+@category Utilities
 */
 export type Opaque<Type, Token = unknown> = Type & {readonly __opaque__: Token};

package/source/package-json.d.ts

@@ -227,6 +227,7 @@ declare namespace PackageJson {
 	*/
 	export type Exports =
 	| string
+	| string[]
 	| {[key in ExportCondition]: Exports}
 	| {[key: string]: Exports}; // eslint-disable-line @typescript-eslint/consistent-indexed-object-style
 
@@ -628,6 +629,8 @@ declare namespace PackageJson {
 
 /**
 Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). Also includes types for fields used by other popular projects, like TypeScript and Yarn.
+
+@category Miscellaneous
 */
 export type PackageJson =
 PackageJson.PackageJsonStandard &

package/source/partial-deep.d.ts

@@ -27,6 +27,8 @@ const applySavedSettings = (savedSettings: PartialDeep<Settings>) => {
 
 settings = applySavedSettings({textEditor: {fontWeight: 500}});
 ```
+
+@category Utilities
 */
 export type PartialDeep<T> = T extends Primitive
 	? Partial<T>

package/source/primitive.d.ts

@@ -1,5 +1,7 @@
 /**
 Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+
+@category Basic
 */
 export type Primitive =
 	| null

package/source/promisable.d.ts

@@ -18,6 +18,8 @@ async function logger(getLogEntry: () => Promisable<string>): Promise<void> {
 
 logger(() => 'foo');
 logger(() => Promise.resolve('bar'));
+
+@category Utilities
 ```
 */
 export type Promisable<T> = T | PromiseLike<T>;

package/source/promise-value.d.ts

@@ -21,6 +21,8 @@ let syncData: SyncData = getSyncData();
 type RecursiveAsyncData = Promise<Promise<string> >;
 let recursiveAsyncData: PromiseValue<RecursiveAsyncData> = Promise.resolve(Promise.resolve('ABC'));
 ```
+
+@category Utilities
 */
 export type PromiseValue<PromiseType, Otherwise = PromiseType> = PromiseType extends Promise<infer Value>
 	? { 0: PromiseValue<Value>; 1: Value }[PromiseType extends Promise<unknown> ? 0 : 1]

package/source/readonly-deep.d.ts

@@ -28,6 +28,8 @@ import data from './main';
 data.foo.push('bar');
 //=> error TS2339: Property 'push' does not exist on type 'readonly string[]'
 ```
+
+@category Utilities
 */
 export type ReadonlyDeep<T> = T extends Primitive | ((...arguments: any[]) => unknown)
 	? T

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

@@ -19,6 +19,8 @@ const responder: RequireAtLeastOne<Responder, 'text' | 'json'> = {
 	secure: true
 };
 ```
+
+@category Utilities
 */
 export type RequireAtLeastOne<
 	ObjectType,

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

@@ -27,6 +27,8 @@ const responder: RequireExactlyOne<Responder, 'text' | 'json'> = {
 	secure: true
 };
 ```
+
+@category Utilities
 */
 export type RequireExactlyOne<ObjectType, KeysType extends keyof ObjectType = keyof ObjectType> =
 	{[Key in KeysType]: (

package/source/set-optional.d.ts

@@ -23,6 +23,8 @@ type SomeOptional = SetOptional<Foo, 'b' | 'c'>;
 // 	c?: boolean; // Is now optional.
 // }
 ```
+
+@category Utilities
 */
 export type SetOptional<BaseType, Keys extends keyof BaseType> =
 	Simplify<

package/source/set-required.d.ts

@@ -23,6 +23,8 @@ type SomeRequired = SetRequired<Foo, 'b' | 'c'>;
 // 	c: boolean; // Is now required.
 // }
 ```
+
+@category Utilities
 */
 export type SetRequired<BaseType, Keys extends keyof BaseType> =
 	Simplify<

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

@@ -16,6 +16,8 @@ type MyFunctionThatCanThrow = (foo: SomeType, bar: unknown) => SomeOtherType;
 type MyWrappedFunction = SetReturnType<MyFunctionThatCanThrow, SomeOtherType | undefined>;
 //=> type MyWrappedFunction = (foo: SomeType, bar: unknown) => SomeOtherType | undefined;
 ```
+
+@category Utilities
 */
 export type SetReturnType<Fn extends (...args: any[]) => any, TypeToReturn> =
 	// Just using `Parameters<Fn>` isn't ideal because it doesn't handle the `this` fake parameter.

package/source/stringified.d.ts

@@ -17,5 +17,7 @@ const carForm: Stringified<Car> = {
 	speed: '101'
 };
 ```
+
+@category Utilities
 */
 export type Stringified<ObjectType> = {[KeyType in keyof ObjectType]: string};

package/source/tsconfig-json.d.ts

@@ -815,6 +815,11 @@ declare namespace TsConfigJson {
 	}
 }
 
+/**
+Type for [TypeScript's `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) (TypeScript 3.7).
+
+@category Miscellaneous
+*/
 export interface TsConfigJson {
 	/**
 	Instructs the TypeScript compiler how to compile `.ts` files.

package/source/typed-array.d.ts

@@ -1,5 +1,9 @@
+/// <reference lib="es2020.bigint"/>
+
 /**
 Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
+
+@category Basic
 */
 export type TypedArray =
 	| Int8Array

package/source/union-to-intersection.d.ts

@@ -40,6 +40,8 @@ type Union = typeof union;
 type Intersection = UnionToIntersection<Union>;
 //=> {a1(): void; b1(): void; a2(argA: string): void; b2(argB: string): void}
 ```
+
+@category Utilities
 */
 export type UnionToIntersection<Union> = (
 	// `extends unknown` is always going to be the case and is used to convert the

package/source/value-of.d.ts

@@ -36,5 +36,7 @@ onlyBar('foo');
 onlyBar('bar');
 //=> 2
 ```
+
+@category Utilities
 */
 export type ValueOf<ObjectType, ValueType extends keyof ObjectType = keyof ObjectType> = ObjectType[ValueType];

package/ts41/camel-case.d.ts

@@ -60,5 +60,7 @@ const dbResult: CamelCasedProperties<ModelProps> = {
 	foo: 123
 };
 ```
+
+@category Template Literals
 */
 export type CamelCase<K> = K extends string ? CamelCaseStringArray<Split<K, WordSeparators>> : K;

package/ts41/camel-cased-properties-deep.d.ts

@@ -37,6 +37,8 @@ const result: CamelCasedPropertiesDeep<UserWithFriends> = {
 	],
 };
 ```
+
+@category Template Literals
 */
 export type CamelCasedPropertiesDeep<Value> = Value extends Function
 	? Value

package/ts41/camel-cased-properties.d.ts

@@ -20,6 +20,8 @@ const result: CamelCasedProperties<User> = {
 	userName: 'Tom',
 };
 ```
+
+@category Template Literals
 */
 export type CamelCasedProperties<Value> = Value extends Function
 	? Value

package/ts41/delimiter-case.d.ts

@@ -2,6 +2,8 @@ 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.
+
+@category Template Literals
 */
 export type SplitIncludingDelimiters<Source extends string, Delimiter extends string> =
 	Source extends '' ? [] :
@@ -73,8 +75,9 @@ const rawCliOptions: OddlyCasedProperties<SomeOptions> = {
 	foo: 123
 };
 ```
-*/
 
+@category Template Literals
+*/
 export type DelimiterCase<Value, Delimiter extends string> = Value extends string
 	? StringArrayToDelimiterCase<
 		SplitIncludingDelimiters<Value, WordSeparators | UpperCaseCharacters>,

package/ts41/delimiter-cased-properties-deep.d.ts

@@ -37,6 +37,8 @@ const result: DelimiterCasedPropertiesDeep<UserWithFriends, '-'> = {
 	],
 };
 ```
+
+@category Template Literals
 */
 export type DelimiterCasedPropertiesDeep<
 	Value,

package/ts41/delimiter-cased-properties.d.ts

@@ -20,6 +20,8 @@ const result: DelimiterCasedProperties<User, '-'> = {
 	'user-name': 'Tom',
 };
 ```
+
+@category Template Literals
 */
 export type DelimiterCasedProperties<
 	Value,

package/ts41/get.d.ts

@@ -127,5 +127,7 @@ const getName = (apiResponse: ApiResponse) =>
 	get(apiResponse, 'hits.hits[0]._source.name');
 	//=> Array<{given: string[]; family: string}>
 ```
+
+@category Template Literals
 */
 export type Get<BaseType, Path extends string> = GetWithPath<BaseType, ToPath<Path>>;

package/ts41/index.d.ts

@@ -14,6 +14,7 @@ export {PascalCasedPropertiesDeep} from './pascal-cased-properties-deep';
 export {SnakeCase} from './snake-case';
 export {SnakeCasedProperties} from './snake-cased-properties';
 export {SnakeCasedPropertiesDeep} from './snake-cased-properties-deep';
+export {ScreamingSnakeCase} from './screaming-snake-case';
 export {DelimiterCase} from './delimiter-case';
 export {DelimiterCasedProperties} from './delimiter-cased-properties';
 export {DelimiterCasedPropertiesDeep} from './delimiter-cased-properties-deep';

package/ts41/kebab-case.d.ts

@@ -31,6 +31,7 @@ const rawCliOptions: KebabCasedProperties<CliOptions> = {
 	foo: 123
 };
 ```
-*/
 
+@category Template Literals
+*/
 export type KebabCase<Value> = DelimiterCase<Value, '-'>;

package/ts41/kebab-cased-properties-deep.d.ts

@@ -37,5 +37,7 @@ const result: KebabCasedPropertiesDeep<UserWithFriends> = {
 	],
 };
 ```
+
+@category Template Literals
 */
 export type KebabCasedPropertiesDeep<Value> = DelimiterCasedPropertiesDeep<Value, '-'>;

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

@@ -20,5 +20,7 @@ const result: KebabCasedProperties<User> = {
 	'user-name': 'Tom',
 };
 ```
+
+@category Template Literals
 */
 export type KebabCasedProperties<Value> = DelimiterCasedProperties<Value, '-'>;

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

@@ -14,6 +14,8 @@ const array = ['foo', 2];
 typeof lastOf(array);
 //=> number
 ```
+
+@category Template Literals
 */
 export type LastArrayElement<ValueType extends unknown[]> =
 	ValueType extends [infer ElementType]

package/ts41/pascal-case.d.ts

@@ -29,8 +29,9 @@ const dbResult: CamelCasedProperties<ModelProps> = {
 	Foo: 123
 };
 ```
-*/
 
+@category Template Literals
+*/
 export type PascalCase<Value> = CamelCase<Value> extends string
 	? Capitalize<CamelCase<Value>>
 	: CamelCase<Value>;

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

@@ -37,6 +37,8 @@ const result: PascalCasedPropertiesDeep<UserWithFriends> = {
 	],
 };
 ```
+
+@category Template Literals
 */
 export type PascalCasedPropertiesDeep<Value> = Value extends Function
 	? Value

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

@@ -20,6 +20,8 @@ const result: PascalCasedProperties<User> = {
 	UserName: 'Tom',
 };
 ```
+
+@category Template Literals
 */
 export type PascalCasedProperties<Value> = Value extends Function
 	? Value

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

@@ -0,0 +1,40 @@
+import {SplitIncludingDelimiters} from './delimiter-case';
+import {SnakeCase} from './snake-case';
+
+/**
+Returns a boolean for whether the given array includes the given item.
+*/
+type Includes<Value extends any[], Item> = {
+	[P in keyof Value & number as Value[P]]: true;
+}[Item] extends true
+	? true
+	: false;
+
+/**
+Returns a boolean for whether the string is screaming snake case.
+*/
+type IsScreamingSnakeCase<Value extends string> = Value extends Uppercase<Value>
+	? Includes<SplitIncludingDelimiters<Lowercase<Value>, '_'>, '_'> extends true
+		? true
+		: false
+	: false;
+
+/**
+Convert a string literal to screaming-snake-case.
+
+This can be useful when, for example, converting a camel-cased object property to a screaming-snake-cased SQL column name.
+
+@example
+```
+import {ScreamingSnakeCase} from 'type-fest';
+
+const someVariable: ScreamingSnakeCase<'fooBar'> = 'FOO_BAR';
+```
+
+@category Template Literals
+*/
+export type ScreamingSnakeCase<Value> = Value extends string
+	? IsScreamingSnakeCase<Value> extends true
+		? Value
+		: Uppercase<SnakeCase<Value>>
+	: Value;

package/ts41/snake-case.d.ts

@@ -31,5 +31,7 @@ const dbResult: SnakeCasedProperties<ModelProps> = {
 	foo: 123
 };
 ```
+
+@category Template Literals
 */
 export type SnakeCase<Value> = DelimiterCase<Value, '_'>;

package/ts41/snake-cased-properties-deep.d.ts

@@ -37,5 +37,7 @@ const result: SnakeCasedPropertiesDeep<UserWithFriends> = {
 	],
 };
 ```
+
+@category Template Literals
 */
 export type SnakeCasedPropertiesDeep<Value> = DelimiterCasedPropertiesDeep<Value, '_'>;

package/ts41/snake-cased-properties.d.ts

@@ -20,5 +20,7 @@ const result: SnakeCasedProperties<User> = {
 	user_name: 'Tom',
 };
 ```
+
+@category Template Literals
 */
 export type SnakeCasedProperties<Value> = DelimiterCasedProperties<Value, '_'>;

package/ts41/split.d.ts

@@ -15,6 +15,8 @@ let array: Item[];
 
 array = split(items, ',');
 ```
+
+@category Template Literals
 */
 export type Split<S extends string, D extends string> =
 	S extends `${infer T}${D}${infer U}`

package/ts41/trim.d.ts

@@ -18,5 +18,7 @@ import {Trim} from 'type-fest';
 Trim<' foo '>
 //=> 'foo'
 ```
+
+@category Template Literals
 */
 export type Trim<V extends string> = TrimLeft<TrimRight<V>>;