Initial commit

Author: snatalenko

.editorconfig

@@ -0,0 +1,46 @@
+# EditorConfig is awesome: http://EditorConfig.org
+
+# How-to with your editor: http://editorconfig.org/#download
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+indent_style = tab
+insert_final_newline = true
+
+[{Dockerfile,Procfile}]
+trim_trailing_whitespace = true
+
+# Standard at: https://github.com/felixge/node-style-guide
+[{*.js,*.json}]
+trim_trailing_whitespace = true
+quote_type = single
+curly_bracket_next_line = false
+spaces_around_operators = true
+space_after_control_statements = true
+space_after_anonymous_functions = false
+spaces_in_brackets = false
+
+[Dockerfile]
+indent_style = space
+indent_size = 4
+
+[*.md]
+indent_style = space
+indent_size = 2
+
+[*.json]
+indent_style = space
+indent_size = 4
+insert_final_newline = false
+
+[*.yml]
+indent_style = space
+indent_size = 2
+
+[package.json]
+indent_style = space
+indent_size = 2

.github/workflows/audit.yml

@@ -0,0 +1,22 @@
+name: Audit
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  audit:
+    name: "Audit"
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [22.x]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: npm audit --parseable --production --audit-level=moderate

.github/workflows/coveralls.yml

@@ -0,0 +1,25 @@
+name: Coveralls
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [22.x]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: npm ci --no-optional
+      env:
+        CI: true
+    - run: npm run test:coverage
+    - name: Coveralls
+      uses: coverallsapp/github-action@v2

.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to NPM
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci --no-optional
+
+      - name: Publish pre-release to NPM
+        if: contains(github.ref_name, '-')
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --tag next
+
+      - name: Publish release to NPM
+        if: "!contains(github.ref_name, '-')"
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish

.github/workflows/tests.yml

@@ -0,0 +1,25 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    name: "Tests"
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: npm ci --no-optional
+      env:
+        CI: true
+    - run: npm run test

.gitignore

@@ -0,0 +1,12 @@
+/.vscode/
+/coverage/
+/dist/
+/node_modules/
+.DS_Store
+*.sublime-project
+*.sublime-workspace
+*.tgz
+ehthumbs.db
+Icon?
+Thumbs.db
+tsconfig.tsbuildinfo

.npmignore

@@ -0,0 +1,11 @@
+.github/
+.vscode/
+coverage/
+tests/
+.editorconfig
+.eslintrc.json
+.gitignore
+tsconfig.json
+jest.config.ts
+*.tgz
+tsconfig.tsbuildinfo

README.MD

@@ -0,0 +1,96 @@
+Async Iterable Buffer
+=====================
+
+[![NPM Version](https://img.shields.io/npm/v/async-iterable-buffer.svg)](https://www.npmjs.com/package/async-iterable-buffer)
+[![Audit](https://github.com/snatalenko/async-iterable-buffer/actions/workflows/audit.yml/badge.svg)](https://github.com/snatalenko/async-iterable-buffer/actions/workflows/audit.yml)
+[![Tests](https://github.com/snatalenko/async-iterable-buffer/actions/workflows/tests.yml/badge.svg)](https://github.com/snatalenko/async-iterable-buffer/actions/workflows/tests.yml)
+[![Coverage Status](https://coveralls.io/repos/github/snatalenko/async-iterable-buffer/badge.svg?branch=main)](https://coveralls.io/github/snatalenko/async-iterable-buffer?branch=main)
+[![NPM Downloads](https://img.shields.io/npm/dm/async-iterable-buffer.svg)](https://www.npmjs.com/package/async-iterable-buffer)
+
+
+AsyncIterableBuffer is a lightweight, stateful asynchronous buffer that allows you to push values and consume them using async iteration (e.g. `for await...of`). It’s ideal for bridging event-driven or callback-based code with modern async/await patterns.
+
+## Features
+
+- **Asynchronous Iteration:** Implements the `AsyncIterableIterator` interface.
+- **Push and Consume:** Dynamically push values into the buffer and consume them asynchronously.
+- **Graceful Termination:** Signal completion with an `end()` method and handle early termination via `return()`.
+- **TypeScript Support:** Fully typed for TypeScript projects.
+- **Lightweight:** No dependencies.
+
+## Installation
+
+```bash
+npm install async-iterable-buffer
+```
+
+## Usage
+
+### Basic Example
+
+```ts
+import { AsyncIterableBuffer } from 'async-iterable-buffer';
+
+const buffer = new AsyncIterableBuffer<number>();
+
+// Push some values into the buffer.
+buffer.push(1);
+buffer.push(2);
+buffer.push(3);
+
+// Signal that no more values will be pushed.
+buffer.end();
+
+// Consume the buffer with async iteration.
+(async () => {
+  for await (const num of buffer) {
+    console.log(num); // Outputs: 1, 2, 3
+  }
+})();
+```
+
+
+### Advanced Usage with Early Termination
+
+```ts
+import { AsyncIterableBuffer } from 'async-iterable-buffer';
+
+const buffer = new AsyncIterableBuffer<string>();
+
+// Start an async iterator.
+(async () => {
+  for await (const value of buffer) {
+    console.log(value);
+    if (value === 'stop') {
+      // Terminate iteration early.
+      await buffer.return();
+    }
+  }
+})();
+
+// Push values asynchronously.
+buffer.push('first');
+buffer.push('stop');
+buffer.push('ignored'); // This value won't be processed since the buffer is closed after "stop".
+```
+
+
+### API
+
+API
+
+new AsyncIterableBuffer<T>()
+
+Creates a new instance of the asynchronous buffer.
+
+Methods
+- **push(value: T): void**
+  Pushes a new value into the buffer. Throws an error if the buffer has been ended.
+- **end(): void**
+  Marks the buffer as completed and resolves any pending requests with { done: true }.
+- **next(): Promise<IteratorResult<T>>**
+  Returns a promise that resolves to the next buffered value. If the buffer is empty but not ended, it waits until a value is pushed.
+- **return(): Promise<IteratorResult<T>>**
+  Ends the buffer and returns a result indicating that the iterator is done. This is useful for early termination of iteration.
+- **[Symbol.asyncIterator](): AsyncIterableIterator<T>**
+  Returns the async iterator itself, enabling for await...of loops.