feat: 🚀 Add JsonValue utility type

README.md

@@ -37,6 +37,11 @@ npm install --save-dev ts-essentials
 ### Basic
 
 - [`Builtin`](/lib/built-in) - Matches primitive, function, date, error or regular expression
+- [`JsonArray`](/lib/json-primitive) - Matches any [JSON array](https://www.rfc-editor.org/rfc/rfc8259#section-3)
+- [`JsonObject`](/lib/json-object) - Matches any [JSON object](https://www.rfc-editor.org/rfc/rfc8259#section-3)
+- [`JsonPrimitive`](/lib/json-primitive) - Matches any
+  [JSON primitive value](https://www.rfc-editor.org/rfc/rfc8259#section-3)
+- [`JsonValue`](/lib/json-value) - Matches any [JSON value](https://www.rfc-editor.org/rfc/rfc8259#section-3)
 - [`KeyofBase`](/lib/key-of-base) -
   [`keyofStringsOnly`](https://www.typescriptlang.org/tsconfig#keyofStringsOnly)-tolerant analogue for `PropertyKey`
 - [`Prettify<Type>`](/lib/prettify/) - flattens type and makes it more readable on the hover in your IDE

lib/index.ts

@@ -1,8 +1,12 @@
 // Basic
 
-export * from "./primitive";
 export * from "./built-in";
+export * from "./json-array";
+export * from "./json-object";
+export * from "./json-primitive";
+export * from "./json-value";
 export * from "./key-of-base";
+export * from "./primitive";
 export * from "./strict-exclude";
 export * from "./strict-extract";
 export * from "./strict-omit";

lib/json-array/README.md

@@ -0,0 +1,16 @@
+Matches any [JSON array](https://www.rfc-editor.org/rfc/rfc8259#section-3)
+
+```ts
+let jsonArray: JsonArray;
+
+jsonArray = [{ numberProperty: 1 }];
+jsonArray = [{ stringProperty: "1" }];
+jsonArray = [{ booleanProperty: true }];
+// @ts-expect-error: Type 'symbol' is not assignable to type `JsonValue | JsonPrimitive`
+jsonArray = [{ symbolProperty: Symbol.iterator }];
+jsonArray = [{ nullProperty: null }];
+// @ts-expect-error: Type 'undefined' is not assignable to type `JsonValue`
+jsonArray = [{ undefinedProperty: undefined }];
+```
+
+TS Playground - https://tsplay.dev/N5dVPw

lib/json-array/index.ts

@@ -0,0 +1,3 @@
+import { JsonValue } from "../json-value";
+
+export type JsonArray = JsonValue[];

lib/json-object/README.md

@@ -0,0 +1,30 @@
+Matches any [JSON object](https://www.rfc-editor.org/rfc/rfc8259#section-3)
+
+```ts
+let jsonObject: JsonObject;
+
+jsonObject = { numberProperty: 1 };
+jsonObject = { stringProperty: "1" };
+jsonObject = { booleanProperty: true };
+// @ts-expect-error: Type 'symbol' is not assignable to type `JsonValue | JsonPrimitive`
+jsonObject = { symbolProperty: Symbol.iterator };
+jsonObject = { nullProperty: null };
+// @ts-expect-error: Type 'undefined' is not assignable to type `JsonValue | JsonPrimitive`
+jsonObject = { undefinedProperty: undefined };
+```
+
+It accepts optional properties, such as `pets?: string[];`:
+
+```ts
+type Person = {
+  name: string;
+  age: number;
+  pets?: string[];
+};
+
+declare const person: Person;
+
+jsonObject = person;
+```
+
+TS Playground - https://tsplay.dev/mZKV1W

lib/json-object/index.ts

@@ -0,0 +1,8 @@
+import { JsonValue } from "../json-value";
+
+export type JsonObject = {
+  [Key in string]: JsonValue;
+} & {
+  // optional (non-undefined) properties are acceptable
+  [Key in string]?: JsonValue;
+};

lib/json-primitive/README.md

@@ -0,0 +1,16 @@
+Matches any [JSON primitive value](https://www.rfc-editor.org/rfc/rfc8259#section-3)
+
+```ts
+let primitive: JsonPrimitive;
+
+primitive = 1;
+primitive = "1";
+primitive = true;
+// Type 'unique symbol' is not assignable to type 'JsonPrimitive'
+primitive = Symbol.iterator;
+primitive = null;
+// Type 'undefined' is not assignable to type 'JsonPrimitive'
+primitive = undefined;
+```
+
+TS Playground - https://tsplay.dev/WP2ReN

lib/json-primitive/index.ts

@@ -0,0 +1 @@
+export type JsonPrimitive = false | null | number | string | true;

lib/json-value/README.md

@@ -0,0 +1,36 @@
+Matches any [JSON value](https://www.rfc-editor.org/rfc/rfc8259#section-3)
+
+```ts
+let jsonValue: JsonValue;
+
+// primitive
+
+jsonValue = 1;
+jsonValue = "1";
+jsonValue = true;
+jsonValue = null;
+
+// object
+
+jsonValue = { numberProperty: 1 };
+jsonValue = { stringProperty: "1" };
+jsonValue = { booleanProperty: true };
+// @ts-expect-error: Type 'symbol' is not assignable to type `JsonValue | JsonPrimitive`
+jsonValue = { symbolProperty: Symbol.iterator };
+jsonValue = { nullProperty: null };
+// @ts-expect-error: Type 'undefined' is not assignable to type `JsonValue | JsonPrimitive`
+jsonValue = { undefinedProperty: undefined };
+
+// array
+
+jsonValue = [{ numberProperty: 1 }];
+jsonValue = [{ stringProperty: "1" }];
+jsonValue = [{ booleanProperty: true }];
+// @ts-expect-error: Type 'symbol' is not assignable to type `JsonValue | JsonPrimitive`
+jsonValue = [{ symbolProperty: Symbol.iterator }];
+jsonValue = [{ nullProperty: null }];
+// @ts-expect-error: Type 'undefined' is not assignable to type `JsonValue`
+jsonValue = [{ undefinedProperty: undefined }];
+```
+
+TS Playground - https://tsplay.dev/ND0ARN

lib/json-value/index.ts

@@ -0,0 +1,5 @@
+import { JsonArray } from "../json-array";
+import { JsonObject } from "../json-object";
+import { JsonPrimitive } from "../json-primitive";
+
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;