{"id":13694298,"url":"https://github.com/ecoshub/jin","last_synced_at":"2026-04-09T19:03:13.833Z","repository":{"id":38385152,"uuid":"233809925","full_name":"ecoshub/jin","owner":"ecoshub","description":"Fastest JSON interpreter for GO","archived":false,"fork":false,"pushed_at":"2024-03-03T20:33:44.000Z","size":507,"stargazers_count":65,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-03T17:19:25.405Z","etag":null,"topics":["go-json","golang","gotools","interpreter","json","json-go","json-interpreter","json-parser","parser"],"latest_commit_sha":null,"homepage":"","language":"Go","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/ecoshub.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2020-01-14T09:55:33.000Z","updated_at":"2024-04-19T22:31:08.000Z","dependencies_parsed_at":"2024-06-18T22:46:08.634Z","dependency_job_id":"c5d1d6b8-2880-49a4-8bc7-1dc82ff7fc23","html_url":"https://github.com/ecoshub/jin","commit_stats":null,"previous_names":["ecoshub/jsoninterpreter","ecoshub/jint"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecoshub%2Fjin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecoshub%2Fjin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecoshub%2Fjin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecoshub%2Fjin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ecoshub","download_url":"https://codeload.github.com/ecoshub/jin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224346493,"owners_count":17296223,"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":["go-json","golang","gotools","interpreter","json","json-go","json-interpreter","json-parser","parser"],"created_at":"2024-08-02T17:01:28.892Z","updated_at":"2025-12-15T00:21:30.602Z","avatar_url":"https://github.com/ecoshub.png","language":"Go","funding_links":[],"categories":["开源类库","Open source library"],"sub_categories":["JSON"],"readme":"![CircleCI](https://circleci.com/gh/ecoshub/jin.svg?style=svg\u0026circle-token=90aab9c7cf8dddbca48f1079ffd514ca66ffd2ae)[![Go Report Card](https://goreportcard.com/badge/github.com/ecoshub/jin)](https://goreportcard.com/report/github.com/ecoshub/jin) ![License](https://img.shields.io/dub/l/vibe-d.svg) [![GoDoc](https://godoc.org/github.com/ecoshub/jin?status.svg)](https://godoc.org/github.com/ecoshub/jin)\n\n# Welcome To JIN\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"mascot.svg\" width=\"640\" height=\"640\"\u003e\n\u003c/p\u003e\n\n#### _\"Your wish is my command\"_\n\n## Fast and Easy Way to Deal With JSON\n\n**Jin** is a comprehensive JSON manipulation tool bundle.\nAll functions tested with random data with help of **Node.js**.\nAll test-path and test-value creation automated with **Node.js**.\n\n**Jin** provides `parse`, `interpret`, `build` and `format` tools for JSON.\nThird-party packages only used for the benchmark. No dependency need for core functions.\n\nWe make some benchmark with other packages like **Jin**.\n\n```\n    github.com/buger/jsonparser\n    github.com/valyala/fastjson\n    github.com/json-iterator/go\n    github.com/tidwall/gjson\n    github.com/tidwall/sjson\n```\n\nIn Result, **Jin** is the fastest (op/ns) and more memory friendly then others (B/op).\n\nFor more information please take a look at **BENCHMARK** section below.\n\n---\n\n### What is New?\n##### _08.10.2021_\n\n**Store** New! store function. store function can set or override a value like a real JSON object.\n\n##### _04.01.2021_\n\n**JO (JsonObject)** introduced!! Actually that is a fancy word for []byte type\n\nYou can use all interpreter functions with JO. just initialize and go.\n\n`Get()` Example\n\n```go\n\t// instead of repeating []byte for all functions.\n\t// initialize\n\tjsonObject := jin.New(json)\n\t// and go\n\tserial, err := jsonObject.GetString(\"info\", \"serial\")\n\tif err != nil {\n\t\treturn err\n\t}\n\tpooling, err := jsonObject.GetFloat(\"info\", \"polling_time\")\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t// old declaration\n\tserial, err := jin.GetString(json, \"info\", \"serial\")\n\tif err != nil {\n\t\treturn err\n\t}\n\tpooling, err := jin.GetFloat(json, \"info\", \"polling_time\")\n\tif err != nil {\n\t\treturn err\n\t}\n\n```\n\n`Set()` Example\n\n```go\n\t// instead of repeating []byte for all functions.\n\t// initialize\n\tjsonObject := jin.New(json)\n\t// and go\n\terr := jsonObject.SetString(\"at-28C02\", \"info\", \"serial\")\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t// old declaration\n\tjson, err := jin.SetString(json, \"at-28C02\", \"info\", \"serial\")\n\tif err != nil {\n\t\treturn err\n\t}\n\n```\n\n##### _06.04.2020_\n\n**7 new** functions **tested** and **added** to package. Examples in **[GoDoc](https://godoc.org/github.com/ecoshub/jin)**\n\n-   `GetMap()` get objects as `map[string]string` structure with key values pairs\n-   `GetAll()` get only specific keys values\n-   `GetAllMap()` get only specific keys with `map[string]string`structure\n-   `GetKeys()` get objects keys as string array\n-   `GetValues()` get objects values as string array\n-   `GetKeysValues()` get objects keys and values with separate string arrays\n-   `Length()` get length of JSON array.\n\n---\n\n### Installation\n\n```\n\tgo get github.com/ecoshub/jin\n```\n\nAnd you are good to go. Import and start using.\n\n---\n\n### Documentation\n\nThere is a detailed documentation in **[GoDoc](https://godoc.org/github.com/ecoshub/jin)** with lots of examples.\n\n---\n\n### QUICK START\n\n#### Parser vs Interpreter\n\nMajor difference between parsing and interpreting is\nparser has to read all data before answer your needs.\nOn the other hand interpreter reads up to find the data you need.\n\nWith parser, once the parse is complete you can access any data with no time.\nBut there is a time cost to parse all data and this cost can increase as data content grows.\n\nIf you need to access all keys of a JSON then, we are simply recommend you to use `Parser`.\nBut if you need to access some keys of a JSON then we strongly recommend you to use `Interpreter`, it will be much faster and much more memory-friendly than parser.\n\n#### Interpreter\n\n`Interpreter` is core element of this package, no need to create an Interpreter type, just call which function you want.\n\nFirst let's look at general function parameters.\n\n```go\n\n\t// All interpreter functions need one JSON as byte slice.\n\tjson := []byte(`{\"git\":\"ecoshub\",\"repo\":{\"id\":233809925,\"name\":[\"eco\",\"jin\"]}}`)\n\n\t// And most of them needs a path value for navigate.\n\t// Path value determines which part to navigate.\n\t// In this example we want to access 'jin' value.\n\t// So path must be 'repo' (object) -\u003e 'name' (array) -\u003e '1' (second element)\n\tpath := []string{\"repo\", \"name\", \"1\"}\n\n```\n\nWe are gonna use `Get()` function to access the value of path has pointed. In this case 'jin'.\n\n```go\n\n\tvalue, err := jin.Get(json, path...)\n\tif err != nil {\n\t\tlog.Println(err)\n\t\treturn\n\t}\n\t// the Get() functions return type is []byte\n\t// To understand its value,\n\t// first we have to convert it to string.\n\tfmt.Println(string(value))\n\t// Output: jin\n\n```\n\nPath value can consist hard coded values.\n\n```go\n\n\tvalue, err := jin.Get(json, \"repo\", \"name\", \"1\")\n\tif err != nil {\n\t\tlog.Println(err)\n\t\treturn\n\t}\n\n\tfmt.Println(string(value))\n\t//String Output: jin\n\n```\n\n`Get()` function return type is `[]byte` but all other variations of return types are implemented with different functions.\n\nFor example. If you need \"value\" as string use `GetString()`.\n\n```go\n\n\tvalue, err := jin.GetString(json, \"repo\", \"name\", \"0\")\n\tif err != nil {\n\t\tfmt.Println(err)\n\t\treturn\n\t}\n\n\tfmt.Println(string(value))\n\t//Output: eco\n\n```\n\nFor example. If you need \"value\" as string use `GetString()`.\n\n```go\n\n\tvalue, err := jin.GetString(json, \"repo\", \"name\", \"0\")\n\tif err != nil {\n\t\tfmt.Println(err)\n\t\treturn\n\t}\n\n\tfmt.Println(string(value))\n\t//Output: eco\n\n```\n\n---\n\n#### Parser\n\n`Parser` is another alternative for JSON manipulation.\n\nWe recommend to use this structure when you need to access all or most of the keys in the JSON.\n\nParser constructor need only one parameter.\n\n```go\n\n\t// Parser constructor function jin.Parse() need one JSON as []byte.\n\tjson := []byte(`\n\t{\n\t\t\"title\": \"LICENSE\",\n\t\t\"repo\": {\n\t\t\t\"id\": 233809925,\n\t\t\t\"name\": \"ecoshub/jin\",\n\t\t\t\"url\": \"https://api.github.com/repos/ecoshub/jin\"\n\t\t\t}\n\t}`)\n\n```\n\nWe can parse it with `Parse()` function.\n\n```go\n\n\tprs, err := jin.Parse(json)\n\tif err != nil {\n\t\tlog.Println(err)\n\t\treturn\n\t}\n\n```\n\nLet's look at `Parser.Get()`\n\n```go\n\n\tvalue, err := prs.Get(\"repo\", \"url\")\n\tif err != nil {\n\t\tlog.Println(err)\n\t\treturn\n\t}\n\n\tfmt.Println(string(value))\n\t//Output: https://api.github.com/repos/ecoshub/jin\n\n```\n\n_About path value look above._\n\nThere is all return type variations of `Parser.Get()` function like `Interpreter`.\n\nFor return string use `Parser.GetString()` like this,\n\n```go\n\n\tvalue, err := prs.GetString(\"repo\", \"name\")\n\tif err != nil {\n\t\tlog.Println(err)\n\t\treturn\n\t}\n\tfmt.Println(value)\n\t//String Output: ecoshub/jin\n\n```\n\nAll functions has own example provided in **[GoDoc](https://godoc.org/github.com/ecoshub/jin)**.\n\n**Other usefull functions of Jin.**\n\n-`Add()`, `AddKeyValue()`, `Set()`, `SetKey()` `Delete()`, `Insert()`, `IterateArray()`, `IterateKeyValue()` `Tree()`.\n\n---\n\n### Iteration Tools\n\nIteration tools provide functions for access each key-value pair or each value of an array\n\nLet's look at `IterateArray()` function.\n\n```go\n\t// JSON that we want to access.\n\tjson := []byte(`{\"user\":\"eco\",\"languages\":[\"go\",\"java\",\"python\",\"C\",\"Cpp\"]}`)\n\n\t// IterateArray() uses a callback function to return elements.\n\terr := jin.IterateArray(json, func(value []byte) (bool, error) {\n\n\t\t// printing current element as string.\n\t\tfmt.Println(string(value))\n\n\t\t// this return is some kind of control mechanism for escape from iteration any time.\n\t\t// true means keep iterate. false means stop the iteration.\n\t\treturn true, nil\n\t// last parameter is path. Its currently pointing at \"language\" array.\n\t}, \"languages\")\n\n\t// standard error definition\n\tif err != nil {\n\t\tlog.Println(err)\n\t\treturn\n\t}\n\n\t// Output: go\n\t// java\n\t// python\n\t// C\n\t// Cpp\n\n```\n\nAnother useful function is `IterateKeyValue()`check for example in **[GoDoc](https://godoc.org/github.com/ecoshub/jin)**.\n\n---\n\n### Other Tools\n\n#### Formatting\n\nThere are two formatting functions. `Flatten()` and `Indent()`.\n\n`Indent()` is adds indentation to JSON for nicer visualization and `Flatten()` removes this indentation.\n\nExamples in **[GoDoc](https://godoc.org/github.com/ecoshub/jin)**.\n\n#### Control Functions\n\nControl functions are simple and easy way to check value types of any path.\n\nFor example. `IsArray()`.\n\n```go\n\n\tjson := []byte(`{\"repo\":{\"name\":\"ecoshub/jin\"},\"others\":[\"jin\",\"penman\"]}`)\n\n\tresult, _ := jin.IsArray(json, \"repo\")\n\tfmt.Println(result)\n\t// Output: false\n\n\tresult, _ = jin.IsArray(json, \"others\")\n\tfmt.Println(result)\n\t// Output: true\n\n\n```\n\nOr you can use `GetType()`.\n\n```go\n\n\tjson := []byte(`{\"git\":\"ecoshub\",\"repo\":[\"jin\",\"wsftp\",\"penman\"]}`)\n\n\tresult, _ := jin.GetType(json, \"repo\")\n\tfmt.Println(result)\n\t// Output: array\n\n```\n\n#### JSON Build Tools\n\nThere are lots of JSON build functions in this package and all of them has its own examples.\n\nWe just want to mention a couple of them.\n\n`Scheme` is simple and powerful tool for create JSON schemes.\n\n```go\n\n\t// MakeScheme need keys for construct a JSON scheme.\n\tperson := MakeScheme(\"name\", \"lastname\", \"age\")\n\n\t// now we can instantiate a JSON with values.\n\teco := person.MakeJson(\"eco\", \"hub\", \"28\")\n\t// {\"name\":\"eco\",\"lastname\":\"hub\",\"age\":28}\n\n\tkoko := person.MakeJson(\"koko\", \"Bloom\", \"42\")\n\t//{\"name\":\"koko\",\"lastname\":\"Bloom\",\"age\":42}\n\n```\n\n`MakeJson()`, `MakeArray()` functions and other variations are easy to use functions. Go and take a look. **[GoDoc](https://godoc.org/github.com/ecoshub/jin)**.\n\n---\n\n### Testing\n\nTesting is very important thing for this type of packages and it shows how reliable it is.\n\nFor that reasons we use **Node.js** for unit testing.\n\nLets look at folder arrangement and working principle.\n\n-   **test/** folder:\n\n    -   **test-json.json**, this is a temporary file for testing. all other test-cases copying here with this name so they can process by **test-case-creator.js**.\n\n    -   **test-case-creator.js** is core path \u0026 value creation mechanism. When it executed with `executeNode()` function. It reads the **test-json.json** file and generates the paths and values from this files content. With command line arguments it can generate different paths and values. As a result, two files are created with this process. the first of these files is **test-json-paths.json** and the second is **test-json-values.json**\n\n    -   **test-json-paths.json** has all the path values.\n\n    -   **test-json-values.json** has all the values that corresponding to path values.\n\n-   **tests/** folder\n\n    -   All files in this folder is a test-case. But it doesn't mean that you can't change anything, on the contrary, all test-cases are creating automatically based on this folder content. You can add or remove any **.json** file that you want.\n\n    -   All `GO` side test-case automation functions are in **core_test.go** file.\n\nThis package developed with **Node.js** v13.7.0. please make sure that your machine has a valid version of **Node.js** before testing.\n\nAll functions and methods are tested with complicated randomly genereted **.json** files.\n\nLike this,\n\n```go\n\n\t{\n\t\t\"g;}\\\\=LUG[5pwAizS!lfkdRULF=\": true,\n\t\t\"gL1GG'S+-U~#fUz^R^=#genWFVGA$O\": {\n\t\t\t\"Nmg}xK\u0026V5Z\": -1787764711,\n\t\t\t\"=B7a(KoF%m5rqG#En}dl\\\"y`117)WC\u0026w~\": -572664066,\n\t\t\t\"Dj_{6evoMr\u0026\u003c 4m+1u{W!'zf;cl\": \":mqp\u003cs6('\u0026??yG#)qpMs=H?\",\n\t\t\t\",Qx_5V(ceN)%0d-h.\\\"\\\"0v}8fqG-zgEBz;!C{zHZ#9Hfg%no*\": false,\n\t\t\t\"l\u0026d\u003e\": true\n\t\t},\n\t\t\"jhww/SRq?,Y\\\"5O1'{\": \"]\\\"4s{WH]b9aR+[$-'PQm8WW:B\",\n\t\t\":e\": \"Lu9(\u003e9IbrLyx60E;9R]NHml@A~} QHgAUR5$TUCm\u0026z,]d\\\"\u003e\",\n\t\t\"e\u0026Kk^`rz`T!EZopgIo\\\\5)GT'MkSCf]2\u003c{dt+C_H\": 599287421.0854483\n\t}\n\n```\n\nMost of JSON packages not even run properly with this kind of JSON streams.\nWe did't see such packages as competitors to ourselves.\nAnd that's because we didn't even bother to benchmark against them.\n\n---\n\n### Benchmark\n\nBenchmark results.\n\n-   _Benchmark prefix removed from function names for make room to results._\n-   Benchmark between 'buger/jsonparser' and 'ecoshub/jin' use the same payload (JSON test-cases) that 'buger/jsonparser' package use for benchmark it self.\n\n    _github.com/ecoshub/jin -\u003e Jin_\n\n    _github.com/buger/jsonparser -\u003e Jsonparser_\n\n    _github.com/valyala/fastjson -\u003e Fastjson_\n\n    _github.com/json-iterator/go -\u003e Jsoniterator_\n\n    _github.com/tidwall/gjson -\u003e gjson_\n\n    _github.com/tidwall/sjson -\u003e sjon_\n\n```go\n\n\tgoos: linux\n\tgoarch: amd64\n\tpkg: jin/benchmark\n\n\t// Get function (interpert)\n\tJsoniteratorGetSmall-8             2862 ns/op          597 B/op          40 allocs/op\n\tGjsonGetSmall-8                     921 ns/op           64 B/op           3 allocs/op\n\tJsonparserGetSmall-8                787 ns/op            0 B/op           0 allocs/op\n\tJinGetSmall-8                       729 ns/op            0 B/op           0 allocs/op\n\tGjsonGetMedium-8                   7084 ns/op          152 B/op           4 allocs/op\n\tJsonparserGetMedium-8              7329 ns/op            0 B/op           0 allocs/op\n\tJinGetMedium-8                     5624 ns/op            0 B/op           0 allocs/op\n\tGjsonrGetLarge-8                 119925 ns/op        28672 B/op           2 allocs/op\n\tJsonparserGetLarge-8              65725 ns/op            0 B/op           0 allocs/op\n\tJinGetLarge-8                     61516 ns/op            0 B/op           0 allocs/op\n\n\t// Array iteration function (interpert)\n\tIterateArrayGetGjson-8            21966 ns/op         8192 B/op           1 allocs/op\n\tIterateArrayGetJsonparser-8       11814 ns/op            0 B/op           0 allocs/op\n\tIterateArrayGetJin-8              11639 ns/op            0 B/op           0 allocs/op\n\tIterateObjectGetGjson-8           11329 ns/op         2304 B/op           1 allocs/op\n\tIterateObjectGetJsonparser-8       6100 ns/op            0 B/op           0 allocs/op\n\tIterateObjectGetJin-8              4551 ns/op            0 B/op           0 allocs/op\n\n\t// Set function (interpert)\n\tSJonSetSmall-8                     2126 ns/op         1664 B/op           9 allocs/op\n\tJsonParserSetSmall-8               1261 ns/op          704 B/op           4 allocs/op\n\tJinSetSmall-8                      1244 ns/op          704 B/op           4 allocs/op\n\tSjsonSetMedium-8                  15412 ns/op        13008 B/op          11 allocs/op\n\tJsonParserSetMedium-8              6868 ns/op         6912 B/op           3 allocs/op\n\tJinSetMedium-8                     6169 ns/op         6912 B/op           3 allocs/op\n\tSjsonSetLarge-8                  257300 ns/op       136736 B/op          14 allocs/op\n\tJsonParserSetLarge-8             121874 ns/op       114688 B/op           4 allocs/op\n\tJinSetLarge-8                     86574 ns/op       114688 B/op           4 allocs/op\n\n\t// Delete function (interpert)\n\tJsonParserDeleteSmall-8            2015 ns/op          704 B/op           4 allocs/op\n\tJinDeleteSmall-8                   1198 ns/op          640 B/op           4 allocs/op\n\tJsonParserDeleteMedium-8          10321 ns/op         6912 B/op           3 allocs/op\n\tJinDeleteMedium-8                  5780 ns/op         6144 B/op           3 allocs/op\n\tJsonParserDeleteLarge-8          123737 ns/op       114688 B/op           4 allocs/op\n\tJinDeleteLarge-8                  87322 ns/op       114688 B/op           4 allocs/op\n\n\t// Get function (parse)\n\tFastjsonGetSmall-8                 2755 ns/op         3408 B/op          11 allocs/op\n\tJinParseGetSmall-8                 1981 ns/op         1252 B/op          28 allocs/op\n\tFastjsonGetMedium-8               14958 ns/op        17304 B/op          54 allocs/op\n\tJinParseGetMedium-8               14175 ns/op         8304 B/op         201 allocs/op\n\tFastjsonGetLarge-8               229188 ns/op       283200 B/op         540 allocs/op\n\tJinParseGetLarge-8               222246 ns/op       134704 B/op        2903 allocs/op\n\n\t// Set function (parse)\n\tFastjsonSetSmall-8                 3709 ns/op         3792 B/op          19 allocs/op\n\tJinParseSetSmall-8                 3265 ns/op         1968 B/op          36 allocs/op\n\n```\n\n---\n\n### Upcoming\n\nWe are currently working on,\n\n-   `Marshal()` and `Unmarshal()` functions.\n\n-   http.Request parser/interpreter\n\n-   Builder functions for http.ResponseWriter\n\n---\n\n### Contribute\n\nIf you want to contribute this work feel free to fork it.\n\nWe want to fill this section with contributors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecoshub%2Fjin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fecoshub%2Fjin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecoshub%2Fjin/lists"}