Redux Database

Common errors

• Property 'xyz' does not exist on type 'DataTables<State>'

  cause Attempting to access a table or setting that is not defined in the database schema (`interface State`). TypeScript correctly identifies this as a type error.
  fix Ensure your database schema (`interface State`) correctly defines all tables under the `data` key and settings under the `settings` key before attempting to access them via `db.table('xyz')` or `db.get('xyz')`.

• Argument of type '{ name: string; }' is not assignable to parameter of type 'Item'. Property 'id' is missing in type '{ name: string; }' but required in type 'Item'.

  cause Attempting to insert a new record into a table without providing the required `id` property, assuming the model interface requires it.
  fix Ensure that any object passed to `insert()` or `update()` methods strictly conforms to the TypeScript interface defined for that table's model, including all required properties like `id`.

Warnings

• gotcha Directly dispatching many individual write actions (insert, update, delete) can lead to significant performance degradation in UIs that observe state mutations frequently, as each dispatch triggers listeners.
  Fix: Always wrap multiple write operations within a transaction using `db.transaction((dispatch) => { ... })` to ensure a single Redux action is dispatched for all changes, optimizing performance.
• gotcha Although `redux-database` integrates with Redux, it operates with immutable state internally. Direct mutations to objects retrieved from a `DB` instance (e.g., `db.table('items').find('id')`) will not be reflected in the Redux store and can lead to desynchronization.
  Fix: Always use the provided write methods (e.g., `db.table('items').insert()`, `update()`, `delete()`, `db.set()`) on `DB` or table instances. These methods return Redux actions that must be dispatched to correctly update the immutable state.
• gotcha The `DB` instance represents a snapshot of the database state at the time of its creation. If the underlying Redux store's database state changes (e.g., after a dispatch), the existing `DB` instance will be stale and will not reflect the latest data.
  Fix: After any state update that affects the database slice of your Redux store, create a new `DB` instance from the updated store state: `db = new DB(store.getState().db);`.

Install

• npm install redux-database npm
• yarn add redux-database yarn
• pnpm add redux-database pnpm

Imports

• DB
  wrong:

  const { DB } = require('redux-database');

  correct:

  import { DB } from 'redux-database';

  The primary class for interacting with the database state.
• emptyTable
  wrong:

  const emptyTable = require('redux-database').emptyTable;

  correct:

  import { emptyTable } from 'redux-database';

  Utility constant for initializing an empty data table in your schema.
• createDatabaseReducer
  wrong:

  import { databaseReducer } from 'redux-database';

  correct:

  import { createDatabaseReducer } from 'redux-database';

  The function to create a Redux reducer that handles database actions. It's a named export, not a default.
• DataTable

  import type { DataTable } from 'redux-database';

  This is a TypeScript type definition, imported using 'import type'.

Quickstart

Demonstrates defining a database schema, initializing a Redux store with the database reducer, performing transactional writes, and executing chainable queries including embedded relations.

import { createStore, combineReducers } from 'redux';
import { DB, emptyTable, createDatabaseReducer } from 'redux-database';

interface Item { id: string; name: string; categoryId?: string; }
interface Category { id: string; name: string; }

interface AppState {
  settings: { enableFeatureX: boolean; };
  data: {
    items: DataTable<Item>;
    categories: DataTable<Category>;
  };
}

const initialState: AppState = {
  settings: {
    enableFeatureX: true
  },
  data: {
    items: emptyTable,
    categories: emptyTable
  }
};

// Create the database reducer
const databaseReducer = createDatabaseReducer(initialState);

// Combine with other Redux reducers if any
const rootReducer = combineReducers({
  db: databaseReducer
});

const store = createStore(rootReducer);

// Get a DB instance from the current state
let db = new DB(store.getState().db);

// Example: Writing data using a transaction
store.dispatch(
  db.transaction((dispatch) => {
    dispatch(db.table('categories').insert({ id: 'cat1', name: 'Electronics' }));
    dispatch(db.table('items').insert({ id: 'item1', name: 'Laptop', categoryId: 'cat1' }));
    dispatch(db.table('items').insert({ id: 'item2', name: 'Mouse', categoryId: 'cat1' }));
    dispatch(db.set('enableFeatureX', false));
  })
);

// Refresh DB instance after state update
db = new DB(store.getState().db);

// Example: Reading data
console.log('Feature X enabled:', db.get('enableFeatureX'));

const allItems = db.table('items').all;
console.log('All Items:', allItems);

const electronicsItems = db
  .query('items')
  .where({ categoryId: 'cat1' })
  .embed('category', 'categories', 'categoryId')
  .all;

console.log('Electronics Items with Category:', electronicsItems);

// Update an item
store.dispatch(db.table('items').update('item1', { name: 'Gaming Laptop' }));

db = new DB(store.getState().db);
console.log('Updated Laptop:', db.table('items').find('item1'));