Queue

Queuing is an optimization mechanism for fast display to the browser.

• queue

• unqueue

• isQueued

• commit

queue(entity, strong)

Adds an item or an array of items to the queue. This is a fast operation to bypass deep item analysis. It does not provide object uniqueness. The queue functions as a regular data store. If an item exists in the cache it is not replaced or added to the queue. Set the second strong parameter to true and force replacement in the cache.

One get() calls return queued items that are not yet cached as if they were already cached. Their content however is not yet enforced as unique.

Parameters

• entityOrArray Object | Array<Object>, object or array of objects to add to the queue

• strong Boolean, whether to replace existing items into the cache. Defaults to false (same as a weak put). Set to true to force replacement of existing cache items that are being queued.

Returns

• number count of items that were queued.

Example:

let item1 = {uid:1}
let item2 = {uid:2, ref:item1}
One.queue([item1, item2])

// content appears as if cached
One.get(1) === undefined // false
One.get(2) === undefined // false

// but it is not yet unique
One.get(1) === One.get(2).ref // false

Items existing in the cache are not replaced

let item1 = {uid:1}
One.put(item1)

let item2 = {
  uid:2,
  child:{uid:1, text:"test"}
}
let numQueued = One.queue([item1, item2]) // numQueued = 1, only item2 is queued

One.get(1).text === undefined // true item1 was not replaced into the cache

// however it is still on item2 which is only queued and not enforced for uniqueness
let item1InQueue = One.get(2).child
item1InQueue.text === "test" // true

item1InQueue === item1 // false

Cache prevails

Queue an item strongly. It might exist both on cache and queue. In such case get() favors the cached item for retrieval.

let item = {uid: 1};
One.put(item);

let item1 = {uid: 1, text: "test"};
One.queue(item1, true); // strong queuing

JSON.stringify(One.get(1)) // {uid:1}

// you can still get to the queued item
JSON.stringify(One.getQueued(1)) // {uid:1, text:"test"}

unqueue(entity)

Removes a single uid entity from the queue if queued.

Parameters

• entity Object The entity to be unqueued

Returns

• true on success or false otherwise

Example

let item = {uid:1}
One.queue(item)
One.get(1) // {uid:1}

One.unqueue(item)
One.get(1) // undefined

getQueued(uidOrEntity)

Retrieves a specific entity if queued in the cache.

Parameters

• uidOrEntity string | Object object (or its unique id) to be retrieved from queue

Returns

• the queued entity if existing or undefined otherwise

Example

let item1 = {uid:1}
One.queue(item1)
One.getQueued(1) // {uid:1}
One.getQueued(item1) // {uid:1}

One.unqueue(1)
One.getQueued(1) // undefined

commit(threadId, strong)

Commits the queued items to a specific thread. By default commits are weak. If an item being commited already exists in the cache it is not replaced. Set the second parameter to true to force strong commits where all queued items are pushed into the cache.

Parameters

• threadId string the id of the thread to commit all items into. Defaults to main. Note that all items are always placed on the main thread even if another thread id is supplied. In such case items end up on the main thread AND the thread with the id passed in. Of course there is a single instance of the item in the cache. Item is only referenced on each thread.

• strong boolean by default commits are weak. Set this to true to force all queued items to be replaced in the cache.

Returns

• history state Object

Example

let item1 = {uid:1}
let item2 = {
  uid:2,
  child:{
    uid:1,
    text:"test" // item1 edited here
  }
}

// place item1 on the cache first
One.put(item1) 

// queue item2
One.queue(item2)

One.commit() // weak commit
One.get(1).text // undefined

// normally the queue here is empty but if instead you commit with strong above:
One.commit("main", true)
One.get(1).text // "test" a strong commit replaces existing items in the cache