# Adapters

Adapters take a core functionality of the database and replace its internals with different implementations. They are essentially plugins for specific tasks.

Tool Db has three types of adapters:

Network Adapters — Handle peer connections and message routing
Storage Adapters — Handle data persistence
User Adapters — Handle authentication and key management

# Network Adapters

Network adapters handle the connection layer between peers.

# WebSocket Network (`websocket-network`)

The WebSocket adapter creates connections between peers and shares server peer information throughout the network. You'll need at least one server peer to act as a bootstrap node.

npm install @tool-db/websocket-network

import { ToolDb } from "tool-db";
import ToolDbWebsocket from "@tool-db/websocket-network";

const db = new ToolDb({
  networkAdapter: ToolDbWebsocket,
  server: true,
  host: "localhost",
  port: 9000,
});

# WebRTC Network (`webrtc-network`)

The WebRTC adapter creates a mesh network between peers using WebRTC and WebTorrent trackers for peer discovery. This allows browsers to connect directly to each other without a central server.

npm install @tool-db/webrtc-network

import { ToolDb } from "tool-db";
import ToolDbWebrtc from "@tool-db/webrtc-network";

const db = new ToolDb({
  networkAdapter: ToolDbWebrtc,
  topic: "my-app-topic",
});

Features:

Browser-to-browser P2P connections
Automatic peer discovery via WebTorrent trackers
Works in Node.js with the wrtc package
Exponential backoff reconnection
Online/offline network awareness

# Hybrid Network (`hybrid-network`)

Combines multiple network transports for maximum connectivity.

npm install @tool-db/hybrid-network

import { ToolDb } from "tool-db";
import ToolDbHybrid from "@tool-db/hybrid-network";

const db = new ToolDb({
  networkAdapter: ToolDbHybrid,
});

# Storage Adapters

Storage adapters handle how data is persisted locally.

# LevelDB Store (`leveldb-store`)

For Node.js server environments:

npm install @tool-db/leveldb-store

import { ToolDb } from "tool-db";
import ToolDbLeveldb from "@tool-db/leveldb-store";

const db = new ToolDb({
  storageAdapter: ToolDbLeveldb,
  storageName: "my-database",
});

# IndexedDB Store (`indexeddb-store`)

For browser environments:

npm install @tool-db/indexeddb-store

import { ToolDb } from "tool-db";
import ToolDbIndexeddb from "@tool-db/indexeddb-store";

const db = new ToolDb({
  storageAdapter: ToolDbIndexeddb,
  storageName: "my-database",
});

# Redis Store (`redis-store`)

For server deployments requiring shared storage:

npm install @tool-db/redis-store

import { ToolDb } from "tool-db";
import ToolDbRedis from "@tool-db/redis-store";

const db = new ToolDb({
  storageAdapter: ToolDbRedis,
  // Configure via modules option
  modules: {
    redis: {
      url: "redis://localhost:6379"
    }
  }
});

# User Adapters

User adapters handle authentication and cryptographic operations.

# ECDSA User (`ecdsa-user`)

The default ECDSA-based user authentication using Web Crypto API:

npm install @tool-db/ecdsa-user

import { ToolDb } from "tool-db";
import EcdsaUser from "@tool-db/ecdsa-user";

const db = new ToolDb({
  userAdapter: EcdsaUser,
});

// Sign up with username and password
await db.signUp("username", "password");

// Sign in
await db.signIn("username", "password");

# Web3 User (`web3-user`)

For Ethereum wallet-based authentication:

npm install @tool-db/web3-user

import { ToolDb } from "tool-db";
import Web3User from "@tool-db/web3-user";

const db = new ToolDb({
  userAdapter: Web3User,
});

# Writing Custom Adapters

When writing a new adapter, extend the base adapter class and implement the required methods. We highly recommend using TypeScript for type safety.

# Custom Network Adapter

import { ToolDb, ToolDbNetworkAdapter } from "tool-db";

export default class MyNetworkAdapter extends ToolDbNetworkAdapter {
  constructor(db: ToolDb) {
    super(db);
    // Initialize your network layer
  }

  // Implement connection methods
}

# Custom Storage Adapter

import { ToolDb, ToolDbStorageAdapter } from "tool-db";

export default class MyStorageAdapter extends ToolDbStorageAdapter {
  constructor(db: ToolDb, forceStorageName?: string) {
    super(db, forceStorageName);
    // Initialize your storage
  }

  async put(key: string, data: string): Promise<void> {
    // Store data
  }

  async get(key: string): Promise<string> {
    // Retrieve data
  }

  async query(key: string): Promise<string[]> {
    // Query keys by prefix
  }
}

# Custom User Adapter

import { ToolDb, ToolDbUserAdapter, VerificationData } from "tool-db";

export default class MyUserAdapter extends ToolDbUserAdapter {
  constructor(db: ToolDb) {
    super(db);
  }

  async anonUser(): Promise<void> {
    // Generate anonymous user keys
  }

  async signData(data: string): Promise<string> {
    // Sign data with private key
  }

  async verifySignature(message: Partial<VerificationData>): Promise<boolean> {
    // Verify message signature
  }

  getAddress(): string | undefined {
    // Return current user's public key/address
  }

  getUsername(): string | undefined {
    // Return current user's name
  }
}

# Base Adapter Source

For implementation reference, see the base adapter classes:

# Examples

You can see a working example of Tool Db using WebRTC to create a chat (opens new window) (source code on GitHub (opens new window))

← CRDTs

# Adapters

# Network Adapters

# WebSocket Network (websocket-network)

# WebRTC Network (webrtc-network)

# Hybrid Network (hybrid-network)