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 {TakeLast} from './source/take-last';
 
 // 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.
+- [`TakeLast`](source/take-last.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 a query.
+- [`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/take-last.d.ts

@@ -0,0 +1,18 @@
+/**
+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
+declare function lastOf<V extends any[], L extends TakeLast<V>>(array: V): L;
+const array = ['foo', 2];
+typeof lastOf(array); // -> number;
+*/
+export type TakeLast<V> =
+    V extends []
+        ? never
+        : V extends [string]
+            ? V[0]
+            : V extends [string, ...infer R]
+                ? TakeLast<R>
+                : never;

test-d/query-result.ts

@@ -0,0 +1,10 @@
+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'));

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/take-last.ts

@@ -0,0 +1,8 @@
+import {expectType} from 'tsd';
+import {TakeLast} from '..';
+
+declare function lastOf<V extends any[], L extends TakeLast<V>>(array: V): L;
+const array = ['foo', 2];
+
+expectType<number>(lastOf(array));
+expectType<string>(lastOf(array.reverse()));

test-d/trim.ts

@@ -0,0 +1,22 @@
+import {expectError, expectType} from 'tsd';
+import {Trim} from '../ts41';
+
+let leftSpaced: {withSpaces: ' foo'; trimmed: 'foo'};
+let rightSpaced: {withSpaces: 'bar '; trimmed: 'bar'};
+let onceSpaced: {withSpaces: ' baz '; trimmed: 'baz'};
+let twiceSpaced: {withSpaces: '  waldo  '; trimmed: 'waldo'};
+
+type TrimmedFromLeft = Trim<typeof leftSpaced.withSpaces>;
+type TrimmedFromRight = Trim<typeof rightSpaced.withSpaces>;
+type TrimmedOnce = Trim<typeof onceSpaced.withSpaces>;
+type TrimmedTwice = Trim<typeof twiceSpaced.withSpaces>;
+
+expectType<TrimmedFromLeft>(leftSpaced.trimmed);
+expectType<TrimmedFromRight>(rightSpaced.trimmed);
+expectType<TrimmedOnce>(onceSpaced.trimmed);
+expectType<TrimmedTwice>(twiceSpaced.trimmed);
+
+expectError(expectType<TrimmedFromLeft>(rightSpaced.trimmed));
+expectError(expectType<TrimmedFromRight>(onceSpaced.trimmed));
+expectError(expectType<TrimmedOnce>(twiceSpaced.trimmed));
+expectError(expectType<TrimmedTwice>(leftSpaced.trimmed));

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,66 @@
+import {TakeLast} from '..';
+import {Split} from './split';
+import {Trim} from './trim';
+
+/**
+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
+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>>;
+
+/** Internal helper for `QueryResult`. Strips a given modifier from a string. */
+type StripModifier<V extends string, M extends string> = V extends `${infer L}${M}${infer A}` ? L : V;
+
+/** Internal helper for `QueryResult`. Strips CSS modifiers from a string. */
+type StripModifiers<V extends string> = StripModifier<StripModifier<StripModifier<StripModifier<V, '.'>, '#'>, '['>, ':'>;
+
+/** Internal helper for `QueryResult`. Takes the last element after the given token. */
+type TakeLastAfterToken<V extends string, T extends string> = StripModifiers<TakeLast<Split<Trim<V>, T>>>;
+
+/** Internal helper for `QueryResult`. Extracts the last element from a CSS selector string. */
+type GetLastElementName<V extends string> = TakeLastAfterToken<TakeLastAfterToken<V, ' '>, '>'>;
+
+/** Internal helper for `QueryResult`. 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]>]>
+                : [];
+
+/** Internal helper for `QueryResult`. Returns an array of element names with stripped modifiers from a comma-seperated string. */
+type GetElementNames<V extends string> = GetEachElementName<Split<V, ','>>;
+
+/** Internal helper for `QueryResult`. 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;
+
+/** Internal helper for `QueryResult`. 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;

ts41/split.d.ts

@@ -0,0 +1,18 @@
+/**
+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
+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,13 @@
+/**
+Removes spaces from the edges of a string.
+
+@example
+Trim<' foo '> => 'foo';
+*/
+export type Trim<V extends string> = TrimLeft<TrimRight<V>>;
+
+/** Internal helper for `Trim`. Removes spaces from the left side. */
+type TrimLeft<V extends string> = V extends ` ${infer R}` ? TrimLeft<R> : V;
+
+/** Internal helper for `Trim`. Removes spaces from the right side. */
+type TrimRight<V extends string> = V extends `${infer R} ` ? TrimRight<R> : V;