# avenue

> An async/await event queue.

Latest version **0.1.6** (published 2019-08-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install avenue
pnpm add avenue
yarn add avenue
bun add avenue
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.6 |
| Published | 2019-08-25 |
| First published | 2013-08-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 13.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | Alan Gutierrez |
| Maintainers | bigeasy |
| Keywords | queue, es6, async, await |

## Links

- npm: https://www.npmjs.com/package/avenue
- Repository: https://github.com/bigeasy/avenue
- Issues: https://github.com/bigeasy/avenue/issues
- npm.io page: https://npm.io/package/avenue

## Alternatives

- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads
- [fa](https://npm.io/package/fa.md) — 185 weekly downloads

## Recent versions

- 0.1.6 (latest) — 2019-08-25
- 0.6.18 (canary) — 2022-02-01
- 0.6.17 — 2021-10-17
- 0.6.16 — 2021-09-20
- 0.6.15 — 2021-07-23
- 0.6.14 — 2021-07-22
- 0.6.13 — 2021-01-29
- 0.6.12 — 2021-01-29
- 0.6.11 — 2021-01-25
- 0.6.10 — 2021-01-24
- 0.6.9 — 2021-01-24
- 0.6.8 — 2021-01-12
- 0.6.7 — 2021-01-11
- 0.6.6 — 2021-01-11
- 0.6.5 — 2021-01-09
- … 26 more at https://npm.io/package/avenue/versions

## README

[![Actions Status](https://github.com/bigeasy/avenue/workflows/Node%20CI/badge.svg)](https://github.com/bigeasy/avenue/actions)
[![codecov](https://codecov.io/gh/bigeasy/avenue/branch/master/graph/badge.svg)](https://codecov.io/gh/bigeasy/avenue)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An `async`/`await` multiplexed event queue.

| What          | Where                                         |
| --- | --- |
| Discussion    | https://github.com/bigeasy/avenue/issues/1    |
| Documentation | https://bigeasy.github.io/avenue              |
| Source        | https://github.com/bigeasy/avenue             |
| Issues        | https://github.com/bigeasy/avenue/issues      |
| CI            | https://travis-ci.org/bigeasy/avenue          |
| Coverage:     | https://codecov.io/gh/bigeasy/avenue          |
| License:      | MIT                                           |


Avenue installs from NPM.

```
npm install avenue
```

## Living `README.md`

This `README.md` is also a unit test using the
[Proof](https://github.com/bigeasy/proof) unit test framework. We'll use the
Proof `okay` function to assert out statements in the readme. A Proof unit test
generally looks like this.

```javascript
require('proof')(4, async okay => {
    okay('always okay')
    okay(true, 'okay if true')
    okay(1, 1, 'okay if equal')
    okay({ value: 1 }, { value: 1 }, 'okay if deep strict equal')
})
```

You can run this unit test yourself to see the output from the various
code sections of the readme.

```text
git clone git@github.com:bigeasy/avenue.git
cd avenue
npm install --no-package-lock --no-save
node test/readme.t.js
```

## Overview

Avenue implements a queue as a disintegrating linked-list.

Avenue provides a `Queue` class. When you push onto the head of the `Queue` a
new element is added to the head of the list. The queue itself does not maintain
a pointer to the tail.

To remove items from the queue you must first create a `Shifter` by calling
`Queue.shifter()`. This will be created with a reference to the current head of
the list, in order to reference the next item in the list. At this point if you
where to call the synchronous `Shifter.shift()` you would get a `null` return
value because the next value of the head of the list is `null`.

When you push a new element onto the head of the `Queue`, it will become visible
to the `Shifter`. A call to the synchronous `Shifter.shift()` will return the
item. After the shifter returns the item it advances its tail node to the next
node that contained the value returned. The previous node is no longer
referenced by the `Queue` nor the `Shifter` so it is garbage collected.

You can have multiple `Shifter`s for a single `Queue` garbage collection occurs
when the all the `Shifter`s `shift` past a node in the `Queue`.

If there are no `Shifter`s for a queue, then any push onto the `Queue` is
effectively a no-op. The element is discarded the next time item an item is
pushed.

The `'avenue'` module exports a single `Queue` object.

```javascript
const { Queue } = require('avenue')
```

If you want to stream a shifter into a queue with back-pressure you can the
`Shifter.async.push()` method.

```javascript
const from = new Queue
const to = new Queue
const shifter = to.shifter()
const promise = from.shifter().push(value => to.push(value))
await from.enqueue([ 1, 2, 3, null ])
await promise
okay(shifter.sync.splice(4), [ 1, 2, 3 ], 'pushed')
okay(shifter.destroyed, 'pumped received terminator')
```

If you want to stream a shifter into a queue without terminating the queue you
use `Queue.consume`.

```javascript
const from = new Queue
const to = new Queue
const shifter = to.shifter()
const promise = to.consume(from.shifter())
await from.enqueue([ 1, 2, 3, null ])
await promise
okay(shifter.sync.splice(4), [ 1, 2, 3 ], 'pushed')
okay(!shifter.destroyed, 'consumed did not receive terminator')
```

**TODO** Incomplete.

---
_Source: https://npm.io/package/avenue · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._