{"id":27861214,"url":"https://github.com/the-forgebase/dart_forgebase_sdk","last_synced_at":"2025-09-04T06:37:48.136Z","repository":{"id":285644243,"uuid":"958860987","full_name":"The-ForgeBase/dart_forgebase_sdk","owner":"The-ForgeBase","description":"The ForgeBase Dart/Flutter Client SDK - A powerful and flexible SDK for interacting with ForgeBase databases","archived":false,"fork":false,"pushed_at":"2025-04-09T08:42:41.000Z","size":35,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-03T15:13:13.313Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/The-ForgeBase.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-01T22:09:03.000Z","updated_at":"2025-04-09T08:42:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"48e638cf-5d2a-4288-a396-68f1899fffda","html_url":"https://github.com/The-ForgeBase/dart_forgebase_sdk","commit_stats":null,"previous_names":["the-forgebase/dart_forgebase_sdk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/The-ForgeBase/dart_forgebase_sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-ForgeBase%2Fdart_forgebase_sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-ForgeBase%2Fdart_forgebase_sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-ForgeBase%2Fdart_forgebase_sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-ForgeBase%2Fdart_forgebase_sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/The-ForgeBase","download_url":"https://codeload.github.com/The-ForgeBase/dart_forgebase_sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-ForgeBase%2Fdart_forgebase_sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273567067,"owners_count":25128630,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-04T18:34:15.944Z","updated_at":"2025-09-04T06:37:48.119Z","avatar_url":"https://github.com/The-ForgeBase.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ForgeBase SDK for Dart/Flutter\n\nA 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.\n\n## Features\n\n- 🚀 **Fluent Query Builder API**: Build type-safe database queries with an intuitive builder pattern\n- 🔒 **Type Safety**: Full TypeScript-like generic support for your data models\n- 🔄 **CRUD Operations**: Simple methods for Create, Read, Update, and Delete operations\n- 📊 **Advanced Query Features**:\n  - Complex filtering with AND/OR conditions\n  - Window functions and analytics\n  - Common Table Expressions (CTEs)\n  - Aggregations and grouping\n  - Subqueries and EXISTS clauses\n  - Pagination and sorting\n  - Data transformations and computations\n- 🔄 **Result Transformations**:\n  - Compute derived fields\n  - Pivot data for cross-tabulation\n  - Group and aggregate results\n- 🔐 **Authentication Support**: Easily integrate with authentication systems\n- 🧠 **Query Validation**: Validate queries before execution\n- 📦 **Caching Support**: Cache query results for better performance\n- ⚡ **Performance**: Optimized HTTP client using Dio\n- 🔍 **Error Handling**: Detailed error messages and proper error typing\n\n## Installation\n\nAdd this to your package's `pubspec.yaml` file:\n\n```yaml\ndependencies:\n  forgebase_sdk: ^0.0.2\n```\n\n## Quick Start\n\n```dart\n// Initialize the SDK\nfinal sdk = DatabaseSDK('https://your-forgebase-api.com');\n\n// Simple query\nfinal users = await sdk\n    .table\u003cMap\u003cString, dynamic\u003e\u003e('users')\n    .where('status', 'active')\n    .limit(10)\n    .execute();\n\n// Complex query with joins and aggregates\nfinal orderStats = await sdk\n    .table\u003cMap\u003cString, dynamic\u003e\u003e('orders')\n    .whereExists((subquery) =\u003e\n      subquery.table('order_items')\n        .where('order_items.order_id', '=', 'orders.id')\n        .where('quantity', '\u003e', 10)\n    )\n    .groupBy(['status'])\n    .having('total_amount', WhereOperator.greaterThan, 1000)\n    .sum('amount', alias: 'total_amount')\n    .execute();\n```\n\n## Advanced Features\n\n### Window Functions\n\n```dart\nfinal rankedSalaries = await sdk\n    .table\u003cMap\u003cString, dynamic\u003e\u003e('employees')\n    .windowAdvanced(\n      WindowFunctionType.rowNumber,\n      'salary_rank',\n      over: WindowOver(\n        partitionBy: ['department'],\n        orderBy: [OrderByClause(field: 'salary', direction: SortDirection.desc)]\n      ),\n    )\n    .execute();\n```\n\n### Common Table Expressions (CTEs)\n\n```dart\nfinal hierarchicalData = await sdk\n    .table\u003cMap\u003cString, dynamic\u003e\u003e('employees')\n    .withRecursive(\n      'employee_hierarchy',\n      initialQuery,\n      recursiveQuery,\n      columns: ['id', 'manager_id', 'level'],\n    )\n    .execute();\n```\n\n### Aggregations\n\n```dart\nfinal stats = await sdk\n    .table\u003cMap\u003cString, dynamic\u003e\u003e('sales')\n    .groupBy(['region'])\n    .sum('amount', alias: 'total_sales')\n    .avg('amount', alias: 'average_sale')\n    .count('id', alias: 'num_transactions')\n    .execute();\n```\n\n## Error Handling\n\nThe SDK provides detailed error information through the `ForgeBaseException` class:\n\n```dart\ntry {\n  final result = await sdk.table('users').execute();\n} on ForgeBaseException catch (e) {\n  print('Error: ${e.message}');\n  print('Code: ${e.code}');\n  print('Status: ${e.statusCode}');\n}\n```\n\n## API Reference\n\n### DatabaseSDK\n\nThe main entry point for interacting with your ForgeBase database.\n\n```dart\n// Basic initialization\nfinal sdk = DatabaseSDK(\n  'https://api.example.com',\n  interceptors: [], // Optional Dio interceptors\n  dioOptions: BaseOptions(), // Optional Dio configuration\n);\n\n// With custom Dio instance (e.g., for authentication)\nfinal customDio = Dio();\ncustomDio.interceptors.add(AuthInterceptor());\nfinal sdk = DatabaseSDK.withDio(\n  'https://api.example.com',\n  dio: customDio,\n);\n```\n\n### Transformations\n\nTransform query results with computed fields, pivoting, and grouping:\n\n```dart\n// Compute derived fields\nfinal results = await sdk\n    .table\u003cMap\u003cString, dynamic\u003e\u003e('orders')\n    .compute({\n      'discountedTotal': (row) =\u003e row['total'] * 0.9,\n      'fullName': (row) =\u003e '${row['firstName']} ${row['lastName']}',\n    })\n    .execute();\n\n// Pivot data\nfinal pivotedData = await sdk\n    .table\u003cMap\u003cString, dynamic\u003e\u003e('sales')\n    .pivot(\n      'quarter',\n      ['Q1', 'Q2', 'Q3', 'Q4'],\n      AggregateOptions(\n        type: AggregateType.sum,\n        field: 'amount',\n      ),\n    )\n    .execute();\n```\n\n### Caching and Validation\n\n```dart\n// With caching\nfinal cachedResults = await sdk.getRecords\u003cMap\u003cString, dynamic\u003e\u003e(\n  tableName: 'products',\n  params: QueryParams(\n    filter: {'category': 'electronics'},\n  ),\n  cache: CacheConfig(\n    ttl: 300, // 5 minutes\n    key: 'electronics-products',\n    tags: ['products', 'electronics'],\n  ),\n);\n\n// With validation\nfinal validatedResults = await sdk.getRecords\u003cMap\u003cString, dynamic\u003e\u003e(\n  tableName: 'users',\n  params: QueryParams(\n    select: ['id', 'name', 'email'],\n  ),\n  validation: QueryValidation(\n    rules: ValidationRules(\n      maxLimit: 100,\n      requiredFields: ['id'],\n      disallowedFields: ['password'],\n    ),\n    suggestions: true,\n  ),\n);\n```\n\n### QueryBuilder\n\nMethods for building database queries:\n\n- `where(field, operator, value)`: Add a where clause\n- `orWhere((query) =\u003e ...)`: Add an OR where clause\n- `whereExists((subquery) =\u003e ...)`: Add a where exists clause\n- `select(fields)`: Select specific fields (accepts both list and variable arguments)\n- `groupBy(fields)`: Group results by fields (accepts both list and variable arguments)\n- `orderBy(field, direction, nulls)`: Sort results\n- `limit(value)`: Limit number of results\n- `offset(value)`: Skip number of results\n- `compute(computations)`: Add computed fields\n- `pivot(column, values, aggregate)`: Pivot data for cross-tabulation\n- `explain(options)`: Get query execution plan\n- And many more...\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthe-forgebase%2Fdart_forgebase_sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthe-forgebase%2Fdart_forgebase_sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthe-forgebase%2Fdart_forgebase_sdk/lists"}