{"id":13990802,"url":"https://github.com/triggerdotdev/json-infer-types","last_synced_at":"2025-04-15T00:16:20.154Z","repository":{"id":38728661,"uuid":"440982916","full_name":"triggerdotdev/json-infer-types","owner":"triggerdotdev","description":"Infers the type and format of JSON values","archived":false,"fork":false,"pushed_at":"2024-02-06T00:28:14.000Z","size":322,"stargazers_count":30,"open_issues_count":8,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-15T00:15:59.468Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/triggerdotdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-22T20:59:03.000Z","updated_at":"2025-03-31T05:09:07.000Z","dependencies_parsed_at":"2024-06-18T18:35:08.880Z","dependency_job_id":"b9944854-55d3-4e20-a27a-039658441dde","html_url":"https://github.com/triggerdotdev/json-infer-types","commit_stats":null,"previous_names":["jsonhero-io/json-infer-types"],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triggerdotdev%2Fjson-infer-types","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triggerdotdev%2Fjson-infer-types/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triggerdotdev%2Fjson-infer-types/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triggerdotdev%2Fjson-infer-types/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/triggerdotdev","download_url":"https://codeload.github.com/triggerdotdev/json-infer-types/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248981268,"owners_count":21193147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2024-08-09T13:03:16.094Z","updated_at":"2025-04-15T00:16:20.138Z","avatar_url":"https://github.com/triggerdotdev.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# 🤔 JSON Infer Types\n\n\u003e Infer the types of JSON documents \u0026 values, with a large set of formats for strings\n\n![Coverage lines](./badges/badge-lines.svg)\n![Tests](https://github.com/jsonhero-io/json-infer-types/actions/workflows/test.yml/badge.svg?branch=main)\n[![Downloads](https://img.shields.io/npm/dm/%40jsonhero%2Fjson-infer-types.svg)](https://npmjs.com/@jsonhero/json-infer-types)\n[![Install size](https://packagephobia.com/badge?p=%40jsonhero%2Fjson-infer-types)](https://packagephobia.com/result?p=@jsonhero/json-infer-types)\n\n- [🚀 Features](#-features)\n- [💻 Usage](#-usage)\n  - [Strings](#strings)\n- [String Formats](#string-formats)\n  - [Date/Time strings](#datetime-strings)\n  - [URI strings](#uri-strings)\n  - [Email address strings](#email-address-strings)\n  - [JWT Strings](#jwt-strings)\n  - [Credit Card Numbers](#credit-card-numbers)\n  - [Other formats](#other-formats)\n- [Object Formats](#object-formats)\n  - [Firestore Timestamps](#firestore-timestamps)\n\n## 🚀 Features\n\n- Written in typescript\n- Narrows type of the value when using with Typescript\n- Lightweight with only a few third-party dependencies\n- Includes a large set of formats for strings\n  - Dates and times (and timestamps)\n  - URIs\n  - Email addresses\n  - Currencies\n  - Countries\n  - Top-Level Domains\n  - IP Addresses\n  - Languages\n  - Phone Numbers\n  - UUIDs\n  - Hostnames\n  - File sizes\n  - Stringified JSON\n\n## 💻 Usage\n\nInstall JSON Infer Types\n\n```bash\n$ npm install --save @jsonhero/json-infer-types\n```\n\n`inferType` takes any JSON value and returns a `JSONValueType` object:\n\n```js\nconst { inferType } = require(\"@jsonhero/json-infer-types\");\n\ninferType(123); // =\u003e { name: \"int\", value: 123 }\n```\n\nThe following types are supported:\n\n```js\ninferType(null); // =\u003e { name: \"null\", value: null }\ninferType(undefined); // =\u003e { name: \"null\", value: null }\ninferType(true); // =\u003e { name: \"bool\", value: true }\ninferType(123); // =\u003e { name: \"int\", value: 123 }\ninferType(123.456); // =\u003e { name: \"float\", value: 123.456 }\ninferType(\"hello world\"); // =\u003e { name: \"string\", value: \"hello world\" }\ninferType({ foo: \"bar\" }); // =\u003e { name: \"object\", value: { foo: \"bar\" } }\ninferType([1, 2, 3]); // =\u003e { name: \"array\", value: [1, 2, 3] }\n```\n\n### Strings\n\nJSON Infer Types will also recognize certain string formats and include that information in the result, for example if the string is a `URI`:\n\n```js\ninferType(\"https://www.example.com/foo#bar\");\n```\n\nWill be\n\n```json\n{\n  \"name\": \"string\",\n  \"value\": \"https://www.example.com/foo#bar\",\n  \"format\": {\n    \"name\": \"uri\"\n  }\n}\n```\n\nSome formats have mutliple variants, like IP Address. `inferType(\"192.168.0.1\")` will be interpreted as an IPV4 address\n\n```json\n{\n  \"name\": \"string\",\n  \"value\": \"192.168.0.1\",\n  \"format\": {\n    \"name\": \"ip\",\n    \"variant\": \"v4\"\n  }\n}\n```\n\nAnd `inferType(\"2001:db8:1234::1\")` will be interpreted as an IPV6 address\n\n```json\n{\n  \"name\": \"string\",\n  \"value\": \"2001:db8:1234::1\",\n  \"format\": {\n    \"name\": \"ip\",\n    \"variant\": \"v6\"\n  }\n}\n```\n\n## String Formats\n\n### Date/Time strings\n\nJSON Infer Types supports `rfc3339/iso8601` and `rfc2822` string formats\n\n```js\ninferType(\"2019-01-01 00:00:00.000Z\");\n```\n\nWill result in\n\n```json\n{\n  \"name\": \"string\",\n  \"value\": \"2019-01-01 00:00:00.000Z\",\n  \"format\": {\n    \"name\": \"datetime\",\n    \"parts\": \"datetime\",\n    \"variant\": \"rfc3339\"\n  }\n}\n```\n\nThe `parts` field can be either `datetime`, `date` or `time`, depending on the contents of the string.\n\nThe following table illustrates the results of different Date/Time strings\n\n| String                              | Variant | Parts    |\n| ----------------------------------- | ------- | -------- |\n| `\"2019-01-01 00:00:00.000Z\"`        | rfc3339 | datetime |\n| `\"2019-10-12T14:20:50.52+07:00\"`    | rfc3339 | datetime |\n| `\"1983-10-14T13:30Z\"`               | rfc3339 | datetime |\n| `\"2016-05-25\"`                      | rfc3339 | date     |\n| `\"+002016-05-25\"`                   | rfc3339 | date     |\n| `\"2016-W21-3\"`                      | rfc3339 | date     |\n| `\"09:24:15.123Z\"`                   | rfc3339 | time     |\n| `\"09:24:15.123Z\"`                   | rfc3339 | time     |\n| `\"09:24:15\"`                        | rfc3339 | time     |\n| `\"Mon, 02 Jan 2017 06:00:00 -0800\"` | rfc2822 | datetime |\n| `\"Mon, 02 Jan 2017 06:00:00 PST\"`   | rfc2822 | datetime |\n\nTimezone and Calendar extensions for rfc3339 date/times are also detected:\n\n```js\ninferType(\"2022-02-28T11:06:00.092121729+08:00[Asia/Shanghai][u-ca=chinese]\");\n```\n\nWill result in\n\n```json\n{\n  \"name\": \"string\",\n  \"value\": \"2022-02-28T11:06:00.092121729+08:00[Asia/Shanghai][u-ca=chinese]\",\n  \"format\": {\n    \"name\": \"datetime\",\n    \"parts\": \"datetime\",\n    \"variant\": \"rfc3339\",\n    \"extensions\": [\"timezone\", \"calendar\"]\n  }\n}\n```\n\nThis is useful for knowing when you can use `Temporal.ZonedDateTime` in the new [Temporal](https://tc39.es/proposal-temporal/docs/index.html) ECMAScript proposal:\n\n```js\nconst inferredType = inferType(\"2022-02-28T11:06:00.092121729+08:00[Asia/Shanghai][u-ca=chinese]\");\n\nif (\n  inferredType.name === \"string\" \u0026\u0026\n  inferredType.format.name === \"datetime\" \u0026\u0026\n  inferredType.format.variant === \"rfc3339\" \u0026\u0026\n  inferredType.format.extensions.includes(\"timezone\")\n) {\n  const zonedDateTime = Temporal.ZonedDateTime.from(inferredType.value);\n  // Temporal.ZonedDateTime \u003c2022-02-28T11:06:00.092121729+08:00[Asia/Shanghai][u-ca=chinese]\u003e\n}\n```\n\nJSON Infer Types also supports unix epoch timestamps\n\n```js\ninferType(\"1596597629980\");\n```\n\nWill result in\n\n```json\n{\n  \"name\": \"string\",\n  \"value\": \"1596597629980\",\n  \"format\": {\n    \"name\": \"timestamp\",\n    \"variant\": \"millisecondsSinceEpoch\"\n  }\n}\n```\n\nAlso supported are seconds and nanoseconds since epoch timestamp strings\n\n### URI strings\n\nJSON Infer Types will interpret certain strings to be URIs\n\n```js\ninferType(\"https://www.example.com/foo#bar\");\n```\n\nWill result in\n\n```json\n{\n  \"name\": \"string\",\n  \"value\": \"https://www.example.com/foo#bar\",\n  \"format\": {\n    \"name\": \"uri\"\n  }\n}\n```\n\nIf 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\n\n```json\n{\n  \"name\": \"string\",\n  \"value\": \"https://www.example.com/foo.json\",\n  \"format\": {\n    \"name\": \"uri\",\n    \"contentType\": \"application/json\"\n  }\n}\n```\n\nThe mapping of file extension to contentType is done using the [mime-types](https://github.com/jshttp/mime-types) package\n\n### Email address strings\n\nJSON Infer Types supports `rfc5321` and `rfc5321` style email address strings:\n\n```js\ninferType(\"eallam@example.com\");\n```\n\nWill result in\n\n```json\n{\n  \"name\": \"string\",\n  \"value\": \"eallam@example.com\",\n  \"format\": {\n    \"name\": \"email\",\n    \"variant\": \"rfc5321\"\n  }\n}\n```\n\nThe following table illustrates the results of different email strings\n\n| String                                           | Variant |\n| ------------------------------------------------ | ------- |\n| `\"example+suffix@example.com\"`                   | rfc5321 |\n| `\"example@127.0.0.1\"`                            | rfc5321 |\n| `\"foo@example.accountants\"`                      | rfc5321 |\n| `\"Example Name \u003cexample@example.com\u003e\"`           | rfc5322 |\n| `\"Example S. Name \u003cexample.s.name@example.com\u003e\"` | rfc5322 |\n\n### JWT Strings\n\nStrings that contain JWT tokens will have the `jwt` format\n\n```javascript\ninferType(\n  \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.sruoLZNJ59anK67z25t80L62OXDerSiAhWerW-usZLQ\",\n);\n```\n\nWill result in\n\n```json\n{\n  \"name\": \"string\",\n  \"value\": \"...\",\n  \"format\": {\n    \"name\": \"jwt\"\n  }\n}\n```\n\n### Credit Card Numbers\n\nStrings that contain valid credit card numbers will be inferred with the `creditcard` format:\n\n```javascript\ninferType(\"4485428259658366\");\n```\n\nWill result in\n\n```json\n{\n  \"name\": \"string\",\n  \"value\": \"4485428259658366\",\n  \"format\": {\n    \"name\": \"creditcard\",\n    \"variant\": \"visa\"\n  }\n}\n```\n\nThe following table illustrates the results of different credit card number strings\n\n| String                  | Variant    |\n| ----------------------- | ---------- |\n| `\"4485 4282 5965 8366\"` | visa       |\n| `\"4485428259658366\"`    | visa       |\n| `\"375092442988287\"`     | amex       |\n| `\"6011150635208157\"`    | discover   |\n| `\"5291160983813402\"`    | mastercard |\n| `\"38223928053796\"`      | dinersclub |\n\n### Other formats\n\nThe following table illustrates the rest of the formats JSON Infer Types supports\n\n| Example Strings                                      | Name        | Variant   |\n| ---------------------------------------------------- | ----------- | --------- |\n| `\"USD\"`, `\"BTC\"`                                     | currency    | iso4217   |\n| `\"United States dollar\"`, `\"Euro\"`                   | currency    | english   |\n| `\"ETH\"`, `\"LTC\"`                                     | currency    | crypto    |\n| `'$'`, `'£'`, `'€'`, `'¥'`                           | currency    | symbol    |\n| `\"USA\"`, `\"MMR\"`                                     | country     | iso3166-3 |\n| `\"US\"`, `\"GB\"`, `\"JP\"`                               | country     | iso3166-2 |\n| `\".com\"`, `\".co.uk\"`, `\".biz\"`                       | tld         |           |\n| `\"192.168.0.1\"`, `\"172.16.0.0\"`                      | ip          | v4        |\n| `\"2001:db8:1234::1\"`                                 | ip          | v6        |\n| `\"en\"`, `\"ab\"`, `\"es\"`                               | language    | iso693-1  |\n| `\"eng\"`, `\"eus\"`, `\"zul\"`                            | language    | iso693-2  |\n| `\"Arabic\"`, `\"Welsh\"`, `\"Russian\"`                   | language    | english   |\n| `\"dansk\"`, `\"Español\"`                               | language    | native    |\n| `\"+1 (684) 633-5115\"`, `\"+49 30 83050\"`              | phoneNumber | e.164     |\n| `\"4677658f-8865-47db-afb0-908e25246348\"`             | uuid        | v4        |\n| `\"cfa649f0-650b-11ec-acb3-03462fc79f5d\"`             | uuid        | v1        |\n| `\"bde4a7b9-5793-5a1f-b378-211205b15898\"`             | uuid        | v5        |\n| `\"foo.example.com\"`, `\"localhost\"`                   | hostname    | rfc1123   |\n| `\"exa_mple.com\"`                                     | hostname    | rfc5890   |\n| `\"544B\"`, `\"1.0MB\"`, `\"377K\"`, `\"1.87GB\"`            | filesize    | human     |\n| `'{ \"foo\": 1 }'`                                     | json        | ecma262   |\n| `'{ foo: 1, }'`                                      | json        | json5     |\n| `\"/foo/bar\"`, `\"/foo/-/bar\"`                         | jsonPointer | rfc6901   |\n| `\"😄\"`, `\"🤪👨🏽‍🚀\"`, `\"👩‍👩‍👧‍👧\"`                             | emoji       |           |\n| `\"1.11.0\"`, `\"0.0.1\"`, `\"1.0.0-alpha.1\"`             | semver      |           |\n| `\"#ff0000\"`, `\"#D47DB9\"`                             | color       | hex       |\n| `\"rgb(255, 255, 255)\"`, `\"rgb(255, 255, 255,.5)\"`    | color       | rgb       |\n| `\"hsl(100, 100%, 50%)\"`, `\"hsl(235, 100%, 50%, .5)\"` | color       | hsl       |\n\n## Object Formats\n\nWe also infer the format of certain common object shapes, documented below:\n\n### Firestore Timestamps\n\n[Firestore Timestamps](https://firebase.google.com/docs/reference/node/firebase.firestore.Timestamp) are an object with two keys, `_seconds` and `_nanoseconds`:\n\n```json\n{\n  \"_seconds\": 1642533020,\n  \"_nanoseconds\": 932000000\n}\n```\n\nInferring this object will result in the following inferred type:\n\n```json\n{\n  \"name\": \"object\",\n  \"value\": {\n    \"_seconds\": 1642533020,\n    \"_nanoseconds\": 932000000\n  },\n  \"format\": {\n    \"name\": \"firestoreTimestamp\"\n  }\n}\n```\n\nPlease feel free to request additional formats by opening a [Github issue](https://github.com/jsonhero-io/json-infer-types/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftriggerdotdev%2Fjson-infer-types","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftriggerdotdev%2Fjson-infer-types","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftriggerdotdev%2Fjson-infer-types/lists"}