@bernierllc/task-queue

Task queue management service with build queue prioritization, dependency resolution, and ready-to-start detection.

Features

- Intelligent Prioritization: Multi-factor scoring algorithm combining priority, maturity level, and blocking status
- Dependency Resolution: Transitive dependency tracking with circular dependency detection
- Ready-to-Start Detection: Automatically identifies work items that can be started immediately
- Flexible Filtering: Filter by status, priority, maturity, and readiness
- Build Order Optimization: Groups parallelizable work into batches for optimal execution
- Queue Statistics: Comprehensive analytics on queue composition and readiness
- Configurable Weights: Customize prioritization algorithm to your needs

Installation

``bash
npm install @bernierllc/task-queue
`

Usage

$3

`typescript
import { TaskQueue } from '@bernierllc/task-queue';
import { MemoryWorkItemStorage } from '@bernierllc/work-item-core';

// Create queue with default configuration
const storage = new MemoryWorkItemStorage();
const queue = new TaskQueue(storage);

// Get all queue items sorted by score
const result = await queue.getQueue();

if (result.success) {
result.data.forEach(entry => {
console.log(${entry.position}. ${entry.workItem.title});
console.log( Score: ${entry.score.totalScore.toFixed(2)});
console.log( Ready: ${entry.score.readyToStart});
});
}
`

$3

`typescript
// Customize scoring weights
const queue = new TaskQueue(storage, {
priorityWeight: 0.5, // 50% weight for priority
maturityWeight: 0.3, // 30% weight for maturity
blockingWeight: 0.2, // 20% weight for blocking status
maturityOrder: {
'idea': 1,
'planned': 2,
'ready': 3,
'in-progress': 4,
'complete': 5
},
completedStatuses: ['done', 'cancelled']
});
`

$3

`typescript
// Get top 5 highest priority items that are ready to start
const nextItems = await queue.getNextItems(5);

if (nextItems.success) {
for (const entry of nextItems.data) {
console.log(Next: ${entry.workItem.title});
console.log(Priority: ${entry.workItem.priority}/10);
console.log(Score: ${entry.score.totalScore.toFixed(2)});
}
}
`

$3

`typescript
// Check dependencies for a work item
const resolution = await queue.resolveDependencies(workItemId);

if (resolution.success) {
const { data } = resolution;

console.log(Ready to start: ${data.isReady});
console.log(Total dependencies: ${data.totalDependencies});
console.log(Completed: ${data.completedDependencies});
console.log(Pending: ${data.pendingDependencies.length});

// Show what's blocking this item
data.blockedBy.forEach(blocker => {
console.log( Blocked by: ${blocker.title});
});

// Show transitive dependencies
console.log(Transitive deps: ${data.transitiveDependencies.join(', ')});
}
`

$3

`typescript
// Get only ready items with high priority
const filtered = await queue.getQueue({
filters: {
readyToStart: true,
priority_min: 7,
minScore: 0.6,
status_ids: ['open', 'in-progress']
},
sort: { field: 'score', order: 'desc' },
limit: 10
});
`

$3

`typescript
// Get recommended build order with parallel batches
const buildOrder = await queue.getBuildOrder();

if (buildOrder.success) {
const { data } = buildOrder;

console.log(Total items: ${data.totalItems});
console.log(Batches: ${data.estimatedBatches});
console.log(Parallelizable: ${data.parallelizable});

data.batches.forEach((batch, index) => {
console.log(\nBatch ${index + 1} (${batch.length} items):);
batch.forEach(entry => {
console.log( - ${entry.workItem.title});
});
});
}
`

$3

`typescript
// Get comprehensive queue statistics
const stats = await queue.getStatistics();

if (stats.success) {
const { data } = stats;

console.log(Total items: ${data.totalItems});
console.log(Ready to start: ${data.readyItems});
console.log(Blocked: ${data.blockedItems});
console.log(Average score: ${data.averageScore.toFixed(2)});
console.log(High priority: ${data.highPriorityCount});
console.log(Blocking project: ${data.blockingProjectCount});

console.log('\nBy maturity level:');
Object.entries(data.byMaturityLevel).forEach(([level, count]) => {
console.log( ${level}: ${count});
});

console.log('\nBy status:');
Object.entries(data.byStatus).forEach(([status, count]) => {
console.log( ${status}: ${count});
});
}
`

$3

`typescript
// Sort by different fields
const sortOptions = [
{ field: 'score', order: 'desc' }, // Highest score first
{ field: 'priority', order: 'desc' }, // Highest priority first
{ field: 'maturity', order: 'desc' }, // Most mature first
{ field: 'created_at', order: 'asc' }, // Oldest first
{ field: 'updated_at', order: 'desc' }, // Most recent first
{ field: 'title', order: 'asc' } // Alphabetical
];

