{"_id":"@eduardobuzzi/easyindexeddb","_rev":"3-662ae6e15db3a8ddf419fbd730bf8229","name":"@eduardobuzzi/easyindexeddb","dist-tags":{"latest":"2.0.1"},"versions":{"1.0.0":{"name":"@eduardobuzzi/easyindexeddb","version":"1.0.0","keywords":["indexeddb","javascript","nosql","database","storage"],"author":{"name":"Eduardo Gabriel Buzzi"},"license":"MIT","_id":"@eduardobuzzi/easyindexeddb@1.0.0","maintainers":[{"name":"eduardobuzzi","email":"eduardogabrielbuzzi@gmail.com"}],"dist":{"shasum":"ae9955813419f9d46b5341507e5a73bc63776ab2","tarball":"https://registry.npmjs.org/@eduardobuzzi/easyindexeddb/-/easyindexeddb-1.0.0.tgz","fileCount":2,"integrity":"sha512-qwR00KATBXsMZNOKAXGhcXPaeXin+UOXZUBZPdn9EKZNmo/ker3i8Yrvbf/oTkxo6wkmrSNa9E1tkmWU+GP3Sg==","signatures":[{"sig":"MEYCIQCg5d/vsy9jQUppOBVysrZfhMKjn5J3nr8ohJgIhF/2EwIhALoILy6GQFf4FJ/qNLQvBPpPa3X3m5vgPI0kdULwxae9","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":51432},"main":"EasyIndexedDB.js","type":"module","_npmUser":{"name":"eduardobuzzi","email":"eduardogabrielbuzzi@gmail.com"},"_npmVersion":"10.2.3","description":"An easy, simple, and uncomplicated library to handle data with IndexedDB, the JavaScript NoSQL database.","directories":{},"_nodeVersion":"20.10.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/easyindexeddb_1.0.0_1739830933816_0.30578225266330805","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@eduardobuzzi/easyindexeddb","version":"2.0.0","keywords":["indexeddb","javascript","nosql","database","storage"],"author":{"name":"Eduardo Gabriel Buzzi"},"license":"MIT","_id":"@eduardobuzzi/easyindexeddb@2.0.0","maintainers":[{"name":"eduardobuzzi","email":"eduardogabrielbuzzi@gmail.com"}],"dist":{"shasum":"4b65784677fedc47517fd69aba3cddbf498afe45","tarball":"https://registry.npmjs.org/@eduardobuzzi/easyindexeddb/-/easyindexeddb-2.0.0.tgz","fileCount":4,"integrity":"sha512-wlxGvfG873tbn6FoWK0BdhfM4bqeBNcRDHh64ufI+wpmd1yxaoeH0M1CgKIYr+3e8QD3K/fDbx05UrfE4g83kA==","signatures":[{"sig":"MEQCIDzolZpG59a0CblJtSSPCovRLqQZPckkxIpHNbwjrLfaAiBXC2pcvQbt+N7mztFE/ogpTCvqTuFXsa8Tg15MPGVUJA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":40435},"main":"EasyIndexedDB.js","type":"module","gitHead":"e387eb6fab92736de3cb86a0b420d875aba2ac12","_npmUser":{"name":"eduardobuzzi","email":"eduardogabrielbuzzi@gmail.com"},"_npmVersion":"10.2.3","description":"An easy, simple, and uncomplicated library to handle data with IndexedDB, the JavaScript NoSQL database.","directories":{},"_nodeVersion":"20.10.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/easyindexeddb_2.0.0_1753042475775_0.9203384736068452","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"@eduardobuzzi/easyindexeddb","version":"2.0.1","description":"An easy, simple, and uncomplicated library to handle data with IndexedDB, the JavaScript NoSQL database.","main":"EasyIndexedDB.js","type":"module","keywords":["indexeddb","javascript","nosql","database","storage"],"author":{"name":"Eduardo Gabriel Buzzi"},"license":"MIT","_id":"@eduardobuzzi/easyindexeddb@2.0.1","gitHead":"e387eb6fab92736de3cb86a0b420d875aba2ac12","_nodeVersion":"20.10.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-VLVqyx27vm0XgxWKFqZLXVs0IiofY1eVOvDX7KQNwj5HvJl4QCXxDQJt3WzlwH/RweqKeTpZF9a/GnrXHQ/O6A==","shasum":"5be35ae26e6958ab33800b53da5b255cd40a4aeb","tarball":"https://registry.npmjs.org/@eduardobuzzi/easyindexeddb/-/easyindexeddb-2.0.1.tgz","fileCount":4,"unpackedSize":40094,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDFb+wj1s9k3+OGyGxZoqCR12F/paiXgaqGidBSgCAeDwIhAIQJjB70LKjypbYBsmg38oXSov2XrcHrVOCQdJCVSSaP"}]},"_npmUser":{"name":"eduardobuzzi","email":"eduardogabrielbuzzi@gmail.com"},"directories":{},"maintainers":[{"name":"eduardobuzzi","email":"eduardogabrielbuzzi@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/easyindexeddb_2.0.1_1753044588600_0.5309113983332681"},"_hasShrinkwrap":false}},"time":{"created":"2025-02-17T22:22:13.726Z","modified":"2025-07-20T20:49:49.036Z","1.0.0":"2025-02-17T22:22:13.986Z","2.0.0":"2025-07-20T20:14:35.956Z","2.0.1":"2025-07-20T20:49:48.782Z"},"author":{"name":"Eduardo Gabriel Buzzi"},"license":"MIT","keywords":["indexeddb","javascript","nosql","database","storage"],"description":"An easy, simple, and uncomplicated library to handle data with IndexedDB, the JavaScript NoSQL database.","maintainers":[{"name":"eduardobuzzi","email":"eduardogabrielbuzzi@gmail.com"}],"readme":"# EasyIndexedDB\r\n\r\nA modern, robust, and promise-based wrapper for IndexedDB, designed to provide a safe and intuitive developer experience.\r\n\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n\r\n## Table of Contents\r\n- [Overview](#overview)\r\n- [Features](#features)\r\n- [Installation](#installation)\r\n  - [NPM](#npm)\r\n  - [Direct Download](#direct-download)\r\n- [Usage](#usage)\r\n  - [Basic Usage](#basic-usage)\r\n  - [Database Operations](#database-operations)\r\n  - [Object Store Operations](#object-store-operations)\r\n  - [Data Operations](#data-operations)\r\n  - [Utility Methods](#utility-methods)\r\n- [API Reference](#api-reference)\r\n- [Examples](#examples)\r\n- [Error Handling](#error-handling)\r\n- [Contributing](#contributing)\r\n- [License](#license)\r\n\r\n## Overview\r\n\r\nEasyIndexedDB is a modern JavaScript library that abstracts away the complexities and pitfalls of raw IndexedDB. It provides a clean, promise-based API that makes database operations intuitive, safe, and efficient. This library is designed for developers who want the power of IndexedDB without the verbose and error-prone boilerplate.\r\n\r\n## Features\r\n\r\n-   **Intuitive, Promise-Based API**: All operations are asynchronous and use modern `async/await` syntax.\r\n-   **Safe, Atomic Schema Migrations**: Create, delete, and update Object Stores and indexes in a single, safe transaction.\r\n-   **Robust Error Handling**: Provides clear error messages and handles common issues like connection blocking.\r\n-   **Automatic Version Management**: The library handles database versioning automatically when the schema changes.\r\n-   **Efficient Data Operations**: Methods for inserting, selecting, updating, and deleting data, including bulk operations.\r\n-   **Timezone-Aware Date Tracking**: Automatically tracks the last modification date of the database schema.\r\n-   **Modern JavaScript**: Built with ES Modules, private class fields, and modern syntax.\r\n-   **Zero Dependencies**: A lightweight, standalone library.\r\n\r\n## Installation\r\n\r\n### NPM\r\n```bash\r\nnpm install @eduardobuzzi/easyindexeddb\r\n```\r\n\r\n### Direct Download\r\n\r\nYou can download the `EasyIndexedDB.js` file and include it directly in your project.\r\n\r\n1.  Download the `EasyIndexedDB.js` file from this repository.\r\n2.  Include it in your HTML using a script tag with `type=\"module\"`.\r\n\r\n```html\r\n<!DOCTYPE html>\r\n<html>\r\n<head>\r\n    <title>EasyIndexedDB Example</title>\r\n</head>\r\n<body>\r\n    <script type=\"module\">\r\n        import EasyIndexedDB from \"./path/to/EasyIndexedDB.js\";\r\n        \r\n        const db = new EasyIndexedDB();\r\n        \r\n        async function run() {\r\n            try {\r\n                await db.initialize(\"my-app-database\");\r\n                console.log(\"Database initialized successfully!\");\r\n            } catch (error) {\r\n                console.error(\"Initialization failed:\", error);\r\n            }\r\n        }\r\n\r\n        run();\r\n    </script>\r\n</body>\r\n</html>\r\n```\r\n\r\n## Usage\r\n\r\n### Basic Usage\r\n\r\n```javascript\r\nimport EasyIndexedDB from \"@eduardobuzzi/easyindexeddb\";\r\n\r\nconst db = new EasyIndexedDB();\r\n\r\n// 1. Initialize the database\r\nawait db.initialize(\"myDatabase\");\r\n\r\n// 2. Create an object store with indexes\r\nawait db.createObjectStore(\"users\", [\r\n    { name: \"email\", unique: true },\r\n    { name: \"age\", unique: false }\r\n]);\r\n\r\n// 3. Insert data\r\nconst newKey = await db.insertDataObjectStore(\"users\", {\r\n    email: \"john.doe@example.com\",\r\n    name: \"John Doe\",\r\n    age: 30\r\n});\r\n\r\nconsole.log(`New user added with key: ${newKey}`);\r\n```\r\n\r\n### Database Operations\r\n\r\n#### Initialize Database\r\n```javascript\r\n// Initialize with automatic versioning\r\nawait db.initialize(\"myDatabase\");\r\n\r\n// Initialize with a specific version (triggers upgrade if needed)\r\nawait db.initialize(\"myDatabase\", 2);\r\n```\r\n\r\n#### Delete Database\r\n```javascript\r\n// Delete the database initialized with the instance\r\nawait db.delete();\r\n\r\n// Or delete a database by name\r\nawait db.delete(\"otherDatabase\");\r\n```\r\n\r\n### Object Store Operations\r\n\r\n#### Create Object Store\r\n```javascript\r\nawait db.createObjectStore(\"products\", [\r\n    { name: \"sku\", unique: true },\r\n    { name: \"category\", unique: false }\r\n]);\r\n```\r\n\r\n#### Delete Object Store\r\n```javascript\r\nawait db.deleteObjectStore(\"products\");\r\n```\r\n\r\n#### Update Object Store Structure\r\n```javascript\r\n// Add a new index\r\nconst indexesToAdd = [{ name: \"last_login\", unique: false }];\r\n\r\n// Remove an existing index\r\nconst indexesToRemove = [\"age\"];\r\n\r\n// Rename an index (data is automatically migrated)\r\nconst indexesToRename = [{ oldName: \"email\", newName: \"userEmail\", unique: true }];\r\n\r\nawait db.updateStructureObjectStore(\r\n    \"users\",\r\n    indexesToAdd,\r\n    indexesToRemove,\r\n    indexesToRename\r\n);\r\n```\r\n\r\n### Data Operations\r\n\r\n#### Insert Data\r\n```javascript\r\n// Insert a single record\r\nconst key = await db.insertDataObjectStore(\"users\", {\r\n    email: \"jane.doe@example.com\",\r\n    age: 28\r\n});\r\n\r\n// Insert multiple records in one transaction\r\nawait db.insertMultipleDataObjectStore(\"users\", [\r\n    { email: \"user1@example.com\", age: 45 },\r\n    { email: \"user2@example.com\", age: 32 }\r\n]);\r\n```\r\n\r\n#### Select Data\r\n```javascript\r\n// Select a single record by its index\r\nconst user = await db.selectDataObjectStore(\"users\", \"email\", \"jane.doe@example.com\");\r\n\r\n// Select only specific fields from a record\r\nconst userAge = await db.selectDataObjectStore(\r\n    \"users\",\r\n    \"email\",\r\n    \"jane.doe@example.com\",\r\n    [\"age\"] // Returns { age: 28 }\r\n);\r\n\r\n// Select all records from an object store\r\nconst allUsers = await db.selectAllDataObjectStore(\"users\");\r\n```\r\n\r\n#### Update Data\r\n```javascript\r\n// Update a specific field based on a query\r\nawait db.updateDataObjectStore(\r\n    \"users\",\r\n    \"email\", // find records where 'email' is...\r\n    \"jane.doe@example.com\", // ...this value\r\n    \"jane.d@new-domain.com\" // and update the 'email' field to this new value\r\n);\r\n\r\n// Update multiple fields on a found record\r\nawait db.updateDataObjectStore(\r\n    \"users\",\r\n    \"email\", // find records where 'email' is...\r\n    \"jane.d@new-domain.com\", // ...this value\r\n    null, // We don't want to change the 'email' field itself\r\n    false, // Set the 4th parameter to false\r\n    [\r\n        { index: \"age\", value: 29 },\r\n        { index: \"last_login\", value: new Date() }\r\n    ] // ...and update these other fields\r\n);\r\n```\r\n\r\n#### Delete Data\r\n```javascript\r\n// Delete the first record matching the query\r\nawait db.deleteDataObjectStore(\"users\", \"email\", \"user1@example.com\");\r\n\r\n// Delete ALL records matching the query (useful for non-unique indexes)\r\nawait db.deleteDataObjectStore(\"users\", \"age\", 32, true);\r\n\r\n// Delete all records in an object store\r\nawait db.deleteAllDataObjectStore(\"users\");\r\n\r\n// Alias for deleteAllDataObjectStore\r\nawait db.cleanObjectStore(\"users\");\r\n```\r\n\r\n### Utility Methods\r\n\r\n#### Last Modification Date\r\n```javascript\r\n// Get the timestamp of the last schema change\r\nconst lastModified = await db.getLastModifyDateDatabase();\r\nconsole.log(`Database schema last modified on: ${lastModified}`);\r\n\r\n// Change the timezone for date tracking (default is \"America/Sao_Paulo\")\r\ndb.setTimezoneLastModifyDate(\"UTC\");\r\n\r\n// Change the name of the internal object store used for tracking\r\ndb.setObjectStoreNameLastModifyDate(\"__myAppLastModified\");\r\n```\r\n\r\n## API Reference\r\n\r\n### Database Methods\r\n- `initialize(databaseName, [databaseVersion])`: Initializes the database.\r\n- `delete([databaseName])`: Deletes a database.\r\n\r\n### Object Store Methods\r\n- `createObjectStore(name, [indexes])`: Creates a new Object Store.\r\n- `deleteObjectStore(name)`: Deletes an Object Store.\r\n- `updateStructureObjectStore(name, [indexesToAdd], [indexesToRemove], [indexesToRename])`: Updates the schema of an Object Store.\r\n- `cleanObjectStore(name)`: Removes all data from an Object Store.\r\n\r\n### Data Methods\r\n- `insertDataObjectStore(storeName, data)`: Inserts a single record. Returns the new record's key.\r\n- `insertMultipleDataObjectStore(storeName, dataArray)`: Inserts multiple records.\r\n- `selectDataObjectStore(storeName, indexName, value, [fields])`: Selects a single record.\r\n- `selectAllDataObjectStore(storeName, [fields])`: Selects all records.\r\n- `updateDataObjectStore(storeName, index, currentValue, newValue, [changeCurrent], [updates])`: Updates records matching a query.\r\n- `deleteDataObjectStore(storeName, indexName, value, [deleteAllOccurrences])`: Deletes records matching a query.\r\n- `deleteAllDataObjectStore(storeName)`: Deletes all data in an Object Store.\r\n\r\n### Utility Methods\r\n- `getLastModifyDateDatabase()`: Gets the timestamp of the last schema modification.\r\n- `setTimezoneLastModifyDate(timezone)`: Sets the timezone for date tracking.\r\n- `setObjectStoreNameLastModifyDate(name)`: Sets the name of the internal tracking store.\r\n\r\n## Examples\r\n\r\n### Complete User Management Flow\r\n```javascript\r\nimport EasyIndexedDB from \"./EasyIndexedDB.js\";\r\n\r\nasync function runUserManagementDemo() {\r\n    const db = new EasyIndexedDB();\r\n    \r\n    try {\r\n        // Initialize\r\n        await db.initialize(\"user-app-db\");\r\n        \r\n        // Create store if it doesn't exist\r\n        await db.createObjectStore(\"users\", [\r\n            { name: \"email\", unique: true },\r\n            { name: \"username\", unique: true },\r\n            { name: \"age\", unique: false }\r\n        ]);\r\n    \r\n        // Add users in a batch\r\n        await db.insertMultipleDataObjectStore(\"users\", [\r\n            { email: \"alpha@example.com\", username: \"alpha\", age: 35 },\r\n            { email: \"beta@example.com\", username: \"beta\", age: 40 }\r\n        ]);\r\n        \r\n        // Query all users\r\n        const allUsers = await db.selectAllDataObjectStore(\"users\");\r\n        console.log(\"All users:\", allUsers);\r\n        \r\n        // Update a user's age\r\n        await db.updateDataObjectStore(\r\n            \"users\", \"username\", \"alpha\", null, false,\r\n            [{ index: \"age\", value: 36 }]\r\n        );\r\n        \r\n        // Get the updated user\r\n        const alphaUser = await db.selectDataObjectStore(\"users\", \"username\", \"alpha\");\r\n        console.log(\"Alpha's updated record:\", alphaUser);\r\n\r\n    } catch (error) {\r\n        console.error(\"An error occurred during the demo:\", error);\r\n    }\r\n}\r\n\r\nrunUserManagementDemo();\r\n```\r\n\r\n## Error Handling\r\n\r\nAll methods are promise-based and will `reject` on failure. Use `try...catch` blocks with `async/await` for clean error handling.\r\n\r\n```javascript\r\ntry {\r\n    await db.initialize(\"myDatabase\");\r\n    await db.createObjectStore(\"products\", [{ name: \"sku\", unique: true }]);\r\n    await db.insertDataObjectStore(\"products\", { sku: \"123\", name: \"My Product\" });\r\n} catch (error) {\r\n    console.error(\"Database operation failed:\", error.message);\r\n}\r\n```\r\n\r\nCommon error cases to handle:\r\n-   **Browser Incompatibility**: The browser does not support IndexedDB.\r\n-   **Connection Blocked**: Another tab has an open connection to the database that is preventing a version upgrade.\r\n-   **Constraint Errors**: Trying to insert data that violates a `unique` index constraint.\r\n-   **Invalid Parameters**: Passing incorrect types or missing required parameters.\r\n-   **Non-existent Stores/Indexes**: Attempting to operate on a store or index that does not exist.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/edubuzzi/EasyIndexedDB/blob/main/LICENSE) file for details.\r\n\r\n---\r\n\r\nCreated by [Eduardo Gabriel Buzzi](https://github.com/edubuzzi)\r\n","readmeFilename":"README.md"}