types-json

Type checking for JSON values.

---

This package uses zod to type check JSON values.

It includes type guards for each of the JSON types, as well as parse functions and corresponding types.

Installation

npm install types-json

yarn add types-json

pnpm add types-json

bun add types-json

Contents

• Installation
• Usage
  • JSONValue
  • JSONObject
  • JSONArray
  • JSONPrimitive
  • JSONOrderable
  • String
  • Number
  • Boolean
  • Null
  • Undefined

Usage

JSONValue

When using isJSONValue, values which cannot be parsed or serialized properly using JSON.parse and JSON.stringify return false.

Similarly, when using parseJSONValue, invalid values return undefined.

Finally, a zod schema provided representing the JSONValue type.

import { isJSONValue, parseJSONValue, jsonValueSchema } from "types-json";

isJSONValue(undefined); // false
isJSONValue(null); // true
isJSONValue(NaN); // false
isJSONValue(Infinity); // false
isJSONValue([1, 2, 3]); // true
isJSONValue([1, 2, () => 3]); // false

Optional types are also provided:

import { isOptionalJSONValue, parseOptionalJSONValue, optionalJSONValueSchema } from "types-json";

isOptionalJSONValue(undefined); // true
isOptionalJSONValue({ a: 1, b: undefined }); // true

JSONObject

JSONObject is a type guard and parse function for objects which can be parsed and serialized using JSON.parse and JSON.stringify.

import {
  isJSONObject,
  parseJSONObject,
  jsonObjectSchema
} from "types-json";

isJSONObject({ foo: "bar" }); // true
isJSONObject({ foo: () => "bar" }); // false
parseJSONObject({ foo: "bar" }); // true
parseJSONObject({ foo: () => "bar" }); // undefined

Optional types are also provided. OptionalJSONObject includes undefined, while NestedOptionalJSONObject only allows for undefined values nested within the object:

import {
  isOptionalJSONObject,
  parseOptionalJSONObject,
  optionalJSONObjectSchema,
  isNestedOptionalJSONObject,
  parseNestedOptionalJSONObject,
  nestedOptionalJSONObjectSchema
} from "types-json";

isOptionalJSONObject(undefined); // true
isOptionalJSONObject({ a: 1, b: undefined }); // true

isNestedOptionalJSONObject(undefined); // false
isNestedOptionalJSONObject({ a: 1, b: undefined }); // true

JSONArray

import {
  isJSONArray,
  parseJSONArray,
  jsonArraySchema,
} from "types-json";

isJSONArray([1]); // true
isJSONArray([1, () => 2]); // false
parseJSONArray([1]); // []
parseJSONArray([1, () => 2]); // undefined

Optional types are also provided. OptionalJSONArray includes undefined, while NestedOptionalJSONArray only allows for undefined values nested within objects inside the array. Note that undefined values nested within arrays are not allowed, as they are not valid JSON:

import {
  isOptionalJSONArray,
  parseOptionalJSONArray,
  optionalJSONArraySchema,
  isNestedOptionalJSONArray,
  parseNestedOptionalJSONArray,
  nestedOptionalJSONArraySchema
} from "types-json";

isOptionalJSONArray(undefined); // true
isOptionalJSONArray([1, undefined]); // false
isOptionalJSONArray([1, { a: 1, b: undefined }]); // true

isNestedOptionalJSONArray(undefined); // false
isNestedOptionalJSONArray([1, undefined]); // false
isNestedOptionalJSONArray([1, { a: 1, b: undefined }]); // true

JSONPrimitive

import {
  isJSONPrimitive,
  parseJSONPrimitive,
  jsonPrimitiveSchema
} from "types-json";

isJSONPrimitive("foo"); // true
isJSONPrimitive(1); // true
isJSONPrimitive(true); // true
isJSONPrimitive(null); // true
isJSONPrimitive(undefined); // false
isJSONPrimitive({}); // false

Optional types are also provided:

import {
  isOptionalJSONPrimitive,
  optionalJSONPrimitiveSchema
} from "types-json";

isOptionalJSONPrimitive("foo"); // true
isOptionalJSONPrimitive(1); // true
isOptionalJSONPrimitive(true); // true
isOptionalJSONPrimitive(null); // true
isOptionalJSONPrimitive(undefined); // true
isOptionalJSONPrimitive({}); // false

JSONOrderable

JSONOrderable is a type for values which can be reasonably compared using operators such as >, <, >=, and <=:

import {
  isJSONOrderable,
  parseJSONOrderable,
  jsonOrderableSchema
} from "types-json";

isJSONOrderable("foo"); // true
isJSONOrderable(1); // true
isJSONOrderable(true); // false
isJSONOrderable(null); // false
isJSONOrderable(undefined); // false
isJSONOrderable({}); // false
isJSONOrderable([]); // false

Optional types are also provided:

import {
  isOptionalJSONOrderable,
  optionalJSONOrderableSchema
} from "types-json";

isOptionalJSONOrderable("foo"); // true
isOptionalJSONOrderable(1); // true
isOptionalJSONOrderable(true); // false
isOptionalJSONOrderable(null); // false
isOptionalJSONOrderable(undefined); // true
isOptionalJSONOrderable({}); // false
isOptionalJSONOrderable([]); // false

String

import {
  isString,
  parseString,
  stringSchema
} from "types-json";

isString("foo"); // true
isString(1); // undefined
parseString("foo"); // "foo"
parseString(1); // undefined

Optional types are also provided:

import {
  isOptionalString,
  optionalStringSchema
} from "types-json";

isOptionalString("foo"); // true
isOptionalString(undefined); // true

Number

import {
  isNumber,
  parseNumber,
  numberSchema
} from "types-json";

isNumber(1); // true
isNumber("1"); // undefined
parseNumber(1); // true
parseNumber("1"); // undefined

Optional types are also provided:

import {
  isOptionalNumber,
  optionalNumberSchema
} from "types-json";

isOptionalNumber(1); // true
isOptionalNumber(undefined); // true

Boolean

import {
  isBoolean,
  parseBoolean,
  booleanSchema
} from "types-json";

isBoolean(true); // true
isBoolean("true"); // undefined
parseBoolean(true); // true
parseBoolean("true"); // undefined

Optional types are also provided:

import {
  isOptionalBoolean,
  optionalBooleanSchema
} from "types-json";

isOptionalBoolean(true); // true
isOptionalBoolean(undefined); // true

Null

import {
  isNull,
  parseNull,
  nullSchema
};

isNull(null); // true
isNull("not null"); // undefined
parseNull(null); // null
parseNull("not null"); // undefined

Optional types are also provided:

import {
  isOptionalNull,
  optionalNullSchema
} from "types-json";

isOptionalNull(null); // true
isOptionalNull(undefined); // true

Undefined

Finally, an isUndefined type guard is provided:

import { isUndefined } from "types-json";

isUndefined(undefined); // true
isUndefined("string"); // false

Related Packages

• types-pkg-json: Type checking for package.json
• types-tsconfig: Type checking for tsconfig.json
• types-eslintrc: Type checking for .eslintrc.json

Dependencies

• is-zod: Typeguard to check if a value matches a zod schema
• zod: TypeScript-first schema declaration and validation library with static type inference

License

MIT - MIT License