Suggested behaviour:

const queue = new Qewe({ reactive: true });

const firstEntry = queue.enqueue('hello', 1);
const secondEntry = queue.enqueue('world', 2);

console.log(...queue); // [ 'world', 'hello' ]

firstEntry.priority = 3;

console.log(...queue); // [ 'hello', 'world ]

This should be possible by returning a Proxy from .enqueue that wraps the QeweEntry's priority setter.

This PR, and subsequently release, adds a new QeweEntry class which is used by a Qewe instance to store values and their priorities.

QeweEntry instances can be created outside of a Qewe instance - either using the new QeweEntry constructor or the .createEntry method on a Qewe instance. They can then be inserted programatically.

const queue = new Qewe<string>();

const entry = new QeweEntry('hello', 1);
queue.enqueue(entry);

const anotherEntry = queue.createEntry('world', 2);
queue.enqueue(anotherEntry);

.enqueue still allows the (value: T, priority?: number) syntax:

const queue = new Qewe<string>();
queue.enqueue('hello', 1);
queue.enqueue('world', 2);

const inferrerdQueue = new Qewe<string>({ inferValuePriority: (value) => value.length });
inferredQueue.enqueue('hello');
inferredQueue.enqueue('world');

This is, however, a breaking change. The initialValues constructor option now only allows raw values and requires the inferValuePriority to be set.

A new constructor option, initialEntries, has been added, which takes an array of QeweEntry instances.

// old behavior, no longer works
const queue = new Qewe({
  initialValues: [
    { value: 'hello', priority: 1 },
    { value: 'world', priority: 2 }
  ]
});

// new behavior
const firstEntry = new QeweEntry('hello', 1);
const secondEntry = new QeweEntry('world', 2);
const queue = new Qewe({ initialEntries: [firstEntry, secondEntry] });

// also works 
const queue = new Qewe({
  inferValuePriority: (value) => value.length,
  initialValues: ['hello', 'world']
});

Max Queue Size

const queue = new Qewe({ maximumQueueSize: 3 });

queue.enqueue('a', 1); // ✅
queue.enqueue('b', 1); // ✅
queue.enqueue('c', 1); // ✅
queue.enqueue('d', 4); // ❌ Error

Explicit Queue Type

// before
const queue = new Qewe({ minQueue: true });

// after
const queue = new Qewe({ queueType: 'min' });

This PR addresses #1.

dequeue and dequeueEnd now throw an error if they are called when the queue is empty:

dequeue(): T {
  const entry = this.queue.shift();

  if (entry !== undefined) {
    return entry.value;
  } else {
    throw new Error('Dequeue failed - the queue is empty.');
  }
}

The documentation in the README file has been updated to suggest users wrap their dequeue/dequeueEnd calls in a try/catch block. It also provides an alternative suggestion, noted in the original issue, where users can instead check for themselves if the queue is empty before attempting a dequeue.

The first value(s) of a queue are often known when the instance is created. It would be beneficial if these values could be included in the initialization process, instead of having to add them afterwards.

Currently both dequeue and dequeueEnd methods return null if the queue is empty when they're called. This is a fairly unobtrusive implementation but does have two fairly significant drawbacks:

• Instances will indefinitely return null whilst their queue is empty. This means that users must manually check to see if their latest dequeue/dequeueEnd call emptied the queue.
• If the user adds null to the queue they have no way of knowing if the null that dequeue/dequeueEnd returns is an inserted value or the "queue is empty" value. Again, they must manually check if the queue is empty instead.

Proposal

A potential solution is to instead throw an error when dequeue/dequeueEnd are called when the queue is empty. This solves both above issues. The instance will inform the user when the queue is empty, since they will have to deal with an error, and null values returned can safely be assumed to be values in the queue.

const queue = new Qewe();

try {
  const value = queue.dequeue();
  // do something with value
} catch {
  // queue is empty, do something else
}

Drawbacks

This behavior change does come with a little overhead. Users would have to handle errors, likely with a try/catch block, or their application would crash.

Alternative

An alternative is to suggest users check if the queue is empty before they call dequeue/dequeueEnd.

const queue = new Qewe();

if (queue.isEmpty === false) {
  const value = queue.dequeue();
  // do something with value
} else {
  // queue is empty, do something else
}

Current Implementation

const queue = new Qewe();

const a = queue.enqueue('hello', 1);
const b = queue.enqueue('world', 2);

console.log(...queue); // [ 'world', 'hello' ]

a.priority = 3;

console.log(...queue); // [ 'hello', 'world' ]

This is achieved by wrapping the QeweEntry created in .enqueue in a Proxy that runs a sort method on the queue when the entry's priority value is changed.

Problems

There is an inconsistency with the current implementation's behaviour if you pass a QeweEntry directly into enqueue:

const queue = new Qewe();

const a = new QeweEntry('hello', 1);
const b = new QeweEntry('world', 2);
queue.enqueue(a);
queue.enqueue(b);

console.log(...queue); // [ 'world', 'hello' ]

a.priority = 3;

console.log(...queue); // [ 'world', 'hello' ]

Because the original QeweEntry instance is being edited, and not the Proxied instance that enqueue creates, the Qewe instance is not aware of any priority changes and so does not react to the change.