https://github.com/the-forgebase/dart_forgebase_sdk
The ForgeBase Dart/Flutter Client SDK - A powerful and flexible SDK for interacting with ForgeBase databases
https://github.com/the-forgebase/dart_forgebase_sdk
Last synced: 10 months ago
JSON representation
The ForgeBase Dart/Flutter Client SDK - A powerful and flexible SDK for interacting with ForgeBase databases
- Host: GitHub
- URL: https://github.com/the-forgebase/dart_forgebase_sdk
- Owner: The-ForgeBase
- License: mit
- Created: 2025-04-01T22:09:03.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-09T08:42:41.000Z (about 1 year ago)
- Last Synced: 2025-06-03T15:13:13.313Z (about 1 year ago)
- Language: Dart
- Size: 34.2 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ForgeBase SDK for Dart/Flutter
A powerful and flexible Dart SDK for interacting with ForgeBase databases. This SDK provides a fluent interface for building complex queries, performing CRUD operations, and working with advanced database features like window functions, CTEs, and aggregates.
## Features
- 🚀 **Fluent Query Builder API**: Build type-safe database queries with an intuitive builder pattern
- 🔒 **Type Safety**: Full TypeScript-like generic support for your data models
- 🔄 **CRUD Operations**: Simple methods for Create, Read, Update, and Delete operations
- 📊 **Advanced Query Features**:
- Complex filtering with AND/OR conditions
- Window functions and analytics
- Common Table Expressions (CTEs)
- Aggregations and grouping
- Subqueries and EXISTS clauses
- Pagination and sorting
- Data transformations and computations
- 🔄 **Result Transformations**:
- Compute derived fields
- Pivot data for cross-tabulation
- Group and aggregate results
- 🔐 **Authentication Support**: Easily integrate with authentication systems
- 🧠 **Query Validation**: Validate queries before execution
- 📦 **Caching Support**: Cache query results for better performance
- ⚡ **Performance**: Optimized HTTP client using Dio
- 🔍 **Error Handling**: Detailed error messages and proper error typing
## Installation
Add this to your package's `pubspec.yaml` file:
```yaml
dependencies:
forgebase_sdk: ^0.0.2
```
## Quick Start
```dart
// Initialize the SDK
final sdk = DatabaseSDK('https://your-forgebase-api.com');
// Simple query
final users = await sdk
.table>('users')
.where('status', 'active')
.limit(10)
.execute();
// Complex query with joins and aggregates
final orderStats = await sdk
.table>('orders')
.whereExists((subquery) =>
subquery.table('order_items')
.where('order_items.order_id', '=', 'orders.id')
.where('quantity', '>', 10)
)
.groupBy(['status'])
.having('total_amount', WhereOperator.greaterThan, 1000)
.sum('amount', alias: 'total_amount')
.execute();
```
## Advanced Features
### Window Functions
```dart
final rankedSalaries = await sdk
.table>('employees')
.windowAdvanced(
WindowFunctionType.rowNumber,
'salary_rank',
over: WindowOver(
partitionBy: ['department'],
orderBy: [OrderByClause(field: 'salary', direction: SortDirection.desc)]
),
)
.execute();
```
### Common Table Expressions (CTEs)
```dart
final hierarchicalData = await sdk
.table>('employees')
.withRecursive(
'employee_hierarchy',
initialQuery,
recursiveQuery,
columns: ['id', 'manager_id', 'level'],
)
.execute();
```
### Aggregations
```dart
final stats = await sdk
.table>('sales')
.groupBy(['region'])
.sum('amount', alias: 'total_sales')
.avg('amount', alias: 'average_sale')
.count('id', alias: 'num_transactions')
.execute();
```
## Error Handling
The SDK provides detailed error information through the `ForgeBaseException` class:
```dart
try {
final result = await sdk.table('users').execute();
} on ForgeBaseException catch (e) {
print('Error: ${e.message}');
print('Code: ${e.code}');
print('Status: ${e.statusCode}');
}
```
## API Reference
### DatabaseSDK
The main entry point for interacting with your ForgeBase database.
```dart
// Basic initialization
final sdk = DatabaseSDK(
'https://api.example.com',
interceptors: [], // Optional Dio interceptors
dioOptions: BaseOptions(), // Optional Dio configuration
);
// With custom Dio instance (e.g., for authentication)
final customDio = Dio();
customDio.interceptors.add(AuthInterceptor());
final sdk = DatabaseSDK.withDio(
'https://api.example.com',
dio: customDio,
);
```
### Transformations
Transform query results with computed fields, pivoting, and grouping:
```dart
// Compute derived fields
final results = await sdk
.table>('orders')
.compute({
'discountedTotal': (row) => row['total'] * 0.9,
'fullName': (row) => '${row['firstName']} ${row['lastName']}',
})
.execute();
// Pivot data
final pivotedData = await sdk
.table>('sales')
.pivot(
'quarter',
['Q1', 'Q2', 'Q3', 'Q4'],
AggregateOptions(
type: AggregateType.sum,
field: 'amount',
),
)
.execute();
```
### Caching and Validation
```dart
// With caching
final cachedResults = await sdk.getRecords>(
tableName: 'products',
params: QueryParams(
filter: {'category': 'electronics'},
),
cache: CacheConfig(
ttl: 300, // 5 minutes
key: 'electronics-products',
tags: ['products', 'electronics'],
),
);
// With validation
final validatedResults = await sdk.getRecords>(
tableName: 'users',
params: QueryParams(
select: ['id', 'name', 'email'],
),
validation: QueryValidation(
rules: ValidationRules(
maxLimit: 100,
requiredFields: ['id'],
disallowedFields: ['password'],
),
suggestions: true,
),
);
```
### QueryBuilder
Methods for building database queries:
- `where(field, operator, value)`: Add a where clause
- `orWhere((query) => ...)`: Add an OR where clause
- `whereExists((subquery) => ...)`: Add a where exists clause
- `select(fields)`: Select specific fields (accepts both list and variable arguments)
- `groupBy(fields)`: Group results by fields (accepts both list and variable arguments)
- `orderBy(field, direction, nulls)`: Sort results
- `limit(value)`: Limit number of results
- `offset(value)`: Skip number of results
- `compute(computations)`: Add computed fields
- `pivot(column, values, aggregate)`: Pivot data for cross-tabulation
- `explain(options)`: Get query execution plan
- And many more...
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the LICENSE file for details.