@debros/network

DebrosFramework - A powerful Node.js framework that provides an ORM-like abstraction over OrbitDB and IPFS, making it easy to build scalable decentralized applications.

What is DebrosFramework?

DebrosFramework simplifies the development of decentralized applications by providing:

• Model-based Abstraction: Define your data models using decorators and TypeScript classes
• Automatic Database Management: Handle user-scoped and global databases automatically
• Smart Sharding: Distribute data across multiple databases for scalability
• Advanced Query System: Rich query capabilities with relationship loading and caching
• Automatic Features: Built-in pinning strategies and PubSub event publishing
• Migration System: Schema evolution and data transformation capabilities
• Type Safety: Full TypeScript support with strong typing throughout

Installation

npm install @debros/network

Quick Start

1. Define Your Models

import { BaseModel, Model, Field, HasMany } from '@debros/network';

@Model({
  scope: 'global',
  type: 'docstore',
  sharding: { strategy: 'hash', count: 4, key: 'id' },
})
export class User extends BaseModel {
  @Field({ type: 'string', required: true, unique: true })
  username: string;

  @Field({ type: 'string', required: true, unique: true })
  email: string;

  @HasMany(() => Post, 'userId')
  posts: Post[];
}

@Model({
  scope: 'user',
  type: 'docstore',
  sharding: { strategy: 'user', count: 2, key: 'userId' },
})
export class Post extends BaseModel {
  @Field({ type: 'string', required: true })
  title: string;

  @Field({ type: 'string', required: true })
  content: string;

  @Field({ type: 'string', required: true })
  userId: string;
}

2. Initialize the Framework

import { DebrosFramework } from '@debros/network';
import { setupOrbitDB, setupIPFS } from './services';

async function startApp() {
  // Initialize services
  const orbitDBService = await setupOrbitDB();
  const ipfsService = await setupIPFS();

  // Initialize framework
  const framework = new DebrosFramework({
    features: {
      queryCache: true,
      automaticPinning: true,
      pubsub: true,
    },
  });

  await framework.initialize(orbitDBService, ipfsService);
  console.log('✅ DebrosFramework initialized successfully!');

  // Create a user
  const user = await User.create({
    username: 'alice',
    email: 'alice@example.com',
  });

  // Create a post
  const post = await Post.create({
    title: 'My First Post',
    content: 'Hello DebrosFramework!',
    userId: user.id,
  });

  // Query with relationships
  const usersWithPosts = await User.query().with(['posts']).where('username', 'alice').find();

  console.log('User:', usersWithPosts[0]);
  console.log('Posts:', usersWithPosts[0].posts);
}

Key Features

🏗️ Model-Driven Development

Define your data models using familiar decorator patterns:

@Model({
  scope: 'user',
  type: 'docstore',
  sharding: { strategy: 'hash', count: 4, key: 'userId' },
})
class Post extends BaseModel {
  @Field({ type: 'string', required: true })
  title: string;

  @BelongsTo(() => User, 'userId')
  user: User;
}

🔍 Powerful Query System

Build complex queries with relationship loading:

const users = await User.query()
  .where('isActive', true)
  .where('registeredAt', '>', Date.now() - 30 * 24 * 60 * 60 * 1000)
  .with(['posts', 'followers'])
  .orderBy('username')
  .limit(20)
  .find();

🚀 Automatic Scaling

Handle millions of users with automatic sharding and pinning:

// Framework automatically:
// - Creates user-scoped databases
// - Distributes data across shards
// - Manages pinning strategies
// - Optimizes query routing

🔄 Schema Evolution

Migrate your data structures safely:

const migration = createMigration('add_user_profiles', '1.1.0')
  .addField('User', 'profilePicture', { type: 'string', required: false })
  .addField('User', 'bio', { type: 'string', required: false })
  .transformData('User', (user) => ({
    ...user,
    displayName: user.username || 'Anonymous',
  }))
  .build();

🔗 Rich Relationships

Handle complex relationships between models:

@Model({ scope: 'global' })
class User extends BaseModel {
  @HasMany(() => Post, 'userId')
  posts: Post[];

  @ManyToMany(() => User, 'followers', 'following')
  followers: User[];
}

// Load user with all relationships
const user = await User.findById(userId, {
  with: ['posts.comments', 'followers.posts'],
});

⚡ Performance Features

// Query caching
const cachedUsers = await User.query()
  .where('isActive', true)
  .cache(300) // Cache for 5 minutes
  .find();

// Eager loading
const usersWithPosts = await User.query().with(['posts.comments']).find();

// Optimized pagination
const page = await User.query().orderBy('createdAt', 'desc').paginate(1, 20);

🎯 Model Hooks

