Add KeyPath and PathValue types

readme.md

@@ -97,6 +97,8 @@ 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.
+- [`KeyPath`](ts41/key-path.d.ts) - Represents a dot path to a nested object property.
+- [`PathValue`](ts41/key-path.d.ts) - Targets a property from a nested object using a dot path.
 
 ### Miscellaneous
 

test-d/key-path.ts

@@ -0,0 +1,21 @@
+import {expectError, expectType} from 'tsd';
+import {KeyPath, PathValue} from '../ts41';
+
+const user = {
+    firstName: 'Foo',
+    lastName: 'Bar',
+    projects: [
+        {name: 'Baz', contributors: 68},
+        {name: 'Waldo', contributors: 12}
+    ]
+};
+
+declare function get<T, P extends KeyPath<T>>(object: T, path: P): PathValue<T, P>;
+
+get(user, 'projects.0.name');
+expectType<string>(get(user, 'projects.0.name'));
+expectType<number>(get(user, 'projects.1.contributors'));
+
+expectError(get(user, 'projects.2.name'));
+expectError(get(user, 'projects.name'));
+expectError(get(user, 'name'));

ts41/index.d.ts

@@ -7,3 +7,4 @@ export {KebabCase} from './kebab-case';
 export {PascalCase} from './pascal-case';
 export {SnakeCase} from './snake-case';
 export {DelimiterCase} from './delimiter-case';
+export {KeyPath, PathValue} from './key-path';

ts41/key-path.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Targets a property from a nested object using a dot path.
+ *
+ * Use case: Extracting a given value from a complex API requests that is otherwise non-essential outside that value.
+ *
+ * @see KeyPath
+ * @example
+ * declare function get<T, P extends KeyPath<T>>(obj: T, path: P): PathValue<T, P>;
+ * const user = {
+ *   firstName: 'Foo',
+ *   lastName: 'Bar',
+ *   projects: [
+ *     { name: 'Baz', contributors: 68 },
+ *     { name: 'Waldo', contributors: 12 },
+ *   ]
+ * };
+ *
+ * get(user, 'projects.0.name');
+ */
+export type PathValue<ObjectType, PathType extends KeyPath<ObjectType>> =
+    PathType extends `${infer KeyType}.${infer Rest}`
+        ? KeyType extends keyof ObjectType
+            ? Rest extends KeyPath<ObjectType[KeyType]>
+                ? PathValue<ObjectType[KeyType], Rest>
+                : never
+            : never
+    : PathType extends keyof ObjectType
+        ? ObjectType[PathType]
+        : never;
+
+/**
+ * Represents a dot path to a nested object property.
+ *
+ * Use case: to be used in any helper function that extracts values based on a string dot path, like [lodash.get](https://lodash.com/docs/#get) or [dot-prop](https://github.com/sindresorhus/dot-prop).
+ *
+ * @see PathValue
+ * @example
+ * declare function get<T, P extends KeyPath<T>>(obj: T, path: P): PathValue<T, P>;
+ * const user = {
+ *   firstName: 'Foo',
+ *   lastName: 'Bar',
+ *   projects: [
+ *     { name: 'Baz', contributors: 68 },
+ *     { name: 'Waldo', contributors: 12 },
+ *   ]
+ * };
+ *
+ * get(user, 'projects.0.name');
+ */
+export type KeyPath<ObjectType> =
+    ImpliedPath<ObjectType> extends string | keyof ObjectType
+        ? ImpliedPath<ObjectType>
+        : keyof ObjectType;
+
+type ImpliedPath<ObjectType> = ImpliedPathDeep<ObjectType, keyof ObjectType> | keyof ObjectType;
+
+type ImpliedPathDeep<ObjectType, KeyType extends keyof ObjectType> =
+    KeyType extends string
+        ? ObjectType[KeyType] extends Record<string, any>
+            ?
+                | `${KeyType}.${ImpliedPathDeep<ObjectType[KeyType], Exclude<keyof ObjectType[KeyType], keyof any[]>> & string}`
+                | `${KeyType}.${Exclude<keyof ObjectType[KeyType], keyof any[]> & string}`
+            : never
+        : never;