type-fest 4.28.0 → 4.29.0

package/index.d.ts

@@ -66,7 +66,7 @@ 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 {Schema, SchemaOptions} from './source/schema';
 export type {LiteralToPrimitive} from './source/literal-to-primitive';
 export type {LiteralToPrimitiveDeep} from './source/literal-to-primitive-deep';
 export type {
@@ -106,6 +106,7 @@ export type {IsFloat} from './source/is-float';
 export type {TupleToUnion} from './source/tuple-to-union';
 export type {UnionToTuple} from './source/union-to-tuple';
 export type {IntRange} from './source/int-range';
+export type {IntClosedRange} from './source/int-closed-range';
 export type {IsEqual} from './source/is-equal';
 export type {
 	IsLiteral,

package/package.json

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

package/readme.md

@@ -192,6 +192,8 @@ Click the type names for complete docs.
 - [`Spread`](source/spread.d.ts) - Mimic the type inferred by TypeScript when merging two objects or two arrays/tuples using the spread syntax.
 - [`IsEqual`](source/is-equal.d.ts) - Returns a boolean for whether the two given types are equal.
 - [`TaggedUnion`](source/tagged-union.d.ts) - Create a union of types that share a common discriminant property.
+- [`IntRange`](source/int-range.d.ts) - Generate a union of numbers (includes the start and excludes the end).
+- [`IntClosedRange`](source/int-closed-range.d.ts) - Generate a union of numbers (includes the start and the end).
 - [`IntRange`](source/int-range.d.ts) - Generate a union of numbers.
 - [`ArrayIndices`](source/array-indices.d.ts) - Provides valid indices for a constant array or tuple.
 - [`ArrayValues`](source/array-values.d.ts) - Provides all values for a constant array or tuple.

package/source/int-closed-range.d.ts

@@ -0,0 +1,35 @@
+import type {IntRange} from './int-range';
+import type {Sum} from './sum';
+
+/**
+Generate a union of numbers.
+
+The numbers are created from the given `Start` (inclusive) parameter to the given `End` (inclusive) parameter.
+
+You skip over numbers using the `Step` parameter (defaults to `1`). For example, `IntClosedRange<0, 10, 2>` will create a union of `0 | 2 | 4 | 6 | 8 | 10`.
+
+Note: `Start` or `End` must be non-negative and smaller than `999`.
+
+Use-cases:
+1. This can be used to define a set of valid input/output values. for example:
+	```
+	type Age = IntClosedRange<0, 120>; //=> 0 | 1 | 2 | ... | 119 | 120
+	type FontSize = IntClosedRange<10, 20>; //=> 10 | 11 | ... | 19 | 20
+	type EvenNumber = IntClosedRange<0, 10, 2>; //=> 0 | 2 | 4 | 6 | 8 | 10
+	```
+2. This can be used to define random numbers in a range. For example, `type RandomNumber = IntClosedRange<0, 100>;`
+
+@example
+```
+import type {IntClosedRange} from 'type-fest';
+
+// Create union type `0 | 1 | ... | 9`
+type ZeroToNine = IntClosedRange<0, 9>;
+
+// Create union type `100 | 200 | 300 | ... | 900`
+type Hundreds = IntClosedRange<100, 900, 100>;
+```
+
+@see IntRange
+*/
+export type IntClosedRange<Start extends number, End extends number, Skip extends number = 1> = IntRange<Start, Sum<End, 1>, Skip>;

package/source/int-range.d.ts

@@ -29,6 +29,8 @@ type ZeroToNine = IntRange<0, 10>;
 // Create union type `100 | 200 | 300 | ... | 900`
 type Hundreds = IntRange<100, 901, 100>;
 ```
+
+@see IntClosedRange
 */
 export type IntRange<Start extends number, End extends number, Step extends number = 1> = PrivateIntRange<Start, End, Step>;
 

package/source/schema.d.ts

@@ -19,6 +19,7 @@ interface User {
 	created: Date;
 	active: boolean;
 	passwordHash: string;
+	attributes: ['Foo', 'Bar']
 }
 
 type UserMask = Schema<User, 'mask' | 'hide' | 'show'>;
@@ -32,12 +33,13 @@ const userMaskSettings: UserMask = {
 	created: 'show',
 	active: 'show',
 	passwordHash: 'hide',
+	attributes: ['mask', 'show']
 }
 ```
 
 @category Object
 */
-export type Schema<ObjectType, ValueType> = ObjectType extends string
+export type Schema<ObjectType, ValueType, Options extends SchemaOptions = {}> = ObjectType extends string
 	? ValueType
 	: ObjectType extends Map<unknown, unknown>
 		? ValueType
@@ -48,7 +50,9 @@ export type Schema<ObjectType, ValueType> = ObjectType extends string
 				: ObjectType extends ReadonlySet<unknown>
 					? ValueType
 					: ObjectType extends Array<infer U>
-						? Array<Schema<U, ValueType>>
+						? Options['recurseIntoArrays'] extends false | undefined
+							? ValueType
+							: Array<Schema<U, ValueType>>
 						: ObjectType extends (...arguments_: unknown[]) => unknown
 							? ValueType
 							: ObjectType extends Date
@@ -58,14 +62,53 @@ export type Schema<ObjectType, ValueType> = ObjectType extends string
 									: ObjectType extends RegExp
 										? ValueType
 										: ObjectType extends object
-											? SchemaObject<ObjectType, ValueType>
+											? SchemaObject<ObjectType, ValueType, Options>
 											: 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]: ObjectType[KeyType] extends readonly unknown[] | unknown[]
-		? Schema<ObjectType[KeyType], K>
-		: Schema<ObjectType[KeyType], K> | K;
+type SchemaObject<
+	ObjectType extends object,
+	K,
+	Options extends SchemaOptions,
+> = {
+	[KeyType in keyof ObjectType]: ObjectType[KeyType] extends
+	| readonly unknown[]
+	| unknown[]
+		? Options['recurseIntoArrays'] extends false | undefined
+			? K
+			: Schema<ObjectType[KeyType], K, Options>
+		: Schema<ObjectType[KeyType], K, Options> | K;
+};
+
+/**
+@see Schema
+*/
+export type SchemaOptions = {
+	/**
+	By default, this affects elements in array and tuple types. You can change this by passing `{recurseIntoArrays: false}` as the third type argument:
+	- If `recurseIntoArrays` is set to `true` (default), array elements will be recursively processed as well.
+	- If `recurseIntoArrays` is set to `false`, arrays will not be recursively processed, and the entire array will be replaced with the given value type.
+
+	@example
+	```
+	type UserMask = Schema<User, 'mask' | 'hide' | 'show', {recurseIntoArrays: false}>;
+
+	const userMaskSettings: UserMask = {
+		id: 'show',
+		name: {
+			firstname: 'show',
+			lastname: 'mask',
+		},
+		created: 'show',
+		active: 'show',
+		passwordHash: 'hide',
+		attributes: 'hide'
+	}
+	```
+
+	@default true
+	*/
+	readonly recurseIntoArrays?: boolean | undefined;
 };

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

@@ -98,13 +98,18 @@ export type SharedUnionFieldsDeep<Union, Options extends SharedUnionFieldsDeepOp
 Same as `SharedUnionFieldsDeep`, but accepts only `object`s and as inputs. Internal helper for `SharedUnionFieldsDeep`.
 */
 type SharedObjectUnionFieldsDeep<Union, Options extends SharedUnionFieldsDeepOptions> =
+	// `keyof Union` can extract the same key in union type, if there is no same key, return never.
 	keyof Union extends infer Keys
 		? IsNever<Keys> extends false
 			? {
 				[Key in keyof Union]:
 				Union[Key] extends NonRecursiveType
 					? Union[Key]
-					: SharedUnionFieldsDeep<Union[Key], Options>
+					// Remove `undefined` from the union to support optional
+					// fields, then recover `undefined` if union was already undefined.
+					: SharedUnionFieldsDeep<Exclude<Union[Key], undefined>, Options> | (
+						undefined extends Required<Union>[Key] ? undefined : never
+					)
 			}
 			: {}
 		: Union;