sascha10000 / json-infer-types

Infers the type and format of JSON values

🤔 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
"[phone]", "[phone]"	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