type-fest
Version:
A collection of essential TypeScript types
165 lines (119 loc) • 6.76 kB
TypeScript
import type {IsEqual} from './is-equal.d.ts';
import type {Jsonify} from './jsonify.d.ts'; // For `@link`
import type {JsonPrimitive} from './json-value.d.ts';
/**
Matches an object that can be losslessly converted to JSON.
Use it instead of `Jsonifiable` when a primitive is not allowed, for example for log fields, a request body, or a config file.
It matches the value you pass to `JSON.stringify`, not the JSON it produces. An object with a `toJSON` method, like `Date`, matches even when `toJSON` returns a primitive.
Note: An `interface` is not assignable. See {@link Jsonifiable} for how to fix it. A class instance is not assignable either, unless it has a `toJSON` method.
@example
```
import type {JsonifiableObject} from 'type-fest';
function log(message: string, fields: JsonifiableObject) {
console.log(JSON.stringify({message, fields}));
}
log('User signed in', {userId: 1, date: new Date()});
// @ts-expect-error
log('User signed in', 1);
// @ts-expect-error
log('User signed in', [1]);
```
@category JSON
*/
export type JsonifiableObject = {[Key in string]: Jsonifiable | undefined} | {toJSON: (...arguments_: any[]) => Jsonifiable};
/**
Matches an array that can be losslessly converted to JSON.
Use it instead of `Jsonifiable` when the value must be an array.
`undefined` is not allowed as an element, because `JSON.stringify([undefined])` is `[null]`.
@example
```
import type {JsonifiableArray} from 'type-fest';
function saveRows(rows: JsonifiableArray) {
console.log(JSON.stringify(rows));
}
saveRows([{id: 1, date: new Date()}, [1, 'a']]);
// @ts-expect-error
saveRows({id: 1});
// @ts-expect-error
saveRows([1, undefined]);
```
@category JSON
*/
export type JsonifiableArray = readonly Jsonifiable[];
/**
Matches a value that can be losslessly converted to JSON.
Can be used to type values that you expect to pass to `JSON.stringify`. Use `JsonifiableObject` or `JsonifiableArray` when a primitive is not allowed.
`undefined` is allowed in object fields (for example, `{a?: number}`) as a special case even though `JSON.stringify({a: undefined})` is `{}` because it makes this class more widely useful and checking for undefined-but-present values is likely an anti-pattern.
Note: An `interface` is not assignable to `Jsonifiable`, because TypeScript does not give an interface an implicit index signature (more properties can be merged into an interface later). This also applies to a nested interface. To fix it, do one of these:
- Use a `type` alias instead.
- Make the interface extend `JsonObject`. This only works if it has no `toJSON` values, like `Date`. Optional properties then need `exactOptionalPropertyTypes`.
- Make the interface extend `Record<string, Jsonifiable | undefined>`. This allows `toJSON` values and does not need `exactOptionalPropertyTypes`.
- Use `SimplifyDeep` to transform it: `value as SimplifyDeep<SomeInterface>`. `Simplify` is not enough for a nested interface.
For a generic function that must accept any JSON-able value, use {@link JsonifiableValue} as the parameter type.
@example
```
import type {Jsonifiable} from 'type-fest';
// @ts-expect-error
const error: Jsonifiable = {
map: new Map([['a', 1]]),
};
console.log(JSON.stringify(error)); // {"map": {}}
const good: Jsonifiable = {
number: 3,
date: new Date('2025-12-25'),
missing: undefined,
};
console.log(JSON.stringify(good)); // {"number": 3, "date": "2025-12-25T00:00:00.000Z"}
```
@category JSON
*/
export type Jsonifiable = JsonPrimitive | JsonifiableObject | JsonifiableArray;
/**
Validates that a function argument of type `Value` can be losslessly converted to JSON, including an `interface`.
{@link Jsonifiable} is a union that a value must be assignable to. An `interface` is not assignable, because it has no implicit index signature. `JsonifiableValue` takes the concrete type `Value`, keeps it, and checks its properties, so an interface works. It accepts everything `Jsonifiable` accepts, apart from a callable type without `toJSON`, and it also accepts interfaces and data-only class instances.
Use it as a parameter type, not as a constraint: `Value extends JsonifiableValue<Value>` is circular.
@example
```
import type {JsonifiableValue} from 'type-fest';
interface User {
name: string;
createdAt: Date;
}
function save<Value>(value: JsonifiableValue<Value>) {
return JSON.stringify(value);
}
const user: User = {name: 'Alice', createdAt: new Date()};
save(user);
// @ts-expect-error
save({name: 'Alice', tags: new Set()});
```
Unlike {@link Jsonify}, which models the `JSON.parse` result, this type models the `JSON.stringify` input. `Jsonify` rejects `Date` and required `string | undefined` properties; this type accepts them, like `Jsonifiable`.
Note: `undefined` is allowed only in object properties, and symbol keys are ignored. `any` and `{}` pass; `object` does not, because it can be a `Map`. A union member assignable to a valid member passes, even with non-JSON properties. Private fields are not checked (`private` fields are serialized, `#private` fields are not). A `toJSON` return must be assignable to `Jsonifiable`; an array with a non-JSON-able return is checked by its elements. The check recurses, so very deep types can hit the compiler's stack limit.
@category JSON
*/
export type JsonifiableValue<Value> = Value & JsonifiableValueCheck<Value>;
// `JSON.stringify` drops object properties that are `undefined`, so `Jsonifiable` allows them. Array elements are not properties, so they stay strict.
type JsonifiableValueObjectProperty<Value> = Value extends undefined ? undefined : JsonifiableValueCheck<Value>;
// `JSON.stringify` ignores symbol keys, so they are removed instead of checked.
type JsonifiableValueObject<ObjectType extends object> = {
[Key in keyof ObjectType as Key extends symbol ? never : Key]: JsonifiableValueObjectProperty<ObjectType[Key]>;
};
type JsonifiableValueCheck<Value> =
Value extends JsonPrimitive
? Value
// `JSON.stringify` calls `toJSON` on functions and arrays too, so this comes before both. An array whose `toJSON` result is not JSON-able falls through to the array branch, which checks only its elements, the same as `Jsonifiable`.
: Value extends {toJSON(...arguments_: any[]): Jsonifiable}
? Value
: Value extends Function
? never
: Value extends ReadonlyArray<infer Element>
? ReadonlyArray<JsonifiableValueCheck<Element>>
: Value extends object
? keyof Value extends never
// `object` has no keys, so the mapped copy would be `{}`, which every object matches. Reject the wide type, but keep `{}` and an empty interface.
? IsEqual<Value, object> extends true
? never
: {}
: JsonifiableValueObject<Value>
: never;
export {};