network/README.md

# @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

```bash
npm install @debros/network
```

## Basic Usage

```typescript
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:

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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();
```