type-fest 2.10.0 → 2.11.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.11.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/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;
+};