type-fest 0.21.2 → 1.0.2

package/license

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https:/sindresorhus.com)
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/package.json

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

package/readme.md

@@ -110,11 +110,24 @@ Click the type names for complete docs.
 *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`).
+- [`CamelCasedProperties`](ts41/camel-cased-properties.d.ts) – Convert object properties to camel-case  (`fooBar`).
+- [`CamelCasedPropertiesDeep`](ts41/camel-cased-properties-deep.d.ts) – Convert object properties to camel-case recursively  (`fooBar`).
 - [`KebabCase`](ts41/kebab-case.d.ts) – Convert a string literal to kebab-case (`foo-bar`).
+- [`KebabCasedProperties`](ts41/kebab-cased-properties.d.ts) – Convert a object properties to kebab-case recursively (`foo-bar`).
+- [`KebabCasedPropertiesDeep`](ts41/kebab-cased-properties-deep.d.ts) – Convert object properties to kebab-case (`foo-bar`).
 - [`PascalCase`](ts41/pascal-case.d.ts) – Converts a string literal to pascal-case (`FooBar`)
+- [`PascalCasedProperties`](ts41/pascal-cased-properties.d.ts) – Converts object properties to pascal-case (`FooBar`)
+- [`PascalCasedPropertiesDeep`](ts41/pascal-cased-properties-deep.d.ts) – Converts object properties to pascal-case (`FooBar`)
 - [`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`).
 - [`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.
