IndexedDB Export/Import Utility

Common errors

• TypeError: Cannot read properties of undefined (reading 'length') OR Database doesn't have object store: 'storeName'

  cause Attempting to import JSON data where some keys in the JSON do not correspond to existing object store names in the IndexedDB database, or vice versa, especially in older versions.
  fix Ensure the JSON structure exactly matches the object store names in your `IDBDatabase`. Upgrade to `indexeddb-export-import@2.1.5` or later to mitigate issues with missing/extra keys.

• ReferenceError: require is not defined (in browser)

  cause Attempting to use CommonJS `require` syntax in a browser environment without a module bundler like Webpack or Rollup.
  fix For browser usage without a bundler, include the library via a `<script>` tag. If using a bundler, configure it to handle CommonJS modules or use ES module `import` syntax if your project supports it.

Warnings

• breaking Version 2.0.0 introduced a requirement for ES6, meaning Node.js 8+ or a modern browser. If you need to support older environments (like ES5), you must use a transpiler or stick with the v1.x series of this package.
  Fix: Upgrade your Node.js runtime to version 8 or higher, or ensure your browser environment supports ES6. If targeting ES5, consider using Babel or downgrade to a v1.x version of `indexeddb-export-import`.
• gotcha Prior to v2.1.3 and v2.1.5, importing JSON data could lead to bugs if the import JSON structure had keys that did not exactly match the existing object store names in the IndexedDB database. This could result in data not being imported correctly or errors during the process.
  Fix: Update to version 2.1.5 or later to ensure robust handling of object store key mismatches during import. This version fixes issues where import JSON is missing keys or contains keys not present as object store names.
• gotcha The `importFromJsonString` function does not delete any existing data in the database before importing. If you import data into a non-empty database, keys could clash, potentially leading to errors or unexpected data merges.
  Fix: If you intend to completely restore a database or prevent key clashes, always call `clearDatabase` before `importFromJsonString`. Ensure your application logic handles potential key conflicts if partial imports are desired.
• breaking Version 2.0.0 removed all external dependencies, reducing package size and simplifying the dependency tree. While beneficial, this change means any previously implicitly relied-upon transitive dependencies are no longer present.
  Fix: No direct fix needed unless your project implicitly relied on a removed transitive dependency. This is primarily an internal architecture change with positive effects.

Install

• npm install indexeddb-export-import npm
• yarn add indexeddb-export-import yarn
• pnpm add indexeddb-export-import pnpm

Imports

• IDBExportImport
  wrong:

  const IDBExportImport = require('indexeddb-export-import');

  correct:

  import * as IDBExportImport from 'indexeddb-export-import';

  While CommonJS `require` works, the package is primarily ES module focused since v2.0.0, so named imports or `import * as` is the recommended modern approach.
• exportToJsonString
  wrong:

  const { exportToJsonString } = require('indexeddb-export-import');

  correct:

  import { exportToJsonString } from 'indexeddb-export-import';

  The functions are exported as named members of the module. Direct destructuring `const { func } = require()` is a valid CommonJS pattern, but `import { func } from '...'` is preferred for ESM.
• importFromJsonString

  import { importFromJsonString } from 'indexeddb-export-import';

  Used for restoring database content from a JSON string.

Quickstart

This example demonstrates how to export an IndexedDB database to a JSON string, clear all its object stores, and then re-import the data from the previously exported JSON string. It uses Dexie.js to manage the IndexedDB connection for convenience, which is a common pattern for obtaining an `IDBDatabase` instance.

import Dexie from 'dexie';
import { exportToJsonString, clearDatabase, importFromJsonString } from 'indexeddb-export-import';

const db = new Dexie('MyDB');
db.version(1).stores({
  things: 'id++, thing_name, thing_description'
});

db.open().then(function() {
  // Dexie.js provides a convenient way to get the native IDBDatabase object
  const idbDatabase = db.backendDB(); 

  // Export to JSON, clear database, and then import from JSON
  exportToJsonString(idbDatabase, function(err, jsonString) {
    if (err) {
      console.error('Error exporting:', err);
      return;
    }
    console.log('Exported as JSON:', jsonString.substring(0, 100) + '...'); // Log a snippet
    
    clearDatabase(idbDatabase, function(err) {
      if (err) {
        console.error('Error clearing database:', err);
        return;
      }
      console.log('Database cleared successfully.');
      
      importFromJsonString(idbDatabase, jsonString, function(err) {
        if (err) {
          console.error('Error importing:', err);
          return;
        }
        console.log('Data imported successfully.');
        // You can now verify the data is back in the DB
        db.table('things').count().then(count => {
          console.log(`Things in DB after import: ${count}`);
        });
      });
    });
  });
}).catch(function(e) {
  console.error('Could not connect to IndexedDB: ' + e);
});