@nxtedition/scheduler 3.0.2 → 3.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) nxtedition
+
+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.

package/README.md

@@ -0,0 +1,162 @@
+# @nxtedition/scheduler
+
+A high-performance, priority-based task scheduler for Node.js with support for concurrency limiting and multi-worker coordination via `SharedArrayBuffer`.
+
+## Install
+
+```sh
+npm install @nxtedition/scheduler
+```
+
+## Usage
+
+### Basic
+
+```js
+import { Scheduler } from '@nxtedition/scheduler'
+
+const scheduler = new Scheduler({ concurrency: 4 })
+
+const result = await scheduler.run(async () => {
+  const res = await fetch('https://example.com')
+  return res.json()
+})
+```
+
+### Priority
+
+Seven priority levels are available:
+
+| Name      | Value |
+| --------- | ----- |
+| `lowest`  | -3    |
+| `lower`   | -2    |
+| `low`     | -1    |
+| `normal`  | 0     |
+| `high`    | 1     |
+| `higher`  | 2     |
+| `highest` | 3     |
+
+```js
+// Using string priority
+await scheduler.run(() => importantWork(), 'high')
+
+// Using static constants
+await scheduler.run(() => backgroundWork(), Scheduler.LOW)
+```
+
+### Low-Level API
+
+For more control, use `acquire` / `release` directly:
+
+```js
+scheduler.acquire(
+  (opaque) => {
+    try {
+      doWork(opaque)
+    } finally {
+      scheduler.release()
+    }
+  },
+  Scheduler.NORMAL,
+  opaqueData,
+)
+```
+
+### Multi-Worker Coordination
+
+Share a concurrency limit across worker threads using `SharedArrayBuffer`:
+
+```js
+// Main thread
+import { Scheduler } from '@nxtedition/scheduler'
+import { Worker } from 'node:worker_threads'
+
+const sharedState = Scheduler.makeSharedState(8)
+const worker = new Worker('./worker.js', { workerData: sharedState })
+
+// Worker thread
+import { Scheduler } from '@nxtedition/scheduler'
+import { workerData } from 'node:worker_threads'
+
+const scheduler = new Scheduler(workerData)
+await scheduler.run(() => work())
+```
+
+### UV Thread Pool Scheduling
+
+A practical use case is coordinating access to the libuv thread pool (`UV_THREADPOOL_SIZE`) across multiple worker threads. For example, several HTTP file-serving workers can share a scheduler so that file-system operations (which consume UV thread pool slots) are prioritized and throttled globally:
+
+```js
+// main.js
+import { Scheduler } from '@nxtedition/scheduler'
+import { Worker } from 'node:worker_threads'
+
+const UV_THREADPOOL_SIZE = parseInt(process.env.UV_THREADPOOL_SIZE || '4', 10)
+const sharedState = Scheduler.makeSharedState(UV_THREADPOOL_SIZE)
+
+for (let i = 0; i < 4; i++) {
+  new Worker('./http-worker.js', { workerData: { sharedState } })
+}
+```
+
+```js
+// http-worker.js
+import { Scheduler, parsePriority } from '@nxtedition/scheduler'
+import { workerData } from 'node:worker_threads'
+import fs from 'node:fs/promises'
+
+const scheduler = new Scheduler(workerData.sharedState)
+
+async function handleRequest(req, res) {
+  // Derive priority from a request header, e.g. "X-Priority: high"
+  const priority = parsePriority(req.headers['x-priority'] || 'normal')
+
+  const data = await scheduler.run(() => fs.readFile(filePath), priority)
+  res.end(data)
+}
+```
+
+This ensures that high-priority requests get file-system access first, while low-priority background work (thumbnails, transcoding, etc.) yields thread pool capacity without starving entirely — thanks to the built-in starvation prevention.
+
+### Monitoring
+
+```js
+const { running, pending, deferred, queues } = scheduler.stats
+```
+
+- `running` — currently executing tasks
+- `pending` — tasks waiting in queues
+- `deferred` — total tasks that were queued (lifetime counter)
+- `queues` — per-priority queue counts
+
+## API
+
+### `new Scheduler(opts)`
+
+- `opts.concurrency` — max concurrent tasks (default: `Infinity`)
+- `opts` may also be a `SharedArrayBuffer` created by `Scheduler.makeSharedState()`
+
+### `scheduler.run(fn, priority?, opaque?): Promise<T>`
+
+Execute `fn` within the scheduler. Returns a promise that resolves with the return value of `fn`.
+
+### `scheduler.acquire(fn, priority?, opaque?): void`
+
+Low-level task acquisition. You **must** call `scheduler.release()` when done.
+
+### `scheduler.release(): void`
+
+Signal task completion. Dequeues the next pending task if concurrency allows.
+
+### `Scheduler.makeSharedState(concurrency): SharedArrayBuffer`
+
+Create shared state for cross-worker scheduling.
+
+### `parsePriority(value): number`
+
+Parse a string or number into a normalized priority value.
+
+## License
+
+MIT

package/lib/index.js

@@ -1,8 +1,15 @@
+import os from 'node:os'
+
 const RUNNING_INDEX = 0
 const CONCURRENCY_INDEX = 1
 
 const maxInt = 2147483647
 
+// On x86/x64, aligned 32-bit reads do not tear, so a plain array access is safe
+// and avoids the overhead of Atomics.load() in V8. On other architectures (e.g. ARM),
+// use Atomics.load() to prevent tearing.
+const useAtomicLoad = os.arch() !== 'x64' && os.arch() !== 'ia32'
+
 class FastQueue {
   idx = 0
   cnt = 0
@@ -145,7 +152,17 @@ export class Scheduler {
     const queue = this.#queues[p + 3]
 
     if (this.#stateView) {
-      if (this.#running < 1 || this.#stateView[RUNNING_INDEX] < this.#concurrency) {
+      // NOTE: The read of stateView followed by Atomics.add is a TOCTOU race. Multiple
+      // workers may simultaneously read a value below the concurrency limit and all
+      // proceed, briefly exceeding it by up to N-1 (where N is the number of workers).
+      // This is by design — the concurrency limit is a soft / best-effort constraint.
+      // Small, transient over-subscriptions are acceptable and self-correcting on the
+      // next release() cycle.
+      // Plain array read on x86 (aligned 32-bit reads don't tear); Atomics.load elsewhere.
+      const running = useAtomicLoad
+        ? Atomics.load(this.#stateView, RUNNING_INDEX)
+        : this.#stateView[RUNNING_INDEX]
+      if (this.#running < 1 || running < this.#concurrency) {
         Atomics.add(this.#stateView, RUNNING_INDEX, 1)
         this.#running += 1
         fn(opaque)

package/package.json

@@ -1,23 +1,31 @@
 {
   "name": "@nxtedition/scheduler",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "files": [
-    "lib"
+    "lib",
+    "README.md",
+    "LICENSE"
   ],
-  "license": "UNLICENSED",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "rimraf lib && tsc && amaroc ./src/index.ts && mv src/index.js lib/",
     "prepublishOnly": "yarn build",
     "typecheck": "tsc --noEmit",
-    "test": "node --test",
-    "test:ci": "node --test"
+    "test": "yarn build && node --test",
+    "test:ci": "yarn build && node --test"
   },
   "devDependencies": {
+    "@types/node": "^25.2.3",
     "amaroc": "^1.0.1",
+    "oxlint-tsgolint": "^0.12.2",
     "rimraf": "^6.1.2",
     "typescript": "^5.9.3"
-  }
+  },
+  "gitHead": "17807cefcac092e20ebf99befddf0e742e5fc0e2"
 }