{"id":50547752,"url":"https://github.com/cacheplane/cacheplane","last_synced_at":"2026-06-04T00:04:32.632Z","repository":{"id":355966274,"uuid":"1230450209","full_name":"cacheplane/cacheplane","owner":"cacheplane","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-06T03:11:28.000Z","size":135,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T04:32:19.859Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cacheplane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-06T02:25:29.000Z","updated_at":"2026-05-06T03:11:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cacheplane/cacheplane","commit_stats":null,"previous_names":["cacheplane/cacheplane"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/cacheplane/cacheplane","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cacheplane%2Fcacheplane","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cacheplane%2Fcacheplane/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cacheplane%2Fcacheplane/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cacheplane%2Fcacheplane/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cacheplane","download_url":"https://codeload.github.com/cacheplane/cacheplane/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cacheplane%2Fcacheplane/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33884798,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2026-06-04T00:04:31.990Z","updated_at":"2026-06-04T00:04:32.619Z","avatar_url":"https://github.com/cacheplane.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cacheplane\n\nStreaming parsers for AI interfaces.\n\nCacheplane helps applications render structured model output while it is still\narriving. LLMs routinely stream JSON and Markdown mid-token, mid-string,\nmid-list, or mid-table. Traditional parsers wait for the whole document;\nCacheplane gives you a typed tree that grows in place, with stable node identity\nso UI layers can render partial output without losing memoization.\n\n## Packages\n\n| Package | npm | Use it for | Highlights |\n|---|---|---|---|\n| [`@cacheplane/partial-json`](packages/partial-json) | [![npm](https://img.shields.io/npm/v/@cacheplane/partial-json.svg)](https://www.npmjs.com/package/@cacheplane/partial-json) | JSON streamed from an LLM or any incremental source | Partial strings and numbers, JSON Pointer lookup, push and pull APIs, structural-sharing snapshots |\n| [`@cacheplane/partial-markdown`](packages/partial-markdown) | [![npm](https://img.shields.io/npm/v/@cacheplane/partial-markdown.svg)](https://www.npmjs.com/package/@cacheplane/partial-markdown) | Markdown streamed into chat, agent logs, reports, or AI writing surfaces | Headings, lists, task lists, tables, citations, link references, math, raw HTML, inline formatting, stable AST identity |\n\nBoth packages are:\n\n- Built for Node `\u003e=20`\n- TypeScript-first\n- ESM and CJS bundled\n- Zero runtime dependencies\n- Marked side-effect free\n- Published independently under `@cacheplane/*`\n\n## Why This Exists\n\nAI products increasingly render model output as it streams: tool arguments,\nstructured extraction results, reports, citations, markdown answers, task lists,\nand agent traces. The hard part is not just accepting incomplete input. The hard\npart is giving the UI a stable representation while the input is still changing.\n\nCacheplane parsers are designed around that constraint:\n\n- **Truncation tolerant:** incomplete input is normal, not an exception path.\n- **Stable node identity:** a node keeps the same object reference as future\n  chunks update it.\n- **Streaming status:** every public node exposes\n  `pending | streaming | complete`.\n- **Evented updates:** push-style parsers return node creation, value update,\n  and completion events.\n- **Structural-sharing snapshots:** `materialize()` returns plain values while\n  preserving references for unchanged subtrees.\n\nThe result is a parser layer that works naturally with React memoization,\nAngular OnPush, Solid signals, editor views, virtualized renderers, and custom\nagent UIs.\n\n## Quick Start\n\nInstall the package you need:\n\n```bash\nnpm install @cacheplane/partial-json\nnpm install @cacheplane/partial-markdown\n```\n\nParse JSON while it streams:\n\n```ts\nimport { createPartialJsonParser, materialize } from '@cacheplane/partial-json';\n\nconst parser = createPartialJsonParser();\n\nparser.push('{\"items\":[{\"title\":\"Alpha\"},{\"title\":\"Bet');\n\nconst first = parser.getByPath('/items/0/title');\nconst second = parser.getByPath('/items/1/title');\n\nconsole.log(first?.status);  // \"complete\"\nconsole.log(second?.status); // \"streaming\"\nconsole.log(materialize(parser.root!));\n```\n\nParse Markdown while it streams:\n\n```ts\nimport { createPartialMarkdownParser } from '@cacheplane/partial-markdown';\n\nconst parser = createPartialMarkdownParser();\n\nparser.push('# Plan\\n\\n- [ ] Parse stream');\nparser.push('\\n- [x] Render stable tree\\n');\n\nfor (const block of parser.root?.children ?? []) {\n  console.log(block.type, block.status);\n}\n```\n\nSee the package READMEs for full API details:\n\n- [`@cacheplane/partial-json`](packages/partial-json/README.md)\n- [`@cacheplane/partial-markdown`](packages/partial-markdown/README.md)\n\n## API Shape\n\nEach package exposes two APIs over the same parser core.\n\n### Push-style API\n\nUse this for UI streaming, agent output renderers, and anything that wants\nlong-lived node references.\n\n```ts\nconst parser = createPartialJsonParser();\n\nconst events = parser.push(chunk);\nparser.root;\nparser.getByPath('/path/to/node');\nparser.finish();\n```\n\n`push()` and `finish()` return parser events:\n\n- `node-created`\n- `value-updated`\n- `node-completed`\n\n### Pull-style API\n\nUse this for reducers, deterministic state transitions, undo/redo stacks, and\ntests that prefer immutable state objects.\n\n```ts\nlet state = create();\nstate = push(state, chunk);\nstate = finish(state);\nconst value = resolve(state);\n```\n\n## Repository Layout\n\n```text\npackages/\n  partial-json/       Published package: @cacheplane/partial-json\n  partial-markdown/   Published package: @cacheplane/partial-markdown\napps/                 Reserved for deployable apps\nlibs/                 Reserved for private workspace libraries\ntools/                Reserved for repo-internal scripts\ndocs/\n  specs/              Design specs for larger changes\n  plans/              Implementation plans for larger changes\n```\n\nTests live next to package source files under `packages/*/src`.\n\n## Development\n\nInstall dependencies:\n\n```bash\npnpm install\n```\n\nRun the full local verification suite:\n\n```bash\npnpm verify\n```\n\nCommon commands:\n\n```bash\npnpm lint\npnpm typecheck\npnpm test\npnpm test:coverage\npnpm build\n```\n\nPackage-scoped commands:\n\n```bash\npnpm --filter @cacheplane/partial-json test\npnpm --filter @cacheplane/partial-json build\npnpm --filter @cacheplane/partial-json publint\npnpm --filter @cacheplane/partial-json attw\n\npnpm --filter @cacheplane/partial-markdown test\npnpm --filter @cacheplane/partial-markdown build\npnpm --filter @cacheplane/partial-markdown publint\npnpm --filter @cacheplane/partial-markdown attw\n```\n\nBuild output is written to `packages/*/dist`.\n\n## Contributing Parser Changes\n\nParser behavior is public API. When changing it:\n\n1. Add or update focused tests in the affected package.\n2. Preserve node identity across pushes unless the README explicitly says a\n   reference can be replaced.\n3. Keep `pending | streaming | complete` transitions intentional and tested.\n4. Update the package README when behavior, guarantees, warnings, or unsupported\n   syntax changes.\n5. Update the package `CHANGELOG.md` for released user-visible changes.\n6. Run `pnpm verify` before opening a PR.\n\nFor packaging changes, also run the package's `publint` and `attw` scripts.\nThese catch common npm, ESM, CJS, and TypeScript declaration regressions before\npublish.\n\n## Releasing\n\nPackages are versioned and released independently. Releases are tag-routed via\nthe publish workflow:\n\n- `partial-json-v0.2.1` publishes `@cacheplane/partial-json@0.2.1`\n- `partial-markdown-v0.3.2` publishes `@cacheplane/partial-markdown@0.3.2`\n\nSee [`RELEASING.md`](RELEASING.md) for the release process.\n\n## Support\n\n- Open issues in the [Cacheplane GitHub repository](https://github.com/cacheplane/cacheplane/issues).\n- Check package changelogs before upgrading:\n  - [`packages/partial-json/CHANGELOG.md`](packages/partial-json/CHANGELOG.md)\n  - [`packages/partial-markdown/CHANGELOG.md`](packages/partial-markdown/CHANGELOG.md)\n\nMonorepo-level changes (CI, tooling, workspace structure) are tracked in the root [CHANGELOG.md](CHANGELOG.md). Per-package release notes live in each package's own `CHANGELOG.md`.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcacheplane%2Fcacheplane","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcacheplane%2Fcacheplane","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcacheplane%2Fcacheplane/lists"}