@debros/network

Core networking functionality for the Debros decentralized network. This package provides a powerful database interface with advanced features built on IPFS and OrbitDB for decentralized applications.

Features

• Rich database-like API with TypeScript support
• Multiple database store types (KeyValue, Document, Feed, Counter)
• Document operations with schema validation
• Advanced querying with pagination, sorting and filtering
• Transaction support for batch operations
• Built-in file storage with metadata
• Real-time subscriptions for data changes
• Memory caching for performance
• Connection pooling for managing multiple database instances
• Index creation for faster queries
• Comprehensive error handling with error codes
• Performance metrics and monitoring

Installation

npm install @debros/network

Basic Usage

import { initDB, create, get, query, uploadFile, logger } from '@debros/network';

// Initialize the database service
async function startApp() {
  try {
    // Initialize with default configuration
    await initDB();
    logger.info('Database initialized successfully');

    // Create a new user document
    const userId = 'user123';
    const user = {
      username: 'johndoe',
      walletAddress: '0x1234567890',
      avatar: null,
    };

    const result = await create('users', userId, user);
    logger.info(`Created user with ID: ${result.id}`);

    // Get a user by ID
    const retrievedUser = await get('users', userId);
    logger.info('User:', retrievedUser);

    // Query users with filtering
    const activeUsers = await query('users', (user) => user.isActive === true, {
      limit: 10,
      sort: { field: 'createdAt', order: 'desc' },
    });
    logger.info(`Found ${activeUsers.total} active users`);

    // Upload a file
    const fileData = Buffer.from('File content');
    const fileUpload = await uploadFile(fileData, { filename: 'document.txt' });
    logger.info(`Uploaded file with CID: ${fileUpload.cid}`);

    return true;
  } catch (error) {
    logger.error('Failed to start app:', error);
    throw error;
  }
}

startApp();

Database Store Types

The library supports multiple OrbitDB store types, each optimized for different use cases:

import { create, get, update, StoreType } from '@debros/network';

// Default KeyValue store (for general use)
await create('users', 'user1', { name: 'Alice' });

// Document store (better for complex documents with indexing)
await create(
  'posts',
  'post1',
  { title: 'Hello', content: '...' },
  { storeType: StoreType.DOCSTORE },
);

// Feed/EventLog store (append-only, good for immutable logs)
await create('events', 'evt1', { type: 'login', user: 'alice' }, { storeType: StoreType.FEED });

// Counter store (for numeric counters)
await create('stats', 'visits', { value: 0 }, { storeType: StoreType.COUNTER });

// Increment a counter
await update('stats', 'visits', { increment: 1 }, { storeType: StoreType.COUNTER });

// Get counter value
const stats = await get('stats', 'visits', { storeType: StoreType.COUNTER });
console.log(`Visit count: ${stats.value}`);

Advanced Features

Schema Validation

import { defineSchema, create } from '@debros/network';

// Define a schema
defineSchema('users', {
  properties: {
    username: {
      type: 'string',
      required: true,
      min: 3,
      max: 20,
    },
    email: {
      type: 'string',
      pattern: '^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$',
    },
    age: {
      type: 'number',
      min: 18,
    },
  },
  required: ['username'],
});

// Document creation will be validated against the schema
await create('users', 'user1', {
  username: 'alice',
  email: 'alice@example.com',
  age: 25,
});

Transactions

import { createTransaction, commitTransaction } from '@debros/network';

// Create a transaction
const transaction = createTransaction();

// Add multiple operations
transaction
  .create('posts', 'post1', { title: 'Hello World', content: '...' })
  .update('users', 'user1', { postCount: 1 })
  .delete('drafts', 'draft1');

// Commit all operations
const result = await commitTransaction(transaction);
console.log(`Transaction completed with ${result.results.length} operations`);

Event Subscriptions

import { subscribe } from '@debros/network';

// Subscribe to document changes
const unsubscribe = subscribe('document:created', (data) => {
  console.log(`New document created in ${data.collection}:`, data.id);
  console.log('Document data:', data.document);
});

// Other event types
// subscribe('document:updated', (data) => { ... });
// subscribe('document:deleted', (data) => { ... });

// Later, unsubscribe when done
unsubscribe();

Pagination and Sorting

import { list, query } from '@debros/network';

// List with pagination and sorting
const page1 = await list('users', {
  limit: 10,
  offset: 0,
  sort: { field: 'createdAt', order: 'desc' },
});

// Query with pagination
const results = await query('users', (user) => user.age > 21, { limit: 10, offset: 20 });

console.log(`Found ${results.total} matches, showing ${results.documents.length}`);
console.log(`Has more pages: ${results.hasMore}`);

TypeScript Support

import { get, update, query } from '@debros/network';

interface User {
  username: string;
  email: string;
  age: number;
  createdAt: number;
  updatedAt: number;
}

// Type-safe operations
const user = await get<User>('users', 'user1');

await update<User>('users', 'user1', { age: 26 });

const results = await query<User>('users', (user) => user.age > 21);

Connection Management

import { initDB, closeConnection } from '@debros/network';

// Create multiple connections
const conn1 = await initDB('connection1');
const conn2 = await initDB('connection2');

// Use specific connection
await create('users', 'user1', { name: 'Alice' }, { connectionId: conn1 });

// Close a specific connection
await closeConnection(conn1);

API Reference

Core Database Operations

• initDB(connectionId?: string): Promise<string> - Initialize the database
• create<T>(collection, id, data, options?): Promise<CreateResult> - Create a document
• get<T>(collection, id, options?): Promise<T | null> - Get a document by ID
• update<T>(collection, id, data, options?): Promise<UpdateResult> - Update a document
• remove(collection, id, options?): Promise<boolean> - Delete a document
• list<T>(collection, options?): Promise<PaginatedResult<T>> - List documents with pagination
• query<T>(collection, filter, options?): Promise<PaginatedResult<T>> - Query documents
• stopDB(): Promise<void> - Stop the database service

Store Types

• StoreType.KEYVALUE - Key-value pair storage (default)
• StoreType.DOCSTORE - Document storage with indexing
• StoreType.FEED - Append-only log
• StoreType.EVENTLOG - Alias for FEED
• StoreType.COUNTER - Numeric counter

Schema Validation

• defineSchema(collection, schema): void - Define a schema for a collection

Transactions

• createTransaction(connectionId?): Transaction - Create a new transaction
• commitTransaction(transaction): Promise<{success, results}> - Execute the transaction
• Transaction.create<T>(collection, id, data): Transaction - Add a create operation
• Transaction.update<T>(collection, id, data): Transaction - Add an update operation
• Transaction.delete(collection, id): Transaction - Add a delete operation

Event Subscriptions

• subscribe(event, callback): () => void - Subscribe to database events, returns unsubscribe function
• Event types: 'document:created', 'document:updated', 'document:deleted'

File Operations

• uploadFile(fileData, options?): Promise<FileUploadResult> - Upload a file
• getFile(cid, options?): Promise<FileResult> - Get a file by CID
• deleteFile(cid, options?): Promise<boolean> - Delete a file

Connection Management

• closeConnection(connectionId): Promise<boolean> - Close a specific connection

Indexes and Performance

• createIndex(collection, field, options?): Promise<boolean> - Create an index

Configuration

import { config, initDB } from '@debros/network';

// Configure (optional)
config.env.fingerprint = 'my-unique-app-id';
config.env.port = 9000;
config.ipfs.blockstorePath = './custom-path/blockstore';
config.orbitdb.directory = './custom-path/orbitdb';

// Initialize with configuration
await initDB();