anonpenguin
067e462339
- Added a new SVG file `undraw_docusaurus_tree.svg` to the static images directory for enhanced visual representation. - Created a `tsconfig.json` file to improve TypeScript support and editor experience, extending from the Docusaurus base configuration.
454 lines
12 KiB
Markdown
454 lines
12 KiB
Markdown
---
|
|
sidebar_position: 1
|
|
---
|
|
|
|
# API Reference Overview
|
|
|
|
The DebrosFramework API provides a comprehensive set of classes, methods, and interfaces for building decentralized applications. This reference covers all public APIs, their parameters, return types, and usage examples.
|
|
|
|
## Core Framework Classes
|
|
|
|
### Primary Classes
|
|
|
|
| Class | Description | Key Features |
|
|
| ----------------------------------------------- | ---------------------------- | ------------------------------------ |
|
|
| [`DebrosFramework`](./debros-framework) | Main framework class | Initialization, lifecycle management |
|
|
| [`BaseModel`](./base-model) | Abstract base for all models | CRUD operations, validation, hooks |
|
|
| [`DatabaseManager`](./database-manager) | Database management | User/global databases, lifecycle |
|
|
| [`ShardManager`](./shard-manager) | Data sharding | Distribution strategies, routing |
|
|
| [`QueryBuilder`](./query-builder) | Query construction | Fluent API, type safety |
|
|
| [`QueryExecutor`](./query-executor) | Query execution | Optimization, caching |
|
|
| [`RelationshipManager`](./relationship-manager) | Relationship handling | Lazy/eager loading, caching |
|
|
| [`MigrationManager`](./migration-manager) | Schema migrations | Version control, rollbacks |
|
|
| [`MigrationBuilder`](./migration-builder) | Migration creation | Fluent API, validation |
|
|
|
|
### Utility Classes
|
|
|
|
| Class | Description | Use Case |
|
|
| ------------------- | ------------------------ | ------------------------------ |
|
|
| `ModelRegistry` | Model registration | Framework initialization |
|
|
| `ConfigManager` | Configuration management | Environment-specific settings |
|
|
| `PinningManager` | Automatic pinning | Data availability optimization |
|
|
| `PubSubManager` | Event publishing | Real-time features |
|
|
| `QueryCache` | Query result caching | Performance optimization |
|
|
| `QueryOptimizer` | Query optimization | Automatic performance tuning |
|
|
| `RelationshipCache` | Relationship caching | Relationship performance |
|
|
| `LazyLoader` | Lazy loading | On-demand data loading |
|
|
|
|
## Decorators
|
|
|
|
### Model Decorators
|
|
|
|
| Decorator | Purpose | Usage |
|
|
| ------------------------------ | -------------------------- | ------------------ |
|
|
| [`@Model`](./decorators/model) | Define model configuration | Class decorator |
|
|
| [`@Field`](./decorators/field) | Define field properties | Property decorator |
|
|
|
|
### Relationship Decorators
|
|
|
|
| Decorator | Relationship Type | Usage |
|
|
| ------------------------------------------------------ | ----------------- | ------------------ |
|
|
| [`@BelongsTo`](./decorators/relationships#belongsto) | Many-to-one | Property decorator |
|
|
| [`@HasMany`](./decorators/relationships#hasmany) | One-to-many | Property decorator |
|
|
| [`@HasOne`](./decorators/relationships#hasone) | One-to-one | Property decorator |
|
|
| [`@ManyToMany`](./decorators/relationships#manytomany) | Many-to-many | Property decorator |
|
|
|
|
### Hook Decorators
|
|
|
|
| Decorator | Trigger | Usage |
|
|
| -------------------------------------------------- | --------------------------- | ---------------- |
|
|
| [`@BeforeCreate`](./decorators/hooks#beforecreate) | Before creating record | Method decorator |
|
|
| [`@AfterCreate`](./decorators/hooks#aftercreate) | After creating record | Method decorator |
|
|
| [`@BeforeUpdate`](./decorators/hooks#beforeupdate) | Before updating record | Method decorator |
|
|
| [`@AfterUpdate`](./decorators/hooks#afterupdate) | After updating record | Method decorator |
|
|
| [`@BeforeDelete`](./decorators/hooks#beforedelete) | Before deleting record | Method decorator |
|
|
| [`@AfterDelete`](./decorators/hooks#afterdelete) | After deleting record | Method decorator |
|
|
| [`@BeforeSave`](./decorators/hooks#beforesave) | Before save (create/update) | Method decorator |
|
|
| [`@AfterSave`](./decorators/hooks#aftersave) | After save (create/update) | Method decorator |
|
|
|
|
## Type Definitions
|
|
|
|
### Core Types
|
|
|
|
```typescript
|
|
// Model configuration
|
|
interface ModelConfig {
|
|
scope: 'user' | 'global';
|
|
type: StoreType;
|
|
sharding?: ShardingConfig;
|
|
pinning?: PinningConfig;
|
|
pubsub?: PubSubConfig;
|
|
validation?: ValidationConfig;
|
|
}
|
|
|
|
// Field configuration
|
|
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;
|
|
}
|
|
|
|
// Query types
|
|
interface QueryOptions {
|
|
where?: WhereClause[];
|
|
orderBy?: OrderByClause[];
|
|
limit?: number;
|
|
offset?: number;
|
|
with?: string[];
|
|
cache?: boolean | number;
|
|
}
|
|
```
|
|
|
|
### Enum Types
|
|
|
|
```typescript
|
|
// Store types
|
|
type StoreType = 'docstore' | 'eventlog' | 'keyvalue' | 'counter' | 'feed';
|
|
|
|
// Field types
|
|
type FieldType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'date';
|
|
|
|
// Sharding strategies
|
|
type ShardingStrategy = 'hash' | 'range' | 'user';
|
|
|
|
// Query operators
|
|
type QueryOperator =
|
|
| 'eq'
|
|
| 'ne'
|
|
| 'gt'
|
|
| 'gte'
|
|
| 'lt'
|
|
| 'lte'
|
|
| 'in'
|
|
| 'not in'
|
|
| 'like'
|
|
| 'regex'
|
|
| 'is null'
|
|
| 'is not null'
|
|
| 'includes'
|
|
| 'includes any'
|
|
| 'includes all';
|
|
```
|
|
|
|
## Configuration Interfaces
|
|
|
|
### Framework Configuration
|
|
|
|
```typescript
|
|
interface DebrosFrameworkConfig {
|
|
// Cache configuration
|
|
cache?: {
|
|
enabled?: boolean;
|
|
maxSize?: number;
|
|
ttl?: number;
|
|
};
|
|
|
|
// Query optimization
|
|
queryOptimization?: {
|
|
enabled?: boolean;
|
|
cacheQueries?: boolean;
|
|
parallelExecution?: boolean;
|
|
};
|
|
|
|
// Automatic features
|
|
automaticPinning?: {
|
|
enabled?: boolean;
|
|
strategy?: 'popularity' | 'fixed' | 'tiered';
|
|
};
|
|
|
|
// PubSub configuration
|
|
pubsub?: {
|
|
enabled?: boolean;
|
|
bufferSize?: number;
|
|
};
|
|
|
|
// Development settings
|
|
development?: {
|
|
logLevel?: 'debug' | 'info' | 'warn' | 'error';
|
|
enableMetrics?: boolean;
|
|
};
|
|
}
|
|
```
|
|
|
|
### Sharding Configuration
|
|
|
|
```typescript
|
|
interface ShardingConfig {
|
|
strategy: ShardingStrategy;
|
|
count: number;
|
|
key: string;
|
|
ranges?: ShardRange[];
|
|
}
|
|
|
|
interface ShardRange {
|
|
min: any;
|
|
max: any;
|
|
shard: number;
|
|
}
|
|
```
|
|
|
|
### Pinning Configuration
|
|
|
|
```typescript
|
|
interface PinningConfig {
|
|
strategy: 'fixed' | 'popularity' | 'tiered';
|
|
factor?: number;
|
|
maxPins?: number;
|
|
ttl?: number;
|
|
}
|
|
```
|
|
|
|
## Error Types
|
|
|
|
### Framework Errors
|
|
|
|
```typescript
|
|
class DebrosFrameworkError extends Error {
|
|
code: string;
|
|
details?: any;
|
|
}
|
|
|
|
class ValidationError extends DebrosFrameworkError {
|
|
field: string;
|
|
value: any;
|
|
constraint: string;
|
|
}
|
|
|
|
class QueryError extends DebrosFrameworkError {
|
|
query: string;
|
|
parameters?: any[];
|
|
}
|
|
|
|
class RelationshipError extends DebrosFrameworkError {
|
|
modelName: string;
|
|
relationshipName: string;
|
|
relatedModel: string;
|
|
}
|
|
```
|
|
|
|
## Response Types
|
|
|
|
### Query Results
|
|
|
|
```typescript
|
|
interface QueryResult<T> {
|
|
data: T[];
|
|
total: number;
|
|
page?: number;
|
|
perPage?: number;
|
|
totalPages?: number;
|
|
hasMore?: boolean;
|
|
}
|
|
|
|
interface PaginationInfo {
|
|
page: number;
|
|
perPage: number;
|
|
total: number;
|
|
totalPages: number;
|
|
hasNext: boolean;
|
|
hasPrev: boolean;
|
|
}
|
|
```
|
|
|
|
### Operation Results
|
|
|
|
```typescript
|
|
interface CreateResult<T> {
|
|
model: T;
|
|
created: boolean;
|
|
errors?: ValidationError[];
|
|
}
|
|
|
|
interface UpdateResult<T> {
|
|
model: T;
|
|
updated: boolean;
|
|
changes: string[];
|
|
errors?: ValidationError[];
|
|
}
|
|
|
|
interface DeleteResult {
|
|
deleted: boolean;
|
|
id: string;
|
|
}
|
|
```
|
|
|
|
## Event Types
|
|
|
|
### Model Events
|
|
|
|
```typescript
|
|
interface ModelEvent {
|
|
type: 'create' | 'update' | 'delete';
|
|
modelName: string;
|
|
modelId: string;
|
|
data?: any;
|
|
changes?: string[];
|
|
timestamp: number;
|
|
userId?: string;
|
|
}
|
|
|
|
interface RelationshipEvent {
|
|
type: 'attach' | 'detach';
|
|
modelName: string;
|
|
modelId: string;
|
|
relationshipName: string;
|
|
relatedModelName: string;
|
|
relatedModelId: string;
|
|
timestamp: number;
|
|
}
|
|
```
|
|
|
|
### Framework Events
|
|
|
|
```typescript
|
|
interface FrameworkEvent {
|
|
type: 'initialized' | 'stopped' | 'error';
|
|
message?: string;
|
|
error?: Error;
|
|
timestamp: number;
|
|
}
|
|
|
|
interface DatabaseEvent {
|
|
type: 'created' | 'opened' | 'closed';
|
|
databaseName: string;
|
|
scope: 'user' | 'global';
|
|
userId?: string;
|
|
timestamp: number;
|
|
}
|
|
```
|
|
|
|
## Migration Types
|
|
|
|
### Migration Configuration
|
|
|
|
```typescript
|
|
interface Migration {
|
|
id: string;
|
|
version: string;
|
|
name: string;
|
|
description: string;
|
|
targetModels: string[];
|
|
up: MigrationOperation[];
|
|
down: MigrationOperation[];
|
|
dependencies?: string[];
|
|
validators?: MigrationValidator[];
|
|
createdAt: number;
|
|
}
|
|
|
|
interface MigrationOperation {
|
|
type:
|
|
| 'add_field'
|
|
| 'remove_field'
|
|
| 'modify_field'
|
|
| 'rename_field'
|
|
| 'add_index'
|
|
| 'remove_index'
|
|
| 'transform_data'
|
|
| 'custom';
|
|
modelName: string;
|
|
fieldName?: string;
|
|
newFieldName?: string;
|
|
fieldConfig?: FieldConfig;
|
|
transformer?: (data: any) => any;
|
|
customOperation?: (context: MigrationContext) => Promise<void>;
|
|
}
|
|
```
|
|
|
|
## Constants
|
|
|
|
### Default Values
|
|
|
|
```typescript
|
|
const DEFAULT_CONFIG = {
|
|
CACHE_SIZE: 1000,
|
|
CACHE_TTL: 300000, // 5 minutes
|
|
QUERY_TIMEOUT: 30000, // 30 seconds
|
|
MAX_CONCURRENT_QUERIES: 10,
|
|
DEFAULT_PAGE_SIZE: 20,
|
|
MAX_PAGE_SIZE: 1000,
|
|
SHARD_COUNT: 4,
|
|
PIN_FACTOR: 2,
|
|
};
|
|
```
|
|
|
|
### Status Codes
|
|
|
|
```typescript
|
|
enum StatusCodes {
|
|
SUCCESS = 200,
|
|
CREATED = 201,
|
|
NO_CONTENT = 204,
|
|
BAD_REQUEST = 400,
|
|
NOT_FOUND = 404,
|
|
VALIDATION_ERROR = 422,
|
|
INTERNAL_ERROR = 500,
|
|
}
|
|
```
|
|
|
|
## Utility Functions
|
|
|
|
### Helper Functions
|
|
|
|
```typescript
|
|
// Model utilities
|
|
function getModelConfig(modelClass: typeof BaseModel): ModelConfig;
|
|
function getFieldConfig(modelClass: typeof BaseModel, fieldName: string): FieldConfig;
|
|
function getRelationshipConfig(modelClass: typeof BaseModel): RelationshipConfig[];
|
|
|
|
// Query utilities
|
|
function buildWhereClause(field: string, operator: QueryOperator, value: any): WhereClause;
|
|
function optimizeQuery(query: QueryBuilder): QueryBuilder;
|
|
function cacheKey(query: QueryBuilder): string;
|
|
|
|
// Validation utilities
|
|
function validateFieldValue(value: any, config: FieldConfig): ValidationResult;
|
|
function sanitizeInput(value: any): any;
|
|
function normalizeEmail(email: string): string;
|
|
```
|
|
|
|
## Version Information
|
|
|
|
Current API version: **1.0.0**
|
|
|
|
### Version Compatibility
|
|
|
|
| Framework Version | API Version | Breaking Changes |
|
|
| ----------------- | ----------- | --------------------------- |
|
|
| 1.0.x | 1.0.0 | None |
|
|
| 1.1.x | 1.0.0 | None (backwards compatible) |
|
|
|
|
### Deprecation Policy
|
|
|
|
- Deprecated APIs are marked with `@deprecated` tags
|
|
- Deprecated features are supported for at least 2 minor versions
|
|
- Breaking changes only occur in major version updates
|
|
- Migration guides are provided for breaking changes
|
|
|
|
## Getting Help
|
|
|
|
### Documentation
|
|
|
|
- **[Getting Started Guide](../getting-started)** - Basic setup and usage
|
|
- **[Core Concepts](../core-concepts/architecture)** - Framework architecture
|
|
- **[Examples](../examples/basic-usage)** - Practical examples
|
|
|
|
### Support
|
|
|
|
- **GitHub Issues** - Bug reports and feature requests
|
|
- **Discord Community** - Real-time help and discussion
|
|
- **Stack Overflow** - Tagged questions with `debros-framework`
|
|
|
|
### Contributing
|
|
|
|
- **[Contributing Guide](https://github.com/debros/network/blob/main/CONTRIBUTING.md)** - How to contribute
|
|
- **[API Design Guidelines](https://github.com/debros/network/blob/main/API_DESIGN.md)** - API design principles
|
|
- **[Development Setup](https://github.com/debros/network/blob/main/DEVELOPMENT.md)** - Local development setup
|
|
|
|
This API reference provides comprehensive documentation for all public interfaces in DebrosFramework. For detailed information about specific classes and methods, explore the individual API documentation pages.
|