{"id":21259468,"url":"https://github.com/ori88c/data-oriented-slim-queue","last_synced_at":"2026-01-31T02:31:40.944Z","repository":{"id":252994304,"uuid":"841140628","full_name":"ori88c/data-oriented-slim-queue","owner":"ori88c","description":"A slim and efficient in-memory queue with a basic API for Node.js projects. The implementation employs Data-Oriented Design using a cyclic buffer, optimizing memory layout through sequential item allocation.","archived":false,"fork":false,"pushed_at":"2024-11-23T23:46:07.000Z","size":166,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-22T03:55:08.634Z","etag":null,"topics":["circular-buffer","cyclic-buffer","data-oriented-design","es2020","fifo","fifo-queue","first-in-first-out","in-memory","in-memory-storage","js","node-js","nodejs","queue","ts","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ori88c.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-08-11T18:55:34.000Z","updated_at":"2024-11-23T23:41:21.000Z","dependencies_parsed_at":"2025-07-11T03:43:11.276Z","dependency_job_id":"4e11a9f0-0558-49ac-ab1c-552446bd9405","html_url":"https://github.com/ori88c/data-oriented-slim-queue","commit_stats":null,"previous_names":["ori88c/data-oriented-slim-queue"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ori88c/data-oriented-slim-queue","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ori88c%2Fdata-oriented-slim-queue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ori88c%2Fdata-oriented-slim-queue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ori88c%2Fdata-oriented-slim-queue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ori88c%2Fdata-oriented-slim-queue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ori88c","download_url":"https://codeload.github.com/ori88c/data-oriented-slim-queue/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ori88c%2Fdata-oriented-slim-queue/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28927159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T22:32:35.345Z","status":"online","status_checked_at":"2026-01-31T02:00:09.179Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["circular-buffer","cyclic-buffer","data-oriented-design","es2020","fifo","fifo-queue","first-in-first-out","in-memory","in-memory-storage","js","node-js","nodejs","queue","ts","typescript"],"created_at":"2024-11-21T04:14:12.294Z","updated_at":"2026-01-31T02:31:40.929Z","avatar_url":"https://github.com/ori88c.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch2 align=\"middle\"\u003eData Oriented Slim Queue\u003c/h2\u003e\n\nThe `SlimQueue` class implements an in-memory queue with a basic API, targeting pure FIFO use cases such as task queues, breadth-first search (BFS), and similar scenarios.\n\nThis versatile data structure is commonly associated with task prioritization, ensuring tasks are processed in order. It also proves valuable in optimizing sliding-window algorithms, where the oldest item (First In) is evicted based on a specific indicator.\n\n## Data-Oriented Design :gear:\n\nThis implementation follows the principles of Data-Oriented Design (DOD), optimizing memory layout and access patterns using arrays, particularly to enhance CPU cache efficiency. Unlike Object-Oriented Programming (OOP), where each object may be allocated in disparate locations on the heap, DOD leverages the sequential allocation of arrays, reducing the likelihood of cache misses.\n\n## Focused API :dart:\n\nThis package provides a queue and nothing more. The absence of linear operations like iteration and splicing reflects a deliberate design choice, as resorting to such methods often indicates that a queue may not have been the most appropriate data structure in the first place.  \nThe sole exception is the `getSnapshot` method, included to support metrics or statistical analysis, particularly in use cases like tracking the K most recent items.\n\n## Table of Contents :bookmark_tabs:\n\n* [Key Features](#key-features)\n* [API](#api)\n* [Getter Methods](#getter-methods)\n* [Use Case Example: Rate Limiting](#use-case-example)\n* [Capacity Tunning](#capacity-tuning)\n* [License](#license)\n\n## Key Features :sparkles:\u003ca id=\"key-features\"\u003e\u003c/a\u003e\n\n- __Basic Queue API__: Targeting pure use-cases of queues.\n- __Efficiency :gear:__: Featuring a Data-Oriented Design with capacity-tuning capability, to reduce or prevent reallocations of the internal cyclic buffer.\n- __Comprehensive Documentation :books:__: The class is thoroughly documented, enabling IDEs to provide helpful tooltips that enhance the coding experience.\n- __Tests :test_tube:__: **Fully covered** by comprehensive unit tests, including **randomized simulations** of real-life scenarios and validations to ensure proper internal capacity scaling.\n- **TypeScript** support.\n- No external runtime dependencies: Only development dependencies are used.\n- ES2020 Compatibility: The `tsconfig` target is set to ES2020, ensuring compatibility with ES2020 environments.\n\n## API :globe_with_meridians:\u003ca id=\"api\"\u003e\u003c/a\u003e\n\nThe `SlimQueue` class provides the following methods:\n\n* __push__: Appends an item to the end of the queue (i.e., the Last In), increasing its size by one.\n* __pop__: Removes and returns the oldest (First In) item from the queue, decreasing its size by one.\n* __clear__: Removes all items from the queue, leaving it empty.\n* __getSnapshot__: Returns an array of references to all the currently stored items in the queue, ordered from First-In to Last-In.\n\nIf needed, refer to the code documentation for a more comprehensive description.\n\nThe `push` and `pop` terminology is inspired by std::queue in C++. Unlike more complex data structures, a queue only allows pushing in one direction and popping from the other, making this straightforward terminology appropriate.  \n\n## Getter Methods :mag:\u003ca id=\"getter-methods\"\u003e\u003c/a\u003e\n\nThe `SlimQueue` class provides the following getter methods to reflect the current state:\n\n* __size__: The amount of items currently stored in the queue.\n* __isEmpty__: Indicates whether the queue does not contain any item.\n* __firstIn__: Returns a reference to the oldest item currently stored in the queue (the First In item), which will be removed during the next pop operation.\n* __capacity__: The length of the internal buffer storing items. If the observed capacity remains significantly larger than the queue's size after the initial warm-up period, it may indicate that the initial capacity was overestimated. Conversely, if the capacity has grown excessively due to buffer reallocations, it may suggest that the initial capacity was underestimated.\n* __numberOfCapacityIncrements__: The number of internal buffer reallocations due to insufficient capacity that have occurred during the instance's lifespan. A high number of capacity increments suggests that the initial capacity was underestimated.\n\nTo eliminate any ambiguity, all getter methods have **O(1)** time and space complexity.\n\n## Use Case Example: Rate Limiting :man_technologist:\u003ca id=\"use-case-example\"\u003e\u003c/a\u003e\n\nConsider a component designed for rate-limiting promises using a sliding-window approach. Suppose a window duration of `windowDurationMs` milliseconds, with a maximum of `tasksPerWindow` tasks allowed within each window. The rate limiter will only trigger the execution of a task if fewer than `tasksPerWindow` tasks have started execution within the time window `[now - windowDurationMs, now]`.\n\nFor simplicity, this example focuses on a single method that initiates task execution only if the current window's limit has not been reached. If the limit has been exceeded, an error is thrown.\nIn this scenario, we employ the `isEmpty`, `firstIn`, and `size` getters, along with the `push` and `pop` methods.\n\n```ts\nimport { SlimQueue } from 'data-oriented-slim-queue';\n\ntype RateLimiterTask\u003cT\u003e = () =\u003e Promise\u003cT\u003e;\n\nclass RateLimiterThrottlingError extends Error { /* ... */ }\n\nclass RateLimiter\u003cT\u003e {\n  // Monotonic queue of ascending task-execution timestamps.\n  private readonly _ascWindowTimestamps: SlimQueue\u003cnumber\u003e;\n\n  constructor(\n    private readonly _windowDurationMs: number,\n    private readonly _tasksPerWindow: number\n  ) { \n    // The maximum queue size is predetermined.\n    // Leveraging this knowledge, we initialize with a capacity equal to the maximum,\n    // avoiding unnecessary internal reallocations.\n    this._ascWindowTimestamps = new SlimQueue\u003cnumber\u003e(this._tasksPerWindow);\n  }\n\n  public async tryExecutingTask(task: RateLimiterTask\u003cT\u003e): Promise\u003cT\u003e {\n    // Evict out-of-window past execution timestamps.\n    const now: number = Date.now();\n    while (this._isOutdatedFirstIn(now)) {\n      this._ascWindowTimestamps.pop();\n    }\n\n    if (this._ascWindowTimestamps.size === this._tasksPerWindow) {\n      throw new RateLimiterThrottlingError();\n    }\n\n    this._ascWindowTimestamps.push(now);\n    return task();\n  }\n\n  // Eviction indicator.\n  private _isOutdatedFirstIn(now: number): boolean {\n    if (this._ascWindowTimestamps.isEmpty) {\n      return false;\n    }\n\n    const elapsedMsSinceOldestTimestamp = now - this._ascWindowTimestamps.firstIn;\n    return elapsedMsSinceOldestTimestamp \u003e= this._windowDurationMs;\n  }\n}\n```\n\n## Capacity Tunning :wrench:\u003ca id=\"capacity-tuning\"\u003e\u003c/a\u003e\n\nThe `SlimQueue` constructor allows precise control over the initial capacity and the increment factor of the internal queue buffer.\n```ts\nconstructor(\n  initialCapacity: number = DEFAULT_SLIM_QUEUE_INITIAL_CAPACITY,\n  capacityIncrementFactor: number = DEFAULT_SLIM_QUEUE_CAPACITY_INCREMENT_FACTOR\n)\n```\n\nThe initial capacity defines the number of pre-allocated slots in the buffer. As long as the number of queue items does not exceed this capacity, no buffer reallocation is required. Since buffer reallocation is an `O(new buffer size)` operation, it is advisable to set the initial capacity to match the expected maximum queue size, if known in advance.\n\nIf the number of items exceeds the current capacity, a new internal buffer will be allocated, and all existing items will be transferred to this new buffer. The size of the new buffer will be `oldBufferSize * capacityIncrementFactor`.  \nFor example, if the initial capacity is 100 and the increment factor is 2, the queue will allocate a new buffer of 200 slots before adding the 101st item.  \nNote: The valid range of `capacityIncrementFactor` is **[1.1, 2]**. Any out-of-range factor will cause the constructor to throw an error.\n\nA small initial capacity may lead to frequent dynamic memory reallocations, potentially causing latency spikes. Conversely, an overly large initial capacity may result in wasted memory. Each use case should **weigh the trade-offs** between these factors. Ideally, the maximum queue size is known in advance, making the increment factor unnecessary.\n\n## License :scroll:\u003ca id=\"license\"\u003e\u003c/a\u003e\n\n[Apache 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fori88c%2Fdata-oriented-slim-queue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fori88c%2Fdata-oriented-slim-queue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fori88c%2Fdata-oriented-slim-queue/lists"}