Initial commit

.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+insert_final_newline = true

.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": "./node_modules/gts/"
+}

.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+      fail-fast: false
+
+    steps:
+      - id: checkout
+        name: Checkout
+        uses: actions/checkout@v3
+      - id: setup-bun
+        name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+      - id: install-deps
+        name: Install dependencies
+        run: |
+          bun install
+      - id: test
+        name: Run test
+        run: |
+          bun test

.github/workflows/release.yml

@@ -0,0 +1,22 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16.x
+
+      - run: npx changelogithub
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

.prettierrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  ...require('gts/.prettierrc.json')
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Kakashi <https://github.com/libkakashi>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,233 @@
+### Class: `Queue<T>`
+
+### Constructors
+
+- **`constructor()`**: Initializes a new instance of the `Queue` class.
+
+### Methods
+
+- **`push(...vals: T[]): void`**: Pushes one or more values onto the queue.
+- **`end(): void`**: Marks the queue as ended.
+- **`waitForEnd(): Promise<void>`**: Returns a promise that resolves when the queue ends.
+- **collect`(): Promise<T[]>`**: Converts the queue into an array. Collects all elements of the queue into an array and returns a promise that resolves to this array when the queue ends.
+
+    ```tsx
+    const myQueue = new Queue<number>();
+
+    myQueue.collect().then(console.log);
+
+    // Pushing values into the queue
+    myQueue.push(1, 2, 3, 4);
+    await sleep(1000);
+    myQueue.push(5, 6, 7, 8);
+
+    myQueue.end();
+    console.log('Queue ended');
+
+    // Output: 
+    // Queue ended
+    // [1, 2, 3, 4, 5, 6, 7, 8]
+    ```
+
+- **`pushCount(): number`**: Returns the number of items that have been pushed into the queue.
+
+    ```tsx
+    const myQueue = new Queue<string>();
+    
+    myQueue.push("apple");
+    console.log(myQueue.pushCount());
+    
+    myQueue.push("banana");
+    console.log(myQueue.pushCount());
+    
+    // Output:
+    // 1
+    // 2
+    ```
+
+- **`size(): number`**: Returns the current size of the queue.
+
+    ```tsx
+    const myQueue = new Queue<string>();
+    
+    myQueue.push("apple", "banana");
+    myQueue.end();
+    
+    console.log('Size before consuming:', myQueue.size());
+    console.log('Push count before consuming:', myQueue.pushCount()); 
+    
+    await myQueue.map(_ = _); // consume the queue
+    
+    console.log('Size after consuming:', myQueue.size());
+    console.log('Push count after consuming:', myQueue.pushCount()); 
+    
+    // Output:
+    // Size before consuming: 2
+    // Push count before consuming: 2
+    // Size after consuming: 0
+    // Push count after consuming: 2
+    ```
+
+- **`map(callback: (v: T) => void): Promise<void>`**: Applies the provided callback function to each item in the queue.
+
+    ```tsx
+    const stringQueue = new Queue<string>();
+    
+    stringQueue.push("apple");
+    
+    // Applying a callback to each item
+    stringQueue.map(item => console.log(item.toUpperCase()));
+    
+    stringQueue.push("banana", "cherry");
+    
+    // Output:
+    // APPLE
+    // BANANA
+    // CHERRY
+    ```
+
+- **`pipe<U>(callback: (v: T) => U | undefined): Queue<U>`**: Transforms the queue's elements using the given callback function and returns a new queue with the transformed elements.
+
+    ```tsx
+    const numberQueue = Queue.fromArray([1, 2, 3, 4, 5]);
+    
+    // Processing items and filtering out even numbers
+    const filteredQueue = numberQueue.pipe(num => {
+      if (num % 2 !== 0) {
+        return num * 2; // Double all odd numbers
+      }
+    	// Drop all even numbers
+    	return undefined;
+    });
+    
+    filteredQueue.collect().then(console.log); // Output: [2, 6, 10]
+    ```
+
+- **`split<U, V = U>(callback: (v: T) => [U, 0] | [V, 1]): [Queue<U>, Queue<V>]`**: Splits the queue into two separate queues based on a callback function.
+
+    ```tsx
+    const queue = Queue.fromArray([1, 2, 3, 4, 5, 6]);
+    
+    // Splitting the queue into even and odd numbers
+    const [evenQueue, oddQueue] = queue.split(num => {
+      return num % 2 === 0 ? [num, 0] : [num, 1];
+    });
+    
+    evenQueue.toArray().then(array => console.log("Even:", array));
+    oddQueue.toArray().then(array => console.log("Odd:", array));
+    
+    // Output: 
+    // Even: [2, 4, 6]
+    // Odd: [1, 3, 5]
+    ```
+
+
+### Concurrency Methods
+
+- **`mapParallel(callback: (v: T) => Promise<void>, n: number = 8): Promise<void>`**: Similar to `map`, but processes items in parallel up to `n` at a time. The `n+1`th call is made when any one of the first `n` calls finishes, such that there are always `n` calls running in parallel.
+
+    ```tsx
+    const asyncQueue = Queue.fromArray([1, 2, 3, 4, 5, 6, 7, 8]);
+    
+    let lastTimestamp = Date.now();
+    
+    asyncQueue.mapParallel(async item => {
+      await sleep(1000);
+    
+      const newTimestamp = Date.now();
+      console.log(`Processed ${item} in ${newTimestamp - lastTimestamp}ms`);
+    
+      lastTimestamp = newTimestamp;
+    }, 4);
+    
+    // Output:
+    // Processed 1 in 1004ms
+    // Processed 2 in 5ms
+    // Processed 3 in 1ms
+    // Processed 4 in 0ms
+    // Processed 5 in 999ms
+    // Processed 6 in 6ms
+    // Processed 7 in 0ms
+    // Processed 8 in 0ms
+    ```
+
+- **`upipe<U>(callback: (v: T) => Promise<U | undefined>, n: number = 8): Queue<U>`**: Unordered version of `pipe`, processing items in parallel.
+- **`usplit<U, V = U>(callback: (v: T) => Promise<[U, 0] | [V, 1] | undefined>, n: number = 8): [Queue<U>, Queue<V>]`**: Unordered version of `split`, processing items in parallel and splitting them into two queues based on a callback function.
+- **`umerge(q: Queue<T>): Queue<T>`**: Merges the current queue with another queue in an unordered manner.
+    
+    ```tsx
+    const queue1 = new Queue<number>();
+    const queue2 = new Queue<number>();
+
+    queue1.push(1);
+    queue1.push(2);
+    queue2.push(3);
+    queue2.push(4);
+
+    queue1.end();
+    queue2.end();
+
+    const mergedQueue = queue1.umerge(queue2);
+
+    const mergedArray = await mergedQueue.collect();
+    console.log('Merged Array:', mergedArray);
+
+    // Output:
+    // Merged Array: [1, 2, 3, 4]
+    ```
+
+
+### Batching Methods
+
+- **`batch(n: number): Queue<T[]>`**: Groups the queue's elements into batches of size `n`.
+
+    ```tsx
+    const batchQueue = Queue.fromArray([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+    
+    // Creating batches of size 3
+    const batchedQueue = batchQueue.batch(3);
+    
+    batchedQueue.map(batch => console.log(batch));
+    
+    // Output:
+    // [1, 2, 3]
+    // [4, 5, 6]
+    // [7, 8, 9]
+    // [10]
+    ```
+
+- **`flat(): Queue<T extends Array<infer U> ? U : never>`**: Flattens the queue's elements if they are arrays.
+
+    ```tsx
+    const batchQueue = new Queue<number>();
+    batchQueue.push(1, 2, 3);
+    
+    const asyncBatchCall = async (array: number[]) => {
+    	await sleep(1000);
+    	return array.map(a => a * 2);
+    };
+    
+    const outQueue = batchQueue.batch(3).upipe(asyncBatchCall).flat();
+    
+    outQueue.map(res => console.log(res));
+    
+    // Output:
+    // 2
+    // 2
+    // 6
+    ```
+
+
+### Properties
+
+- **`ended: boolean`**: Indicates whether the queue has ended.
+- **`piped: boolean`**: Indicates whether the queue has been piped.
+
+### Static Methods
+
+- **`static fromArray<T>(array: Array<T>): Queue<T>`**: Creates a new queue from an array. The queue is ended at the time of creation itself. Further elements cannot be pushed.
+
+### Notes
+
+- Methods that start with `u` (e.g., `upipe`, `usplit`, `umerge`) are unordered methods, which means the order of elements is lost going from the input queue to the output queue. You're **not** supposed to make **any assumptions at all** about the order of the elements.
+- It's very easy to inadvertently misuse the queues or overlook certain error conditions. Please be very cautious while handling errors, especially with the unordered methods.

build.mjs

@@ -0,0 +1,8 @@
+import dts from 'bun-plugin-dts'
+
+await Bun.build({
+  entrypoints: ['./src/index.ts'],
+  outdir: './dist',
+  minify: true,
+  plugins: [dts()]
+})

package.json

@@ -0,0 +1,37 @@
+{
+  "name": "superqueue",
+  "version": "0.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "description": "",
+  "scripts": {
+    "build": "bun run build.mjs",
+    "prepublishOnly": "bun run build",
+    "lint": "gts lint",
+    "clean": "gts clean",
+    "fix": "gts fix"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "bun"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/libkakashi/superqueue#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/libkakashi/superqueue.git"
+  },
+  "bugs": "https://github.com/libkakashi/superqueue/issues",
+  "author": "Kakashi <[email protected]",
+  "devDependencies": {
+    "@types/bun": "^1.0.0",
+    "bun-plugin-dts": "^0.2.1",
+    "gts": "^5.3.0",
+    "typescript": "^5.2.2"
+  },
+  "engines": {
+    "node": ">=12.9.0"
+  }
+}