icetea-queue 0.1.1

package/README.md

@@ -0,0 +1,145 @@
+# icetea-queue
+
+A simple, lightweight TypeScript queue implementation for processing items concurrently across multiple slots. Supports both synchronous and asynchronous executors with completion tracking.
+
+## Installation
+
+```bash
+npm install icetea-queue
+```
+
+## Quick Start
+
+```typescript
+import { Queue } from "icetea-queue";
+
+// Create a queue with 3 parallel slots
+const queue = new Queue<number>(3);
+
+// Set an executor function (called for each item)
+queue.setExecutor(async (item, allData) => {
+  console.log(`Processing: ${item}`);
+  return true; // return truthy to continue to next item
+});
+
+// Provide data to process
+queue.setData([1, 2, 3, 4, 5, 6]);
+
+// Handle completion
+queue.onCompleted((result) => {
+  console.log("All done!", result);
+  // { status: true, completed: 6 }
+});
+
+// Start processing
+queue.execute();
+```
+
+## API
+
+### `Queue<T>(roomSize: number)`
+
+Creates a new queue with the specified number of parallel slots.
+
+| Parameter  | Type     | Description                               |
+| ---------- | -------- | ----------------------------------------- |
+| `roomSize` | `number` | Number of parallel processing slots/rooms |
+
+### Methods
+
+#### `setData(data: T[]): this`
+
+Sets the data to be processed and distributes it across the available slots in a round-robin fashion. Returns `this` for chaining.
+
+```typescript
+queue.setData([1, 2, 3, 4, 5, 6]);
+// Slot distribution with roomSize=3:
+//   Slot 0: [1, 4]
+//   Slot 1: [2, 5]
+//   Slot 2: [3, 6]
+```
+
+#### `setExecutor(executor: Function): void`
+
+Sets the callback function that processes each item. The executor receives the current item and the full dataset.
+
+```typescript
+// Sync executor
+queue.setExecutor((item, allData) => {
+  // process item
+  return true; // truthy → proceed to next item, falsy → stop
+});
+
+// Async executor
+queue.setExecutor(async (item, allData) => {
+  await someAsyncWork(item);
+  return true;
+});
+```
+
+- **Throws** `Error` if executor is not a function.
+
+#### `execute(): void`
+
+Starts processing all items across the queue slots. The executor must be set before calling this method.
+
+- **Throws** `Error` if no executor has been set.
+- Does nothing if data is empty.
+
+#### `onCompleted(callback: Function): void`
+
+Registers a callback that fires when all items have been processed.
+
+```typescript
+queue.onCompleted((result) => {
+  console.log(result.status); // true
+  console.log(result.completed); // total items processed
+});
+```
+
+- **Throws** `Error` if callback is not a function.
+
+#### `isPromise(callback: Function): boolean`
+
+Checks whether a given callback is an async function.
+
+```typescript
+queue.isPromise(async () => {}); // true
+queue.isPromise(() => {}); // false
+queue.isPromise(null); // false
+```
+
+### Behavior
+
+- **Round-robin distribution**: Data is evenly distributed across the available slots.
+- **Sequential within slots**: Each slot processes its items one after another.
+- **Parallel across slots**: All slots process concurrently.
+- **Completion callback**: Fires once every item across all slots has been processed.
+- **Auto-reset**: After all items are processed, internal state resets automatically.
+- **Falsy return stops progression**: If the executor returns a falsy value, that slot stops processing further items.
+
+## Example
+
+### Processing with completion tracking
+
+```typescript
+import { Queue } from "icetea-queue";
+
+const queue = new Queue<string>(2);
+
+queue.onCompleted(({ status, completed }) => {
+  console.log(`Completed ${completed} items: ${status}`);
+});
+
+queue.setExecutor(async (item) => {
+  const result = await fetch(`https://api.example.com/${item}`);
+  return result.ok;
+});
+
+queue.setData(["a", "b", "c", "d"]);
+queue.execute();
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { }

package/dist/index.js

