type-fest 2.10.0 → 2.12.0

package/index.d.ts

@@ -18,6 +18,7 @@ export {ReadonlyDeep} from './source/readonly-deep';
 export {LiteralUnion} from './source/literal-union';
 export {Promisable} from './source/promisable';
 export {Opaque} from './source/opaque';
+export {InvariantOf} from './source/invariant-of';
 export {SetOptional} from './source/set-optional';
 export {SetRequired} from './source/set-required';
 export {ValueOf} from './source/value-of';
@@ -38,6 +39,7 @@ export {SetReturnType} from './source/set-return-type';
 export {Asyncify} from './source/asyncify';
 export {Simplify} from './source/simplify';
 export {Jsonify} from './source/jsonify';
+export {Schema} from './source/schema';
 export {LiteralToPrimitive} from './source/literal-to-primitive';
 export {
 	PositiveInfinity,

package/package.json

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

package/readme.md

@@ -104,6 +104,7 @@ Click the type names for complete docs.
 - [`ReadonlyDeep`](source/readonly-deep.d.ts) - Create a deeply immutable version of an `object`/`Map`/`Set`/`Array` type. Use [`Readonly<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype) if you only need one level deep.
 - [`LiteralUnion`](source/literal-union.d.ts) - Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union. Workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729).
 - [`Opaque`](source/opaque.d.ts) - Create an [opaque type](https://codemix.com/opaque-types-in-javascript/).
+- [`InvariantOf`](source/invariant-of.d.ts) - Create an [invariant type](https://basarat.gitbook.io/typescript/type-system/type-compatibility#footnote-invariance), which is a type that does not accept supertypes and subtypes.
 - [`SetOptional`](source/set-optional.d.ts) - Create a type that makes the given keys optional.
 - [`SetRequired`](source/set-required.d.ts) - Create a type that makes the given keys required.
 - [`ValueOf`](source/value-of.d.ts) - Create a union of the given object's values, and optionally specify which keys to get the values from.
@@ -120,6 +121,7 @@ Click the type names for complete docs.
 - [`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.
 - [`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.
 - [`StringKeyOf`](source/string-key-of.d.ts) - Get keys of the given type as strings.
+- [`Schema`](source/schema.d.ts) - Create a deep version of another object type where property values are recursively replaced into a given value type.
 
 ### JSON
 
@@ -196,12 +198,14 @@ Click the type names for complete docs.
 - [`Url2Json`](https://github.com/sindresorhus/type-fest/pull/262) - Inferring search parameters from a URL string is a cute idea, but not very useful in practice, since search parameters are usually dynamic and defined separately.
 - [`Nullish`](https://github.com/sindresorhus/type-fest/pull/318) - The type only saves a couple of characters, not everyone knows what "nullish" means, and I'm also trying to [get away from `null`](https://github.com/sindresorhus/meta/discussions/7).
 - [`TitleCase`](https://github.com/sindresorhus/type-fest/pull/303) - It's not solving a common need and is a better fit for a separate package.
+- [`ExtendOr` and `ExtendAnd`](https://github.com/sindresorhus/type-fest/pull/247) - The benefits don't outweigh having to learn what they mean.
 
 ## Alternative type names
 
 *If you know one of our types by a different name, add it here for discovery.*
 
 - `PartialBy` - See [`SetOptional`](https://github.com/sindresorhus/type-fest/blob/main/source/set-optional.d.ts)
+- `RecordDeep`- See [`Schema`](https://github.com/sindresorhus/type-fest/blob/main/source/schema.d.ts)
 
 ## Tips
 

package/source/get.d.ts

@@ -12,7 +12,7 @@ Like the `Get` type but receives an array of strings as a path parameter.
 type GetWithPath<BaseType, Keys extends readonly string[], Options extends GetOptions = {}> =
 	Keys extends []
 	? BaseType
-	: Keys extends [infer Head, ...infer Tail]
+	: Keys extends readonly [infer Head, ...infer Tail]
 	? GetWithPath<
 		PropertyOf<BaseType, Extract<Head, string>, Options>,
 		Extract<Tail, string[]>,
@@ -139,7 +139,7 @@ Use-case: Retrieve a property from deep inside an API response or some other com
 import {Get} from 'type-fest';
 import * as lodash from 'lodash';
 
-const get = <BaseType, Path extends string | string[]>(object: BaseType, path: Path): Get<BaseType, Path> =>
+const get = <BaseType, Path extends string | readonly string[]>(object: BaseType, path: Path): Get<BaseType, Path> =>
 	lodash.get(object, path);
 
 interface ApiResponse {
@@ -161,9 +161,9 @@ const getName = (apiResponse: ApiResponse) =>
 	get(apiResponse, 'hits.hits[0]._source.name');
 	//=> Array<{given: string[]; family: string}>
 
-// Path also supports an array of strings
+// Path also supports a readonly array of strings
 const getNameWithPathArray = (apiResponse: ApiResponse) =>
-	get(apiResponse, ['hits','hits', '0', '_source', 'name']);
+	get(apiResponse, ['hits','hits', '0', '_source', 'name'] as const);
 	//=> Array<{given: string[]; family: string}>
 
 // Strict mode:
@@ -175,5 +175,5 @@ Get<Record<string, string>, 'foo', {strict: true}> // => string | undefined
 @category Array
 @category Template literal
 */
-export type Get<BaseType, Path extends string | string[], Options extends GetOptions = {}> =
+export type Get<BaseType, Path extends string | readonly string[], Options extends GetOptions = {}> =
 	GetWithPath<BaseType, Path extends string ? ToPath<Path> : Path, Options>;

package/source/invariant-of.d.ts

@@ -0,0 +1,72 @@
+import {Opaque} from './opaque';
+
+/**
+Create an [invariant type](https://basarat.gitbook.io/typescript/type-system/type-compatibility#footnote-invariance), which is a type that does not accept supertypes and subtypes.
+
+Use-case:
+- Prevent runtime errors that may occur due to assigning subtypes to supertypes.
+- Improve type signature of object methods like [`Object.keys()` or `Object.entries()`](https://github.com/microsoft/TypeScript/pull/12253#issuecomment-263132208) by sealing the object type.
+
+@example
+```
+class Animal {
+	constructor(public name: string){}
+}
+
+class Cat extends Animal {
+	meow() {}
+}
+
+let animalArray: Animal[] = [animal];
+let catArray: Cat[] = [cat];
+
+animalArray = catArray; // Okay if covariant
+animalArray.push(new Animal('another animal')); // Pushed an animal into catArray
+catArray.forEach(c => c.meow()); // Allowed but, error at runtime
+
+let invariantAnimalArray: InvariantOf<Animal>[] = [animal] as InvariantOf<Animal>[];
+let invariantCatArray: InvariantOf<Cat>[] = [cat] as InvariantOf<Cat>[];
+
+invariantAnimalArray = invariantCatArray; // Error: Type 'InvariantOf<Cat>[]' is not assignable to type 'InvariantOf<Animal>[]'.
+```
+
+@example
+```
+// In covariance (default)
+
+interface FooBar {
+	foo: number;
+	bar: string
+}
+
+interface FooBarBaz extends FooBar {
+	baz: boolean
+}
+
+declare const fooBar: FooBar
+declare const fooBarBaz: FooBarBaz
+
+function keyOfFooBar(fooBar: FooBar) {
+	return Object.keys(fooBar) as (keyof FooBar)[]
+}
+
+keyOfFooBar(fooBar) //=> (keyof FooBar)[]
+keyOfFooBar(fooBarBaz) //=> (keyof FooBar)[] but, (keyof FooBarBaz)[] at runtime
+
+// In invariance
+
+export function invariantOf<Type>(value: Type): InvariantOf<Type> {
+	return value as InvariantOf<Type>;
+}
+
+function keyOfInvariantFooBar(fooBar: InvariantOf<FooBar>) {
+	return Object.keys(fooBar) as (keyof FooBar)[]
+}
+
+keyOfInvariantFooBar(invariantOf(fooBar)); // (keyof FooBar)[]
+keyOfInvariantFooBar(invariantOf(fooBarBaz)); // Error: Argument of type 'InvariantOf<FooBarBaz>' is not assignable to parameter of type 'InvariantOf<FooBar>'.
+```
+
+@category Type
+*/
+export type InvariantOf<Type> = Opaque<Type, (argument: Type) => Type>;

package/source/package-json.d.ts

@@ -214,6 +214,7 @@ declare namespace PackageJson {
 		| 'import'
 		| 'require'
 		| 'node'
+		| 'node-addons'
 		| 'deno'
 		| 'browser'
 		| 'electron'
@@ -231,6 +232,13 @@ declare namespace PackageJson {
 	| {[key in ExportCondition]: Exports}
 	| {[key: string]: Exports}; // eslint-disable-line @typescript-eslint/consistent-indexed-object-style
 
+	/**
+	Import map entries of a module, optionally with conditions.
+	*/
+	export type Imports = { // eslint-disable-line @typescript-eslint/consistent-indexed-object-style
+		[key: string]: string | {[key in ExportCondition]: Exports};
+	};
+
 	export interface NonStandardEntryPoints {
 		/**
 		An ECMAScript module ID that is the primary entry point to the program.
@@ -415,12 +423,19 @@ declare namespace PackageJson {
 		main?: string;
 
 		/**
-		Standard entry points of the package, with enhanced support for ECMAScript Modules.
+		Subpath exports to define entry points of the package.
 
-		[Read more.](https://nodejs.org/api/esm.html#esm_package_entry_points)
+		[Read more.](https://nodejs.org/api/packages.html#subpath-exports)
 		*/
 		exports?: Exports;
 
+		/**
+		Subpath imports to define internal package import maps that only apply to import specifiers from within the package itself.
+
+		[Read more.](https://nodejs.org/api/packages.html#subpath-imports)
+		*/
+		imports?: Imports;
+
 		/**
 		The executable files that should be installed into the `PATH`.
 		*/

package/source/readonly-deep.d.ts

@@ -34,11 +34,17 @@ data.foo.push('bar');
 @category Set
 @category Map
 */
-export type ReadonlyDeep<T> = T extends BuiltIns | ((...arguments: any[]) => unknown)
+export type ReadonlyDeep<T> = T extends BuiltIns
 	? T
-	: T extends ReadonlyMap<infer KeyType, infer ValueType>
+	: T extends (...arguments: any[]) => unknown
+	? {} extends ReadonlyObjectDeep<T>
+		? T
+		: HasMultipleCallSignatures<T> extends true
+		? T
+		: ((...arguments: Parameters<T>) => ReturnType<T>) & ReadonlyObjectDeep<T>
+	: T extends Readonly<ReadonlyMap<infer KeyType, infer ValueType>>
 	? ReadonlyMapDeep<KeyType, ValueType>
-	: T extends ReadonlySet<infer ItemType>
+	: T extends Readonly<ReadonlySet<infer ItemType>>
 	? ReadonlySetDeep<ItemType>
 	: T extends object
 	? ReadonlyObjectDeep<T>
@@ -48,13 +54,13 @@ export type ReadonlyDeep<T> = T extends BuiltIns | ((...arguments: any[]) => unk
 Same as `ReadonlyDeep`, but accepts only `ReadonlyMap`s as inputs. Internal helper for `ReadonlyDeep`.
 */
 interface ReadonlyMapDeep<KeyType, ValueType>
-	extends ReadonlyMap<ReadonlyDeep<KeyType>, ReadonlyDeep<ValueType>> {}
+	extends Readonly<ReadonlyMap<ReadonlyDeep<KeyType>, ReadonlyDeep<ValueType>>> {}
 
 /**
 Same as `ReadonlyDeep`, but accepts only `ReadonlySet`s as inputs. Internal helper for `ReadonlyDeep`.
 */
 interface ReadonlySetDeep<ItemType>
-	extends ReadonlySet<ReadonlyDeep<ItemType>> {}
+	extends Readonly<ReadonlySet<ReadonlyDeep<ItemType>>> {}
 
 /**
 Same as `ReadonlyDeep`, but accepts only `object`s as inputs. Internal helper for `ReadonlyDeep`.
@@ -62,3 +68,18 @@ Same as `ReadonlyDeep`, but accepts only `object`s as inputs. Internal helper fo
 type ReadonlyObjectDeep<ObjectType extends object> = {
 	readonly [KeyType in keyof ObjectType]: ReadonlyDeep<ObjectType[KeyType]>
 };
+
+/**
+Test if the given function has multiple call signatures.
+
+Needed to handle the case of a single call signature with properties.
+
+Multiple call signatures cannot currently be supported due to a TypeScript limitation.
+@see https://github.com/microsoft/TypeScript/issues/29732
+*/
+type HasMultipleCallSignatures<T extends (...arguments: any[]) => unknown> =
+	T extends {(...arguments: infer A): unknown; (...arguments: any[]): unknown}
+		? unknown[] extends A
+			? false
+			: true
+		: false;

package/source/schema.d.ts

@@ -0,0 +1,72 @@
+/**
+Create a deep version of another object type where property values are recursively replaced into a given value type.
+
+Use-cases:
+- Form validation: Define how each field should be validated.
+- Form settings: Define configuration for input fields.
+- Parsing: Define types that specify special behavior for specific fields.
+
+@example
+```
+import {Schema} from 'type-fest';
+
+interface User {
+	id: string;
+	name: {
+		firstname: string;
+		lastname: string;
+	};
+	created: Date;
+	active: boolean;
+	passwordHash: string;
+}
+
+type UserMask = Schema<User, 'mask' | 'hide' | 'show'>;
+
+const userMaskSettings: UserMask = {
+	id: 'show',
+	name: {
+		firstname: 'show',
+		lastname: 'mask',
+	},
+	phoneNumbers: 'mask',
+	created: 'show',
+	active: 'show',
+	passwordHash: 'hide',
+}
+```
+
+@category Object
+*/
+export type Schema<ObjectType, ValueType> = ObjectType extends string
+	? ValueType
+	: ObjectType extends Map<unknown, unknown>
+	? ValueType
+	: ObjectType extends Set<unknown>
+	? ValueType
+	: ObjectType extends ReadonlyMap<unknown, unknown>
+	? ValueType
+	: ObjectType extends ReadonlySet<unknown>
+	? ValueType
+	: ObjectType extends readonly unknown[]
+	? ValueType
+	: ObjectType extends unknown[]
+	? ValueType
+	: ObjectType extends (...arguments: unknown[]) => unknown
+	? ValueType
+	: ObjectType extends Date
+	? ValueType
+	: ObjectType extends Function
+	? ValueType
+	: ObjectType extends RegExp
+	? ValueType
+	: ObjectType extends object
+	? SchemaObject<ObjectType, ValueType>
+	: ValueType;
+
+/**
+Same as `Schema`, but accepts only `object`s as inputs. Internal helper for `Schema`.
+*/
+type SchemaObject<ObjectType extends object, K> = {
+	[KeyType in keyof ObjectType]: Schema<ObjectType[KeyType], K> | K;
+};