type-fest 4.20.0 → 4.21.0

package/index.d.ts

@@ -64,6 +64,7 @@ export type {Simplify} from './source/simplify';
 export type {SimplifyDeep} from './source/simplify-deep';
 export type {Jsonify} from './source/jsonify';
 export type {Jsonifiable} from './source/jsonifiable';
+export type {StructuredCloneable} from './source/structured-cloneable';
 export type {Schema} from './source/schema';
 export type {LiteralToPrimitive} from './source/literal-to-primitive';
 export type {LiteralToPrimitiveDeep} from './source/literal-to-primitive-deep';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "4.20.0",
+	"version": "4.21.0",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -42,11 +42,12 @@
 		"expect-type": "^0.19.0",
 		"npm-run-all2": "^6.1.2",
 		"tsd": "^0.31.0",
-		"typescript": "~5.4.5",
+		"typescript": "~5.5.3",
 		"xo": "^0.58.0"
 	},
 	"xo": {
 		"rules": {
+			"@typescript-eslint/no-extraneous-class": "off",
 			"@typescript-eslint/ban-ts-comment": "off",
 			"@typescript-eslint/ban-types": "off",
 			"@typescript-eslint/naming-convention": "off",

package/readme.md

@@ -167,7 +167,7 @@ Click the type names for complete docs.
 - [`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.
 - [`LiteralToPrimitiveDeep`](source/literal-to-primitive-deep.d.ts) - Like `LiteralToPrimitive` except it converts literal types inside an object or array deeply.
 - [`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.
+- [`IterableElement`](source/iterable-element.d.ts) - Get the element type of an `Iterable`/`AsyncIterable`. For example, `Array`, `Set`, `Map`, generator, stream, etc.
 - [`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.
@@ -249,6 +249,10 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 - [`JsonArray`](source/basic.d.ts) - Matches a JSON array.
 - [`JsonValue`](source/basic.d.ts) - Matches any valid JSON value.
 
+### Structured clone
+
+- [`StructuredCloneable`](source/structured-cloneable.d.ts) - Matches a value that can be losslessly cloned using `structuredClone`.
+
 ### Async
 
 - [`Promisable`](source/promisable.d.ts) - Create a type that represents either the value or the value wrapped in `PromiseLike`.
@@ -348,6 +352,9 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 - `AllKeys` - See [`KeysOfUnion`](source/keys-of-union.d.ts)
 - `Branded` - See [`Tagged`](source/opaque.d.ts)
 - `Opaque` - See [`Tagged`](source/opaque.d.ts)
+- `SetElement` - See [`IterableElement`](source/iterable-element.d.ts)
+- `SetEntry` - See [`IterableElement`](source/iterable-element.d.ts)
+- `SetValues` - See [`IterableElement`](source/iterable-element.d.ts)
 
 ## Tips
 

package/source/camel-cased-properties-deep.d.ts

@@ -1,4 +1,5 @@
 import type {CamelCase, CamelCaseOptions} from './camel-case';
+import type {NonRecursiveType} from './internal';
 import type {UnknownArray} from './unknown-array';
 
 /**
@@ -48,7 +49,7 @@ const result: CamelCasedPropertiesDeep<UserWithFriends> = {
 export type CamelCasedPropertiesDeep<
 	Value,
 	Options extends CamelCaseOptions = {preserveConsecutiveUppercase: true},
-> = Value extends Function
+> = Value extends NonRecursiveType
 	? Value
 	: Value extends UnknownArray
 		? CamelCasedPropertiesArrayDeep<Value>

package/source/exact.d.ts

@@ -1,7 +1,7 @@
 import type {ArrayElement, ObjectValue} from './internal';
-import type {Opaque, TagContainer} from './opaque';
 import type {IsEqual} from './is-equal';
 import type {KeysOfUnion} from './keys-of-union';
+import type {JsonObject} from './basic';
 
 /**
 Create a type from `ParameterType` and `InputType` and change keys exclusive to `InputType` to `never`.
@@ -57,7 +57,6 @@ export type Exact<ParameterType, InputType> =
 		: ParameterType extends unknown[] ? Array<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
 			// In TypeScript, Array is a subtype of ReadonlyArray, so always test Array before ReadonlyArray.
 			: ParameterType extends readonly unknown[] ? ReadonlyArray<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
-				// Leave tagged types as-is. We could try to make the untagged part Exact, and just leave the tag as-is, but that seems to create instanitation excessively deep errors.
-				: ParameterType extends TagContainer<unknown> ? ParameterType
-					: ParameterType extends object ? ExactObject<ParameterType, InputType>
-						: ParameterType;
+				// Only apply Exact for pure object types. For types from a class, leave it unchanged to TypeScript to handle.
+				: ParameterType extends JsonObject ? ExactObject<ParameterType, InputType>
+					: ParameterType;

package/source/int-range.d.ts

@@ -8,7 +8,7 @@ The numbers are created from the given `Start` (inclusive) parameter to the give
 
 You skip over numbers using the `Step` parameter (defaults to `1`). For example, `IntRange<0, 10, 2>` will create a union of `0 | 2 | 4 | 6 | 8`.
 
-Note: `Start` or `End` must smaller than `1000`.
+Note: `Start` or `End` must be non-negative and smaller than `1000`.
 
 Use-cases:
 1. This can be used to define a set of valid input/output values. for example:

package/source/iterable-element.d.ts

@@ -1,5 +1,5 @@
 /**
-Get the element type of an `Iterable`/`AsyncIterable`. For example, an array or a generator.
+Get the element type of an `Iterable`/`AsyncIterable`. For example, `Array`, `Set`, `Map`, generator, stream, etc.
 
 This can be useful, for example, if you want to get the type that is yielded in a generator function. Often the return type of those functions are not specified.
 
@@ -33,7 +33,7 @@ async function * iAmGeneratorAsync() {
 type MeStringOrBoolean = IterableElement<ReturnType<typeof iAmGeneratorAsync>>
 ```
 
-Many types in JavaScript/TypeScript are iterables. This type works on all types that implement those interfaces. For example, `Array`, `Set`, `Map`, `stream.Readable`, etc.
+Many types in JavaScript/TypeScript are iterables. This type works on all types that implement those interfaces.
 
 An example with an array of strings:
 
@@ -44,6 +44,16 @@ import type {IterableElement} from 'type-fest';
 type MeString = IterableElement<string[]>
 ```
 
+@example
+```
+import type {IterableElement} from 'type-fest';
+
+const fruits = new Set(['🍎', '🍌', '🍉'] as const);
+
+type Fruit = IterableElement<typeof fruits>;
+//=> '🍎' | '🍌' | '🍉'
+```
+
 @category Iterable
 */
 export type IterableElement<TargetIterable> =

package/source/jsonify.d.ts

@@ -12,6 +12,7 @@ import type {UnknownArray} from './unknown-array';
 type NotJsonable = ((...arguments_: any[]) => any) | undefined | symbol;
 
 type NeverToNull<T> = IsNever<T> extends true ? null : T;
+type UndefinedToNull<T> = T extends undefined ? null : T;
 
 // Handles tuples and arrays
 type JsonifyList<T extends UnknownArray> = T extends readonly []
@@ -20,7 +21,7 @@ type JsonifyList<T extends UnknownArray> = T extends readonly []
 		? [NeverToNull<Jsonify<F>>, ...JsonifyList<R>]
 		: IsUnknown<T[number]> extends true
 			? []
-			: Array<T[number] extends NotJsonable ? null : Jsonify<T[number]>>;
+			: Array<T[number] extends NotJsonable ? null : Jsonify<UndefinedToNull<T[number]>>>;
 
 type FilterJsonableKeys<T extends object> = {
 	[Key in keyof T]: T[Key] extends NotJsonable ? never : Key;

package/source/paths.d.ts

@@ -3,6 +3,8 @@ import type {EmptyObject} from './empty-object';
 import type {IsAny} from './is-any';
 import type {IsNever} from './is-never';
 import type {UnknownArray} from './unknown-array';
+import type {Sum} from './sum';
+import type {LessThan} from './less-than';
 
 /**
 Generate a union of all possible paths to properties in the given object.
@@ -45,7 +47,9 @@ open('listB.1'); // TypeError. Because listB only has one element.
 @category Object
 @category Array
 */
-export type Paths<T> =
+export type Paths<T> = Paths_<T>;
+
+type Paths_<T, Depth extends number = 0> =
 	T extends NonRecursiveType | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown>
 		? never
 		: IsAny<T> extends true
@@ -53,14 +57,14 @@ export type Paths<T> =
 			: T extends UnknownArray
 				? number extends T['length']
 					// We need to handle the fixed and non-fixed index part of the array separately.
-					? InternalPaths<StaticPartOfArray<T>>
-					| InternalPaths<Array<VariablePartOfArray<T>[number]>>
-					: InternalPaths<T>
+					? InternalPaths<StaticPartOfArray<T>, Depth>
+					| InternalPaths<Array<VariablePartOfArray<T>[number]>, Depth>
+					: InternalPaths<T, Depth>
 				: T extends object
-					? InternalPaths<T>
+					? InternalPaths<T, Depth>
 					: never;
 
-export type InternalPaths<_T, T = Required<_T>> =
+export type InternalPaths<_T, Depth extends number = 0, T = Required<_T>> =
 	T extends EmptyObject | readonly []
 		? never
 		: {
@@ -71,8 +75,10 @@ export type InternalPaths<_T, T = Required<_T>> =
 				| Key
 				| ToString<Key>
 				| (
-					IsNever<Paths<T[Key]>> extends false
-						? `${Key}.${Paths<T[Key]>}`
+					LessThan<Depth, 15> extends true // Limit the depth to prevent infinite recursion
+						? IsNever<Paths_<T[Key], Sum<Depth, 1>>> extends false
+							? `${Key}.${Paths_<T[Key], Sum<Depth, 1>>}`
+							: never
 						: never
 				)
 				: never

package/source/schema.d.ts

@@ -47,25 +47,25 @@ export type Schema<ObjectType, ValueType> = ObjectType extends string
 				? ValueType
 				: ObjectType extends ReadonlySet<unknown>
 					? ValueType
-					: ObjectType extends readonly unknown[]
-						? ValueType
-						: ObjectType extends unknown[]
+					: ObjectType extends Array<infer U>
+						? Array<Schema<U, ValueType>>
+						: ObjectType extends (...arguments_: unknown[]) => unknown
 							? ValueType
-							: ObjectType extends (...arguments_: unknown[]) => unknown
+							: ObjectType extends Date
 								? ValueType
-								: ObjectType extends Date
+								: ObjectType extends Function
 									? ValueType
-									: ObjectType extends Function
+									: ObjectType extends RegExp
 										? ValueType
-										: ObjectType extends RegExp
-											? ValueType
-											: ObjectType extends object
-												? SchemaObject<ObjectType, ValueType>
-												: 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;
+	[KeyType in keyof ObjectType]: ObjectType[KeyType] extends readonly unknown[] | unknown[]
+		? Schema<ObjectType[KeyType], K>
+		: Schema<ObjectType[KeyType], K> | K;
 };

package/source/structured-cloneable.d.ts

@@ -0,0 +1,89 @@
+import type {TypedArray} from './typed-array';
+
+type StructuredCloneablePrimitive =
+	| string
+	| number
+	| bigint
+	| boolean
+	| null
+	| undefined
+	| Boolean
+	| Number
+	| String;
+
+type StructuredCloneableData =
+	| ArrayBuffer
+	| DataView
+	| Date
+	| Error
+	| RegExp
+	| TypedArray
+	| Blob
+	| File;
+// DOM exclusive types
+//	| AudioData
+//	| CropTarget
+//	| CryptoKey
+//	| DOMException
+//	| DOMMatrix
+//	| DOMMatrixReadOnly
+//	| DOMPoint
+//	| DOMPointReadOnly
+//	| DOMQuad
+//	| DOMRect
+//	| DOMRectReadOnly
+//	| FileList
+//	| FileSystemDirectoryHandle
+//	| FileSystemFileHandle
+//	| FileSystemHandle
+//	| GPUCompilationInfo
+//	| GPUCompilationMessage
+//	| ImageBitmap
+//	| ImageData
+//	| RTCCertificate
+//	| VideoFrame
+
+type StructuredCloneableCollection =
+	| readonly StructuredCloneable[]
+	| {readonly [key: string]: StructuredCloneable; readonly [key: number]: StructuredCloneable}
+	| ReadonlyMap<StructuredCloneable, StructuredCloneable>
+	| ReadonlySet<StructuredCloneable>;
+
+/**
+Matches a value that can be losslessly cloned using `structuredClone`.
+
+Note:
+- Custom error types will be cloned as the base `Error` type
+- This type doesn't include types exclusive to the TypeScript DOM library (e.g. `DOMRect` and `VideoFrame`)
+
+@see https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
+
+@example
+```
+import type {StructuredCloneable} from 'type-fest';
+
+class CustomClass {}
+
+// @ts-expect-error
+const error: StructuredCloneable = {
+    custom: new CustomClass(),
+};
+
+structuredClone(error);
+//=> {custom: {}}
+
+const good: StructuredCloneable = {
+    number: 3,
+    date: new Date(),
+    map: new Map<string, number>(),
+}
+
+good.map.set('key', 1);
+
+structuredClone(good);
+//=> {number: 3, date: Date(2022-10-17 22:22:35.920), map: Map {'key' -> 1}}
+```
+
+@category Structured clone
+*/
+export type StructuredCloneable = StructuredCloneablePrimitive | StructuredCloneableData | StructuredCloneableCollection;