{"_id":"@buddhilive/dsh-deque","name":"@buddhilive/dsh-deque","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-deque","description":"Zero-dependency circular deque with amortized constant-time end operations and bounded vacant storage","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/util/deque"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","peerDependencies":{"@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"devDependencies":{"@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"_id":"@buddhilive/dsh-deque@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-q5oyQpdz4fjBFOsGAiaZxgK4AHJwvKSuKYTMCT4tcNWe2odvw5MzJy5srRwzwRSAsCh7ZPldWC5bAfssVQQgCA==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-deque-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-deque-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-q5oyQpdz4fjBFOsGAiaZxgK4AHJwvKSuKYTMCT4tcNWe2odvw5MzJy5srRwzwRSAsCh7ZPldWC5bAfssVQQgCA==","shasum":"35f11e66132c081b678a446f12b401b37a17eabd","tarball":"https://registry.npmjs.org/@buddhilive/dsh-deque/-/dsh-deque-0.1.2-alpha.3.tgz","fileCount":9,"unpackedSize":15144,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICzWf1y7RxUyC+PETT1zgcKMoBD7MkT7pXtCNh+PVYsQAiEAtyTIbtOAj8iyeJNY5MBJqgKKeUM4TJLMMHh9pBXfXkw="}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-deque_0.1.2-alpha.3_1788165344622_0.5251416221556207"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:35:42.756Z","0.1.2-alpha.3":"2026-08-31T08:35:44.758Z","modified":"2026-08-31T08:35:46.606Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Zero-dependency circular deque with amortized constant-time end operations and bounded vacant storage","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/util/deque"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"供 Host 和浏览器包使用的环形双端队列，提供摊销常数时间的队列操作、已移除条目的即时释放和有界空闲存储。\"\nkind: \"package-library\"\n---\n\n# @buddhilive/dsh-deque\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-deque` 让 Host 和浏览器包可以排空长期存在的进程内队列，而无需在每次移除后移动所有剩余条目。调用方可以追加或前插条目，并以摊销常数时间从前端移除。双端队列负责条目顺序和后备存储释放；唤醒、失败、取消、容量和过载行为仍由各消费方负责。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [模型体验](#model-experience)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n### 何时使用\n\n当条目可能在异步工作期间持续积累，且消费方需要 FIFO 移除、可选前插或显式清空队列时，使用 `Deque<T>`。如果有限本地工作列表的最大规模使头部移除成本无关紧要，它可以继续使用数组。\n\n### 入口\n\n导入双端队列，在尾部追加条目；当条目类型可能包含 `undefined` 时，在移除前检查 `size`：\n\n```ts\nimport { Deque } from '@buddhilive/dsh-deque'\n\nconst frames = new Deque<string>()\nframes.pushBack('first')\nframes.pushFront('before-first')\n\nwhile (frames.size > 0) {\n  console.log(frames.popFront())\n}\n```\n\n这些方法不施加队列限制，也不转换消费方失败。准确的 TypeScript 约定见 [`src/index.ts`](src/index.ts)。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n双端队列把条目存入环形数组。移除条目会立即清空对应槽位；按几何级数扩容并在四分之一满时缩容，使复制工作保持摊销常数时间，并防止头游标保留持续增长的空闲存储。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | 环形双端队列操作与后备存储生命周期 |\n| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；顺序和存储生命周期由单元测试覆盖） |\n| [`tests/deque.spec.ts`](tests/deque.spec.ts) | FIFO、前插、环绕、扩容、压缩、清空和复用覆盖 |\n| [`benchmarks/drain.ts`](benchmarks/drain.ts) | 随队列规模增长的可复现 backlog 排空计时 |\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n- [工具包映射](../README.zh.md)——跨包组共享的其他零依赖原语。\n- [线性流队列决策](../../../.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.zh.md)——生产流为何使用本双端队列而非数组头部移除。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n无，因为这个进程内集合不注册任何面向模型的内容。\n\n#### KV 缓存影响\n\n这里的内容不会进入模型请求，因此不影响提供方缓存复用。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n- **没有容量策略**——双端队列不会限制、合并或拒绝条目；每个消费方必须定义适合其流的过载行为。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-b907a43227febd331f242b83b7e496ae"}