{"_id":"@daisy-petal/bx-storage-cache","_rev":"2-0a3e6ca1b58cebe73c4b4b8856b41d68","name":"@daisy-petal/bx-storage-cache","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@daisy-petal/bx-storage-cache","version":"1.0.0","keywords":["browser-extension","web-extension","chrome-extension","firefox-extension","firefox-addon","wxt","background-sync","storage-cache","exponential-backoff","jitter","cache-management","typescript"],"author":{"name":"Daisy Petal","email":"daisy-petal@yandex.ru"},"license":"MIT","_id":"@daisy-petal/bx-storage-cache@1.0.0","maintainers":[{"name":"daisy-petal","email":"daisy-petal@yandex.ru"}],"homepage":"https://gitflic.ru/project/daisy-petal/bx-storage-cache#readme","bugs":{"url":"https://gitflic.ru/project/daisy-petal/bx-storage-cache/issue"},"dist":{"shasum":"f2ba8931f655aacb80dacd002873b2e5888c0493","tarball":"https://registry.npmjs.org/@daisy-petal/bx-storage-cache/-/bx-storage-cache-1.0.0.tgz","fileCount":5,"integrity":"sha512-Z+v22qKb432WWJxJ00EZdxHKaFtNwr9p1MURH2Z70Kj66PWLIIiPUa8FaXoOdrD2Z+6JaoY7DkeajaQgZuq8xQ==","signatures":[{"sig":"MEYCIQCbCdU+q94CzL1flitVwNECOhfNJAXmOxAzTE9lSlYRuwIhAKdbGStAWOVjBfTgK5LzTA2vnqkc1hUSbYMwrnBQvBr4","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":10685},"type":"module","_from":"file:daisy-petal-bx-storage-cache-1.0.0.tgz","engines":{"node":">=24.0.0"},"exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"}},"scripts":{"lint":"pnpm run lint:code & pnpm run lint:package","test":"vitest","build":"tsdown","lint:code":"biome check","lint:package":"publint && attw --pack . --profile esm-only"},"_npmUser":{"name":"daisy-petal","email":"daisy-petal@yandex.ru"},"_resolved":"/tmp/577dfb01ddac183e6008540cf7be1b16/daisy-petal-bx-storage-cache-1.0.0.tgz","_integrity":"sha512-Z+v22qKb432WWJxJ00EZdxHKaFtNwr9p1MURH2Z70Kj66PWLIIiPUa8FaXoOdrD2Z+6JaoY7DkeajaQgZuq8xQ==","repository":{"url":"https://gitflic.ru/project/daisy-petal/bx-storage-cache.git","type":"git"},"_npmVersion":"11.6.2","description":"Lightweight background data synchronization library for browser extensions with built-in exponential backoff and jitter.","directories":{},"sideEffects":false,"_nodeVersion":"24.12.0","dependencies":{"@wxt-dev/browser":"^0.1.37"},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"^0.20.3","vitest":"^4.0.18","publint":"^0.3.18","typescript":"^5.9.3","@biomejs/biome":"2.4.5","@tsconfig/node24":"^24.0.4","@arethetypeswrong/cli":"^0.18.2","@webext-core/fake-browser":"^1.3.4"},"_npmOperationalInternal":{"tmp":"tmp/bx-storage-cache_1.0.0_1773064895611_0.7774187194099629","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@daisy-petal/bx-storage-cache","version":"1.0.1","description":"Lightweight background data synchronization library for browser extensions with built-in exponential backoff and jitter.","keywords":["browser-extension","web-extension","chrome-extension","firefox-extension","firefox-addon","wxt","background-sync","storage-cache","exponential-backoff","jitter","cache-management","typescript"],"homepage":"https://gitflic.ru/project/daisy-petal/bx-storage-cache#readme","bugs":{"url":"https://gitflic.ru/project/daisy-petal/bx-storage-cache/issue"},"license":"MIT","author":{"name":"Daisy Petal","email":"daisy-petal@yandex.ru"},"repository":{"type":"git","url":"https://gitflic.ru/project/daisy-petal/bx-storage-cache.git"},"type":"module","sideEffects":false,"exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"}},"dependencies":{"@wxt-dev/browser":"^0.1.37"},"devDependencies":{"@arethetypeswrong/cli":"^0.18.2","@biomejs/biome":"2.4.5","@tsconfig/node24":"^24.0.4","@webext-core/fake-browser":"^1.3.4","publint":"^0.3.18","tsdown":"^0.20.3","typescript":"^5.9.3","vitest":"^4.0.18"},"engines":{"node":">=24.0.0"},"scripts":{"lint":"pnpm run lint:code & pnpm run lint:package","lint:code":"biome check","lint:package":"publint && attw --pack . --profile esm-only","build":"tsdown","test":"vitest"},"_id":"@daisy-petal/bx-storage-cache@1.0.1","_integrity":"sha512-P1N6Mf8XJ/xKaM7KMl5KSBHwyxpIlB3Vgpgutrb2eodY195ex4v1YhQZ+r/KBk5aLmZRbRqJdh2zK1HeP4pVbg==","_resolved":"/tmp/4353aa121693cd32e343766db49e7925/daisy-petal-bx-storage-cache-1.0.1.tgz","_from":"file:daisy-petal-bx-storage-cache-1.0.1.tgz","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-P1N6Mf8XJ/xKaM7KMl5KSBHwyxpIlB3Vgpgutrb2eodY195ex4v1YhQZ+r/KBk5aLmZRbRqJdh2zK1HeP4pVbg==","shasum":"44a286c30e8ade4cda4019051727952ea688ff8b","tarball":"https://registry.npmjs.org/@daisy-petal/bx-storage-cache/-/bx-storage-cache-1.0.1.tgz","fileCount":5,"unpackedSize":10777,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCHpQ6j7CT/qvF06Qpovr1twhV7UBTse3sH+w+stk6fHAIhAPnLBkGpuraA9SbktnPAZ5jppuJIS8LH5q0qJhUVEZ9q"}]},"_npmUser":{"name":"daisy-petal","email":"daisy-petal@yandex.ru"},"directories":{},"maintainers":[{"name":"daisy-petal","email":"daisy-petal@yandex.ru"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/bx-storage-cache_1.0.1_1774620986151_0.34389705548300054"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-09T14:01:35.474Z","modified":"2026-03-27T14:16:26.399Z","1.0.0":"2026-03-09T14:01:35.739Z","1.0.1":"2026-03-27T14:16:26.302Z"},"bugs":{"url":"https://gitflic.ru/project/daisy-petal/bx-storage-cache/issue"},"author":{"name":"Daisy Petal","email":"daisy-petal@yandex.ru"},"license":"MIT","homepage":"https://gitflic.ru/project/daisy-petal/bx-storage-cache#readme","keywords":["browser-extension","web-extension","chrome-extension","firefox-extension","firefox-addon","wxt","background-sync","storage-cache","exponential-backoff","jitter","cache-management","typescript"],"repository":{"type":"git","url":"https://gitflic.ru/project/daisy-petal/bx-storage-cache.git"},"description":"Lightweight background data synchronization library for browser extensions with built-in exponential backoff and jitter.","maintainers":[{"name":"daisy-petal","email":"daisy-petal@yandex.ru"}],"readme":"# bx-storage-cache\n\nLightweight background data synchronization library\nfor browser extensions with built-in exponential backoff and jitter.\n\n## Features\n\n- 🔄 **Automated Background Sync**: Leverages `browser.alarms` for periodic updates.\n- 📉 **Resilient Retries**: Implements **Equal Jitter** strategy to prevent thundering herd problems during API failures.\n- 🛠 **Lifecycle Management**: Auto-initializes on extension install or update.\n\n## Installation\n\n```bash\nnpm install @daisy-petal/bx-storage-cache\nyarn add @daisy-petal/bx-storage-cache\npnpm add @daisy-petal/bx-storage-cache\nbun add @daisy-petal/bx-storage-cache\n```\n\n## Quick Start\n\n1. Add permissions to your `manifest.json`:\n```json\n{\n  \"permissions\": [\"storage\", \"alarms\"]\n}\n```\n\n2. Register your cache in the background script:\n\n```ts\nimport { registerBxStorageCache } from '@daisy-petal/bx-storage-cache'\n\ninterface PriceData {\n\tprice: number\n\tcurrency: string\n}\n\nconst priceCache = registerBxStorageCache<PriceData>(\n\t{ price: 0, currency: 'USD' },\n\t'price',\n\tasync () => {\n\t\tconst data = await fetch('https://api.example.com')\n\t\treturn data.json()\n\t},\n\t{\n\t\tperiodInMin: 30,\n\t\tretryDelayInMs: {\n\t\t\tbase: 2 * 1000,\n\t\t\tmax: 10 * 60 * 1000\n\t\t}\n\t}\n);\n\n// To get the value later:\n// const { price } = await browser.storage.local.get('price');\n```\n\n## How it works\n\n1. **Initialization**: On `runtime.onInstalled`, `init()` is called to set the default state.\n2. **Sync Cycle**: The onAlarm handler triggers your `getActualValue` function.\n3. **Error Recovery**: If the fetcher throws an error:\n\t1. It calculates a retry delay using exponential backoff.\n\t2. Adds \"Equal Jitter\" to the delay to spread out server load.\n\t3. Persists the attempt count in storage to survive background page suspensions.\n4. **Storage Keys**:\n\t\t`id`: Contains the cached data.\n\t\t`@daisy-petal/bx-storage-cache:${id}`: Internal metadata for managing retry state.\n\n## API Reference\n\n### `registerBxStorageCache<Value>(initValue, id, getActualValue, options)`\n\nThe primary entry point. It instantiates the class and attaches necessary listeners to browser.alarms and browser.runtime.\n\n### `BxStorageCache<Value>` Class\n\n- `forceSync()`: Clears existing alarms and triggers an immediate update.\n- `destroy()`: Wipes data from storage and cancels all scheduled alarms.\n- `init(value)`: Resets the cache to a specific value and clears retry metadata.\n","readmeFilename":"README.md"}