Merge pull request #3 from typescript-package/develop

v1.0.0-beta

Author: wwwdev-ai

.github/FUNDING.yml

@@ -0,0 +1,12 @@
+# These are supported funding model platforms
+
+github: [angular-package] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: angularpackage # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

README.md

@@ -22,9 +22,11 @@ A lightweight TypeScript library for managing various queue and stack structures
 
 * [Installation](#installation)
 * [Api](#api)
-  * `ProcessingQueue`
-  * `Queue`
-  * `Stack`
+  * [`Elements`](#elements)
+  * [`ProcessingQueue`](#processingqueue)
+  * [`Processing`](#processing)
+  * [`Queue`](#queue)
+  * [`Stack`](#stack)
 * [Git](#git)
   * [Commit](#commit)
   * [Versioning](#versioning)
@@ -40,12 +42,215 @@ npm install @typescript-package/queue
 
 ```typescript
 import {
+  // Class.
+  Elements,
+  // Abstract.
   ProcessingQueue,
   Queue,
   Stack
 } from '@typescript-package/queue';
 ```
 
+### `Elements`
+
+```typescript
+import { Elements } from '@typescript-package/queue';
+
+let elements = new Elements(
+  [1, 2, 3, 4], // Array type elements.
+  15 // Maximum size of the elements.
+);
+
+// Appends the value at the end of an array state.
+elements.append(5);
+console.log(elements.state); // Output: [1, 2, 3, 4, 5]
+
+// Inserts the value at the specified index into the array state.
+elements.insert(2, 10);
+console.log(elements.state); // Output: [1, 2, 10, 3, 4, 5]
+
+// Adds the values at the beginning of array state.
+elements.prepend(0);
+console.log(elements.state); // Output: [0, 1, 2, 10, 3, 4, 5]
+
+// Updates the value at the index in the array state.
+elements.update(0, 127);
+console.log(elements.state); // Output: [127, 1, 2, 10, 3, 4, 5]
+```
+
+### `ProcessingQueue`
+
+```typescript
+import { ProcessingQueue } from '@typescript-package/queue';
+
+// Initialize the `ProcessingQueue`.
+let processingQueue = new ProcessingQueue(
+  2, // concurrency
+  10, // size
+  1, 2, 3 // items
+);
+
+// The maximum number of elements that can be processed concurrently.
+console.log(`concurrency, `, processingQueue.concurrency); // Output: 2
+
+// A set containing all elements that have been successfully processed.
+console.log(`processed, `, processingQueue.processed); // Output: Set(0)
+
+// Checks whether the queue is empty.
+console.log(`isEmpty(), `, processingQueue.isEmpty()); // Output: false
+
+// Checks whether the queue is full.
+console.log(`isFull(), `, processingQueue.isFull()); // Output: false
+
+// The maximum queue size.
+console.log(`size, `, processingQueue.size); // Output: 10
+
+// The actual queue Elements state - raw array state of the queue.
+console.log(`state, `, processingQueue.state); // Output: [1, 2, 3]
+
+// The actual queue length.
+console.log(`length, `, processingQueue.length); // Output: 3
+
+// Adds a new element to the queue.
+console.log(`enqueue(4), `, processingQueue.enqueue(4));
+
+// The actual queue length.
+console.log(`length, `, processingQueue.length); // Output: 4
+
+// Returns the first element in the queue.
+console.log(`peek(), `, processingQueue.peek()); // Output: 1
+
+// Returns the first element in the queue.
+console.log(`dequeue(), `, processingQueue.dequeue()); // Output: 1
+
+// The actual queue length.
+console.log(`length, `, processingQueue.length); // Output: 3
+
+// Adds to the full.
+processingQueue.enqueue(5).enqueue(6).enqueue(7).enqueue(8).enqueue(9).enqueue(10).enqueue(11);
+
+// The actual queue Elements state - raw array state of the queue.
+console.log(`state, `, processingQueue.state); // Output: [2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
+
+// Waits for all elements in the queue to be processed and returns the set of processed elements.
+processingQueue.isCompleted().then(
+  processed => console.log(`Completed`, processed), // Output: Completed Set(10)
+  reason => console.log(reason)
+);
+
+// Starts processing elements in the queue using the provided callback function.
+processingQueue.run(element => console.log(`Processed`, element)); // Output: Processed {element}
+
+// A set containing all elements that have been successfully processed.
+console.log(`processed, `, processingQueue.processed); // Output: Set(10)
+```
+
+### `Processing`
+
+### `Queue`
+
+```typescript
+import { Queue } from '@typescript-package/queue';
+
+// Initialize the new `Queue`.
+let queue = new Queue(
+  10, // size
+  1, 2, 3 // item
+);
+
+// Adds a new element to the queue.
+queue.enqueue(4);
+
+// The actual queue Elements state - raw array state of the queue.
+console.log(`state,`, queue.state); // Output: [1, 2, 3, 4]
+
+// Returns the first element in the queue.
+console.log(`peek(), `, queue.peek()); // Output: 1
+
+// Checks if the queue is empty.
+console.log(`isEmpty(),`, queue.isEmpty()); // Output: false
+
+// The maximum queue size.
+console.log(`size,`, queue.size); // Output: 10
+
+// The actual queue Elements state - raw array state of the queue.
+console.log(`state,`, queue.state); // Output: [1, 2, 3, 4]
+
+// Adds to the full.
+queue.enqueue(5).enqueue(6).enqueue(7).enqueue(8).enqueue(9).enqueue(10);
+
+// Checks whether the queue is full.
+console.log(`isFull(), `, queue.isFull()); // Output: true
+
+try {
+  queue.enqueue(11);
+} catch(error) {
+  console.log(error); // Error: Queue is full.
+}
+
+// Clears the queue.
+console.log(`clear(), `, queue.clear());
+
+// Checks if the queue is empty.
+console.log(`isEmpty(),`, queue.isEmpty()); // Output: true
+
+// The actual queue Elements state - raw array state of the queue.
+console.log(`state,`, queue.state); // Output: []
+
+```
+
+### `Stack`
+
+```typescript
+import { Stack } from '@typescript-package/queue';
+
+// Initialize the `Stack`.
+let stack = new Stack(
+  10, // size
+  1, 2, 3 // items
+);
+
+// The actual stack length.
+console.log(`length, `, stack.length); // Output: 3
+
+// Adds a new element on the stack.
+stack.push(4); 
+
+// The maximum stack size.
+console.log(`size, `, stack.size); // Output: 10
+
+// The actual stack length.
+console.log(`length, `, stack.length); // Output: 4
+
+// Returns the top element on the stack.
+console.log(`peek(), `, stack.peek()); // Output: 4
+
+// The actual stack `Elements` state.
+console.log(`state, `, stack.state); // Output: [1, 2, 3, 4]
+
+// Removes and returns the top element from the stack.
+console.log(`pop(), `, stack.pop()); // Output: 4
+
+// The actual stack `Elements` state.
+console.log(`state, `, stack.state); // Output: [1, 2, 3]
+
+// Adds to the full.
+stack.push(4).push(5).push(6).push(7).push(8).push(9).push(10);
+
+// The actual stack `Elements` state.
+console.log(`state, `, stack.state); // Output: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+
+// Checks if the stack is full.
+console.log(`isFull(), `, stack.isFull()); // Output: true
+
+// Clears the queue.
+stack.clear()
+
+// The actual stack `Elements` state.
+console.log(`state, `, stack.state); // Output: []
+console.log(`isEmpty(), `, stack.isEmpty()); // Output: true
+```
+
 ## GIT
 
 ### Commit

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@typescript-package/queue",
-  "version": "0.0.1",
+  "version": "1.0.0-beta",
   "author": "wwwdev.io <dev@wwwdev.io>",
   "description": "A lightweight TypeScript library for managing various queue and stack structures.",
   "license": "MIT",

package.json

@@ -0,0 +1,111 @@
+// Abstract.
+import { ArrayState } from "@typescript-package/state";
+/**
+ * @description Array state elements in data structures such as Stack and Queue.
+ * @export
+ * @class Elements
+ * @template Type 
+ * @extends {ArrayState<Type>}
+ */
+export class Elements<Type, Size extends number = number> extends ArrayState<Type>{
+  /**
+   * @description The maximum size of the `Elements`.
+   * @public
+   * @readonly
+   * @type {Size}
+   */
+  public get size(): Size {
+    return this.#size;
+  }
+
+  /**
+   * @description Privately stored maximum elements size.
+   * @type {Size}
+   */
+  #size: Size;
+
+  /**
+   * Creates an instance of `Elements`.
+   * @constructor
+   * @param {Type[]} elements 
+   * @param {Size} [size=Infinity as Size] 
+   */
+  constructor(elements: Type[], size: Size = Infinity as Size) {
+    super(elements.length <= size ? elements : []);
+    // Sets the size.
+    this.#size = size;
+    // Throws an error if the elements exceeds the maximum size.
+    if (elements.length > size) {
+      throw new Error(`The \`elements\` size exceeds the maximum size ${size} by ${elements.length - size}.`);
+    }
+  }
+
+  /**
+   * @inheritdoc
+   * @public
+   * @param {Type} element The element of `Type` to append.
+   * @returns {this} 
+   */
+  public override append(element: Type): this {
+    this.#checkFull();
+    super.append(element);
+    return this;
+  }
+
+  /**
+   * @inheritdoc
+   * @public
+   * @param {number} index The index under which the specified `element` is inserted.
+   * @param {Type} element The element of `Type` to insert at specified `index`.
+   * @returns {this} 
+   */
+  public override insert(index: number, element: Type): this {
+    this.#checkFull();
+    super.insert(index, element);
+    return this;
+  }
+
+  /**
+   * @description Checks whether the `Elements` state is full, equal to size.
+   * @public
+   * @returns {boolean} 
+   */
+  public isFull(): boolean {
+    return this.#size === this.length;
+  }
+
+  /**
+   * @description Add the element at the beginning of `array` state.
+   * @public
+   * @param {Type} element The element of `Type` to prepend.
+   * @returns {this} 
+   */
+  public override prepend(element: Type): this {
+    this.#checkFull();
+    super.prepend(element);
+    return this;
+  }
+
+  /**
+   * @inheritdoc
+   * @public
+   * @param {number} index The index to update update element.
+   * @param {Type} element The element of `Type` to update under the specified `index`.
+   * @returns {this} 
+   */
+  public override update(index: number, element: Type): this {
+    super.update(index, element);
+    return this;
+  }
+
+  /** 
+   * @description Checks whether length of the array is equal to maximum size.
+   * @returns {this} 
+   */
+  #checkFull(): this {
+    if (this.isFull()) {
+      throw new Error(`Elements array state is full of size ${super.length}.`);
+    }
+    return this;
+  }
+};

src/lib/elements.class.ts

@@ -1,3 +1,7 @@
+// Class.
+export { Elements } from './elements.class';
+export { Processing } from './processing.class';
+// Abstract.
 export { ProcessingQueue } from './processing-queue.class';
 export { Queue } from './queue.abstract';
 export { Stack } from './stack.abstract';