# 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:**

```javascript
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

```javascript
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.

```javascript
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**

```javascript
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&#x20;

**Returns**

* the queued entity if existing or `undefined` otherwise

**Example**

```javascript
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**

```javascript
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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dahn.gitbook.io/one/api/queue.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.