export class User extends BaseModel {
  @BeforeCreate()
  async beforeCreate() {
    this.createdAt = Date.now();
    // Hash password, validate data, etc.
  }

  @AfterCreate()
  async afterCreate() {
    // Send welcome email, create defaults, etc.
  }
}

API Reference

Framework Management

• new DebrosFramework(config?) - Create framework instance
• framework.initialize(orbitDBService, ipfsService, config?) - Initialize framework
• framework.start() - Start the framework
• framework.stop() - Stop the framework
• framework.getStatus() - Get framework status

Model Operations

• Model.create(data) - Create a new model instance
• Model.findById(id, options?) - Find model by ID
• Model.findOne(criteria, options?) - Find single model
• Model.query() - Start a query builder
• model.save() - Save model changes
• model.delete() - Delete model instance

Query System

• Model.query().where(field, operator, value) - Add where condition
• Model.query().with(relationships) - Eager load relationships
• Model.query().orderBy(field, direction) - Add ordering
• Model.query().limit(count) - Limit results
• Model.query().offset(count) - Add offset
• Model.query().paginate(page, perPage) - Paginate results
• Model.query().cache(ttl) - Cache query results
• Model.query().find() - Execute query
• Model.query().count() - Count results

Decorators

• @Model(config) - Define model configuration
• @Field(config) - Define field properties
• @BelongsTo(target, foreignKey) - Many-to-one relationship
• @HasMany(target, foreignKey) - One-to-many relationship
• @HasOne(target, foreignKey) - One-to-one relationship
• @ManyToMany(target, through) - Many-to-many relationship
• @BeforeCreate(), @AfterCreate() - Lifecycle hooks
• @BeforeUpdate(), @AfterUpdate() - Update hooks
• @BeforeDelete(), @AfterDelete() - Delete hooks

Migration System

• createMigration(name, version) - Create new migration
• migration.addField(model, field, config) - Add field to model
• migration.removeField(model, field) - Remove field from model
• migration.transformData(model, transformer) - Transform existing data
• migrationManager.runPendingMigrations() - Run pending migrations

Configuration

Framework Configuration

import { DebrosFramework, PRODUCTION_CONFIG, DEVELOPMENT_CONFIG } from '@debros/network';

// Development configuration
const framework = new DebrosFramework({
  ...DEVELOPMENT_CONFIG,
  features: {
    queryCache: true,
    automaticPinning: false,
    pubsub: true,
    relationshipCache: true,
    autoMigration: true,
  },
  performance: {
    queryTimeout: 30000,
    batchSize: 50,
  },
  monitoring: {
    enableMetrics: true,
    logLevel: 'debug',
  },
});

// Production configuration
const prodFramework = new DebrosFramework({
  ...PRODUCTION_CONFIG,
  performance: {
    queryTimeout: 10000,
    batchSize: 200,
    maxConcurrentOperations: 500,
  },
});

Model Configuration

@Model({
  scope: 'global', // 'user' or 'global'
  type: 'docstore', // OrbitDB store type
  sharding: {
    strategy: 'hash', // 'hash', 'range', or 'user'
    count: 4, // Number of shards
    key: 'id', // Sharding key
  },
  pinning: {
    strategy: 'popularity', // Pinning strategy
    factor: 2,
  },
})
export class MyModel extends BaseModel {
  // Model definition
}

Architecture Overview

DebrosFramework is built around several core components:

1. Models & Decorators: Define your data structure and behavior
2. Database Manager: Handles database creation and management
3. Shard Manager: Distributes data across multiple databases
4. Query System: Processes queries with optimization and caching
5. Relationship Manager: Handles complex relationships between models
6. Migration System: Manages schema evolution over time
7. Automatic Features: Pinning, PubSub, and performance optimization

Key Benefits

• Scalability: Automatic sharding and distributed data management
• Performance: Built-in caching, query optimization, and lazy loading
• Developer Experience: Familiar ORM patterns with TypeScript support
• Flexibility: Support for various data patterns and relationships
• Reliability: Comprehensive error handling and recovery mechanisms

Getting Started

Ready to build your first decentralized application? Check out our comprehensive documentation:

• 📖 Complete Documentation - Comprehensive guides and examples
• 🚀 Getting Started Guide - Set up your development environment
• 🏗️ Architecture Overview - Understand how the framework works
• 📝 API Reference - Complete API documentation
• 💡 Examples - Practical usage examples

Testing

# Run unit tests
npm run test:unit

# Run integration tests
npm run test:real

# Run specific blog scenario integration test
npm run test:blog-integration

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the GNU GPL v3.0 License - see the LICENSE file for details.

---

DebrosFramework - Making decentralized application development as simple as traditional web development, while providing the benefits of distributed systems.