docs: Add development guidelines, project overview, and technical reference documentation
This commit is contained in:
parent
97d9191a45
commit
9877ddf5ec
391
.claude/development-guidelines.md
Normal file
391
.claude/development-guidelines.md
Normal file
@ -0,0 +1,391 @@
|
|||||||
|
# DebrosFramework Development Guidelines
|
||||||
|
|
||||||
|
## Code Style and Standards
|
||||||
|
|
||||||
|
### TypeScript Configuration
|
||||||
|
- **Strict Mode**: Always use strict TypeScript configuration
|
||||||
|
- **Decorators**: Enable `experimentalDecorators` and `emitDecoratorMetadata`
|
||||||
|
- **Target**: ES2020 for modern JavaScript features
|
||||||
|
- **Module System**: ES modules with CommonJS interop
|
||||||
|
|
||||||
|
### Code Formatting
|
||||||
|
- **Prettier**: Use Prettier for consistent code formatting
|
||||||
|
- **ESLint**: Follow ESLint rules for code quality
|
||||||
|
- **Indentation**: 2 spaces for all files
|
||||||
|
- **Line Length**: Max 120 characters per line
|
||||||
|
- **Semicolons**: Always use semicolons
|
||||||
|
- **Quotes**: Single quotes for strings, double quotes for JSX
|
||||||
|
|
||||||
|
### Naming Conventions
|
||||||
|
- **Classes**: PascalCase (e.g., `UserModel`, `QueryBuilder`)
|
||||||
|
- **Functions/Methods**: camelCase (e.g., `createUser`, `findById`)
|
||||||
|
- **Variables**: camelCase (e.g., `userId`, `queryResult`)
|
||||||
|
- **Constants**: UPPER_SNAKE_CASE (e.g., `DEFAULT_CACHE_SIZE`)
|
||||||
|
- **Files**: PascalCase for classes, camelCase for utilities
|
||||||
|
- **Interfaces**: PascalCase with descriptive names (e.g., `ModelConfig`)
|
||||||
|
|
||||||
|
## Framework Architecture Patterns
|
||||||
|
|
||||||
|
### Model System
|
||||||
|
```typescript
|
||||||
|
// Always extend BaseModel for data models
|
||||||
|
@Model({
|
||||||
|
scope: 'user' | 'global',
|
||||||
|
type: 'docstore',
|
||||||
|
sharding: { strategy: 'hash', count: 4, key: 'fieldName' }
|
||||||
|
})
|
||||||
|
export class ModelName extends BaseModel {
|
||||||
|
@Field({ type: 'string', required: true })
|
||||||
|
propertyName: string;
|
||||||
|
|
||||||
|
@BelongsTo(() => RelatedModel, 'foreignKey')
|
||||||
|
relation: RelatedModel;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Query Patterns
|
||||||
|
```typescript
|
||||||
|
// Use chainable query builder pattern
|
||||||
|
const results = await Model.query()
|
||||||
|
.where('field', 'operator', value)
|
||||||
|
.with(['relationship1', 'relationship2'])
|
||||||
|
.orderBy('field', 'direction')
|
||||||
|
.limit(count)
|
||||||
|
.find();
|
||||||
|
|
||||||
|
// Prefer specific methods over generic ones
|
||||||
|
const user = await User.findById(id); // Good
|
||||||
|
const user = await User.query().where('id', id).findOne(); // Less preferred
|
||||||
|
```
|
||||||
|
|
||||||
|
### Error Handling
|
||||||
|
```typescript
|
||||||
|
// Always use try-catch for async operations
|
||||||
|
try {
|
||||||
|
const result = await someAsyncOperation();
|
||||||
|
return result;
|
||||||
|
} catch (error) {
|
||||||
|
console.error('Operation failed:', error);
|
||||||
|
throw new DebrosFrameworkError('Descriptive error message', { originalError: error });
|
||||||
|
}
|
||||||
|
|
||||||
|
// Validate inputs early
|
||||||
|
if (!userId || typeof userId !== 'string') {
|
||||||
|
throw new ValidationError('User ID must be a non-empty string');
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Service Layer Pattern
|
||||||
|
```typescript
|
||||||
|
// Encapsulate business logic in service classes
|
||||||
|
export class UserService {
|
||||||
|
async createUser(userData: CreateUserData): Promise<User> {
|
||||||
|
// Validation
|
||||||
|
await this.validateUserData(userData);
|
||||||
|
|
||||||
|
// Business logic
|
||||||
|
const user = await User.create(userData);
|
||||||
|
|
||||||
|
// Post-processing
|
||||||
|
await this.sendWelcomeEmail(user);
|
||||||
|
|
||||||
|
return user;
|
||||||
|
}
|
||||||
|
|
||||||
|
private async validateUserData(data: CreateUserData): Promise<void> {
|
||||||
|
// Validation logic
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing Standards
|
||||||
|
|
||||||
|
### Unit Tests
|
||||||
|
- **Jest**: Use Jest for all unit testing
|
||||||
|
- **Mocking**: Mock external dependencies (OrbitDB, IPFS)
|
||||||
|
- **Coverage**: Aim for >90% code coverage
|
||||||
|
- **Structure**: One test file per source file
|
||||||
|
- **Naming**: `*.test.ts` for test files
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
describe('ModelName', () => {
|
||||||
|
let model: ModelName;
|
||||||
|
|
||||||
|
beforeEach(() => {
|
||||||
|
model = new ModelName();
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('methodName', () => {
|
||||||
|
it('should handle normal case', async () => {
|
||||||
|
// Arrange
|
||||||
|
const input = 'test value';
|
||||||
|
|
||||||
|
// Act
|
||||||
|
const result = await model.methodName(input);
|
||||||
|
|
||||||
|
// Assert
|
||||||
|
expect(result).toBeDefined();
|
||||||
|
expect(result.property).toBe('expected value');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should throw error for invalid input', async () => {
|
||||||
|
// Arrange & Act & Assert
|
||||||
|
await expect(model.methodName(null)).rejects.toThrow('Expected error message');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Integration Tests
|
||||||
|
- **Docker**: Use Docker for real integration tests
|
||||||
|
- **Scenarios**: Test complete user workflows
|
||||||
|
- **Data**: Use realistic test data
|
||||||
|
- **Cleanup**: Always clean up test data
|
||||||
|
|
||||||
|
## Performance Guidelines
|
||||||
|
|
||||||
|
### Query Optimization
|
||||||
|
```typescript
|
||||||
|
// Use selective field loading when possible
|
||||||
|
const users = await User.query().select(['id', 'username']).find();
|
||||||
|
|
||||||
|
// Prefer eager loading for predictable relationships
|
||||||
|
const posts = await Post.query().with(['author', 'comments']).find();
|
||||||
|
|
||||||
|
// Use caching for expensive queries
|
||||||
|
const popularPosts = await Post.query()
|
||||||
|
.where('likeCount', '>', 100)
|
||||||
|
.cache(300) // Cache for 5 minutes
|
||||||
|
.find();
|
||||||
|
```
|
||||||
|
|
||||||
|
### Memory Management
|
||||||
|
- **Lazy Loading**: Use lazy loading for large datasets
|
||||||
|
- **Pagination**: Always use pagination for large result sets
|
||||||
|
- **Cache Limits**: Set appropriate cache size limits
|
||||||
|
- **Cleanup**: Clean up resources in finally blocks
|
||||||
|
|
||||||
|
### Database Design
|
||||||
|
- **Sharding**: Design effective sharding strategies
|
||||||
|
- **Indexing**: Use indexes for frequently queried fields
|
||||||
|
- **Relationships**: Avoid deep relationship chains
|
||||||
|
- **Data Types**: Use appropriate data types for storage efficiency
|
||||||
|
|
||||||
|
## Security Considerations
|
||||||
|
|
||||||
|
### Input Validation
|
||||||
|
```typescript
|
||||||
|
// Always validate and sanitize inputs
|
||||||
|
@Field({
|
||||||
|
type: 'string',
|
||||||
|
required: true,
|
||||||
|
validate: (value: string) => value.length >= 3 && value.length <= 50,
|
||||||
|
transform: (value: string) => value.trim().toLowerCase()
|
||||||
|
})
|
||||||
|
username: string;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Access Control
|
||||||
|
- **User Scoping**: Use user-scoped models for private data
|
||||||
|
- **Validation**: Validate user permissions before operations
|
||||||
|
- **Sanitization**: Sanitize all user inputs
|
||||||
|
- **Encryption**: Use encryption for sensitive data
|
||||||
|
|
||||||
|
### Error Messages
|
||||||
|
- **Security**: Don't expose internal system details in error messages
|
||||||
|
- **Logging**: Log security-relevant events
|
||||||
|
- **Validation**: Provide clear validation error messages
|
||||||
|
|
||||||
|
## Documentation Standards
|
||||||
|
|
||||||
|
### Code Documentation
|
||||||
|
```typescript
|
||||||
|
/**
|
||||||
|
* Creates a new user with the provided data.
|
||||||
|
*
|
||||||
|
* @param userData - The user data to create
|
||||||
|
* @param options - Additional creation options
|
||||||
|
* @returns Promise resolving to the created user
|
||||||
|
* @throws ValidationError if user data is invalid
|
||||||
|
* @throws DuplicateError if username or email already exists
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* ```typescript
|
||||||
|
* const user = await userService.createUser({
|
||||||
|
* username: 'alice',
|
||||||
|
* email: 'alice@example.com'
|
||||||
|
* });
|
||||||
|
* ```
|
||||||
|
*/
|
||||||
|
async createUser(userData: CreateUserData, options?: CreateOptions): Promise<User> {
|
||||||
|
// Implementation
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### README Updates
|
||||||
|
- Keep README.md up to date with latest features
|
||||||
|
- Include practical examples
|
||||||
|
- Document breaking changes
|
||||||
|
- Provide migration guides
|
||||||
|
|
||||||
|
### API Documentation
|
||||||
|
- Document all public APIs
|
||||||
|
- Include parameter types and return types
|
||||||
|
- Provide usage examples
|
||||||
|
- Document error conditions
|
||||||
|
|
||||||
|
## Common Patterns and Anti-Patterns
|
||||||
|
|
||||||
|
### ✅ Good Patterns
|
||||||
|
|
||||||
|
#### Model Definition
|
||||||
|
```typescript
|
||||||
|
@Model({
|
||||||
|
scope: 'user',
|
||||||
|
type: 'docstore',
|
||||||
|
sharding: { strategy: 'hash', count: 4, key: 'userId' }
|
||||||
|
})
|
||||||
|
export class Post extends BaseModel {
|
||||||
|
@Field({ type: 'string', required: true, maxLength: 200 })
|
||||||
|
title: string;
|
||||||
|
|
||||||
|
@Field({ type: 'string', required: true })
|
||||||
|
content: string;
|
||||||
|
|
||||||
|
@BeforeCreate()
|
||||||
|
setDefaults() {
|
||||||
|
this.createdAt = Date.now();
|
||||||
|
this.updatedAt = Date.now();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Service Methods
|
||||||
|
```typescript
|
||||||
|
async createPost(authorId: string, postData: CreatePostData): Promise<Post> {
|
||||||
|
// Validate input
|
||||||
|
if (!authorId) throw new ValidationError('Author ID is required');
|
||||||
|
|
||||||
|
// Check permissions
|
||||||
|
const author = await User.findById(authorId);
|
||||||
|
if (!author) throw new NotFoundError('Author not found');
|
||||||
|
|
||||||
|
// Create post
|
||||||
|
const post = await Post.create({
|
||||||
|
...postData,
|
||||||
|
authorId,
|
||||||
|
});
|
||||||
|
|
||||||
|
// Post-processing
|
||||||
|
await this.notifyFollowers(author, post);
|
||||||
|
|
||||||
|
return post;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### ❌ Anti-Patterns
|
||||||
|
|
||||||
|
#### Avoid Direct Database Access
|
||||||
|
```typescript
|
||||||
|
// Bad: Direct database manipulation
|
||||||
|
const db = await orbitdb.open('posts');
|
||||||
|
await db.put('key', data);
|
||||||
|
|
||||||
|
// Good: Use model methods
|
||||||
|
const post = await Post.create(data);
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Avoid Synchronous Operations
|
||||||
|
```typescript
|
||||||
|
// Bad: Synchronous file operations
|
||||||
|
const data = fs.readFileSync('file.json');
|
||||||
|
|
||||||
|
// Good: Async operations
|
||||||
|
const data = await fs.promises.readFile('file.json');
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Avoid Deep Relationship Chains
|
||||||
|
```typescript
|
||||||
|
// Bad: Deep relationship loading
|
||||||
|
const posts = await Post.query()
|
||||||
|
.with(['author.profile.settings.preferences'])
|
||||||
|
.find();
|
||||||
|
|
||||||
|
// Good: Load only what you need
|
||||||
|
const posts = await Post.query()
|
||||||
|
.with(['author'])
|
||||||
|
.find();
|
||||||
|
```
|
||||||
|
|
||||||
|
## Migration Guidelines
|
||||||
|
|
||||||
|
### Schema Changes
|
||||||
|
```typescript
|
||||||
|
// Create migration for schema changes
|
||||||
|
const migration = createMigration('add_user_avatar', '1.1.0')
|
||||||
|
.addField('User', 'avatarUrl', {
|
||||||
|
type: 'string',
|
||||||
|
required: false
|
||||||
|
})
|
||||||
|
.transformData('User', (user) => ({
|
||||||
|
...user,
|
||||||
|
avatarUrl: user.avatarUrl || null
|
||||||
|
}))
|
||||||
|
.build();
|
||||||
|
```
|
||||||
|
|
||||||
|
### Backwards Compatibility
|
||||||
|
- Always maintain backwards compatibility in minor versions
|
||||||
|
- Deprecate features before removing them
|
||||||
|
- Provide migration paths for breaking changes
|
||||||
|
- Document all changes in CHANGELOG.md
|
||||||
|
|
||||||
|
## Deployment Considerations
|
||||||
|
|
||||||
|
### Environment Configuration
|
||||||
|
- Use environment variables for configuration
|
||||||
|
- Provide default configurations for development
|
||||||
|
- Validate configuration on startup
|
||||||
|
- Document required environment variables
|
||||||
|
|
||||||
|
### Production Readiness
|
||||||
|
- Enable production optimizations
|
||||||
|
- Configure appropriate cache sizes
|
||||||
|
- Set up monitoring and logging
|
||||||
|
- Implement health checks
|
||||||
|
|
||||||
|
### Performance Monitoring
|
||||||
|
- Monitor query performance
|
||||||
|
- Track cache hit rates
|
||||||
|
- Monitor memory usage
|
||||||
|
- Set up alerts for errors
|
||||||
|
|
||||||
|
## Contributing Guidelines
|
||||||
|
|
||||||
|
### Pull Request Process
|
||||||
|
1. Fork the repository
|
||||||
|
2. Create feature branch from main
|
||||||
|
3. Implement changes with tests
|
||||||
|
4. Update documentation
|
||||||
|
5. Submit pull request with description
|
||||||
|
|
||||||
|
### Code Review Checklist
|
||||||
|
- [ ] Code follows style guidelines
|
||||||
|
- [ ] Tests are included and passing
|
||||||
|
- [ ] Documentation is updated
|
||||||
|
- [ ] No breaking changes (or properly documented)
|
||||||
|
- [ ] Performance implications considered
|
||||||
|
- [ ] Security implications reviewed
|
||||||
|
|
||||||
|
### Commit Message Format
|
||||||
|
```
|
||||||
|
type(scope): description
|
||||||
|
|
||||||
|
body (optional)
|
||||||
|
|
||||||
|
footer (optional)
|
||||||
|
```
|
||||||
|
|
||||||
|
Types: feat, fix, docs, style, refactor, test, chore
|
||||||
|
|
||||||
|
These guidelines ensure consistent, maintainable, and high-quality code throughout the DebrosFramework project.
|
||||||
249
.claude/project-overview.md
Normal file
249
.claude/project-overview.md
Normal file
@ -0,0 +1,249 @@
|
|||||||
|
# DebrosFramework Project Overview
|
||||||
|
|
||||||
|
## Project Identity
|
||||||
|
**DebrosFramework** is a powerful Node.js framework that provides an ORM-like abstraction over OrbitDB and IPFS, making it easy to build scalable decentralized applications.
|
||||||
|
|
||||||
|
- **Package Name**: `@debros/network`
|
||||||
|
- **Version**: 0.5.1-beta (Active Development)
|
||||||
|
- **License**: GNU GPL v3.0
|
||||||
|
- **Language**: TypeScript
|
||||||
|
- **Framework Type**: Decentralized Application Framework
|
||||||
|
|
||||||
|
## What This Project Does
|
||||||
|
|
||||||
|
DebrosFramework simplifies the development of decentralized applications by providing:
|
||||||
|
|
||||||
|
### Core Capabilities
|
||||||
|
- **Model-based Abstraction**: Define 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
|
||||||
|
|
||||||
|
### Key Features
|
||||||
|
1. **🏗️ Model-Driven Development**: Familiar decorator patterns for data models
|
||||||
|
2. **🔍 Powerful Query System**: Complex queries with relationship loading
|
||||||
|
3. **🚀 Automatic Scaling**: Handle millions of users with automatic sharding
|
||||||
|
4. **🔄 Schema Evolution**: Safe data structure migrations
|
||||||
|
5. **🔗 Rich Relationships**: Complex relationships between models
|
||||||
|
6. **⚡ Performance Features**: Query caching, eager loading, optimized pagination
|
||||||
|
7. **🎯 Model Hooks**: Lifecycle hooks for business logic
|
||||||
|
|
||||||
|
## Architecture Overview
|
||||||
|
|
||||||
|
The framework is built around several core components:
|
||||||
|
|
||||||
|
1. **Models & Decorators**: Define 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
|
||||||
|
|
||||||
|
## Technology Stack
|
||||||
|
|
||||||
|
### Core Dependencies
|
||||||
|
- **OrbitDB**: Distributed peer-to-peer database on IPFS
|
||||||
|
- **IPFS/Helia**: Distributed file system for data storage
|
||||||
|
- **libp2p**: Peer-to-peer networking stack
|
||||||
|
- **TypeScript**: Strong typing and modern JavaScript features
|
||||||
|
|
||||||
|
### Key Libraries
|
||||||
|
- `@orbitdb/core`: Core OrbitDB functionality
|
||||||
|
- `@helia/unixfs`: IPFS file system operations
|
||||||
|
- `@libp2p/*`: Various libp2p modules for networking
|
||||||
|
- `winston`: Logging
|
||||||
|
- `node-cache`: In-memory caching
|
||||||
|
- `express`: HTTP server for integration tests
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
src/framework/
|
||||||
|
├── core/ # Core framework components
|
||||||
|
│ ├── ConfigManager.ts
|
||||||
|
│ ├── DatabaseManager.ts
|
||||||
|
│ └── ModelRegistry.ts
|
||||||
|
├── models/ # Model system and decorators
|
||||||
|
│ ├── BaseModel.ts
|
||||||
|
│ └── decorators/
|
||||||
|
├── query/ # Query builder and execution
|
||||||
|
│ ├── QueryBuilder.ts
|
||||||
|
│ ├── QueryExecutor.ts
|
||||||
|
│ ├── QueryOptimizer.ts
|
||||||
|
│ └── QueryCache.ts
|
||||||
|
├── relationships/ # Relationship management
|
||||||
|
│ ├── RelationshipManager.ts
|
||||||
|
│ ├── LazyLoader.ts
|
||||||
|
│ └── RelationshipCache.ts
|
||||||
|
├── sharding/ # Data sharding logic
|
||||||
|
│ └── ShardManager.ts
|
||||||
|
├── migrations/ # Schema migration system
|
||||||
|
│ ├── MigrationManager.ts
|
||||||
|
│ └── MigrationBuilder.ts
|
||||||
|
├── pinning/ # Automatic pinning features
|
||||||
|
│ └── PinningManager.ts
|
||||||
|
├── pubsub/ # Event publishing system
|
||||||
|
│ └── PubSubManager.ts
|
||||||
|
├── services/ # External service integrations
|
||||||
|
│ ├── OrbitDBService.ts
|
||||||
|
│ ├── IPFSService.ts
|
||||||
|
│ └── RealOrbitDBService.ts
|
||||||
|
└── types/ # TypeScript type definitions
|
||||||
|
├── framework.ts
|
||||||
|
├── models.ts
|
||||||
|
└── queries.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
## Development Status
|
||||||
|
|
||||||
|
**Current State**: Beta (v0.5.1-beta) - Active Development
|
||||||
|
|
||||||
|
### What's Stable
|
||||||
|
- ✅ Core model system with decorators
|
||||||
|
- ✅ Basic CRUD operations
|
||||||
|
- ✅ Query builder and execution
|
||||||
|
- ✅ Relationship management
|
||||||
|
- ✅ Database management and sharding
|
||||||
|
- ✅ Migration system foundation
|
||||||
|
|
||||||
|
### What's In Development
|
||||||
|
- 🚧 Advanced query optimization
|
||||||
|
- 🚧 Performance optimization features
|
||||||
|
- 🚧 Production-ready configurations
|
||||||
|
- 🚧 Extended relationship types
|
||||||
|
- 🚧 Enhanced error handling
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
- **Unit Tests**: Comprehensive test suite using Jest
|
||||||
|
- **Integration Tests**: Docker-based real-world scenarios
|
||||||
|
- **Blog Scenario**: Complete blogging platform test case
|
||||||
|
|
||||||
|
## Key Concepts
|
||||||
|
|
||||||
|
### Model Scoping
|
||||||
|
- **Global Models**: Shared across all users (e.g., User profiles)
|
||||||
|
- **User Models**: Each user has their own database instance (e.g., Posts, Comments)
|
||||||
|
|
||||||
|
### Sharding Strategies
|
||||||
|
- **Hash Sharding**: Distribute data based on key hashing
|
||||||
|
- **Range Sharding**: Distribute data based on value ranges
|
||||||
|
- **User Sharding**: Dedicated shards per user or user group
|
||||||
|
|
||||||
|
### Query System
|
||||||
|
- **Chainable API**: Fluent interface for building queries
|
||||||
|
- **Type Safety**: Full TypeScript support with auto-completion
|
||||||
|
- **Relationship Loading**: Eager and lazy loading strategies
|
||||||
|
- **Caching**: Intelligent query result caching
|
||||||
|
|
||||||
|
### Relationships
|
||||||
|
- **BelongsTo**: Many-to-one relationships
|
||||||
|
- **HasMany**: One-to-many relationships
|
||||||
|
- **HasOne**: One-to-one relationships
|
||||||
|
- **ManyToMany**: Many-to-many relationships (with through tables)
|
||||||
|
|
||||||
|
## Common Use Cases
|
||||||
|
|
||||||
|
### 1. Social Platforms
|
||||||
|
- User profiles and authentication
|
||||||
|
- Posts, comments, and reactions
|
||||||
|
- Friend networks and messaging
|
||||||
|
- Activity feeds and notifications
|
||||||
|
|
||||||
|
### 2. Content Management
|
||||||
|
- Blogs and publishing platforms
|
||||||
|
- Document management systems
|
||||||
|
- Media galleries and collections
|
||||||
|
- Version control for content
|
||||||
|
|
||||||
|
### 3. Collaborative Applications
|
||||||
|
- Real-time document editing
|
||||||
|
- Project management tools
|
||||||
|
- Team collaboration platforms
|
||||||
|
- Knowledge bases and wikis
|
||||||
|
|
||||||
|
### 4. Marketplace Applications
|
||||||
|
- Product catalogs and inventory
|
||||||
|
- User reviews and ratings
|
||||||
|
- Order management systems
|
||||||
|
- Payment and transaction records
|
||||||
|
|
||||||
|
## Development Workflow
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
- Node.js 18.0 or higher
|
||||||
|
- TypeScript knowledge
|
||||||
|
- Basic understanding of IPFS and OrbitDB concepts
|
||||||
|
- Docker (for integration tests)
|
||||||
|
|
||||||
|
### Build Process
|
||||||
|
```bash
|
||||||
|
npm run build # Compile TypeScript
|
||||||
|
npm run dev # Development with watch mode
|
||||||
|
npm run lint # ESLint code checking
|
||||||
|
npm run format # Prettier code formatting
|
||||||
|
```
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
```bash
|
||||||
|
npm run test:unit # Fast unit tests with mocks
|
||||||
|
npm run test:real # Full integration tests with Docker
|
||||||
|
npm run test:blog-integration # Blog scenario integration tests
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Development Principles
|
||||||
|
1. **Type Safety First**: Everything is strongly typed
|
||||||
|
2. **Decorator-Based**: Use decorators for configuration
|
||||||
|
3. **Async/Await**: All operations are promise-based
|
||||||
|
4. **Error Handling**: Comprehensive error management
|
||||||
|
5. **Performance**: Built-in optimization and caching
|
||||||
|
6. **Scalability**: Designed for distributed systems
|
||||||
|
|
||||||
|
## API Patterns
|
||||||
|
|
||||||
|
### Model Definition
|
||||||
|
```typescript
|
||||||
|
@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;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Query Operations
|
||||||
|
```typescript
|
||||||
|
const posts = await Post.query()
|
||||||
|
.where('isPublished', true)
|
||||||
|
.where('createdAt', '>', Date.now() - 7 * 24 * 60 * 60 * 1000)
|
||||||
|
.with(['user', 'comments'])
|
||||||
|
.orderBy('likeCount', 'desc')
|
||||||
|
.limit(20)
|
||||||
|
.find();
|
||||||
|
```
|
||||||
|
|
||||||
|
### Lifecycle Hooks
|
||||||
|
```typescript
|
||||||
|
class User extends BaseModel {
|
||||||
|
@BeforeCreate()
|
||||||
|
setupNewUser() {
|
||||||
|
this.registeredAt = Date.now();
|
||||||
|
}
|
||||||
|
|
||||||
|
@AfterCreate()
|
||||||
|
async sendWelcomeEmail() {
|
||||||
|
// Business logic after creation
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This framework makes building decentralized applications feel like traditional web development while providing the benefits of distributed, peer-to-peer systems.
|
||||||
607
.claude/technical-reference.md
Normal file
607
.claude/technical-reference.md
Normal file
@ -0,0 +1,607 @@
|
|||||||
|
# DebrosFramework Technical Reference
|
||||||
|
|
||||||
|
## Core Architecture Components
|
||||||
|
|
||||||
|
### DebrosFramework Main Class
|
||||||
|
**Location**: `src/framework/DebrosFramework.ts`
|
||||||
|
|
||||||
|
The main framework class that orchestrates all components:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export class DebrosFramework {
|
||||||
|
// Core services
|
||||||
|
private orbitDBService: FrameworkOrbitDBService;
|
||||||
|
private ipfsService: FrameworkIPFSService;
|
||||||
|
|
||||||
|
// Framework components
|
||||||
|
private databaseManager: DatabaseManager;
|
||||||
|
private shardManager: ShardManager;
|
||||||
|
private queryCache: QueryCache;
|
||||||
|
private relationshipManager: RelationshipManager;
|
||||||
|
private pinningManager: PinningManager;
|
||||||
|
private pubsubManager: PubSubManager;
|
||||||
|
private migrationManager: MigrationManager;
|
||||||
|
|
||||||
|
// Lifecycle methods
|
||||||
|
async initialize(orbitDBService?, ipfsService?, config?): Promise<void>
|
||||||
|
async start(): Promise<void>
|
||||||
|
async stop(): Promise<void>
|
||||||
|
getStatus(): FrameworkStatus
|
||||||
|
getMetrics(): FrameworkMetrics
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### BaseModel Class
|
||||||
|
**Location**: `src/framework/models/BaseModel.ts`
|
||||||
|
|
||||||
|
Abstract base class for all data models:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export abstract class BaseModel {
|
||||||
|
// Instance properties
|
||||||
|
public id: string;
|
||||||
|
public _loadedRelations: Map<string, any>;
|
||||||
|
protected _isDirty: boolean;
|
||||||
|
protected _isNew: boolean;
|
||||||
|
|
||||||
|
// Static configuration
|
||||||
|
static modelName: string;
|
||||||
|
static storeType: StoreType;
|
||||||
|
static scope: 'user' | 'global';
|
||||||
|
static sharding?: ShardingConfig;
|
||||||
|
static fields: Map<string, FieldConfig>;
|
||||||
|
static relationships: Map<string, RelationshipConfig>;
|
||||||
|
|
||||||
|
// CRUD operations
|
||||||
|
async save(): Promise<this>
|
||||||
|
static async create<T>(data: any): Promise<T>
|
||||||
|
static async findById<T>(id: string): Promise<T | null>
|
||||||
|
static query<T>(): QueryBuilder<T>
|
||||||
|
async delete(): Promise<void>
|
||||||
|
|
||||||
|
// Lifecycle hooks
|
||||||
|
async beforeCreate(): Promise<void>
|
||||||
|
async afterCreate(): Promise<void>
|
||||||
|
async beforeUpdate(): Promise<void>
|
||||||
|
async afterUpdate(): Promise<void>
|
||||||
|
async beforeDelete(): Promise<void>
|
||||||
|
async afterDelete(): Promise<void>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Decorator System
|
||||||
|
|
||||||
|
### @Model Decorator
|
||||||
|
**Location**: `src/framework/models/decorators/Model.ts`
|
||||||
|
|
||||||
|
Configures model behavior and database storage:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface ModelConfig {
|
||||||
|
scope: 'user' | 'global'; // Database scope
|
||||||
|
type: StoreType; // OrbitDB store type
|
||||||
|
sharding?: ShardingConfig; // Data distribution strategy
|
||||||
|
pinning?: PinningConfig; // Automatic pinning configuration
|
||||||
|
pubsub?: PubSubConfig; // Event publishing configuration
|
||||||
|
validation?: ValidationConfig; // Model-level validation
|
||||||
|
}
|
||||||
|
|
||||||
|
@Model({
|
||||||
|
scope: 'user',
|
||||||
|
type: 'docstore',
|
||||||
|
sharding: { strategy: 'hash', count: 4, key: 'userId' }
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### @Field Decorator
|
||||||
|
**Location**: `src/framework/models/decorators/Field.ts`
|
||||||
|
|
||||||
|
Defines field properties and validation:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface FieldConfig {
|
||||||
|
type: FieldType; // Data type
|
||||||
|
required?: boolean; // Required field
|
||||||
|
unique?: boolean; // Unique constraint
|
||||||
|
default?: any | (() => any); // Default value
|
||||||
|
validate?: (value: any) => boolean; // Custom validation
|
||||||
|
transform?: (value: any) => any; // Data transformation
|
||||||
|
serialize?: boolean; // Include in serialization
|
||||||
|
index?: boolean; // Create index for field
|
||||||
|
virtual?: boolean; // Virtual field (not stored)
|
||||||
|
}
|
||||||
|
|
||||||
|
@Field({
|
||||||
|
type: 'string',
|
||||||
|
required: true,
|
||||||
|
unique: true,
|
||||||
|
validate: (value: string) => value.length >= 3,
|
||||||
|
transform: (value: string) => value.trim().toLowerCase()
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### Relationship Decorators
|
||||||
|
**Location**: `src/framework/models/decorators/relationships.ts`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Many-to-one relationship
|
||||||
|
@BelongsTo(() => User, 'userId')
|
||||||
|
author: User;
|
||||||
|
|
||||||
|
// One-to-many relationship
|
||||||
|
@HasMany(() => Post, 'authorId')
|
||||||
|
posts: Post[];
|
||||||
|
|
||||||
|
// One-to-one relationship
|
||||||
|
@HasOne(() => Profile, 'userId')
|
||||||
|
profile: Profile;
|
||||||
|
|
||||||
|
// Many-to-many relationship
|
||||||
|
@ManyToMany(() => Tag, 'post_tags', 'tag_id', 'post_id')
|
||||||
|
tags: Tag[];
|
||||||
|
```
|
||||||
|
|
||||||
|
### Lifecycle Hook Decorators
|
||||||
|
**Location**: `src/framework/models/decorators/hooks.ts`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
@BeforeCreate()
|
||||||
|
setupDefaults() {
|
||||||
|
this.createdAt = Date.now();
|
||||||
|
}
|
||||||
|
|
||||||
|
@AfterCreate()
|
||||||
|
async sendNotification() {
|
||||||
|
await this.notifyUsers();
|
||||||
|
}
|
||||||
|
|
||||||
|
@BeforeUpdate()
|
||||||
|
updateTimestamp() {
|
||||||
|
this.updatedAt = Date.now();
|
||||||
|
}
|
||||||
|
|
||||||
|
@AfterUpdate()
|
||||||
|
async invalidateCache() {
|
||||||
|
await this.clearRelatedCache();
|
||||||
|
}
|
||||||
|
|
||||||
|
@BeforeDelete()
|
||||||
|
async checkPermissions() {
|
||||||
|
if (!this.canDelete()) {
|
||||||
|
throw new Error('Cannot delete this record');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@AfterDelete()
|
||||||
|
async cleanupRelations() {
|
||||||
|
await this.removeRelatedData();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Query System
|
||||||
|
|
||||||
|
### QueryBuilder Class
|
||||||
|
**Location**: `src/framework/query/QueryBuilder.ts`
|
||||||
|
|
||||||
|
Fluent interface for building queries:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export class QueryBuilder<T> {
|
||||||
|
// Filter methods
|
||||||
|
where(field: string, value: any): QueryBuilder<T>
|
||||||
|
where(field: string, operator: string, value: any): QueryBuilder<T>
|
||||||
|
where(callback: (query: QueryBuilder<T>) => void): QueryBuilder<T>
|
||||||
|
orWhere(field: string, value: any): QueryBuilder<T>
|
||||||
|
whereIn(field: string, values: any[]): QueryBuilder<T>
|
||||||
|
whereNotIn(field: string, values: any[]): QueryBuilder<T>
|
||||||
|
whereNull(field: string): QueryBuilder<T>
|
||||||
|
whereNotNull(field: string): QueryBuilder<T>
|
||||||
|
whereLike(field: string, pattern: string): QueryBuilder<T>
|
||||||
|
|
||||||
|
// Relationship methods
|
||||||
|
with(relations: string[]): QueryBuilder<T>
|
||||||
|
withCount(relations: string[]): QueryBuilder<T>
|
||||||
|
|
||||||
|
// Ordering and limiting
|
||||||
|
orderBy(field: string, direction?: 'asc' | 'desc'): QueryBuilder<T>
|
||||||
|
limit(count: number): QueryBuilder<T>
|
||||||
|
offset(count: number): QueryBuilder<T>
|
||||||
|
|
||||||
|
// Field selection
|
||||||
|
select(fields: string[]): QueryBuilder<T>
|
||||||
|
distinct(field?: string): QueryBuilder<T>
|
||||||
|
|
||||||
|
// Caching
|
||||||
|
cache(ttl?: number): QueryBuilder<T>
|
||||||
|
|
||||||
|
// Execution methods
|
||||||
|
find(): Promise<T[]>
|
||||||
|
findOne(): Promise<T | null>
|
||||||
|
first(): Promise<T | null>
|
||||||
|
count(): Promise<number>
|
||||||
|
exists(): Promise<boolean>
|
||||||
|
paginate(page: number, perPage: number): Promise<PaginationResult<T>>
|
||||||
|
|
||||||
|
// Aggregation
|
||||||
|
sum(field: string): Promise<number>
|
||||||
|
avg(field: string): Promise<number>
|
||||||
|
min(field: string): Promise<any>
|
||||||
|
max(field: string): Promise<any>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Query Operators
|
||||||
|
```typescript
|
||||||
|
type QueryOperator =
|
||||||
|
| 'eq' // Equal to
|
||||||
|
| 'ne' // Not equal to
|
||||||
|
| 'gt' // Greater than
|
||||||
|
| 'gte' // Greater than or equal
|
||||||
|
| 'lt' // Less than
|
||||||
|
| 'lte' // Less than or equal
|
||||||
|
| 'in' // In array
|
||||||
|
| 'not in' // Not in array
|
||||||
|
| 'like' // Pattern matching
|
||||||
|
| 'regex' // Regular expression
|
||||||
|
| 'is null' // Is null
|
||||||
|
| 'is not null' // Is not null
|
||||||
|
| 'includes' // Array includes value
|
||||||
|
| 'includes any'// Array includes any of values
|
||||||
|
| 'includes all'// Array includes all values
|
||||||
|
```
|
||||||
|
|
||||||
|
## Database Management
|
||||||
|
|
||||||
|
### DatabaseManager Class
|
||||||
|
**Location**: `src/framework/core/DatabaseManager.ts`
|
||||||
|
|
||||||
|
Handles database creation and lifecycle:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export class DatabaseManager {
|
||||||
|
// Database operations
|
||||||
|
async getGlobalDatabase(modelName: string): Promise<Database>
|
||||||
|
async getUserDatabase(userId: string, modelName: string): Promise<Database>
|
||||||
|
async createDatabase(name: string, type: StoreType, options?: any): Promise<Database>
|
||||||
|
async closeDatabase(name: string): Promise<void>
|
||||||
|
|
||||||
|
// Document operations
|
||||||
|
async getDocument(database: Database, storeType: StoreType, id: string): Promise<any>
|
||||||
|
async putDocument(database: Database, storeType: StoreType, id: string, data: any): Promise<void>
|
||||||
|
async deleteDocument(database: Database, storeType: StoreType, id: string): Promise<void>
|
||||||
|
async queryDocuments(database: Database, storeType: StoreType, query: any): Promise<any[]>
|
||||||
|
|
||||||
|
// Lifecycle
|
||||||
|
async initialize(orbitDBService: FrameworkOrbitDBService): Promise<void>
|
||||||
|
async stop(): Promise<void>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### ShardManager Class
|
||||||
|
**Location**: `src/framework/sharding/ShardManager.ts`
|
||||||
|
|
||||||
|
Handles data distribution across shards:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export class ShardManager {
|
||||||
|
// Shard operations
|
||||||
|
getShardForKey(modelName: string, key: string): Shard
|
||||||
|
getShardForRange(modelName: string, value: any): Shard
|
||||||
|
getAllShards(modelName: string): Shard[]
|
||||||
|
|
||||||
|
// Shard management
|
||||||
|
async createShards(modelName: string, config: ShardingConfig): Promise<void>
|
||||||
|
async redistributeData(modelName: string, newShardCount: number): Promise<void>
|
||||||
|
|
||||||
|
// Configuration
|
||||||
|
setShardingConfig(modelName: string, config: ShardingConfig): void
|
||||||
|
getShardingConfig(modelName: string): ShardingConfig | undefined
|
||||||
|
}
|
||||||
|
|
||||||
|
interface ShardingConfig {
|
||||||
|
strategy: 'hash' | 'range' | 'user';
|
||||||
|
count: number;
|
||||||
|
key: string;
|
||||||
|
ranges?: ShardRange[];
|
||||||
|
}
|
||||||
|
|
||||||
|
interface Shard {
|
||||||
|
id: string;
|
||||||
|
database: Database;
|
||||||
|
range?: { min: any; max: any };
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Relationship Management
|
||||||
|
|
||||||
|
### RelationshipManager Class
|
||||||
|
**Location**: `src/framework/relationships/RelationshipManager.ts`
|
||||||
|
|
||||||
|
Handles loading and caching of model relationships:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export class RelationshipManager {
|
||||||
|
// Relationship loading
|
||||||
|
async loadRelationship(model: BaseModel, relationshipName: string): Promise<any>
|
||||||
|
async loadRelationships(model: BaseModel, relationshipNames: string[]): Promise<void>
|
||||||
|
async eagerLoadRelationships(models: BaseModel[], relationshipNames: string[]): Promise<void>
|
||||||
|
|
||||||
|
// Relationship operations
|
||||||
|
async attachRelationship(model: BaseModel, relationshipName: string, relatedModel: BaseModel): Promise<void>
|
||||||
|
async detachRelationship(model: BaseModel, relationshipName: string, relatedModel: BaseModel): Promise<void>
|
||||||
|
async syncRelationship(model: BaseModel, relationshipName: string, relatedModels: BaseModel[]): Promise<void>
|
||||||
|
|
||||||
|
// Caching
|
||||||
|
getCachedRelationship(model: BaseModel, relationshipName: string): any
|
||||||
|
setCachedRelationship(model: BaseModel, relationshipName: string, data: any): void
|
||||||
|
clearRelationshipCache(model: BaseModel, relationshipName?: string): void
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Migration System
|
||||||
|
|
||||||
|
### MigrationManager Class
|
||||||
|
**Location**: `src/framework/migrations/MigrationManager.ts`
|
||||||
|
|
||||||
|
Handles schema evolution and data transformation:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export class MigrationManager {
|
||||||
|
// Migration operations
|
||||||
|
async runMigration(migrationId: string): Promise<MigrationResult>
|
||||||
|
async rollbackMigration(migrationId: string): Promise<MigrationResult>
|
||||||
|
async runPendingMigrations(): Promise<MigrationResult[]>
|
||||||
|
|
||||||
|
// Migration management
|
||||||
|
registerMigration(migration: Migration): void
|
||||||
|
getPendingMigrations(): Migration[]
|
||||||
|
getAppliedMigrations(): Promise<string[]>
|
||||||
|
|
||||||
|
// Status
|
||||||
|
getMigrationStatus(): Promise<MigrationStatus>
|
||||||
|
}
|
||||||
|
|
||||||
|
interface Migration {
|
||||||
|
id: string;
|
||||||
|
version: string;
|
||||||
|
name: string;
|
||||||
|
description: string;
|
||||||
|
targetModels: string[];
|
||||||
|
up: MigrationOperation[];
|
||||||
|
down: MigrationOperation[];
|
||||||
|
dependencies?: string[];
|
||||||
|
validators?: MigrationValidator[];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### MigrationBuilder Class
|
||||||
|
**Location**: `src/framework/migrations/MigrationBuilder.ts`
|
||||||
|
|
||||||
|
Fluent interface for creating migrations:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export function createMigration(name: string, version: string): MigrationBuilder {
|
||||||
|
return new MigrationBuilder(name, version);
|
||||||
|
}
|
||||||
|
|
||||||
|
export class MigrationBuilder {
|
||||||
|
// Field operations
|
||||||
|
addField(modelName: string, fieldName: string, config: FieldConfig): MigrationBuilder
|
||||||
|
removeField(modelName: string, fieldName: string): MigrationBuilder
|
||||||
|
modifyField(modelName: string, fieldName: string, config: FieldConfig): MigrationBuilder
|
||||||
|
renameField(modelName: string, oldName: string, newName: string): MigrationBuilder
|
||||||
|
|
||||||
|
// Index operations
|
||||||
|
addIndex(modelName: string, fields: string[], options?: IndexOptions): MigrationBuilder
|
||||||
|
removeIndex(modelName: string, indexName: string): MigrationBuilder
|
||||||
|
|
||||||
|
// Data transformation
|
||||||
|
transformData(modelName: string, transformer: (data: any) => any): MigrationBuilder
|
||||||
|
|
||||||
|
// Validation
|
||||||
|
addValidator(name: string, validator: MigrationValidator): MigrationBuilder
|
||||||
|
|
||||||
|
// Build migration
|
||||||
|
build(): Migration
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Caching System
|
||||||
|
|
||||||
|
### QueryCache Class
|
||||||
|
**Location**: `src/framework/query/QueryCache.ts`
|
||||||
|
|
||||||
|
Intelligent caching of query results:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export class QueryCache {
|
||||||
|
// Cache operations
|
||||||
|
get(key: string): Promise<any>
|
||||||
|
set(key: string, value: any, ttl?: number): Promise<void>
|
||||||
|
delete(key: string): Promise<void>
|
||||||
|
clear(): Promise<void>
|
||||||
|
|
||||||
|
// Cache management
|
||||||
|
invalidateModelCache(modelName: string): Promise<void>
|
||||||
|
invalidateUserCache(userId: string): Promise<void>
|
||||||
|
|
||||||
|
// Statistics
|
||||||
|
getStats(): CacheStats
|
||||||
|
getHitRate(): number
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### RelationshipCache Class
|
||||||
|
**Location**: `src/framework/relationships/RelationshipCache.ts`
|
||||||
|
|
||||||
|
Specialized caching for relationship data:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export class RelationshipCache {
|
||||||
|
// Relationship caching
|
||||||
|
getCachedRelationship(modelId: string, relationshipName: string): any
|
||||||
|
setCachedRelationship(modelId: string, relationshipName: string, data: any, ttl?: number): void
|
||||||
|
invalidateRelationship(modelId: string, relationshipName: string): void
|
||||||
|
|
||||||
|
// Batch operations
|
||||||
|
preloadRelationships(modelIds: string[], relationshipNames: string[]): Promise<void>
|
||||||
|
warmCache(modelName: string, relationshipName: string): Promise<void>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Type Definitions
|
||||||
|
|
||||||
|
### Framework Types
|
||||||
|
**Location**: `src/framework/types/framework.ts`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export interface FrameworkConfig {
|
||||||
|
cache?: CacheConfig;
|
||||||
|
queryOptimization?: QueryOptimizationConfig;
|
||||||
|
automaticPinning?: PinningConfig;
|
||||||
|
pubsub?: PubSubConfig;
|
||||||
|
development?: DevelopmentConfig;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface CacheConfig {
|
||||||
|
enabled?: boolean;
|
||||||
|
maxSize?: number;
|
||||||
|
ttl?: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
export type StoreType = 'docstore' | 'eventlog' | 'keyvalue' | 'counter' | 'feed';
|
||||||
|
```
|
||||||
|
|
||||||
|
### Model Types
|
||||||
|
**Location**: `src/framework/types/models.ts`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export interface FieldConfig {
|
||||||
|
type: FieldType;
|
||||||
|
required?: boolean;
|
||||||
|
unique?: boolean;
|
||||||
|
default?: any | (() => any);
|
||||||
|
validate?: (value: any) => boolean;
|
||||||
|
transform?: (value: any) => any;
|
||||||
|
serialize?: boolean;
|
||||||
|
index?: boolean;
|
||||||
|
virtual?: boolean;
|
||||||
|
}
|
||||||
|
|
||||||
|
export type FieldType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'date';
|
||||||
|
|
||||||
|
export interface RelationshipConfig {
|
||||||
|
type: 'belongsTo' | 'hasMany' | 'hasOne' | 'manyToMany';
|
||||||
|
target: () => typeof BaseModel;
|
||||||
|
foreignKey: string;
|
||||||
|
localKey?: string;
|
||||||
|
through?: string;
|
||||||
|
throughForeignKey?: string;
|
||||||
|
throughLocalKey?: string;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Query Types
|
||||||
|
**Location**: `src/framework/types/queries.ts`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export interface QueryOptions {
|
||||||
|
where?: WhereClause[];
|
||||||
|
orderBy?: OrderByClause[];
|
||||||
|
limit?: number;
|
||||||
|
offset?: number;
|
||||||
|
with?: string[];
|
||||||
|
cache?: boolean | number;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface WhereClause {
|
||||||
|
field: string;
|
||||||
|
operator: QueryOperator;
|
||||||
|
value: any;
|
||||||
|
boolean: 'and' | 'or';
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface OrderByClause {
|
||||||
|
field: string;
|
||||||
|
direction: 'asc' | 'desc';
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface PaginationResult<T> {
|
||||||
|
data: T[];
|
||||||
|
total: number;
|
||||||
|
page: number;
|
||||||
|
perPage: number;
|
||||||
|
totalPages: number;
|
||||||
|
hasNext: boolean;
|
||||||
|
hasPrev: boolean;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
### Framework Errors
|
||||||
|
```typescript
|
||||||
|
export class DebrosFrameworkError extends Error {
|
||||||
|
code: string;
|
||||||
|
details?: any;
|
||||||
|
|
||||||
|
constructor(message: string, code?: string, details?: any) {
|
||||||
|
super(message);
|
||||||
|
this.name = 'DebrosFrameworkError';
|
||||||
|
this.code = code || 'UNKNOWN_ERROR';
|
||||||
|
this.details = details;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export class ValidationError extends DebrosFrameworkError {
|
||||||
|
field: string;
|
||||||
|
value: any;
|
||||||
|
constraint: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
export class QueryError extends DebrosFrameworkError {
|
||||||
|
query: string;
|
||||||
|
parameters?: any[];
|
||||||
|
}
|
||||||
|
|
||||||
|
export class RelationshipError extends DebrosFrameworkError {
|
||||||
|
modelName: string;
|
||||||
|
relationshipName: string;
|
||||||
|
relatedModel: string;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Performance Optimization
|
||||||
|
|
||||||
|
### Query Optimization
|
||||||
|
**Location**: `src/framework/query/QueryOptimizer.ts`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export class QueryOptimizer {
|
||||||
|
// Query optimization
|
||||||
|
optimizeQuery(query: QueryBuilder<any>): QueryBuilder<any>
|
||||||
|
analyzeQueryPerformance(query: QueryBuilder<any>): Promise<QueryAnalysis>
|
||||||
|
suggestIndexes(modelName: string): Promise<IndexSuggestion[]>
|
||||||
|
|
||||||
|
// Statistics
|
||||||
|
getSlowQueries(): Promise<SlowQuery[]>
|
||||||
|
getQueryStats(): Promise<QueryStats>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### LazyLoader Class
|
||||||
|
**Location**: `src/framework/relationships/LazyLoader.ts`
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export class LazyLoader {
|
||||||
|
// Lazy loading
|
||||||
|
async loadOnDemand(model: BaseModel, relationshipName: string): Promise<any>
|
||||||
|
async batchLoad(models: BaseModel[], relationshipName: string): Promise<void>
|
||||||
|
|
||||||
|
// Configuration
|
||||||
|
setBatchSize(size: number): void
|
||||||
|
setLoadingStrategy(strategy: 'immediate' | 'batched' | 'deferred'): void
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This technical reference provides the implementation details needed to work effectively with the DebrosFramework codebase.
|
||||||
Reference in New Issue
Block a user