{"id":15442481,"url":"https://github.com/promplate/partial-json-parser-js","last_synced_at":"2025-04-05T15:10:07.935Z","repository":{"id":201047875,"uuid":"706636808","full_name":"promplate/partial-json-parser-js","owner":"promplate","description":"Parse partial JSON generated by LLM","archived":false,"fork":false,"pushed_at":"2024-09-17T13:35:34.000Z","size":16,"stargazers_count":108,"open_issues_count":3,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T14:12:48.524Z","etag":null,"topics":["agent","json","langchain","llm","parser","prompt-engineering","streaming"],"latest_commit_sha":null,"homepage":"https://npmjs.com/partial-json","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/promplate.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":"2023-10-18T10:39:11.000Z","updated_at":"2025-03-28T00:11:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"8e2efc0b-04f3-47ba-acee-cee09bf8de7b","html_url":"https://github.com/promplate/partial-json-parser-js","commit_stats":{"total_commits":16,"total_committers":2,"mean_commits":8.0,"dds":0.0625,"last_synced_commit":"5eb1039e74974b4135af888c6bf51abd040da5ad"},"previous_names":["promplate/partial-json-parser-js"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/promplate%2Fpartial-json-parser-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/promplate%2Fpartial-json-parser-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/promplate%2Fpartial-json-parser-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/promplate%2Fpartial-json-parser-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/promplate","download_url":"https://codeload.github.com/promplate/partial-json-parser-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353749,"owners_count":20925329,"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":["agent","json","langchain","llm","parser","prompt-engineering","streaming"],"created_at":"2024-10-01T19:28:01.823Z","updated_at":"2025-04-05T15:10:07.888Z","avatar_url":"https://github.com/promplate.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Partial JSON Parser\n\nSometimes we need **LLM (Large Language Models)** to produce **structural information** instead of natural language. The easiest way is to use JSON.\n\nBut before receiving the last token of response, the JSON is broken, which means you can't use `JSON.parse` to decode it. But we still want to stream the data to the user.\n\nHere comes `partial-json`, a lightweight and customizable library for parsing partial JSON strings. Here is a [demo](https://promplate.dev/partial-json-parser).\n\n(Note that there is [a Python implementation](https://github.com/promplate/partial-json-parser) too)\n\n## Installation\n\n```sh\nnpm i partial-json # or pnpm / bun / yarn\n```\n\n`partial-json` is implemented purely in JavaScript, and have both `commonjs` and `esm` builds.\n\n## Usage\n\n### Importing the library\n\nYou can import the `parse` function and the `Allow` object from the library like this:\n\n```js\nimport { parse, Allow } from \"partial-json\";\n```\n\nThe `Allow` object is just an Enum for options. It determines what types can be partial. types not included in `allow` only appears after its completion can be ensured.\n\n### Parsing complete / partial JSON strings\n\nThe `parse` function works just like the built-in `JSON.parse` when parsing a complete JSON string:\n\n```js\nlet result = parse('{\"key\":\"value\"}');\nconsole.log(result); // Outputs: { key: 'value' }\n```\n\nYou can parse a partial JSON string by passing an additional parameter to the `parse` function. This parameter is a **bitwise OR** of the constants from the `Allow` object:\n\n(Note that you can directly import the constants you need from `partial-json`)\n\n```js\nimport { parse, STR, OBJ } from \"partial-json\";\n\nresult = parse('{\"key\": \"v', STR | OBJ);\nconsole.log(result); // Outputs: { key: 'v' }\n```\n\nIn this example, `Allow.STR` tells the parser that it's okay if a string is incomplete, and `Allow.OBJ` tells the parser so as an object. The parser then try to return as much data as it can.\n\nIf you don't allow partial strings, then it will not add `\"key\"` to the object because `\"v` is not close:\n\n```js\nresult = parse('{\"key\": \"v', OBJ);\nconsole.log(result); // Outputs: {}\n\nresult = parse('{\"key\": \"value\"', OBJ);\nconsole.log(result); // Outputs: { key: 'value' }\n```\n\nSimilarity, you can parse partial arrays or even partial special values if you allow it:\n\n(Note that `allow` defaults to `Allow.ALL`)\n\n```js\nresult = parse('[ {\"key1\": \"value1\", \"key2\": [ \"value2');\nconsole.log(result); // Outputs: [ { key1: 'value1', key2: [ 'value2' ] } ]\n\nresult = parse(\"-Inf\");\nconsole.log(result); // Outputs: -Infinity\n```\n\n### Handling malformed JSON\n\nIf the JSON string is malformed, the `parse` function will throw an error:\n\n```js\nparse(\"wrong\"); // MalformedJSON [Error]: SyntaxError: Unexpected token 'w', \"wrong\" is not valid JSON at position 0\n```\n\n## API Reference\n\n### parse(jsonString, [allowPartial])\n\n- `jsonString` `\u003cstring\u003e`: The JSON string to parse.\n- `allowPartial` `\u003cnumber\u003e`: Specify what kind of partialness is allowed during JSON parsing (default: `Allow.ALL`).\n\nReturns the parsed JavaScript value.\n\n### Allow\n\nAn object that specifies what kind of partialness is allowed during JSON parsing. It has the following properties:\n\n- `STR`: Allow partial string.\n- `NUM`: Allow partial number.\n- `ARR`: Allow partial array.\n- `OBJ`: Allow partial object.\n- `NULL`: Allow partial null.\n- `BOOL`: Allow partial boolean.\n- `NAN`: Allow partial NaN.\n- `INFINITY`: Allow partial Infinity.\n- `_INFINITY`: Allow partial -Infinity.\n- `INF`: Allow both partial Infinity and -Infinity.\n- `SPECIAL`: Allow all special values.\n- `ATOM`: Allow all atomic values.\n- `COLLECTION`: Allow all collection values.\n- `ALL`: Allow all values.\n\n## Testing\n\nTo run the tests for this library, you should clone the repository and install the dependencies:\n\n```sh\ngit clone https://github.com/promplate/partial-json-parser-js.git\ncd partial-json-parser-js\nnpm i\n```\n\nThen, you can run the tests using [Vitest](https://vitest.dev/):\n\n```sh\nnpm run test\n```\n\nPlease note that while we strive to cover as many edge cases as possible, it's always possible that some cases might not be covered.\n\n## License\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpromplate%2Fpartial-json-parser-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpromplate%2Fpartial-json-parser-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpromplate%2Fpartial-json-parser-js/lists"}