+- [`Split`](ts41/split.d.ts) - Represents an array of strings split using a given character or character set.
+- [`Trim`](ts41/trim.d.ts) - Remove leading and trailing spaces from a string.
 - [`Get`](ts41/get.d.ts) - Get a deeply-nested property from an object using a key path, like [Lodash's `.get()`](https://lodash.com/docs/latest#get) function.
+- [`LastArrayElement`](ts41/last-array-element.d.ts) - Extracts the type of the last element of an array.
 
 ### Miscellaneous
 
@@ -132,6 +145,10 @@ Click the type names for complete docs.
 
 ## Tips
 
+### Related
+
+- [typed-query-selector](https://github.com/g-plane/typed-query-selector) - Enhances `document.querySelector` and `document.querySelectorAll` with a template literal type that matches element types returned from an HTML element query selector.
+
 ### Built-in types
 
 There are many advanced types most users don't know about.

package/source/basic.d.ts

@@ -1,4 +1,4 @@
-/// <reference lib="esnext"/>
+/// <reference lib="es2020.bigint"/>
 
 // TODO: This can just be `export type Primitive = not object` when the `not` keyword is out.
 /**

package/source/entry.d.ts

@@ -44,7 +44,7 @@ const arrayEntryNumber: Entry<typeof arrayExample> = [1, 1];
 
 // Maps
 const mapExample = new Map([['a', 1]]);
-const mapEntry: Entry<typeof map> = ['a', 1];
+const mapEntry: Entry<typeof mapExample> = ['a', 1];
 
 // Sets
 const setExample = new Set(['a', 1]);

package/source/except.d.ts

@@ -3,7 +3,7 @@ Create a type from an object type without certain keys.
 
 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.
 
-Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/30825) if you want to have the stricter version as a built-in in TypeScript.
+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)).
 
 @example
 ```

package/ts41/camel-case.d.ts

@@ -44,7 +44,7 @@ const someVariable: CamelCase<'foo-bar'> = 'fooBar';
 
 // Advanced
 
-type CamelCasedProps<T> = {
+type CamelCasedProperties<T> = {
 	[K in keyof T as CamelCase<K>]: T[K]
 };
 
@@ -54,7 +54,7 @@ interface RawOptions {
 	foo: number;
 }
 
-const dbResult: CamelCasedProps<ModelProps> = {
+const dbResult: CamelCasedProperties<ModelProps> = {
 	dryRun: true,
 	fullFamilyName: 'bar.js',
 	foo: 123

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

@@ -0,0 +1,48 @@
+import {CamelCase} from './camel-case';
+
+/**
+Convert object properties to camel case recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see CamelCasedProperties
+@see CamelCase
+
+@example
+```
+interface User {
+	UserId: number;
+	UserName: string;
+}
+
+interface UserWithFriends {
+	UserInfo: User;
+	UserFriends: User[];
+}
+
+const result: CamelCasedPropertiesDeep<UserWithFriends> = {
+	userInfo: {
+		userId: 1,
+		userName: 'Tom',
+	},
+	userFriends: [
+		{
+			userId: 2,
+			userName: 'Jerry',
+		},
+		{
+			userId: 3,
+			userName: 'Spike',
+		},
+	],
+};
+```
+*/
+export type CamelCasedPropertiesDeep<Value> = Value extends Function
+	? Value
+	: Value extends Array<infer U>
+	? Array<CamelCasedPropertiesDeep<U>>
+	: Value extends Set<infer U>
+	? Set<CamelCasedPropertiesDeep<U>> : {
+			[K in keyof Value as CamelCase<K>]: CamelCasedPropertiesDeep<Value[K]>;
+	};

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

@@ -0,0 +1,30 @@
+import {CamelCase} from './camel-case';
+
+/**
+Convert object properties to camel case but not recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see CamelCasedPropertiesDeep
+@see CamelCase
+
+@example
+```
+interface User {
+	UserId: number;
+	UserName: string;
+}
+
+const result: CamelCasedProperties<User> = {
+	userId: 1,
+	userName: 'Tom',
+};
+```
+*/
+export type CamelCasedProperties<Value> = Value extends Function
+	? Value
+	: Value extends Array<infer U>
+	? Value
+	: {
+			[K in keyof Value as CamelCase<K>]: Value[K];
+	};

package/ts41/delimiter-case.d.ts

@@ -57,7 +57,7 @@ const someVariable: DelimiterCase<'fooBar', '#'> = 'foo#bar';
 
 // Advanced
 
-type OddlyCasedProps<T> = {
+type OddlyCasedProperties<T> = {
 	[K in keyof T as DelimiterCase<K, '#'>]: T[K]
 };
 
@@ -67,7 +67,7 @@ interface SomeOptions {
 	foo: number;
 }
 
-const rawCliOptions: OddlyCasedProps<SomeOptions> = {
+const rawCliOptions: OddlyCasedProperties<SomeOptions> = {
 	'dry#run': true,
 	'include#file': 'bar.js',
 	foo: 123

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

@@ -0,0 +1,54 @@
+import {DelimiterCase} from './delimiter-case';
+
+/**
+Convert object properties to delimiter case recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see DelimiterCase
+@see DelimiterCasedProperties
+
+@example
+```
+interface User {
+	userId: number;
+	userName: string;
+}
+
+interface UserWithFriends {
+	userInfo: User;
+	userFriends: User[];
+}
+
+const result: DelimiterCasedPropertiesDeep<UserWithFriends, '-'> = {
+	'user-info': {
+	'user-id': 1,
+		'user-name': 'Tom',
+	},
+	'user-friends': [
+		{
+			'user-id': 2,
+			'user-name': 'Jerry',
+		},
+		{
+			'user-id': 3,
+			'user-name': 'Spike',
+		},
+	],
+};
+```
+*/
+export type DelimiterCasedPropertiesDeep<
+	Value,
+	Delimiter extends string
+> = Value extends Function
+	? Value
+	: Value extends Array<infer U>
+	? Array<DelimiterCasedPropertiesDeep<U, Delimiter>>
+	: Value extends Set<infer U>
+	? Set<DelimiterCasedPropertiesDeep<U, Delimiter>> : {
+			[K in keyof Value as DelimiterCase<
+				K,
+				Delimiter
+			>]: DelimiterCasedPropertiesDeep<Value[K], Delimiter>;
+	};

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

@@ -0,0 +1,31 @@
+import {DelimiterCase} from './delimiter-case';
+
+/**
+Convert object properties to delimiter case but not recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see DelimiterCase
+@see DelimiterCasedPropertiesDeep
+
+@example
+```
+interface User {
+	userId: number;
+	userName: string;
+}
+
+const result: DelimiterCasedProperties<User, '-'> = {
+	'user-id': 1,
+	'user-name': 'Tom',
+};
+```
+*/
+export type DelimiterCasedProperties<
+	Value,
+	Delimiter extends string
+> = Value extends Function
+	? Value
+	: Value extends Array<infer U>
+	? Value
+	: { [K in keyof Value as DelimiterCase<K, Delimiter>]: Value[K] };

package/ts41/index.d.ts

@@ -3,8 +3,21 @@ export * from '../base';
 
 // These are special types that require at least TypeScript 4.1.
 export {CamelCase} from './camel-case';
+export {CamelCasedProperties} from './camel-cased-properties';
+export {CamelCasedPropertiesDeep} from './camel-cased-properties-deep';
 export {KebabCase} from './kebab-case';
+export {KebabCasedProperties} from './kebab-cased-properties';
+export {KebabCasedPropertiesDeep} from './kebab-cased-properties-deep';
 export {PascalCase} from './pascal-case';
+export {PascalCasedProperties} from './pascal-cased-properties';
+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 {DelimiterCase} from './delimiter-case';
+export {DelimiterCasedProperties} from './delimiter-cased-properties';
+export {DelimiterCasedPropertiesDeep} from './delimiter-cased-properties-deep';
+export {Split} from './split';
+export {Trim} from './trim';
 export {Get} from './get';
+export {LastArrayElement} from './last-array-element';

package/ts41/kebab-case.d.ts

@@ -15,7 +15,7 @@ const someVariable: KebabCase<'fooBar'> = 'foo-bar';
 
 // Advanced
 
-type KebabCasedProps<T> = {
+type KebabCasedProperties<T> = {
 	[K in keyof T as KebabCase<K>]: T[K]
 };
 
@@ -25,7 +25,7 @@ interface CliOptions {
 	foo: number;
 }
 
-const rawCliOptions: KebabCasedProps<CliOptions> = {
+const rawCliOptions: KebabCasedProperties<CliOptions> = {
 	'dry-run': true,
 	'include-file': 'bar.js',
 	foo: 123

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

@@ -0,0 +1,41 @@
+import {DelimiterCasedPropertiesDeep} from './delimiter-cased-properties-deep';
+
+/**
+Convert object properties to kebab case recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see KebabCase
+@see KebabCasedProperties
+
+@example
+```
+interface User {
+	userId: number;
+	userName: string;
+}
+
+interface UserWithFriends {
+	userInfo: User;
+	userFriends: User[];
+}
+
+const result: KebabCasedPropertiesDeep<UserWithFriends> = {
+	'user-info': {
+		'user-id': 1,
+		'user-name': 'Tom',
+	},
+	'user-friends': [
+		{
+			'user-id': 2,
+			'user-name': 'Jerry',
+		},
+		{
+			'user-id': 3,
+			'user-name': 'Spike',
+		},
+	],
+};
+```
+*/
+export type KebabCasedPropertiesDeep<Value> = DelimiterCasedPropertiesDeep<Value, '-'>;

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

@@ -0,0 +1,24 @@
+import {DelimiterCasedProperties} from './delimiter-cased-properties';
+
+/**
+Convert object properties to kebab case but not recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see KebabCase
+@see KebabCasedPropertiesDeep
+
+@example
+```
+interface User {
+	userId: number;
+	userName: string;
+}
+
+const result: KebabCasedProperties<User> = {
+	'user-id': 1,
+	'user-name': 'Tom',
+};
+```
+*/
+export type KebabCasedProperties<Value> = DelimiterCasedProperties<Value, '-'>;

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

@@ -0,0 +1,23 @@
+/**
+Extracts the type of the last element of an array.
+
+Use-case: Defining the return type of functions that extract the last element of an array, for example [`lodash.last`](https://lodash.com/docs/4.17.15#last).
+
+@example
+```
+import {LastArrayElement} from 'type-fest';
+
+declare function lastOf<V extends any[]>(array: V): LastArrayElement<V>;
+
+const array = ['foo', 2];
+
+typeof lastOf(array);
+//=> number
+```
+*/
+export type LastArrayElement<ValueType extends unknown[]> =
+	ValueType extends [infer ElementType]
+		? ElementType
+		: ValueType extends [infer _, ...infer Tail]
+			? LastArrayElement<Tail>
+			: never;

package/ts41/pascal-case.d.ts

@@ -23,7 +23,7 @@ interface RawOptions {
 	foo: number;
 }
 
-const dbResult: CamelCasedProps<ModelProps> = {
+const dbResult: CamelCasedProperties<ModelProps> = {
 	DryRun: true,
 	FullFamilyName: 'bar.js',
 	Foo: 123

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

@@ -0,0 +1,48 @@
+import {PascalCase} from './pascal-case';
+
+/**
+Convert object properties to pascal case recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see PascalCase
+@see PascalCasedProperties
+
+@example
+```
+interface User {
+	userId: number;
+	userName: string;
+}
+
+interface UserWithFriends {
+	userInfo: User;
+	userFriends: User[];
+}
+
+const result: PascalCasedPropertiesDeep<UserWithFriends> = {
+	UserInfo: {
+		UserId: 1,
+		UserName: 'Tom',
+	},
+	UserFriends: [
+		{
+			UserId: 2,
+			UserName: 'Jerry',
+		},
+		{
+			UserId: 3,
+			UserName: 'Spike',
+		},
+	],
+};
+```
+*/
+export type PascalCasedPropertiesDeep<Value> = Value extends Function
+	? Value
+	: Value extends Array<infer U>
+	? Array<PascalCasedPropertiesDeep<U>>
+	: Value extends Set<infer U>
+	? Set<PascalCasedPropertiesDeep<U>> : {
+			[K in keyof Value as PascalCase<K>]: PascalCasedPropertiesDeep<Value[K]>;
+	};

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

@@ -0,0 +1,28 @@
+import {PascalCase} from './pascal-case';
+
+/**
+Convert object properties to pascal case but not recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see PascalCase
+@see PascalCasedPropertiesDeep
+
+@example
+```
+interface User {
+	userId: number;
+	userName: string;
+}
+
+const result: PascalCasedProperties<User> = {
+	UserId: 1,
+	UserName: 'Tom',
+};
+```
+*/
+export type PascalCasedProperties<Value> = Value extends Function
+	? Value
+	: Value extends Array<infer U>
+	? Value
+	: { [K in keyof Value as PascalCase<K>]: Value[K] };

package/ts41/snake-case.d.ts

@@ -15,7 +15,7 @@ const someVariable: SnakeCase<'fooBar'> = 'foo_bar';
 
 // Advanced
 
-type SnakeCasedProps<T> = {
+type SnakeCasedProperties<T> = {
 	[K in keyof T as SnakeCase<K>]: T[K]
 };
 
@@ -25,7 +25,7 @@ interface ModelProps {
 	foo: number;
 }
 
-const dbResult: SnakeCasedProps<ModelProps> = {
+const dbResult: SnakeCasedProperties<ModelProps> = {
 	'is_happy': true,
 	'full_family_name': 'Carla Smith',
 	foo: 123

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

@@ -0,0 +1,41 @@
+import {DelimiterCasedPropertiesDeep} from './delimiter-cased-properties-deep';
+
+/**
+Convert object properties to snake case recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see SnakeCase
+@see SnakeCasedProperties
+
+@example
+```
+interface User {
+	userId: number;
+	userName: string;
+}
+
+interface UserWithFriends {
+	userInfo: User;
+	userFriends: User[];
+}
+
+const result: SnakeCasedPropertiesDeep<UserWithFriends> = {
+	user_info: {
+		user_id: 1,
+		user_name: 'Tom',
+	},
+	user_friends: [
+		{
+			user_id: 2,
+			user_name: 'Jerry',
+		},
+		{
+			user_id: 3,
+			user_name: 'Spike',
+		},
+	],
+};
+```
+*/
+export type SnakeCasedPropertiesDeep<Value> = DelimiterCasedPropertiesDeep<Value, '_'>;

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

@@ -0,0 +1,24 @@
+import {DelimiterCasedProperties} from './delimiter-cased-properties';
+
+/**
+Convert object properties to snake case but not recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see SnakeCase
+@see SnakeCasedPropertiesDeep
+
+@example
+```
+interface User {
+	userId: number;
+	userName: string;
+}
+
+const result: SnakeCasedProperties<User> = {
+	user_id: 1,
+	user_name: 'Tom',
+};
+```
+*/
+export type SnakeCasedProperties<Value> = DelimiterCasedProperties<Value, '_'>;

package/ts41/split.d.ts

@@ -0,0 +1,22 @@
+/**
+Represents an array of strings split using a given character or character set.
+
+Use-case: Defining the return type of a method like `String.prototype.split`.
+
+@example
+```
+import {Split} from 'type-fest';
+
+declare function split<S extends string, D extends string>(string: S, separator: D): Split<S, D>;
+
+type Item = 'foo' | 'bar' | 'baz' | 'waldo';
+const items = 'foo,bar,baz,waldo';
+let array: Item[];
+
+array = split(items, ',');
+```
+*/
+export type Split<S extends string, D extends string> =
+	S extends `${infer T}${D}${infer U}`
+		? [T, ...Split<U, D>]
+		: [S];

package/ts41/trim.d.ts

@@ -0,0 +1,22 @@
+/**
+Remove spaces from the left side.
+*/
+type TrimLeft<V extends string> = V extends ` ${infer R}` ? TrimLeft<R> : V;
+
+/**
+Remove spaces from the right side.
+*/
+type TrimRight<V extends string> = V extends `${infer R} ` ? TrimRight<R> : V;
+
+/**
+Remove leading and trailing spaces from a string.
+
+@example
+```
+import {Trim} from 'type-fest';
+
+Trim<' foo '>
+//=> 'foo'
+```
+*/
+export type Trim<V extends string> = TrimLeft<TrimRight<V>>;