const sorted = await queue.getQueue({
sort: sortOptions[0]
});
`

API Reference

$3

#### Constructor

`typescript
constructor(storage: WorkItemStorage, config?: TaskQueueConfig)
`

Creates a new TaskQueue instance.

Parameters:
- storage: WorkItemStorage implementation (e.g., MemoryWorkItemStorage)
- config: Optional configuration for prioritization algorithm

#### Methods

##### getQueue(options?: GetQueueOptions): Promise>

Get all work items in the queue with computed scores and details.

Options:
- filters: QueueFilters - Filter criteria
- sort: QueueSortOptions - Sort field and order
- limit: number - Maximum items to return
- offset: number - Pagination offset

Returns: QueueEntry[] with position, workItem, and score

##### getNextItems(count: number): Promise>

Get the next N highest priority items that are ready to start.

Parameters:
- count: Number of items to return

Returns: Top N ready items sorted by score

##### resolveDependencies(workItemId: string): Promise>

Get detailed dependency resolution for a work item.

Parameters:
- workItemId: Work item ID to analyze

Returns: DependencyResolution with readiness status and blocking dependencies

##### getStatistics(filters?: QueueFilters): Promise>

Get comprehensive queue statistics.

Parameters:
- filters: Optional filters to apply before calculating statistics

Returns: QueueStatistics with counts and distributions

##### getBuildOrder(filters?: QueueFilters): Promise>

Get recommended build order with items grouped into parallel batches.

Parameters:
- filters: Optional filters to apply

Returns: BuildOrder with batches of parallelizable work items

$3

#### TaskQueueConfig

`typescript
interface TaskQueueConfig {
priorityWeight?: number; // 0-1, default: 0.4
maturityWeight?: number; // 0-1, default: 0.3
blockingWeight?: number; // 0-1, default: 0.3
maturityOrder?: Record;
completedStatuses?: string[];
}
`

#### QueueItemScore

`typescript
interface QueueItemScore {
workItemId: string;
totalScore: number; // 0-1 weighted total
priorityScore: number; // 0-1 normalized
maturityScore: number; // 0-1 normalized
blockingScore: number; // 0 or 1
readyToStart: boolean;
blockingDependencies: string[];
}
`

#### QueueEntry

`typescript
interface QueueEntry {
workItem: WorkItemWithDetails;
score: QueueItemScore;
position: number;
}
`

#### DependencyResolution

`typescript
interface DependencyResolution {
workItemId: string;
isReady: boolean;
totalDependencies: number;
completedDependencies: number;
pendingDependencies: WorkItem[];
blockedBy: WorkItem[];
transitiveDependencies: string[];
}
`

#### BuildOrder

`typescript
interface BuildOrder {
batches: QueueEntry[][];
totalItems: number;
estimatedBatches: number;
parallelizable: boolean;
}
`

Prioritization Algorithm

The TaskQueue uses a weighted scoring algorithm to prioritize work items:

$3

1. Priority Score (default weight: 0.4)
- Normalized from 1-10 scale to 0-1
- Higher priority = higher score

2. Maturity Score (default weight: 0.3)
- Based on maturity level progression
- More mature items score higher
- Configurable maturity order

3. Blocking Score (default weight: 0.3)
- Binary: 1 if item blocks project completion, 0 otherwise
- Ensures critical path items are prioritized

$3

`
totalScore = (priority/10 * priorityWeight) +
(maturityOrder/maxOrder * maturityWeight) +
(blocksProject ? 1 : 0) * blockingWeight
`

$3

Adjust weights to match your workflow:

`typescript
// Example: Heavily prioritize blocking items
const queue = new TaskQueue(storage, {
priorityWeight: 0.2,
maturityWeight: 0.2,
blockingWeight: 0.6
});

// Example: Focus on maturity over priority
const queue = new TaskQueue(storage, {
priorityWeight: 0.3,
maturityWeight: 0.5,
blockingWeight: 0.2
});
`

Integration Status

- Logger Integration: Not applicable - Service package delegates logging to consumers. No @bernierllc/logger dependency required as this is a pure service layer component.
- Docs-Suite: Ready (TypeDoc compatible)
- NeverHub Integration: Not applicable - Service package does not require NeverHub adapter. No @bernierllc/neverhub-adapter dependency as this is a stateless service component that operates through WorkItemStorage abstraction.

Dependencies

- @bernierllc/work-item-core` - Core work item types and management

See Also

- @bernierllc/work-item-core - Core work item management
- @bernierllc/workflow-manager - Workflow orchestration

License

Copyright (c) 2025 Bernier LLC. All rights reserved.