Array Operations

/**
 * Adds jobs to the end of the queue
 * @param workers - Jobs to add to the queue
 * @returns New length of the queue
 */
push(...workers: QueueWorker[]): number;

// Add single job
q.push((callback) => {
  setTimeout(() => callback(null, 'done'), 1000);
});

// Add multiple jobs
q.push(
  (cb) => cb(null, 'job 1'),
  (cb) => cb(null, 'job 2'),
  () => Promise.resolve('job 3')
);

// With Promise-based job
q.push(async () => {
  const result = await fetch('/api/data');
  return result.json();
});

/**
 * Adds jobs to the front of the queue
 * @param workers - Jobs to insert at the beginning
 * @returns New length of the queue
 */
unshift(...workers: QueueWorker[]): number;

// Add high-priority job to front
q.unshift((callback) => {
  console.log('High priority job');
  callback();
});

/**
 * Changes queue contents by removing existing jobs and/or adding new jobs
 * @param start - Index to start changing the queue
 * @param deleteCount - Number of jobs to remove
 * @param workers - Jobs to add at the start index
 * @returns Queue instance for chaining
 */
splice(start: number, deleteCount?: number, ...workers: QueueWorker[]): Queue;

// Insert job at position 2
q.splice(2, 0, (cb) => cb(null, 'inserted job'));

// Replace job at position 1
q.splice(1, 1, (cb) => cb(null, 'replacement job'));

// Remove 2 jobs starting at position 3
q.splice(3, 2);

/**
 * Removes and returns the last job from the queue
 * @returns The removed job, or undefined if queue is empty
 */
pop(): QueueWorker | undefined;

const lastJob = q.pop();
if (lastJob) {
  console.log('Removed last job');
}

/**
 * Removes and returns the first job from the queue
 * @returns The removed job, or undefined if queue is empty
 */
shift(): QueueWorker | undefined;

const firstJob = q.shift();
if (firstJob) {
  console.log('Removed first job');
}

/**
 * Returns the first index of a job in the queue
 * @param searchElement - Job to locate
 * @param fromIndex - Index to start search from
 * @returns Index of the job, or -1 if not found
 */
indexOf(searchElement: QueueWorker, fromIndex?: number): number;

/**
 * Returns the last index of a job in the queue
 * @param searchElement - Job to locate  
 * @param fromIndex - Index to start search from (backwards)
 * @returns Index of the job, or -1 if not found
 */
lastIndexOf(searchElement: QueueWorker, fromIndex?: number): number;

const myJob = (cb) => cb(null, 'my job');
q.push(myJob);

// Find the job
const index = q.indexOf(myJob);
console.log(`Job is at index ${index}`);

// Search from specific position
const laterIndex = q.indexOf(myJob, 5);

/**
 * Extracts a section of the queue (modifies original queue)
 * @param start - Beginning index of extraction
 * @param end - End index of extraction (exclusive)
 * @returns Queue instance for chaining
 */
slice(start?: number, end?: number): Queue;

// Keep only jobs 2-5
q.slice(2, 5);

// Keep jobs from index 3 onwards
q.slice(3);

/**
 * Reverses the order of jobs in the queue
 * @returns Queue instance for chaining
 */
reverse(): Queue;

// Reverse job execution order
q.reverse();

/**
 * A job function that can accept a callback or return a Promise
 */
interface QueueWorker {
  (callback?: QueueWorkerCallback): void | Promise<any>;
  /** Override queue timeout for this specific job */
  timeout?: number;
  /** Promise reference if job returns a Promise */
  promise?: Promise<any>;
}

/**
 * Callback function for async jobs
 */
interface QueueWorkerCallback {
  (error?: Error, data?: Object): void;
}

// Callback-based job
function callbackJob(callback) {
  setTimeout(() => {
    callback(null, 'callback result');
  }, 1000);
}

// Promise-based job
function promiseJob() {
  return new Promise((resolve) => {
    setTimeout(() => resolve('promise result'), 1000);
  });
}

// Job with custom timeout
function slowJob(callback) {
  setTimeout(() => callback(null, 'slow result'), 5000);
}
slowJob.timeout = 6000; // Override queue timeout

// Mixed jobs
q.push(callbackJob, promiseJob, slowJob);