ZenithDB Storage

Storage adapters and interfaces that provide a powerful wrapper around IndexedDB and other storage backends with a unified API for the ZenithDB database engine.

Description

@zenithdb/storage provides pluggable storage adapters that abstract different storage backends behind a common interface. The primary adapter wraps IndexedDB with enhanced features like automatic transaction management, optimized bulk operations, and schema migrations, while maintaining compatibility with the browser's native storage capabilities.

Installation

NPM

# Install storage package
npm install @zenithdb/storage @zenithdb/types

# Or install everything at once
npm install @zenithdb/kit

Note: For complete functionality, consider using @zenithdb/kit which includes all ZenithDB packages.

Quick Start

IndexedDB Adapter

import { IndexedDBAdapter } from "@zenithdb/storage";
import { createDatabase, createSchema, fields } from "@zenithdb/core";

// Create IndexedDB adapter
const adapter = new IndexedDBAdapter("myapp", {
  version: 1,
});

// Use with Zenith database
const schema = createSchema({
  name: "MyApp",
  version: 1,
  tables: {
    users: {
      primaryKey: "id",
      schema: {
        id: fields.string({ required: true }),
        name: fields.string({ required: true }),
        email: fields.string({ unique: true }),
      },
    },
  },
  adapter: "indexeddb",
});

const db = await createDatabase(schema);

Direct Adapter Usage

import { IndexedDBAdapter } from "@zenithdb/storage";

const adapter = new IndexedDBAdapter("direct-usage");

// Open connection
await adapter.open({
  name: "DirectDB",
  version: 1,
  tables: {
    items: {
      id: { type: "string", primaryKey: true },
      data: { type: "object" },
    },
  },
});

// Direct CRUD operations
await adapter.insert("items", {
  id: "item-1",
  data: { name: "Test Item" },
});

const item = await adapter.get("items", "item-1");
console.log("Retrieved item:", item);

// Bulk operations
await adapter.bulkInsert("items", [
  { id: "item-2", data: { name: "Bulk Item 1" } },
  { id: "item-3", data: { name: "Bulk Item 2" } },
]);

// Queries
const results = await adapter.find("items", {
  where: [{ field: "data.name", operator: "contains", value: "Bulk" }],
  orderBy: [{ field: "id", direction: "asc" }],
  limit: 10,
});

await adapter.close();

Custom Storage Adapter

import {
  StorageAdapter,
  DatabaseConfig,
  QueryOptions,
} from "@zenithdb/storage";

class CustomStorageAdapter implements StorageAdapter {
  async open(config: DatabaseConfig): Promise<void> {
    // Initialize your storage backend
    console.log("Opening custom storage:", config.name);
  }

  async close(): Promise<void> {
    // Cleanup connections
    console.log("Closing custom storage");
  }

  async insert(table: string, data: any): Promise<any> {
    // Implement insert logic
    return { ...data, _id: generateId() };
  }

  async get(table: string, key: any): Promise<any | null> {
    // Implement get logic
    return null;
  }

  async update(table: string, key: any, data: Partial<any>): Promise<any> {
    // Implement update logic
    return data;
  }

  async delete(table: string, key: any): Promise<boolean> {
    // Implement delete logic
    return true;
  }

  async find(table: string, options?: QueryOptions): Promise<any[]> {
    // Implement query logic
    return [];
  }

  async count(table: string, options?: QueryOptions): Promise<number> {
    // Implement count logic
    return 0;
  }

  async bulkInsert(table: string, items: any[]): Promise<any[]> {
    // Implement bulk insert logic
    return Promise.all(items.map((item) => this.insert(table, item)));
  }

  async beginTransaction(tables: string[]): Promise<any> {
    // Implement transaction begin
    return {};
  }

  async commitTransaction(transaction: any): Promise<void> {
    // Implement transaction commit
  }

  async rollbackTransaction(transaction: any): Promise<void> {
    // Implement transaction rollback
  }

  async createIndex(
    table: string,
    indexName: string,
    keyPath: string | string[],
    unique?: boolean,
  ): Promise<void> {
    // Implement index creation
  }

  async dropIndex(table: string, indexName: string): Promise<void> {
    // Implement index removal
  }
}

// Use custom adapter
const customAdapter = new CustomStorageAdapter();
const db = new Database({
  name: "CustomApp",
  version: 1,
  adapter: customAdapter,
  tables: {
    /* your schema */
  },
});

Storage Adapter Interface

All storage adapters implement the StorageAdapter interface:

interface StorageAdapter {
  // Database lifecycle
  open(config: DatabaseConfig): Promise<void>;
  close(): Promise<void>;

  // CRUD operations
  insert(table: string, data: any): Promise<any>;
  get(table: string, key: any): Promise<any | null>;
  update(table: string, key: any, data: Partial<any>): Promise<any>;
  delete(table: string, key: any): Promise<boolean>;

  // Query operations
  find(table: string, options?: QueryOptions): Promise<any[]>;
  count(table: string, options?: QueryOptions): Promise<number>;

  // Bulk operations
  bulkInsert(table: string, items: any[]): Promise<any[]>;
  bulkUpdate(
    table: string,
    updates: Array<{ key: any; data: Partial<any> }>,
  ): Promise<any[]>;
  bulkDelete(table: string, keys: any[]): Promise<boolean[]>;

  // Transaction management
  beginTransaction(tables: string[]): Promise<any>;
  commitTransaction(transaction: any): Promise<void>;
  rollbackTransaction(transaction: any): Promise<void>;

  // Index management
  createIndex(
    table: string,
    indexName: string,
    keyPath: string | string[],
    unique?: boolean,
  ): Promise<void>;
  dropIndex(table: string, indexName: string): Promise<void>;
}

Available Adapters

IndexedDBAdapter

The primary adapter that wraps IndexedDB with enhanced features:

• Full CRUD operations with automatic transaction management
• Complex queries with multiple conditions and sorting
• Bulk operations optimized for performance
• Schema migrations with version management
• Index management for query optimization
• Transaction support with rollback capabilities

Future Adapters

• SQLiteAdapter - For Node.js environments
• WebSQLAdapter - Legacy browser support