🤔 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

| String | Variant | Parts | | ----------------------------------- | ------- | -------- | | "2019-01-01 00:00:00.000Z" | rfc3339 | datetime | | "2019-10-12T14:20:50.52+07:00" | rfc3339 | datetime | | "1983-10-14T13:30Z" | rfc3339 | datetime | | "2016-05-25" | rfc3339 | date | | "+002016-05-25" | rfc3339 | date | | "2016-W21-3" | rfc3339 | date | | "09:24:15.123Z" | rfc3339 | time | | "09:24:15.123Z" | rfc3339 | time | | "09:24:15" | rfc3339 | time | | "Mon, 02 Jan 2017 06:00:00 -0800" | rfc2822 | datetime | | "Mon, 02 Jan 2017 06:00:00 PST" | rfc2822 | datetime |

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("[email protected]");

Will result in

{
  "name": "string",
  "value": "[email protected]",
  "format": {
    "name": "email",
    "variant": "rfc5321"
  }
}

The following table illustrates the results of different email strings

| String | Variant | | ------------------------------------------------ | ------- | | "[email protected]" | rfc5321 | | "[email protected]" | rfc5321 | | "[email protected]" | rfc5321 | | "Example Name <[email protected]>" | rfc5322 | | "Example S. Name <[email protected]>" | rfc5322 |

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

| String | Variant | | ----------------------- | ---------- | | "4485 4282 5965 8366" | visa | | "4485428259658366" | visa | | "375092442988287" | amex | | "6011150635208157" | discover | | "5291160983813402" | mastercard | | "38223928053796" | dinersclub |

Other formats

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

| Example Strings | Name | Variant | | ---------------------------------------------------- | ----------- | --------- | | "USD", "BTC" | currency | iso4217 | | "United States dollar", "Euro" | currency | english | | "ETH", "LTC" | currency | crypto | | '$', '£', '€', '¥' | currency | symbol | | "USA", "MMR" | country | iso3166-3 | | "US", "GB", "JP" | country | iso3166-2 | | ".com", ".co.uk", ".biz" | tld | | | "192.168.0.1", "172.16.0.0" | ip | v4 | | "2001:db8:1234::1" | ip | v6 | | "en", "ab", "es" | language | iso693-1 | | "eng", "eus", "zul" | language | iso693-2 | | "Arabic", "Welsh", "Russian" | language | english | | "dansk", "Español" | language | native | | "+1 (684) 633-5115", "+49 30 83050" | phoneNumber | e.164 | | "4677658f-8865-47db-afb0-908e25246348" | uuid | v4 | | "cfa649f0-650b-11ec-acb3-03462fc79f5d" | uuid | v1 | | "bde4a7b9-5793-5a1f-b378-211205b15898" | uuid | v5 | | "foo.example.com", "localhost" | hostname | rfc1123 | | "exa_mple.com" | hostname | rfc5890 | | "544B", "1.0MB", "377K", "1.87GB" | filesize | human | | '{ "foo": 1 }' | json | ecma262 | | '{ foo: 1, }' | json | json5 | | "/foo/bar", "/foo/-/bar" | jsonPointer | rfc6901 | | "😄", "🤪👨🏽‍🚀", "👩‍👩‍👧‍👧" | emoji | | | "1.11.0", "0.0.1", "1.0.0-alpha.1" | semver | | | "#ff0000", "#D47DB9" | color | hex | | "rgb(255, 255, 255)", "rgb(255, 255, 255,.5)" | color | rgb | | "hsl(100, 100%, 50%)", "hsl(235, 100%, 50%, .5)" | color | hsl |

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