type-fest 2.8.0 → 2.9.0

package/index.d.ts

@@ -37,6 +37,7 @@ export {SetReturnType} from './source/set-return-type';
 export {Asyncify} from './source/asyncify';
 export {Simplify} from './source/simplify';
 export {Jsonify} from './source/jsonify';
+export {LiteralToPrimitive} from './source/literal-to-primitive';
 export {
 	PositiveInfinity,
 	NegativeInfinity,

package/package.json

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

package/readme.md

@@ -88,10 +88,6 @@ Click the type names for complete docs.
 - [`Class`](source/basic.d.ts) - Matches a [`class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
 - [`Constructor`](source/basic.d.ts) - Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
 - [`TypedArray`](source/typed-array.d.ts) - Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
-- [`JsonPrimitive`](source/basic.d.ts) - Matches a JSON primitive.
-- [`JsonObject`](source/basic.d.ts) - Matches a JSON object.
-- [`JsonArray`](source/basic.d.ts) - Matches a JSON array.
-- [`JsonValue`](source/basic.d.ts) - Matches any valid JSON value.
 - [`ObservableLike`](source/observable-like.d.ts) - Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
 
 ### Utilities
@@ -114,15 +110,23 @@ Click the type names for complete docs.
 - [`ConditionalPick`](source/conditional-pick.d.ts) - Like `Pick` except it selects properties from a shape where the values extend the given `Condition` type.
 - [`ConditionalExcept`](source/conditional-except.d.ts) - Like `Omit` except it removes properties from a shape where the values extend the given `Condition` type.
 - [`UnionToIntersection`](source/union-to-intersection.d.ts) - Convert a union type to an intersection type.
+- [`LiteralToPrimitive`](source/literal-to-primitive.d.ts) - Convert a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) to the [primitive type](source/primitive.d.ts) it belongs to.
 - [`Stringified`](source/stringified.d.ts) - Create a type with the keys of the given type changed to `string` type.
 - [`IterableElement`](source/iterable-element.d.ts) - Get the element type of an `Iterable`/`AsyncIterable`. For example, an array or a generator.
 - [`Entry`](source/entry.d.ts) - Create a type that represents the type of an entry of a collection.
 - [`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.
 - [`Simplify`](source/simplify.d.ts) - Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
-- [`Jsonify`](source/jsonify.d.ts) - Transform a type to one that is assignable to the `JsonValue` type.
 - [`Get`](source/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.
 
+### JSON
+
+- [`Jsonify`](source/jsonify.d.ts) - Transform a type to one that is assignable to the `JsonValue` type.
+- [`JsonPrimitive`](source/basic.d.ts) - Matches a JSON primitive.
+- [`JsonObject`](source/basic.d.ts) - Matches a JSON object.
+- [`JsonArray`](source/basic.d.ts) - Matches a JSON array.
+- [`JsonValue`](source/basic.d.ts) - Matches any valid JSON value.
+
 ### Async
 
 - [`Promisable`](source/promisable.d.ts) - Create a type that represents either the value or the value wrapped in `PromiseLike`.

package/source/get.d.ts

@@ -1,16 +1,43 @@
 import {StringDigit} from '../source/utilities';
 import {Split} from './split';
 
+type GetOptions = {
+	strict?: boolean;
+};
+
 /**
 Like the `Get` type but receives an array of strings as a path parameter.
 */
-type GetWithPath<BaseType, Keys extends readonly string[]> =
+type GetWithPath<BaseType, Keys extends readonly string[], Options extends GetOptions = {}> =
 	Keys extends []
 	? BaseType
 	: Keys extends [infer Head, ...infer Tail]
-	? GetWithPath<PropertyOf<BaseType, Extract<Head, string>>, Extract<Tail, string[]>>
+	? GetWithPath<
+		PropertyOf<BaseType, Extract<Head, string>, Options>,
+		Extract<Tail, string[]>,
+		Options
+	>
 	: never;
 
+/**
+Adds `undefined` to `Type` if `strict` is enabled.
+*/
+type Strictify<Type, Options extends GetOptions> =
+	Options['strict'] extends true ? Type | undefined : Type;
+
+/**
+If `Options['strict']` is `true`, includes `undefined` in the returned type when accessing properties on `Record<string, any>`.
+
+Known limitations:
+- Does not include `undefined` in the type on object types with an index signature (for example, `{a: string; [key: string]: string}`).
+*/
+type StrictPropertyOf<BaseType, Key extends keyof BaseType, Options extends GetOptions> =
+	Record<string, any> extends BaseType
+	? string extends keyof BaseType
+		? Strictify<BaseType[Key], Options> // Record<string, any>
+		: BaseType[Key] // Record<'a' | 'b', any> (Records with a string union as keys have required properties)
+	: BaseType[Key];
+
 /**
 Splits a dot-prop style path into a tuple comprised of the properties in the path. Handles square-bracket notation.
 
@@ -29,8 +56,12 @@ type ToPath<S extends string> = Split<FixPathSquareBrackets<S>, '.'>;
 Replaces square-bracketed dot notation with dots, for example, `foo[0].bar` -> `foo.0.bar`.
 */
 type FixPathSquareBrackets<Path extends string> =
-	Path extends `${infer Head}[${infer Middle}]${infer Tail}`
-	? `${Head}.${Middle}${FixPathSquareBrackets<Tail>}`
+	Path extends `[${infer Head}]${infer Tail}`
+	? Tail extends `[${string}`
+		? `${Head}.${FixPathSquareBrackets<Tail>}`
+		: `${Head}${FixPathSquareBrackets<Tail>}`
+	: Path extends `${infer Head}[${infer Middle}]${infer Tail}`
+	? `${Head}.${FixPathSquareBrackets<`[${Middle}]${Tail}`>}`
 	: Path;
 
 /**
@@ -76,11 +107,11 @@ Note:
 - Returns `unknown` if `Key` is not a property of `BaseType`, since TypeScript uses structural typing, and it cannot be guaranteed that extra properties unknown to the type system will exist at runtime.
 - Returns `undefined` from nullish values, to match the behaviour of most deep-key libraries like `lodash`, `dot-prop`, etc.
 */
-type PropertyOf<BaseType, Key extends string> =
+type PropertyOf<BaseType, Key extends string, Options extends GetOptions = {}> =
 	BaseType extends null | undefined
 	? undefined
 	: Key extends keyof BaseType
-	? BaseType[Key]
+	? StrictPropertyOf<BaseType, Key, Options>
 	: BaseType extends [] | [unknown, ...unknown[]]
 	? unknown // It's a tuple, but `Key` did not extend `keyof BaseType`. So the index is out of bounds.
 	: BaseType extends {
@@ -89,11 +120,11 @@ type PropertyOf<BaseType, Key extends string> =
 	}
 	? (
 		ConsistsOnlyOf<Key, StringDigit> extends true
-		? Item
+		? Strictify<Item, Options>
 		: unknown
 	)
 	: Key extends keyof WithStringKeys<BaseType>
-	? WithStringKeys<BaseType>[Key]
+	? StrictPropertyOf<WithStringKeys<BaseType>, Key, Options>
 	: unknown;
 
 // This works by first splitting the path based on `.` and `[...]` characters into a tuple of string keys. Then it recursively uses the head key to get the next property of the current object, until there are no keys left. Number keys extract the item type from arrays, or are converted to strings to extract types from tuples and dictionaries with number keys.
@@ -128,10 +159,15 @@ interface ApiResponse {
 const getName = (apiResponse: ApiResponse) =>
 	get(apiResponse, 'hits.hits[0]._source.name');
 	//=> Array<{given: string[]; family: string}>
+
+// Strict mode:
+Get<string[], '3', {strict: true}> //=> string | undefined
+Get<Record<string, string>, 'foo', {strict: true}> // => string | undefined
 ```
 
-@category Template literal
 @category Object
 @category Array
+@category Template literal
 */
-export type Get<BaseType, Path extends string> = GetWithPath<BaseType, ToPath<Path>>;
+export type Get<BaseType, Path extends string, Options extends GetOptions = {}> =
+	GetWithPath<BaseType, ToPath<Path>, Options>;

package/source/jsonify.d.ts

@@ -70,6 +70,6 @@ type Jsonify<T> =
 						? (() => J) extends (() => JsonValue) // Is J assignable to JsonValue?
 							? J // Then T is Jsonable and its Jsonable value is J
 							: never // Not Jsonable because its toJSON() method does not return JsonValue
-						: {[P in keyof T]: Jsonify<T[P]>} // It's an object: recursive call for its children
+						: {[P in keyof T]: Jsonify<Required<T>[P]>} // It's an object: recursive call for its children
 					: never // Otherwise any other non-object is removed
 		: never; // Otherwise non-JSONable type union was found not empty

package/source/literal-to-primitive.d.ts

@@ -0,0 +1,36 @@
+/**
+Given a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) return the {@link Primitive | primitive type} it belongs to, or `never` if it's not a primitive.
+
+Use-case: Working with generic types that may be literal types.
+
+@example
+```
+import {LiteralToPrimitive} from 'type-fest';
+
+// No overloads needed to get the correct return type
+function plus<T extends number | bigint | string>(x: T, y: T): LiteralToPrimitive<T> {
+	return x + (y as any);
+}
+
+plus('a', 'b'); // string
+plus(1, 2); // number
+plus(1n, 2n); // bigint
+```
+
+@category Type
+*/
+export type LiteralToPrimitive<T> = T extends number
+	? number
+	: T extends bigint
+	? bigint
+	: T extends string
+	? string
+	: T extends boolean
+	? boolean
+	: T extends symbol
+	? symbol
+	: T extends null
+	? null
+	: T extends undefined
+	? undefined
+	: never;