type-fest
Version:
A collection of essential TypeScript types
131 lines (110 loc) • 3.79 kB
TypeScript
import type {UnknownCollection} from './unknown-collection.d.ts';
import type {IsArrayOfUnknownLength} from './internal/index.d.ts';
import type {ApplyDefaultOptions} from './apply-default-options.d.ts';
import type {NonRecursiveType} from './internal/type.d.ts';
import type {IsNever} from './is-never.d.ts';
import type {UnknownArray} from './unknown-array.d.ts';
/**
@see {@link 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.
An optional flag uses the default strategy.
@example
```
import type {Schema} from 'type-fest';
type Participants = {
attendees: string[];
speakers: string[];
};
type ParticipantsWithMetadata = Schema<Participants, {id: number; name: string}, {recurseIntoArrays: true}>;
//=> {
// attendees: {
// id: number;
// name: string;
// }[];
// speakers: {
// id: number;
// name: string;
// }[];
// }
type ParticipantsCount = Schema<Participants, number, {recurseIntoArrays: false}>;
//=> {attendees: number; speakers: number}
```
@default true
*/
recurseIntoArrays?: boolean;
};
type DefaultSchemaOptions = {
recurseIntoArrays: true;
};
/**
Create a deep version of another object type where property values are recursively replaced with 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 type {Schema} from 'type-fest';
type User = {
id: string;
name: {
firstname: string;
lastname: string;
};
created: Date;
active: boolean;
passwordHash: string;
location: [latitude: number, longitude: number];
};
type UserMask = Schema<User, 'mask' | 'hide' | 'show'>;
const userMaskSettings: UserMask = {
id: 'show',
name: {
firstname: 'show',
lastname: 'mask',
},
created: 'show',
active: 'show',
passwordHash: 'hide',
location: ['hide', 'hide'],
};
```
@see {@link SchemaOptions}
@category Object
*/
export type Schema<Type, Value, Options extends SchemaOptions = {}> =
IsNever<Type> extends true
? Value
: _Schema<Type, Value, ApplyDefaultOptions<SchemaOptions, DefaultSchemaOptions, Options>>;
type _Schema<Type, Value, Options extends Required<SchemaOptions>> =
unknown extends Type
? Value
: Type extends NonRecursiveType | Exclude<UnknownCollection, UnknownArray>
? Value
: Type extends UnknownArray
? Options['recurseIntoArrays'] extends false
? Value
: IsArrayOfUnknownLength<Type> extends true
// Rebuild arrays directly so recursive element types stay lazy. Tuples keep their mapped shape and modifiers.
? Type extends unknown[]
? Array<_Schema<Type[number], Value, Options>>
: ReadonlyArray<_Schema<Type[number], Value, Options>>
: SchemaHelper<Type, Value, Options>
: SchemaHelper<Type, Value, Options>;
/**
Internal helper for {@link _Schema}.
Recursively transforms the value of each property in objects and arrays.
*/
type SchemaHelper<Type, Value, Options extends Required<SchemaOptions>> = {
// `_Schema` already handles broad inputs, so only each mapped property's optionality remains to check.
[Key in keyof Type]: _Schema<
Type extends Record<Key, Type[Key]> ? Type[Key] : Exclude<Type[Key], undefined>, // Remove `| undefined` when accessing optional properties
Value,
Options>
} & {};
export {};