🤔 JSON Infer Types

Infer the types of JSON documents & values, with a large set of formats for strings

• 🚀 Features
• 💻 Usage
  • Strings
• String Formats
  • Date/Time strings
  • URI strings
  • Email address strings
  • JWT Strings
  • Credit Card Numbers
  • Other formats
• Object Formats
  • Firestore Timestamps

🚀 Features

• Written in typescript
• Narrows type of the value when using with Typescript
• Lightweight with only a few third-party dependencies
• Includes a large set of formats for strings
  • Dates and times (and timestamps)
  • URIs
  • Email addresses
  • Currencies
  • Countries
  • Top-Level Domains
  • IP Addresses
  • Languages
  • Phone Numbers
  • UUIDs
  • Hostnames
  • File sizes
  • Stringified JSON

💻 Usage

Install JSON Infer Types

$ npm install --save @jsonhero/json-infer-types

inferType takes any JSON value and returns a JSONValueType object:

const { inferType } = require("@jsonhero/json-infer-types");

inferType(123); // => { name: "int", value: 123 }

The following types are supported:

inferType(null); // => { name: "null", value: null }
inferType(undefined); // => { name: "null", value: null }
inferType(true); // => { name: "bool", value: true }
inferType(123); // => { name: "int", value: 123 }
inferType(123.456); // => { name: "float", value: 123.456 }
inferType("hello world"); // => { name: "string", value: "hello world" }
inferType({ foo: "bar" }); // => { name: "object", value: { foo: "bar" } }
inferType([1, 2, 3]); // => { name: "array", value: [1, 2, 3] }

Strings

JSON Infer Types will also recognize certain string formats and include that information in the result, for example if the string is a URI:

inferType("https://www.example.com/foo#bar");

Will be

{
  "name": "string",
  "value": "https://www.example.com/foo#bar",
  "format": {
    "name": "uri"
  }
}

Some formats have mutliple variants, like IP Address. inferType("192.168.0.1") will be interpreted as an IPV4 address

{
  "name": "string",
  "value": "192.168.0.1",
  "format": {
    "name": "ip",
    "variant": "v4"
  }
}

And inferType("2001:db8:1234::1") will be interpreted as an IPV6 address

{
  "name": "string",
  "value": "2001:db8:1234::1",
  "format": {
    "name": "ip",
    "variant": "v6"
  }
}

String Formats

Date/Time strings

JSON Infer Types supports rfc3339/iso8601 and rfc2822 string formats

inferType("2019-01-01 00:00:00.000Z");

Will result in

{
  "name": "string",
  "value": "2019-01-01 00:00:00.000Z",
  "format": {
    "name": "datetime",
    "parts": "datetime",
    "variant": "rfc3339"
  }
}

The parts field can be either datetime, date or time, depending on the contents of the string.

The following table illustrates the results of different Date/Time strings

Timezone and Calendar extensions for rfc3339 date/times are also detected:

inferType("2022-02-28T11:06:00.092121729+08:00[Asia/Shanghai][u-ca=chinese]");

Will result in

{
  "name": "string",
  "value": "2022-02-28T11:06:00.092121729+08:00[Asia/Shanghai][u-ca=chinese]",
  "format": {
    "name": "datetime",
    "parts": "datetime",
    "variant": "rfc3339",
    "extensions": ["timezone", "calendar"]
  }
}

This is useful for knowing when you can use Temporal.ZonedDateTime in the new Temporal ECMAScript proposal:

const inferredType = inferType("2022-02-28T11:06:00.092121729+08:00[Asia/Shanghai][u-ca=chinese]");

if (
  inferredType.name === "string" &&
  inferredType.format.name === "datetime" &&
  inferredType.format.variant === "rfc3339" &&
  inferredType.format.extensions.includes("timezone")
) {
  const zonedDateTime = Temporal.ZonedDateTime.from(inferredType.value);
  // Temporal.ZonedDateTime <2022-02-28T11:06:00.092121729+08:00[Asia/Shanghai][u-ca=chinese]>
}

JSON Infer Types also supports unix epoch timestamps

inferType("1596597629980");

Will result in

{
  "name": "string",
  "value": "1596597629980",
  "format": {
    "name": "timestamp",
    "variant": "millisecondsSinceEpoch"
  }
}

Also supported are seconds and nanoseconds since epoch timestamp strings

URI strings

JSON Infer Types will interpret certain strings to be URIs

inferType("https://www.example.com/foo#bar");

Will result in

{
  "name": "string",
  "value": "https://www.example.com/foo#bar",
  "format": {
    "name": "uri"
  }
}

If the URI contains a file extension, the inferred contentType will be included in the result. For example inferType("https://www.example.com/foo.json") will result in

{
  "name": "string",
  "value": "https://www.example.com/foo.json",
  "format": {
    "name": "uri",
    "contentType": "application/json"
  }
}

The mapping of file extension to contentType is done using the mime-types package

Email address strings

JSON Infer Types supports rfc5321 and rfc5321 style email address strings:

inferType("eallam@example.com");

Will result in

{
  "name": "string",
  "value": "eallam@example.com",
  "format": {
    "name": "email",
    "variant": "rfc5321"
  }
}

The following table illustrates the results of different email strings

JWT Strings

Strings that contain JWT tokens will have the jwt format

inferType(
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.sruoLZNJ59anK67z25t80L62OXDerSiAhWerW-usZLQ",
);

Will result in

{
  "name": "string",
  "value": "...",
  "format": {
    "name": "jwt"
  }
}

Credit Card Numbers

Strings that contain valid credit card numbers will be inferred with the creditcard format:

inferType("4485428259658366");

Will result in

{
  "name": "string",
  "value": "4485428259658366",
  "format": {
    "name": "creditcard",
    "variant": "visa"
  }
}

The following table illustrates the results of different credit card number strings

Other formats

The following table illustrates the rest of the formats JSON Infer Types supports

Object Formats

We also infer the format of certain common object shapes, documented below:

Firestore Timestamps

Firestore Timestamps are an object with two keys, _seconds and _nanoseconds:

{
  "_seconds": 1642533020,
  "_nanoseconds": 932000000
}

Inferring this object will result in the following inferred type:

{
  "name": "object",
  "value": {
    "_seconds": 1642533020,
    "_nanoseconds": 932000000
  },
  "format": {
    "name": "firestoreTimestamp"
  }
}

Please feel free to request additional formats by opening a Github issue