Dexie Logger Middleware

1.2.6 verified Thu Apr 23 auth: no javascript

Dexie Logger is a middleware for Dexie.js, a wrapper for IndexedDB, designed to provide enhanced debugging capabilities by logging database operations. Currently at version 1.2.6, it offers detailed insights into database interactions such as `mutate`, `get`, `query`, and `openCursor`. While a specific release cadence isn't published, the project includes future development ideas, indicating an active maintenance state. Its key differentiator lies in its deep integration with Dexie, allowing developers to filter logs based on specific tables and operation types using either a whitelist or a blacklist approach. This makes it a valuable tool for isolating and debugging complex data flow issues within Dexie-backed applications, improving development efficiency and understanding of IndexedDB transactions.

Common errors

error TypeError: db.use is not a function ↓

cause The `db` variable or object you are attempting to apply the middleware to is not a valid Dexie instance.

fix

Ensure you have correctly initialized your Dexie database, e.g., const db = new Dexie("MyDatabase"); and that you are calling db.use() on this instance.

error Logs not appearing in console (but operations are succeeding) ↓

cause The logger's `tableWhiteList`, `tablesBlackList`, `operationsWhiteList`, or `operationsBlackList` configuration is too restrictive or incorrectly set, filtering out the operations you expect to see.

fix

Review the logger configuration passed to db.use(logger({ ... })). Temporarily remove all filters or broaden them to confirm the logger is working, then progressively re-apply filters to identify the specific rule preventing logs.

error ReferenceError: logger is not defined ↓

cause This typically occurs in CommonJS environments (like older Node.js scripts or build setups without proper ESM transpilation) when trying to use `import logger from 'dexie-logger';`.

fix

Ensure your project supports ES Modules (ESM) or use a transpiler like Babel or TypeScript to convert ESM imports. If strictly in CommonJS and no transpilation, consider if the library offers a CommonJS export (though dexie-logger is primarily ESM-first).

Warnings

gotcha When configuring the logger, ensure you use either a whitelist OR a blacklist for tables and operations, but not both simultaneously for the same type. For example, using both `tableWhiteList` and `tablesBlackList` can lead to unexpected logging behavior as the options are mutually exclusive. ↓

fix Choose `tableWhiteList` or `tablesBlackList` (not both), and `operationsWhiteList` or `operationsBlackList` (not both) to define your logging scope.

gotcha Applying the logger middleware can introduce a slight performance overhead, especially in applications with very high-frequency database operations or large data volumes. While generally negligible for typical debugging, be mindful of its impact in performance-critical sections. ↓

fix For production builds or performance-sensitive environments, consider disabling the logger or only enabling it conditionally during development or specific debugging sessions.

Install

npm install dexie-logger

yarn add dexie-logger

pnpm add dexie-logger

Imports

logger
wrong
```
const logger = require('dexie-logger');
```
correct
```
import logger from 'dexie-logger';
```
The logger function is exported as the default export. Requires ESM or a transpiler for CommonJS environments.

Quickstart

Initializes a Dexie database, applies the logger middleware with specific table and operation filters, and performs database operations to demonstrate logging output in the console.

import Dexie, { Table } from 'dexie';
import logger from 'dexie-logger';

// Define your database schema
interface Event {
  id?: number;
  name: string;
  timestamp: Date;
}

interface User {
  id?: number;
  name: string;
  email: string;
}

class MyDatabase extends Dexie {
  events!: Table<Event>;
  users!: Table<User>;

  constructor() {
    super("MyDebuggerDatabase");
    this.version(1).stores({
      events: "++id, name, timestamp",
      users: "++id, name, email"
    });
  }
}

const db = new MyDatabase();

// Apply the logger middleware with specific filters
db.use(
  logger({
    tableWhiteList: ["events"], // Only log operations on the 'events' table
    operationsWhiteList: ["mutate", "get"], // Only log 'mutate' (add/update/delete) and 'get' operations
  })
);

async function runExample() {
  try {
    console.log("Applying Dexie Logger middleware...");

    // Perform some operations to trigger logs
    await db.events.add({ name: "App Started", timestamp: new Date() });
    await db.events.add({ name: "User Session Begin", timestamp: new Date() });
    await db.users.add({ name: "John Doe", email: "john@example.com" }); // This operation on 'users' table will NOT be logged due to tableWhiteList

    const firstEvent = await db.events.get(1); // This 'get' operation will be logged
    console.log("Retrieved event:", firstEvent);

    await db.events.put({ id: firstEvent?.id, name: "App Updated", timestamp: new Date() }); // This 'mutate' operation will be logged

    console.log("Check your browser's developer console for Dexie Logger output.");

  } catch (error) {
    console.error("Database operation failed:", error);
  }
}

runExample();