@jsonhero/json-infer-types
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.10 • Public • Published

    🤔 JSON Infer Types

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

    Coverage lines Tests Downloads Install size

    🚀 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("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

    String Variant
    "example+suffix@example.com" rfc5321
    "example@127.0.0.1" rfc5321
    "foo@example.accountants" rfc5321
    "Example Name <example@example.com>" rfc5322
    "Example S. Name <example.s.name@example.com>" 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

    Install

    npm i @jsonhero/json-infer-types

    DownloadsWeekly Downloads

    271

    Version

    1.2.10

    License

    MIT

    Unpacked Size

    93.1 kB

    Total Files

    29

    Last publish

    Collaborators

    • ericallam
    • mattaitken