harpy 0.1.2+1
harpy: ^0.1.2+1 copied to clipboard
A modern, fast, and lightweight backend framework for Dart
Changelog #
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
0.1.2 - 2025-10-07 #
Changed #
- Scheduler → Middleware Refactoring: Converted Scheduler system to Middleware architecture
Scheduler
class moved toSchedulerMiddleware
inlib/src/middleware/
- Integrated task scheduling into the middleware pipeline
- Improved lifecycle management with automatic startup and shutdown
- Better integration with Harpy application lifecycle
- Graceful shutdown of all tasks when server stops
Added #
- Scheduler Middleware Documentation: Complete guide for task scheduling
- Comprehensive documentation in
doc/scheduler.md
- Examples for periodic, scheduled, and instant tasks
- Best practices and patterns
- Integration examples with database operations
- Comprehensive documentation in
- Enhanced CLI Structure: Clear separation between global and project CLIs
- Global CLI (
bin/harpy.dart
) - Framework-level commands (create, version, help) - Project CLI (
bin/<project>.dart
) - Project-specific commands (serve, migrate, task) - New
lib/src/cli/
directory for CLI generation logic create_project_cli.dart
- Separate file for project CLI template generation
- Global CLI (
- Task Management via CLI: New command to add tasks to projects
dart run bin/<project>.dart task add <task_name>
- Generate task template- Automatic task file creation in
lib/tasks/
directory - Task templates for periodic, scheduled, and instant tasks
- Auto-registration hints in generated code
task list
command to display all taskstask help
command for task management help
Technical Details #
- Middleware Integration: Scheduler now follows the standard middleware pattern
- Consistent API with other Harpy middlewares
- Easy to enable via
app.enableScheduler()
- Automatic initialization and cleanup
- CLI Architecture: Improved separation of concerns
- Framework CLI handles project scaffolding
- Project CLI handles application lifecycle and development tasks
- Reusable CLI generation components via
ProjectCliGenerator
- Extensible command structure for custom commands
- Task Management: Enhanced developer experience
- CLI-driven task creation with interactive type selection
- Template-based task generation
- Clear task registration patterns
- Built-in logging and error handling
Migration Guide #
For projects using the old Scheduler:
Before (v0.1.1):
import 'package:harpy/harpy.dart';
void main() async {
final scheduler = Scheduler();
scheduler.add(MyTask());
final app = Harpy();
// Scheduler separate from app
await app.listen(port: 3000);
}
After (v0.1.2):
import 'package:harpy/harpy.dart';
void main() async {
final app = Harpy();
app.enableScheduler();
app.addTask(MyTask());
await app.listen(port: 3000);
// Scheduler automatically stops with the app
}
Breaking Changes #
Scheduler
class deprecated (useSchedulerMiddleware
throughapp.enableScheduler()
)- Direct imports of
src/scheduler/scheduler.dart
should be updated to use middleware approach - Task lifecycle now managed by Harpy application instead of standalone Scheduler
Deprecated #
Scheduler
class (useapp.enableScheduler()
instead)- Direct Scheduler instantiation (tasks should be added via
app.addTask()
)
0.1.1+4 - 2025-10-03 #
Changed #
- Project Structure Refactoring: Generated projects now use
lib/main.dart
instead ofbin/main.dart
for the main application- Main application code now resides in
lib/
following Dart conventions - Improves testability and code organization
- Allows for better code reuse and modularization
- Main application code now resides in
Added #
- CLI Management Tool: Each generated project now includes a CLI utility in
bin/<project_name>.dart
serve
command - Starts the development servermigrate
command - Placeholder for database migrations (ready for implementation)version
command - Shows project and framework versionhelp
command - Displays available commands and usage
- Enhanced project scaffolding with improved documentation
- Updated README templates for generated projects with CLI usage examples
- Better output messages after project creation showing project structure and available commands
Technical Details #
- CLI utility supports extensibility - developers can add custom commands
- Local project management without global installation conflicts
- Cleaner separation between application logic (
lib/
) and management tools (bin/
)
Migration Guide #
For existing projects created with earlier versions:
- Move
bin/main.dart
tolib/main.dart
- Optionally create a CLI utility in
bin/<your_project>.dart
(see template in new projects) - Update your IDE run configurations if needed
0.1.1+3 Previous Version #
Added #
- Initial framework structure
- HTTP server implementation
- Routing system with parameter support
- Middleware support
- Request/Response handling
- Configuration management
- Built-in middlewares (CORS, logging, authentication)
Database & ORM System #
- Complete ORM Implementation - Active Record and Repository patterns
- SQLite Adapter - Production-ready implementation with full SQL support
- PostgreSQL Adapter - Advanced features including JSON support and full-text search
- MySQL Adapter - Complete MySQL integration with connection pooling
- MongoDB Adapter - Document database support with aggregation pipeline
- Redis Adapter - Basic key-value operations (stub implementation)
- Database Migrations - Schema version control and management system
- Query Builder - Type-safe, fluent query construction
- ACID Transactions - Full transaction support with automatic rollback
- Connection Pooling - Efficient database connection management
- Model Validation - Built-in data validation with custom rules
- Active Record Pattern - Instance methods for database operations (save, delete, refresh)
- Repository Pattern - Static methods for querying and bulk operations
- Security Features - Built-in SQL injection prevention through parameterized queries
Database Features Details #
- Multi-Database Support - Unified interface across all database types
- Type Conversion - Automatic type mapping between Dart and database types
- Foreign Key Support - Relationship management and constraint enforcement
- Index Management - Create and manage database indexes for performance
- Schema Introspection - Query database structure and metadata
- Bulk Operations - Efficient batch inserts, updates, and deletes
- Connection Retry Logic - Automatic reconnection on connection failures
- Database Health Checks - Built-in connection monitoring and diagnostics
Database Adapters Status #
- SQLite ✅ Production Ready - Full implementation with file and in-memory support
- PostgreSQL ✅ Production Ready - Advanced SQL features, JSON/JSONB, arrays
- MySQL ✅ Production Ready - Standard SQL with stored procedures support
- MongoDB ✅ Production Ready - Document operations and aggregation pipelines
- Redis ⚠️ Stub Implementation - Basic structure, full implementation planned
Technical Implementation #
- Package Dependencies - sqlite3: ^2.9.0, postgres: ^3.5.6, mysql1: ^0.20.0, mongo_dart: ^0.10.5, redis: ^4.0.0
- Model System - Base Model class with attribute management and serialization
- Migration System - TableBuilder with fluent API for schema definition
- Connection Management - Factory pattern for database adapter creation
- Error Handling - Comprehensive exception hierarchy (QueryException, ConnectionException, TransactionException, ValidationException)
- Testing Support - In-memory database options for unit testing
Documentation Added #
- Complete API documentation for all ORM components
- Database adapter configuration guides
- Migration system documentation
- Model definition and validation examples
- Query builder usage patterns
- Transaction management best practices
- Performance optimization guidelines
0.1.0 - 2025-09-25 #
Added #
- Initial release of Harpy framework
- Basic HTTP server functionality
- RESTful routing
- Middleware system
Known Limitations #
- Redis Adapter - Currently implemented as stub for demonstration purposes
- Model Relationships - Basic implementation, advanced relationships (One-to-Many, Many-to-Many) planned for future releases
- Query Builder Joins - Basic join support, complex join operations under development
- Schema Migrations - Manual rollback required, automatic rollback planned
Planned Features (Future Releases) #
- Complete Redis Implementation - Full Redis client integration with all data types
- Advanced ORM Features - Model relationships, lazy loading, eager loading
- Query Optimization - Query caching, performance monitoring, query hints
- Additional Database Adapters - CouchDB, InfluxDB, Neo4j support
- Enhanced Security - Row-level security, audit logging, encryption at rest
- Performance Improvements - Connection pool optimization, query result caching
Testing & Quality Assurance #
- Comprehensive Test Suite - Over 100 tests covering all ORM functionality
- Database Adapter Tests - Individual test suites for each database adapter
- Integration Tests - Full request-response cycle testing with database operations
- Performance Tests - Connection pooling, query performance, and memory usage validation
- Security Tests - SQL injection prevention and input validation testing
- Migration Tests - Schema creation, modification, and rollback validation
Performance Benchmarks #
- SQLite Operations - 10,000+ inserts/second in single transaction
- PostgreSQL Connections - Efficient connection pooling with configurable pool sizes
- MySQL Compatibility - Full compatibility with MySQL 5.7+ and MariaDB 10.3+
- MongoDB Performance - Optimized document operations with aggregation pipeline support
- Memory Usage - Efficient model attribute management with minimal memory overhead
- Transaction Performance - ACID compliance with minimal performance impact
Breaking Changes #
- None in this initial release
Fixed #
- Deprecated Function - Replaced
getUpdatedRows()
withupdatedRows
in SQLite adapter for compatibility with sqlite3 ^2.9.0 - Router 404 Bug - Fixed critical bug where all routes returned 404 errors. The router was using
request.url.path
which returns paths without leading slash (e.g.,""
for/
,"test"
for/test
), while regex patterns expected paths with leading slash (e.g.,^/$
,^/test$
). Changed to userequest.requestedUri.path
and added path normalization for trailing slashes. Added 30 comprehensive routing tests (14 integration tests + 16 edge case tests) to prevent regressions.