@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

npm install @bernierllc/task-queue

Usage

Basic Queue Management

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}`);
  });
}

Custom Prioritization

// 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']
});

Get Next Items to Work On

// 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)}`);
  }
}

Dependency Resolution

// 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(', ')}`);
}

Advanced Filtering

// 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
});

Build Order Optimization

// 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}`);
    });
  });
}

Queue Statistics

// 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}`);
  });
}

Custom Sorting

// 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

TaskQueue

Constructor

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<QueueResult<QueueEntry[]>>

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<QueueResult<QueueEntry[]>>

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<QueueResult>

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<QueueResult>

Get comprehensive queue statistics.

Parameters:

• filters: Optional filters to apply before calculating statistics

Returns: QueueStatistics with counts and distributions

getBuildOrder(filters?: QueueFilters): Promise<QueueResult>

Get recommended build order with items grouped into parallel batches.

Parameters:

• filters: Optional filters to apply

Returns: BuildOrder with batches of parallelizable work items

Types

TaskQueueConfig

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<string, number>;
  completedStatuses?: string[];
}

QueueItemScore

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

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

DependencyResolution

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

BuildOrder

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

Prioritization Algorithm

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

Score Components

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

Formula

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

Customization

Adjust weights to match your workflow:

// 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.