type-fest - npm Package Compare versions

Comparing version 4.10.3 to 4.11.0

index.d.ts

@@ -29,2 +29,3 @@ // Basic
 export type {PickDeep} from './source/pick-deep';
+export type {OmitDeep} from './source/omit-deep';
 export type {PartialOnUndefinedDeep, PartialOnUndefinedDeepOptions} from './source/partial-on-undefined-deep';
@@ -35,3 +36,3 @@ export type {UndefinedOnPartialDeep} from './source/undefined-on-partial-deep';
 export type {Promisable} from './source/promisable';
-export type {Opaque, UnwrapOpaque, Tagged, UnwrapTagged} from './source/opaque';
+export type {Opaque, UnwrapOpaque, Tagged, GetTagMetadata, UnwrapTagged} from './source/opaque';
 export type {InvariantOf} from './source/invariant-of';
@@ -108,2 +109,3 @@ export type {SetOptional} from './source/set-optional';
 export type {ArrayValues} from './source/array-values';
+export type {ArraySplice} from './source/array-splice';
 export type {SetFieldType} from './source/set-field-type';
@@ -110,0 +112,0 @@ export type {Paths} from './source/paths';

package.json

 {
 	"name": "type-fest",
-	"version": "4.10.3",
+	"version": "4.11.0",
 	"description": "A collection of essential TypeScript types",
@@ -5,0 +5,0 @@ "license": "(MIT OR CC0-1.0)",

readme.md

@@ -130,2 +130,3 @@ <div align="center">
 - [`PickDeep`](source/pick-deep.d.ts) - Pick properties from a deeply-nested object. Use [`Pick<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#picktype-keys) if you only need one level deep.
+- [`OmitDeep`](source/omit-deep.d.ts) - Omit properties from a deeply-nested object. Use [`Omit<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys) if you only need one level deep.
 - [`OmitIndexSignature`](source/omit-index-signature.d.ts) - Omit any index signatures from the given object type, leaving only explicitly defined properties.
@@ -181,2 +182,3 @@ - [`PickIndexSignature`](source/pick-index-signature.d.ts) - Pick only index signatures from the given object type, leaving out all explicitly defined properties.
 - [`ArrayValues`](source/array-values.d.ts) - Provides all values for a constant array or tuple.
+- [`ArraySplice`](source/array-splice.d.ts) - Creates a new array type by adding or removing elements at a specified index range in the original array.
 - [`SetFieldType`](source/set-field-type.d.ts) - Create a type that changes the type of the given keys.
@@ -183,0 +185,0 @@ - [`Paths`](source/paths.d.ts) - Generate a union of all possible paths to properties in the given object.

source/internal.d.ts

@@ -9,2 +9,3 @@ import type {Primitive} from './primitive';
 import type {UnknownArray} from './unknown-array';
+import type {IsEqual} from './is-equal';
 
@@ -481,1 +482,100 @@ // TODO: Remove for v5.
 	: never; // Should never happen
+
+/**
+Set the given array to readonly if `IsReadonly` is `true`, otherwise set the given array to normal, then return the result.
+
+@example
+```
+type ReadonlyArray = readonly string[];
+type NormalArray = string[];
+
+type ReadonlyResult = SetArrayAccess<NormalArray, true>;
+//=> readonly string[]
+
+type NormalResult = SetArrayAccess<ReadonlyArray, false>;
+//=> string[]
+```
+*/
+export type SetArrayAccess<T extends UnknownArray, IsReadonly extends boolean> =
+T extends readonly [...infer U] ?
+	IsReadonly extends true
+		? readonly [...U]
+		: [...U]
+	: T;
+
+/**
+Returns whether the given array `T` is readonly.
+*/
+export type IsArrayReadonly<T extends UnknownArray> = T extends unknown[] ? false : true;
+
+/**
+Returns the result of `A >= B`.
+
+@example
+```
+type A = GTE<15, 10>;
+//=> true
+
+type B = GTE<10, 15>;
+//=> false
+
+type C = GTE<10, 10>;
+//=> true
+```
+*/
+export type GTE<A extends number, B extends number> =
+	BuildTuple<A> extends [...infer _, ...BuildTuple<B>]
+		? true
+		: false;
+
+/**
+Returns the result of `A > B`
+
+@example
+```
+type A = GT<15, 10>;
+//=> true
+
+type B = GT<10, 15>;
+//=> false
+*/
+export type GT<A extends number, B extends number> =
+	IsEqual<A, B> extends true
+		? false
+		: GTE<A, B>;
+
+/**
+Get the exact version of the given `Key` in the given object `T`.
+
+Use-case: You known that a number key (e.g. 10) is in an object, but you don't know how it is defined in the object, as a string or as a number (e.g. 10 or '10'). You can use this type to get the exact version of the key. See the example.
+
+@example
+```
+type Object = {
+	0: number;
+	'1': string;
+};
+
+type Key1 = ExactKey<Object, '0'>;
+//=> 0
+type Key2 = ExactKey<Object, 0>;
+//=> 0
+
+type Key3 = ExactKey<Object, '1'>;
+//=> '1'
+type Key4 = ExactKey<Object, 1>;
+//=> '1'
+```
+
+@category Object
+*/
+export type ExactKey<T extends object, Key extends PropertyKey> =
+Key extends keyof T
+	? Key
+	: ToString<Key> extends keyof T
+		? ToString<Key>
+		: Key extends `${infer NumberKey extends number}`
+			? NumberKey extends keyof T
+				? NumberKey
+				: never
+			: never;

source/opaque.d.ts

@@ -7,5 +7,3 @@ declare const tag: unique symbol;
 
-type MultiTagContainer<Token extends PropertyKey> = {
-	readonly [tag]: {[K in Token]: void};
-};
+type Tag<Token extends PropertyKey, TagMetadata> = TagContainer<{[K in Token]: TagMetadata}>;
 
@@ -117,3 +115,3 @@ /**
 export type UnwrapOpaque<OpaqueType extends TagContainer<unknown>> =
-	OpaqueType extends MultiTagContainer<string | number | symbol>
+	OpaqueType extends Tag<PropertyKey, any>
 		? RemoveAllTags<OpaqueType>
@@ -125,3 +123,3 @@ : OpaqueType extends Opaque<infer Type, OpaqueType[typeof tag]>
 /**
-Attach a "tag" to an arbitrary type. This allows you to create distinct types, that aren't assignable to one another, for runtime values that would otherwise have the same type. (See examples.)
+Attach a "tag" to an arbitrary type. This allows you to create distinct types, that aren't assignable to one another, for distinct concepts in your program that should not be interchangeable, even if their runtime values have the same type. (See examples.)
 
@@ -132,2 +130,9 @@ A type returned by `Tagged` can be passed to `Tagged` again, to create a type with multiple tags.
 
+A tag's name is usually a string (and must be a string, number, or symbol), but each application of a tag can also contain an arbitrary type as its "metadata". See {@link GetTagMetadata} for examples and explanation.
+
+A type `A` returned by `Tagged` is assignable to another type `B` returned by `Tagged` if and only if:
+  - the underlying (untagged) type of `A` is assignable to the underlying type of `B`;
+	- `A` contains at least all the tags `B` has;
+	- and the metadata type for each of `A`'s tags is assignable to the metadata type of `B`'s corresponding tag.
+
 There have been several discussions about adding similar features to TypeScript. Unfortunately, nothing has (yet) moved forward:
@@ -158,18 +163,59 @@ - [Microsoft/TypeScript#202](https://github.com/microsoft/TypeScript/issues/202)
 // But this won't, because it has to be explicitly passed as an `AccountNumber` type!
+// Critically, you could not accidentally use an `AccountBalance` as an `AccountNumber`.
 getMoneyForAccount(2);
 
-// You can use opaque values like they aren't opaque too.
-const accountNumber = createAccountNumber();
+// You can also use tagged values like their underlying, untagged type.
+// I.e., this will compile successfully because an `AccountNumber` can be used as a regular `number`.
+// In this sense, the underlying base type is not hidden, which differentiates tagged types from opaque types in other languages.
+const accountNumber = createAccountNumber() + 2;
+```
 
-// This will compile successfully.
-const newAccountNumber = accountNumber + 2;
+@example
 ```
+import type {Tagged} from 'type-fest';
 
+// You can apply multiple tags to a type by using `Tagged` repeatedly.
+type Url = Tagged<string, 'URL'>;
+type SpecialCacheKey = Tagged<Url, 'SpecialCacheKey'>;
+
+// You can also pass a union of tag names, so this is equivalent to the above, although it doesn't give you the ability to assign distinct metadata to each tag.
+type SpecialCacheKey2 = Tagged<string, 'URL' | 'SpecialCacheKey'>;
+```
+
 @category Type
 */
-export type Tagged<Type, Tag extends PropertyKey> = Type & MultiTagContainer<Tag>;
+export type Tagged<Type, TagName extends PropertyKey, TagMetadata = never> = Type & Tag<TagName, TagMetadata>;
 
 /**
-Revert a tagged type back to its original type by removing the readonly `[tag]`.
+Given a type and a tag name, returns the metadata associated with that tag on that type.
 
+In the example below, one could use `Tagged<string, 'JSON'>` to represent "a string that is valid JSON". That type might be useful -- for instance, it communicates that the value can be safely passed to `JSON.parse` without it throwing an exception. However, it doesn't indicate what type of value will be produced on parse (which is sometimes known). `JsonOf<T>` solves this; it represents "a string that is valid JSON and that, if parsed, would produce a value of type T". The type T is held in the metadata associated with the `'JSON'` tag.
+
+This article explains more about [how tag metadata works and when it can be useful](https://medium.com/@ethanresnick/advanced-typescript-tagged-types-improved-with-type-level-metadata-5072fc125fcf).
+
+@example
+```
+import type {Tagged} from 'type-fest';
+
+type JsonOf<T> = Tagged<string, 'JSON', T>;
+
+function stringify<T>(it: T) {
+  return JSON.stringify(it) as JsonOf<T>;
+}
+
+function parse<T extends JsonOf<unknown>>(it: T) {
+  return JSON.parse(it) as GetTagMetadata<T, 'JSON'>;
+}
+
+const x = stringify({ hello: 'world' });
+const parsed = parse(x); // The type of `parsed` is { hello: string }
+```
+
+@category Type
+*/
+export type GetTagMetadata<Type extends Tag<TagName, unknown>, TagName extends PropertyKey> = Type[typeof tag][TagName];
+
+/**
+Revert a tagged type back to its original type by removing all tags.
+
 Why is this necessary?
@@ -200,12 +246,11 @@
 */
-export type UnwrapTagged<TaggedType extends MultiTagContainer<PropertyKey>> =
+export type UnwrapTagged<TaggedType extends Tag<PropertyKey, any>> =
 RemoveAllTags<TaggedType>;
 
-type RemoveAllTags<T> = T extends MultiTagContainer<infer ExistingTags>
+type RemoveAllTags<T> = T extends Tag<PropertyKey, any>
 	? {
-		[ThisTag in ExistingTags]:
-		T extends Tagged<infer Type, ThisTag>
+		[ThisTag in keyof T[typeof tag]]: T extends Tagged<infer Type, ThisTag, T[typeof tag][ThisTag]>
 			? RemoveAllTags<Type>
 			: never
-	}[ExistingTags]
+	}[keyof T[typeof tag]]
 	: T;