@@ -0,0 +1,66 @@
+//#region src/queue.ts
+var e = class {
+	data;
+	roomSize;
+	queue;
+	queueIndex;
+	temp;
+	callback;
+	callbackIsPromise;
+	completed;
+	completedCallback;
+	constructor(e) {
+		this.data = [], this.roomSize = e, this.temp = Array(this.roomSize).fill([]), this.queue = Array(this.roomSize).fill(null), this.queueIndex = this.queue.map((e) => 0), this.callback = null, this.callbackIsPromise = !1, this.completed = 0, this.completedCallback = null;
+	}
+	setData(e = []) {
+		this.data = e;
+		let t = Array.from(this.data), n = 0;
+		for (; t.length !== 0 && (n === this.temp.length && (n = 0), t.length);) this.#t(n, t.splice(0, 1)[0]), n++;
+		return this.queue = this.queue.map((e, t) => this.temp[t][0]), this;
+	}
+	#e() {
+		this.data = [], this.temp = Array(this.roomSize).fill([]), this.queue = Array(this.roomSize).fill(null), this.queueIndex = this.queue.map((e) => 0), this.completed = 0;
+	}
+	#t(e, t) {
+		this.temp = this.temp.map((n, r) => r === e ? [...n, t] : n);
+	}
+	setCompleted() {
+		this.completed += 1, this.completedCallback && this.completed === this.data.length && this.completedCallback({
+			status: !0,
+			completed: this.completed
+		}), this.completed === this.data.length && this.#e();
+	}
+	isPromise(e) {
+		return e ? e.constructor.name === "AsyncFunction" : !1;
+	}
+	#n(e, t) {
+		let n = this.temp?.[e]?.[t];
+		if (!n) return;
+		this.queueIndex[e] += 1;
+		let r = this.temp[e]?.[this.queueIndex[e]];
+		if (this.callbackIsPromise) return this.callback(n, this.data).then((t) => {
+			t && (this.setCompleted(), this.#n(e, this.queueIndex[e]));
+		});
+		this.callback(n, this.data), this.setCompleted(), r && this.#n(e, this.queueIndex[e]);
+	}
+	setExecutor(e) {
+		if (!e || typeof e != "function") throw Error("executor is not a function");
+		this.callback = e, this.callbackIsPromise = this.isPromise(this.callback);
+	}
+	onCompleted(e) {
+		if (!e || typeof e != "function") throw Error("On Compeleted is not a function");
+		this.completedCallback = e;
+	}
+	execute() {
+		if (!this.callback) throw Error("callback is not set");
+		this.data.length !== 0 && this.queue.map((e, t) => {
+			let n = e, r = ++this.queueIndex[t], i;
+			if (this.callbackIsPromise) return this.callback(n, this.data).then((e) => {
+				e && (this.setCompleted(), this.#n(t, r));
+			});
+			i = this.callback(n, this.data), this.setCompleted(), i && this.#n(t, r);
+		});
+	}
+};
+//#endregion
+export { e as Queue };

package/dist/index.umd.cjs

@@ -0,0 +1 @@
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports):typeof define==`function`&&define.amd?define([`exports`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e[`IceTea Queue`]={}))})(this,function(e){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`}),e.Queue=class{data;roomSize;queue;queueIndex;temp;callback;callbackIsPromise;completed;completedCallback;constructor(e){this.data=[],this.roomSize=e,this.temp=Array(this.roomSize).fill([]),this.queue=Array(this.roomSize).fill(null),this.queueIndex=this.queue.map(e=>0),this.callback=null,this.callbackIsPromise=!1,this.completed=0,this.completedCallback=null}setData(e=[]){this.data=e;let t=Array.from(this.data),n=0;for(;t.length!==0&&(n===this.temp.length&&(n=0),t.length);)this.#t(n,t.splice(0,1)[0]),n++;return this.queue=this.queue.map((e,t)=>this.temp[t][0]),this}#e(){this.data=[],this.temp=Array(this.roomSize).fill([]),this.queue=Array(this.roomSize).fill(null),this.queueIndex=this.queue.map(e=>0),this.completed=0}#t(e,t){this.temp=this.temp.map((n,r)=>r===e?[...n,t]:n)}setCompleted(){this.completed+=1,this.completedCallback&&this.completed===this.data.length&&this.completedCallback({status:!0,completed:this.completed}),this.completed===this.data.length&&this.#e()}isPromise(e){return e?e.constructor.name===`AsyncFunction`:!1}#n(e,t){let n=this.temp?.[e]?.[t];if(!n)return;this.queueIndex[e]+=1;let r=this.temp[e]?.[this.queueIndex[e]];if(this.callbackIsPromise)return this.callback(n,this.data).then(t=>{t&&(this.setCompleted(),this.#n(e,this.queueIndex[e]))});this.callback(n,this.data),this.setCompleted(),r&&this.#n(e,this.queueIndex[e])}setExecutor(e){if(!e||typeof e!=`function`)throw Error(`executor is not a function`);this.callback=e,this.callbackIsPromise=this.isPromise(this.callback)}onCompleted(e){if(!e||typeof e!=`function`)throw Error(`On Compeleted is not a function`);this.completedCallback=e}execute(){if(!this.callback)throw Error(`callback is not set`);this.data.length!==0&&this.queue.map((e,t)=>{let n=e,r=++this.queueIndex[t],i;if(this.callbackIsPromise)return this.callback(n,this.data).then(e=>{e&&(this.setCompleted(),this.#n(t,r))});i=this.callback(n,this.data),this.setCompleted(),i&&this.#n(t,r)})}}});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "icetea-queue",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "A simple queue implementation",
+  "main": "./dist/index.umd.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.umd.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "test": "npx vitest run ./src/test/queue.test.ts"
+  },
+  "keywords": [],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "typescript": "~6.0.2",
+    "vite": "^8.0.12",
+    "vite-plugin-dts": "^4.5.4"
+  }
+}