{"_id":"@aossie-org/idb-backup","_rev":"4-c954e38414f1bb975574ea7974bdf67b","name":"@aossie-org/idb-backup","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@aossie-org/idb-backup","version":"1.0.0","keywords":["indexeddb","backup","export","import","idb","json","browser","typescript"],"author":{"name":"AOSSIE"},"license":"GPL-3.0","_id":"@aossie-org/idb-backup@1.0.0","maintainers":[{"name":"zahnentferner","email":"zahnentferner@gmail.com"}],"homepage":"https://github.com/AOSSIE-Org/IndexedDB-Import-Export#readme","bugs":{"url":"https://github.com/AOSSIE-Org/IndexedDB-Import-Export/issues"},"dist":{"shasum":"c28dbe2ad2712c808567f12f20be3a806fd1a0a9","tarball":"https://registry.npmjs.org/@aossie-org/idb-backup/-/idb-backup-1.0.0.tgz","fileCount":9,"integrity":"sha512-uK9KJ3oli+NXDG4nMeSmdqyus3X7//kyj+Tde/4wwVPRf1ERVe0f9ObElm3FoAFQObLMLhqEUiZJb18YYwRdQQ==","signatures":[{"sig":"MEUCIQDyyfXqnEGev8y4YHnv92CBkeFG/ax+JOLbmIqX9AgrDQIgLy9sACar5QfOxZPV1d88x9W9Y49Pa2zjvKRhW/TOT5U=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aossie-org%2fidb-backup@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":136009},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"327d32815722e676ba295a53f20f913ac1914459","scripts":{"lint":"eslint src/ tests/","test":"vitest run","build":"tsup","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","test:watch":"vitest","format:check":"prettier --check \"src/**/*.ts\" \"tests/**/*.ts\""},"_npmUser":{"name":"zahnentferner","email":"zahnentferner@gmail.com"},"repository":{"url":"git+https://github.com/AOSSIE-Org/IndexedDB-Import-Export.git","type":"git"},"_npmVersion":"10.9.8","description":"A framework-agnostic, lightweight TypeScript library for exporting and importing IndexedDB databases via type-tagged JSON.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"idb":"^8.0.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^10.5.0","vitest":"^4.1.9","prettier":"^3.0.0","happy-dom":"^20.9.0","@eslint/js":"^10.0.1","typescript":"^5.5.0","fake-indexeddb":"^6.0.0","typescript-eslint":"^8.61.1"},"_npmOperationalInternal":{"tmp":"tmp/idb-backup_1.0.0_1781864233088_0.8298838698123787","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@aossie-org/idb-backup","version":"1.0.1","description":"A framework-agnostic, lightweight TypeScript library for exporting and importing IndexedDB databases via type-tagged JSON.","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","test":"vitest run","test:watch":"vitest","lint":"eslint src/ tests/","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","format:check":"prettier --check \"src/**/*.ts\" \"tests/**/*.ts\""},"keywords":["indexeddb","backup","export","import","idb","json","browser","typescript"],"author":{"name":"AOSSIE"},"license":"GPL-3.0","engines":{"node":">=20"},"repository":{"type":"git","url":"git+https://github.com/AOSSIE-Org/IndexedDB-Import-Export.git"},"bugs":{"url":"https://github.com/AOSSIE-Org/IndexedDB-Import-Export/issues"},"homepage":"https://github.com/AOSSIE-Org/IndexedDB-Import-Export#readme","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"dependencies":{"idb":"^8.0.0"},"devDependencies":{"@eslint/js":"^10.0.1","eslint":"^10.5.0","happy-dom":"^20.9.0","prettier":"^3.0.0","tsup":"^8.0.0","typescript":"^5.5.0","typescript-eslint":"^8.61.1","vitest":"^4.1.9","fake-indexeddb":"^6.0.0"},"_id":"@aossie-org/idb-backup@1.0.1","gitHead":"368849d2e5b549760ced2b55d5053fc4305f00f5","_nodeVersion":"22.23.1","_npmVersion":"11.5.1","dist":{"integrity":"sha512-YBvXzxUdzPlHD8Ei2/oM62OHYN2S2ne/psHRZu3nIjVh3bYYQdSaBYSP0D06ZuY/wxqoYq36wkRc0iOLdNbIPQ==","shasum":"ecda9dd23b3217354ac512e900a7e6e6a880ba8f","tarball":"https://registry.npmjs.org/@aossie-org/idb-backup/-/idb-backup-1.0.1.tgz","fileCount":9,"unpackedSize":136133,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aossie-org%2fidb-backup@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIArY/Qu6y+DQuZeLPAatWIaP6hhg/d1p0Z2nxCqI+2FxAiAlv8tf2qLQszfVVCivx7YZge/lPQb1gyq3GiWX2+OqMg=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:d4807dcf-25bc-4a10-8051-1aa7720e8e31"}},"directories":{},"maintainers":[{"name":"zahnentferner","email":"zahnentferner@gmail.com"},{"name":"kpj2006","email":"24ucs074@lnmiit.ac.in"},{"name":"atharva0506","email":"atharvan.coder@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/idb-backup_1.0.1_1785927282738_0.19305263638454595"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-19T10:17:12.899Z","modified":"2026-08-05T10:54:43.237Z","1.0.0":"2026-06-19T10:17:13.243Z","1.0.1":"2026-08-05T10:54:42.881Z"},"bugs":{"url":"https://github.com/AOSSIE-Org/IndexedDB-Import-Export/issues"},"author":{"name":"AOSSIE"},"license":"GPL-3.0","homepage":"https://github.com/AOSSIE-Org/IndexedDB-Import-Export#readme","keywords":["indexeddb","backup","export","import","idb","json","browser","typescript"],"repository":{"type":"git","url":"git+https://github.com/AOSSIE-Org/IndexedDB-Import-Export.git"},"description":"A framework-agnostic, lightweight TypeScript library for exporting and importing IndexedDB databases via type-tagged JSON.","maintainers":[{"name":"zahnentferner","email":"zahnentferner@gmail.com"},{"name":"kpj2006","email":"24ucs074@lnmiit.ac.in"},{"name":"atharva0506","email":"atharvan.coder@gmail.com"}],"readme":"\n
\n\n\n
\n \"AOSSIE\"\n \n \n
\n\n \n\n\n
\n\n[![npm version](https://img.shields.io/npm/v/@aossie-org/idb-backup?style=for-the-badge&color=228B22)](https://www.npmjs.com/package/@aossie-org/idb-backup)\n[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue?style=for-the-badge)](LICENSE)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/AOSSIE-Org/IndexedDB-Import-Export/badge)](https://scorecard.dev/viewer/?uri=github.com/AOSSIE-Org/IndexedDB-Import-Export)\n\n
\n\n\n

\n\n\"Telegram\n  \n\n\"X\n  \n\n\"Discord\n  \n\n \"LinkedIn\n  \n\n \"Youtube\n

\n\n---\n\n
\n

@aossie-org/idb-backup

\n

A framework-agnostic, lightweight TypeScript library for exporting and importing IndexedDB databases via type-tagged JSON.

\n
\n\n---\n\n## What is this?\n\n`@aossie-org/idb-backup` provides a simple, portable way to **back up and restore IndexedDB databases** in the browser. It produces a self-describing JSON file that preserves data types that `JSON.stringify` normally corrupts — such as `Uint8Array`, `bigint`, and `Date`.\n\nThe library is designed to be **framework-agnostic**: it works in any browser environment and includes SSR safety guards for server-rendered frameworks like Next.js and Nuxt.\n\n---\n\n## Features\n\n- **Generic JSON export format** : Structured `schema` + `stores` mapping for portable, human-readable backups\n- **Type-tagged serialization** : Lossless round-trip for `Uint8Array`, `bigint`, and `Date` using a `__type` tag convention\n- **Import strategies** : Choose between `\"overwrite\"` (fresh restore) or `\"merge\"` (additive sync with existing data)\n- **SSR-safe** : Graceful no-op guards for server-side rendering environments\n- **Dual output** : Ships both ESM and CJS bundles\n- **Lightweight** : Uses the [`idb`](https://github.com/jakearchibald/idb) wrapper over the native IndexedDB API with no heavy dependencies\n\n---\n\n## Tech Stack\n\n| Category | Tools |\n| --- | --- |\n| Language | TypeScript 5 |\n| IndexedDB | Native API + [`idb`](https://github.com/jakearchibald/idb) wrapper |\n| Bundler | [`tsup`](https://tsup.egoist.dev/) (ESM + CJS) |\n| Testing | [`vitest`](https://vitest.dev/) + [`happy-dom`](https://github.com/nicedayfor/happy-dom) |\n| Linting | ESLint 9 + TypeScript ESLint |\n| Formatting | Prettier |\n\n---\n\n## Architecture\n\n```mermaid\ngraph TD\n A[\"@aossie-org/idb-backup\"] --> B[\"src/core\"]\n A --> C[\"src/serialization\"]\n A --> D[\"src/types\"]\n A --> E[\"src/utils\"]\n\n B --> B1[\"exporter.ts — exportDB()\"]\n B --> B2[\"importer.ts — importDB()\"]\n B --> B3[\"migrations.ts — future schema migrations\"]\n\n C --> C1[\"index.ts — serialize() / deserialize()\"]\n\n D --> D1[\"index.ts — ExportFormat, TaggedValue, etc.\"]\n\n E --> E1[\"ssr.ts — isBrowser(), assertBrowser()\"]\n E --> E2[\"file.ts — downloadJSON(), readFileAsJSON()\"]\n```\n\n---\n\n## Export Format\n\nThe library produces a self-describing JSON structure:\n\n```json\n{\n \"backupVersion\": 1,\n \"databaseName\": \"my-app-db\",\n \"databaseVersion\": 3,\n \"exportedAt\": \"2025-06-01T12:00:00.000Z\",\n \"schema\": {\n \"messages\": {\n \"keyPath\": \"id\",\n \"autoIncrement\": false,\n \"indexes\": [\n { \"name\": \"by-timestamp\", \"keyPath\": \"timestamp\", \"unique\": false }\n ]\n }\n },\n \"stores\": {\n \"messages\": [\n {\n \"key\": \"msg-001\",\n \"value\": {\n \"id\": \"msg-001\",\n \"payload\": { \"__type\": \"u8\", \"value\": \"SGVsbG8gV29ybGQ=\" },\n \"timestamp\": { \"__type\": \"date\", \"value\": \"2025-06-01T12:00:00.000Z\" },\n \"fee\": { \"__type\": \"bigint\", \"value\": \"1000000000000000000\" }\n }\n }\n ]\n }\n}\n```\n\n### Tagged Types\n\n| Source Type | `__type` | Serialized `value` |\n| --- | --- | --- |\n| `Uint8Array` | `\"u8\"` | Base64-encoded string |\n| `bigint` | `\"bigint\"` | String representation |\n| `Date` | `\"date\"` | ISO 8601 string |\n\nAll other JSON-safe values (strings, numbers, booleans, nulls, plain objects, arrays) pass through unchanged.\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org/) >= 20\n- npm (ships with Node.js)\n\n### Installation\n\n1. **Clone the repository**\n\n```bash\ngit clone https://github.com/AOSSIE-Org/IndexedDB-Import-Export.git\ncd IndexedDB-Import-Export\n```\n\n2. **Install dependencies**\n\n```bash\nnpm install\n```\n\n3. **Build the library**\n\n```bash\nnpm run build\n```\n\n4. **Run tests**\n\n```bash\nnpm test\n```\n\n### Available Scripts\n\n| Script | Description |\n| --- | --- |\n| `npm run build` | Bundle the library with tsup (ESM + CJS + type declarations) |\n| `npm test` | Run the test suite with Vitest |\n| `npm run test:watch` | Run tests in watch mode during development |\n| `npm run lint` | Lint source and test files with ESLint |\n| `npm run format` | Auto-format code with Prettier |\n| `npm run format:check` | Check formatting without modifying files |\n\n---\n\n## Usage\n\n> **Note:** The core API is under active development. The examples below show the intended usage once the feature PRs are merged.\n\n### Export a Database\n\n```typescript\nimport { exportDB } from '@aossie-org/idb-backup';\n\nconst backup = await exportDB({\n dbName: 'my-app-db',\n // Optional: export only specific stores\n storeNames: ['messages', 'contacts'],\n});\n\nconsole.log(JSON.stringify(backup, null, 2));\n```\n\n### Import a Database\n\n```typescript\nimport { importDB } from '@aossie-org/idb-backup';\n\n// Overwrite: delete existing data and restore from backup\nawait importDB({\n dbName: 'my-app-db',\n backupData: backup,\n strategy: 'overwrite',\n});\n\n// Merge: keep existing data and add/update from backup\nawait importDB({\n dbName: 'my-app-db',\n backupData: backup,\n strategy: 'merge',\n});\n```\n\n### Download as JSON File\n\n```typescript\nimport { downloadJSON } from '@aossie-org/idb-backup';\n\ndownloadJSON(backup, 'my-backup.json');\n```\n\n### Read a JSON Backup File\n\n```typescript\nimport { readFileAsJSON } from '@aossie-org/idb-backup';\n\nconst fileInput = document.querySelector('#file-input');\nconst file = fileInput!.files![0];\nconst backup = await readFileAsJSON(file);\n```\n\n---\n\n## Repository Links\n\n- [Main Repository](https://github.com/AOSSIE-Org/IndexedDB-Import-Export)\n- [Issue Tracker](https://github.com/AOSSIE-Org/IndexedDB-Import-Export/issues)\n\n---\n\n## Contributing\n\nContributions are welcome! If you would like to contribute, please refer to [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n---\n\n## Maintainers\n\n- [Atharva0506](https://github.com/Atharva0506)\n- [rohans02](https://github.com/rohans02)\n\n---\n\n## License\n\nThis project is licensed under the **GNU General Public License v3.0**.\nSee the [LICENSE](LICENSE) file for details.\n\n---\n\n## Contributors\n\nThanks to everyone who has contributed to this project.\n\n[![Contributors](https://contrib.rocks/image?repo=AOSSIE-Org/IndexedDB-Import-Export)](https://github.com/AOSSIE-Org/IndexedDB-Import-Export/graphs/contributors)\n\n© 2025 AOSSIE\n","readmeFilename":"README.md"}