Release v0.4.0: Comprehensive job prioritization system

## Major Features Added
- 🎯 **Complete Job Prioritization System**
  - Five priority levels: Background, Low, Normal, High, Critical
  - Enhanced Job struct with priority field and builder methods
  - String parsing and integer conversion for database storage

- ⚖️ **Advanced Priority-Aware Scheduling**
  - Weighted priority scheduling with configurable weights
  - Strict priority scheduling for guaranteed ordering
  - Fairness mechanisms to prevent job starvation
  - Hash-based selection for Send compatibility

- 🗄️ **Database Schema Enhancements**
  - Added priority column to PostgreSQL and MySQL schemas
  - Optimized indexes for priority-based querying
  - Priority-aware dequeue methods with weighted algorithms
  - Full backward compatibility

- 👷 **Worker Priority Configuration**
  - Configurable priority weights and selection strategies
  - Support for strict and weighted priority modes
  - Worker pools with heterogeneous priority configurations
  - Integration with existing timeout and statistics systems

- 📊 **Priority Statistics and Monitoring**
  - PriorityStats tracking per-priority metrics
  - Distribution analysis and starvation detection
  - Integration with InMemoryStatsCollector
  - Comprehensive priority performance monitoring

- 🧪 **Comprehensive Testing Suite**
  - 12 new priority-specific unit tests
  - Priority example demonstrating all features
  - Statistics integration testing
  - Edge case and configuration testing

## Technical Improvements
- Enhanced package description and documentation
- Applied clippy suggestions for cleaner code
- Consistent formatting across all files
- Fixed all stats module tests with priority field

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: CodingAnarchy

CHANGELOG.md

@@ -5,6 +5,61 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2025-06-26
+
+### Added
+- **🎯 Comprehensive Job Prioritization System**
+  - Five priority levels: `Background`, `Low`, `Normal` (default), `High`, `Critical`
+  - Enhanced `Job` struct with priority field and builder methods: `as_critical()`, `as_high_priority()`, `as_low_priority()`, `as_background()`, `with_priority()`
+  - Utility methods: `is_critical()`, `is_high_priority()`, `is_normal_priority()`, `is_low_priority()`, `is_background()`, `priority_value()`
+  - String parsing support with multiple aliases (e.g., "crit", "c" for Critical)
+  - Integer conversion methods for database storage: `as_i32()`, `from_i32()`
+
+- **⚖️ Advanced Priority-Aware Job Scheduling**
+  - Weighted priority scheduling with configurable weights per priority level
+  - Strict priority scheduling (highest priority jobs always first)
+  - Fairness factor to prevent low-priority job starvation
+  - Hash-based job selection for Send compatibility in async contexts
+  - `PriorityWeights` configuration with builder pattern
+
+- **🗄️ Database Schema and Query Enhancements**
+  - Added `priority` column to both PostgreSQL and MySQL schemas with default value `2` (Normal)
+  - Optimized database indexes: `idx_hammerwork_jobs_queue_status_priority_scheduled` for efficient priority-based querying
+  - Priority-aware `dequeue()` and `dequeue_with_priority_weights()` methods
+  - Backward compatibility with existing job records (default to Normal priority)
+
+- **👷 Worker Priority Configuration**
+  - `with_priority_weights()` - Configure custom priority weights
+  - `with_strict_priority()` - Enable strict priority mode
+  - `with_weighted_priority()` - Enable weighted priority scheduling (default)
+  - Worker pools support mixed priority configurations across workers
+  - Integration with existing timeout and statistics systems
+
+- **📊 Priority Statistics and Monitoring**
+  - `PriorityStats` tracking job counts, processing times, and throughput per priority
+  - Priority distribution percentage calculations
+  - Starvation detection with configurable thresholds
+  - Integration with `InMemoryStatsCollector` and `JobEvent` system
+  - Most active priority identification and trend analysis
+
+- **🧪 Comprehensive Testing Suite**
+  - 12 new priority-specific unit tests covering all functionality
+  - Priority ordering, serialization, and string parsing tests
+  - Worker configuration and edge case testing
+  - Statistics integration and starvation detection tests
+  - Example demonstrating weighted scheduling, strict priority, and statistics
+
+### Enhanced
+- Updated package description to highlight job prioritization capabilities
+- Added `priority_example.rs` demonstrating all priority features
+- Enhanced statistics collection to track priority-specific metrics
+- Worker pools now support heterogeneous priority configurations
+
+### Fixed
+- All stats module tests now include required priority field
+- Applied clippy suggestions for cleaner derive macro usage
+- Consistent code formatting across all files
+
 ## [0.3.0] - 2025-06-26
 
 ### Added

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Hammerwork is a high-performance, database-driven job queue library for Rust with support for both PostgreSQL and MySQL. It provides async/await job processing with configurable retry logic, delayed jobs, and worker pools.
+Hammerwork is a high-performance, database-driven job queue library for Rust with support for both PostgreSQL and MySQL. It provides async/await job processing with configurable retry logic, delayed jobs, job prioritization with weighted scheduling, and worker pools.
 
 ## Common Development Commands
 
