Add LastArrayElement, Split, and Trim types

base.d.ts

@@ -32,6 +32,7 @@ export {Entry} from './source/entry';
 export {Entries} from './source/entries';
 export {SetReturnType} from './source/set-return-type';
 export {Asyncify} from './source/asyncify';
+export {LastArrayElement} from './source/last-array-element';
 
 // Miscellaneous
 export {PackageJson} from './source/package-json';

readme.md

@@ -87,6 +87,7 @@ Click the type names for complete docs.
 - [`Entries`](source/entries.d.ts) - Create a type that represents the type of the entries of a collection.
 - [`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.
+- [`LastArrayElement`](source/last-array-element.d.ts) - Extracts the type of the last element of an array.
 
 ### Template literal types
 
@@ -97,6 +98,9 @@ Click the type names for complete docs.
 - [`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.
+- [`QueryResult`](ts41/query-result.d.ts) - Matches element types returned from an HTML element query selector.
+- [`Split`](ts41/split.d.ts) - Represents an array of strings split using a passed-in character or character set.
+- [`Trim`](ts41/trim.d.ts) - Remove leading and trailing spaces from a string.
 
 ### Miscellaneous
 

source/last-array-element.d.ts

@@ -0,0 +1,20 @@
+/**
+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<V extends unknown[]> =
+	V extends [infer X]
+		? X
+		: V extends [infer _, ...infer Tail]
+			? LastArrayElement<Tail>
+			: never;

test-d/last-array-element.ts

@@ -0,0 +1,9 @@
+import {expectType} from 'tsd';
+import {LastArrayElement} from '../ts41';
+
+declare function lastOf<V extends [any, ...any]>(array: V): LastArrayElement<V>;
+const array: ['foo', 2, 'bar'] = ['foo', 2, 'bar'];
+const mixedArray: ['bar', 'foo', 2] = ['bar', 'foo', 2];
+
+expectType<'bar'>(lastOf(array));
+expectType<number>(lastOf(mixedArray));

test-d/query-result.ts

@@ -0,0 +1,18 @@
+import {expectType} from 'tsd';
+import {QueryResult} from '../ts41';
+
+declare function querySelector<T extends string>(query: T): QueryResult<T>;
+
+expectType<HTMLAnchorElement>(querySelector('div.banner > a.call-to-action'));
+expectType<HTMLInputElement | HTMLDivElement>(querySelector('input, div'));
+expectType<SVGCircleElement>(querySelector('circle[cx="150"]'));
+expectType<HTMLButtonElement>(querySelector('button#buy-now'));
+expectType<HTMLParagraphElement>(querySelector('section p:first-of-type'));
+expectType<HTMLDivElement>(querySelector('.menu #leftSide aside div.menu #leftSide aside div'));
+expectType<HTMLButtonElement | HTMLButtonElement | HTMLParagraphElement>(querySelector('button#buy-now, input.input, section>p'));
+expectType<HTMLVideoElement>(querySelector('.main video#trailer'));
+expectType<HTMLTableRowElement>(querySelector('table.main tr'));
+expectType<HTMLStyleElement>(querySelector('html style'));
+expectType<HTMLSourceElement>(querySelector('.main source'));
+expectType<HTMLScriptElement>(querySelector('head script[src="script-source"]'));
+expectType<Element>(querySelector('.class'));

test-d/split.ts

@@ -0,0 +1,13 @@
+import {expectType} from 'tsd';
+import {Split} from '../ts41';
+
+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';
+const array = split(items, ',');
+
+expectType<Item>(array[0]);
+expectType<Item>(array[1]);
+expectType<Item>(array[2]);
+expectType<Item>(array[3]);

test-d/trim.ts

@@ -0,0 +1,10 @@
+import {expectType} from 'tsd';
+import {Trim} from '../ts41';
+
+declare function trim<S extends string>(value: S): Trim<S>;
+
+expectType<'foo'>(trim(' foo'));
+expectType<'bar'>(trim('bar '));
+expectType<'baz'>(trim(' baz '));
+expectType<'waldo'>(trim('  waldo  '));
+expectType<'fr ed'>(trim(' fr ed '));

ts41/index.d.ts

@@ -7,3 +7,6 @@ export {KebabCase} from './kebab-case';
 export {PascalCase} from './pascal-case';
 export {SnakeCase} from './snake-case';
 export {DelimiterCase} from './delimiter-case';
+export {QueryResult} from './query-result';
+export {Split} from './split';
+export {Trim} from './trim';

ts41/query-result.d.ts

@@ -0,0 +1,70 @@
+import {LastArrayElement} from '..';
+import {Split} from './split';
+import {Trim} from './trim';
+
+/** Strips a given modifier from a string. */
+type StripModifier<V extends string, M extends string> = V extends `${infer L}${M}${infer A}` ? L : V;
+
+/** Strips CSS modifiers from a string. */
+type StripModifiers<V extends string> = StripModifier<StripModifier<StripModifier<StripModifier<V, '.'>, '#'>, '['>, ':'>;
+
+/** Takes the last element after the given token. */
+type LastArrayElementAfterToken<V extends string, T extends string> = StripModifiers<LastArrayElement<Split<Trim<V>, T>>>;
+
+/** Extracts the last element from a CSS selector string. */
+type GetLastElementName<V extends string> = LastArrayElementAfterToken<LastArrayElementAfterToken<V, ' '>, '>'>;
+
+/** Returns an array of element names with stripped modifiers. */
+type GetEachElementName<V, L extends string[] = []> =
+	V extends []
+		? L
+		: V extends [string]
+			? [...L, GetLastElementName<V[0]>]
+			: V extends [string, ...infer R]
+				? GetEachElementName<R, [...L, GetLastElementName<V[0]>]>
+				: [];
+
+/** Returns an array of element names with stripped modifiers from a comma-seperated string. */
+type GetElementNames<V extends string> = GetEachElementName<Split<V, ','>>;
+
+/** Returns a HTML element using a CSS selector. */
+type ElementByName<V extends string> =
+	V extends keyof HTMLElementTagNameMap
+		? HTMLElementTagNameMap[V]
+		: V extends keyof SVGElementTagNameMap
+			? SVGElementTagNameMap[V]
+			: Element;
+
+/** Returns an HTML element array based on CSS selector names. */
+type MatchEachElement<V, L extends Element | null = null> =
+	V extends []
+		? L
+		: V extends [string]
+			? L | ElementByName<V[0]>
+			: V extends [string, ...infer R]
+				? MatchEachElement<R, L | ElementByName<V[0]>>
+				: L;
+
+/**
+Matches element types returned from a query.
+
+Use cases:
+- anywhere you'd use `querySelector` or `querySelectorAll`.
+- used on other element-selecting functions that are working based on CSS selectors.
+
+If you'd like to see this integrated into TypeScript, please upvote [this issue](https://github.com/microsoft/TypeScript/issues/29037).
+
+@example
+```
+import {QueryResult} from 'type-fest';
+
+declare function querySelector<T extends string>(query: T): QueryResult<T>;
+
+const anchor = querySelector('div.banner > a.call-to-action') //-> HTMLAnchorElement
+const div = querySelector('input, div') //-> HTMLInputElement | HTMLDivElement
+const svg = querySelector('circle[cx="150"]') //-> SVGCircleElement
+const button = querySelector('button#buy-now') //-> HTMLButtonElement
+const paragraph = querySelector('section p:first-of-type'); //-> HTMLParagraphElement
+```
+*/
+export type QueryResult<T extends string> = MatchEachElement<GetElementNames<T>>;

ts41/split.d.ts

@@ -0,0 +1,22 @@
+/**
+Represents an array of strings split using a passed-in character or character set.
+
+Use case: defining the return type of the `String.prototype.split` method.
+
+@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];

ts41/trim.d.ts

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