source/shared-union-fields-deep.d.ts

@@ -1,2 +0,2 @@
-import type {NonRecursiveType, UnionMin, UnionMax, TupleLength, StaticPartOfArray, VariablePartOfArray, IsUnion} from './internal';
+import type {NonRecursiveType, UnionMin, UnionMax, TupleLength, StaticPartOfArray, VariablePartOfArray, IsUnion, IsArrayReadonly, SetArrayAccess} from './internal';
 import type {IsNever} from './is-never';
@@ -6,29 +6,2 @@ import type {UnknownArray} from './unknown-array';
 /**
-Set the given array to readonly if `IsReadonly` is `true`, otherwise set the given array to normal, then return the result.
-
-@example
-```
-type ReadonlyArray = readonly string[];
-type NormalArray = string[];
-
-type ReadonlyResult = SetArrayAccess<NormalArray, true>;
-//=> readonly string[]
-
-type NormalResult = SetArrayAccess<ReadonlyArray, false>;
-//=> string[]
-```
-*/
-type SetArrayAccess<T extends UnknownArray, IsReadonly extends boolean> =
-	T extends readonly [...infer U] ?
-		IsReadonly extends true
-			? readonly [...U]
-			: [...U]
-		: T;
-
-/**
-Returns whether the given array `T` is readonly.
-*/
-type IsArrayReadonly<T extends UnknownArray> = T extends unknown[] ? false : true;
-
-/**
 SharedUnionFieldsDeep options.
@@ -35,0 +8,0 @@

No alert changes

Improved metrics

Total package byte prevSize

331495

increased by3.46%

Number of package files

123

increased by1.65%

Lines of code

7826

increased by3.94%

Number of lines in readme file

959

increased by0.21%

No dependency changes