@@ -23,6 +23,8 @@ cargo test --features mysql
 # Run examples
 cargo run --example postgres_example --features postgres
 cargo run --example mysql_example --features mysql
+cargo run --example cron_example --features postgres
+cargo run --example priority_example --features postgres
 
 # Check code formatting
 cargo fmt --check
@@ -44,33 +46,43 @@ The codebase follows a modular architecture with clear separation of concerns:
 ### Core Components
 
 1. **Job (`src/job.rs`)**
-   - Defines the `Job` struct with UUID, payload, status, retry logic
-   - Job statuses: Pending, Running, Completed, Failed, Retrying
-   - Supports delayed execution and configurable retry attempts
+   - Defines the `Job` struct with UUID, payload, status, priority, retry logic
+   - Job statuses: Pending, Running, Completed, Failed, Retrying, Dead, TimedOut
+   - Job priorities: Background, Low, Normal, High, Critical
+   - Supports delayed execution, configurable retry attempts, and priority levels
 
 2. **Queue (`src/queue.rs`)**
    - `DatabaseQueue` trait defines the interface for database operations
    - `JobQueue<DB>` generic struct wraps database connection pools
    - Database-specific implementations in `postgres` and `mysql` modules
    - Uses database transactions for atomic job operations
+   - Priority-aware job selection with weighted algorithms
 
 3. **Worker (`src/worker.rs`)**
    - `Worker<DB>` processes jobs from specific queues
-   - Configurable polling intervals, retry delays, and max retries
+   - Configurable polling intervals, retry delays, max retries, and priority weights
+   - Support for strict priority or weighted priority scheduling
    - `WorkerPool<DB>` manages multiple workers with graceful shutdown
    - Uses async channels for shutdown coordination
 
-4. **Error Handling (`src/error.rs`)**
+4. **Priority System (`src/priority.rs`)**
+   - `JobPriority` enum with 5 levels: Background, Low, Normal, High, Critical
+   - `PriorityWeights` for configurable weighted job selection
+   - `PriorityStats` for monitoring priority distribution and performance
+   - Prevents job starvation through fairness mechanisms
+
+5. **Error Handling (`src/error.rs`)**
    - `HammerworkError` enum using thiserror for structured error handling
    - Wraps SQLx, serialization, and custom errors
 
 ### Database Schema
 
 Both PostgreSQL and MySQL implementations use a single table `hammerwork_jobs` with:
-- Job metadata (id, queue_name, status, attempts)
-- Timing information (created_at, scheduled_at, started_at, completed_at)
+- Job metadata (id, queue_name, status, priority, attempts)
+- Timing information (created_at, scheduled_at, started_at, completed_at, failed_at, timed_out_at)
 - Payload data (JSON/JSONB) and error messages
-- Optimized indexes for queue polling
+- Cron scheduling fields (cron_schedule, next_run_at, recurring, timezone)
+- Optimized indexes for priority-aware queue polling
 
 ### Key Design Patterns
 
@@ -79,11 +91,15 @@ Both PostgreSQL and MySQL implementations use a single table `hammerwork_jobs` w
 - **Async-first**: Built on Tokio with async/await throughout
 - **Transaction safety**: Uses database transactions for job state changes
 - **Type-safe job handling**: Job handlers return `Result<()>` for error handling
+- **Priority-aware scheduling**: Weighted and strict priority algorithms prevent starvation
+- **Comprehensive monitoring**: Statistics track priority distribution and performance
 
 ## Development Notes
 
 - SQLx compile-time query checking requires database connections
 - PostgreSQL uses `FOR UPDATE SKIP LOCKED` for efficient job polling
 - MySQL implementation uses transaction-based locking (less optimal)
+- Priority-aware queries use `ORDER BY priority DESC, scheduled_at ASC`
+- Weighted selection uses hash-based algorithms for Send compatibility
 - Tracing is integrated for observability
-- Examples demonstrate both database configurations
+- Examples demonstrate database configurations, cron scheduling, and prioritization

Cargo.toml

@@ -21,12 +21,13 @@ tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 async-trait = "0.1"
 tokio-test = "0.4"
+rand = "0.8"
 
 [package]
 name = "hammerwork"
-version = "0.3.0"
+version = "0.4.0"
 edition = "2021"
-description = "A high-performance, database-driven job queue for Rust with PostgreSQL and MySQL support, featuring cron scheduling, job timeouts, dead job management, and comprehensive statistics collection"
+description = "A high-performance, database-driven job queue for Rust with PostgreSQL and MySQL support, featuring job prioritization, cron scheduling, timeouts, dead job management, and comprehensive statistics collection"
 license = "MIT"
 repository = "https://github.com/CodingAnarchy/hammerwork"
 authors = ["CodingAnarchy <[email protected]>"]
@@ -48,6 +49,7 @@ serde_json = { workspace = true }
 thiserror = { workspace = true }
 tracing = { workspace = true }
 async-trait = { workspace = true }
+rand = { workspace = true }
 
 [features]
 default = []
@@ -69,3 +71,7 @@ required-features = ["mysql"]
 [[example]]
 name = "cron_example"
 required-features = ["postgres"]
+
+[[example]]
+name = "priority_example"
+required-features = ["postgres"]