npm - htmx-ext-concurrency-limit - Versions diffs - 0.1.0 - Mend

htmx-ext-concurrency-limit 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,5 @@
+# Changelog
+## 0.1.0
+- Initial release

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Tresolis
+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 ADDED Viewed

@@ -0,0 +1,63 @@
+# htmx-ext-concurrency-limit
+An [htmx](https://htmx.org) extension that caps the number of **simultaneous in-flight
+requests per page** and puts the rest in a FIFO standby queue, releasing them
+automatically as active requests finish.
+It changes **timing only** — request content, headers, target, swap, and response
+handling are untouched. Nothing is dropped.
+## How it works
+htmx fires `htmx:confirm` for every request trigger. The extension holds each request
+(`preventDefault`) and either issues it immediately (a slot is free) or queues its
+`issueRequest` callback. On `htmx:afterRequest` (success, error, timeout, or abort) a
+slot is freed and the next queued request is issued. The cap can never be exceeded and
+a finished request always frees its slot (no deadlock).
+The counting/queue/drain logic lives in a pure, dependency-free module
+([`src/limiter.js`](./src/limiter.js)) and is unit-tested with `node --test`.
+## Install
+In-repo pnpm workspace package. Register it in `pnpm-workspace.yaml` (`packages/*`) and
+reference it with the workspace protocol:
+```jsonc
+// package.json
+"dependencies": {
+  "htmx-ext-concurrency-limit": "workspace:*"
+}
+```
+Then `pnpm install`. `htmx.org` (^2.0.10) is a peer dependency.
+## Usage
+```js
+// bundle entry (e.g. main.js) — registers the extension
+import 'htmx-ext-concurrency-limit'
+```
+```html
+<!-- enable page-wide and set the limit X -->
+<body hx-ext="concurrency-limit" data-htmx-max-concurrent="6">
+```
+- Enable via `hx-ext="concurrency-limit"` on `<body>` (or any subtree). Descendants
+  inherit it; requests outside an enabled subtree are not limited.
+- `data-htmx-max-concurrent` — maximum simultaneous in-flight requests. Read once at
+  startup. Missing / empty / `< 1` / non-numeric → defaults to **6**.
+While a request waits in the queue, its triggering element gets the
+`htmx-request-queued` class and `aria-busy="true"`; both are removed when it is issued.
+## Test
+```bash
+npm test    # node --test
+```
+## License
+MIT

package/package.json ADDED Viewed

@@ -0,0 +1,45 @@
+{
+  "name": "htmx-ext-concurrency-limit",
+  "version": "0.1.0",
+  "description": "htmx extension that caps simultaneous in-flight requests per page and queues the rest (FIFO).",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./limiter": "./src/limiter.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "htmx",
+    "htmx-extension",
+    "concurrency",
+    "rate-limit",
+    "queue"
+  ],
+  "license": "MIT",
+  "author": "Loeiz Tanguy",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tresolis/htmx-ext-concurrency-limit.git"
+  },
+  "homepage": "https://github.com/tresolis/htmx-ext-concurrency-limit#readme",
+  "bugs": "https://github.com/tresolis/htmx-ext-concurrency-limit/issues",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "provenance": true
+  },
+  "peerDependencies": {
+    "htmx.org": "^2.0.10"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/index.js ADDED Viewed

@@ -0,0 +1,66 @@
+// htmx extension `concurrency-limit`: caps simultaneous in-flight htmx requests
+// per page at `data-htmx-max-concurrent` (default 6) and queues the rest (FIFO).
+//
+// Thin glue only — the counting/queue/drain logic lives in ./limiter.js so it can
+// be unit-tested without a browser. This file maps htmx's request lifecycle onto it:
+//   htmx:confirm       -> hold the request; issue now if a slot is free, else queue it
+//   htmx:afterRequest  -> release the slot (any outcome) and drain the next queued one
+import htmx from 'htmx.org'
+import { createLimiter, parseMax } from './limiter.js'
+const DEFAULT_MAX = 6
+const PENDING_CLASS = 'htmx-request-queued'
+let limiter = null
+function getLimiter() {
+  if (!limiter) {
+    const max = parseMax(document.body && document.body.dataset.htmxMaxConcurrent, DEFAULT_MAX)
+    limiter = createLimiter(max)
+  }
+  return limiter
+}
+function markQueued(elt) {
+  if (elt && elt.classList) {
+    elt.classList.add(PENDING_CLASS)
+    elt.setAttribute('aria-busy', 'true')
+  }
+}
+function unmarkQueued(elt) {
+  if (elt && elt.classList) {
+    elt.classList.remove(PENDING_CLASS)
+    elt.removeAttribute('aria-busy')
+  }
+}
+htmx.defineExtension('concurrency-limit', {
+  init() {
+    // Read the limit once at startup (page-wide, fixed for the page lifetime).
+    getLimiter()
+  },
+  onEvent(name, evt) {
+    if (name === 'htmx:confirm') {
+      // Leave hx-confirm requests to htmx's native flow so the confirmation
+      // prompt still runs exactly once. These discrete, user-confirmed actions
+      // are not throttled (they are not a request-flood source).
+      if (evt.detail.question) return
+      const elt = evt.detail.elt
+      const realIssue = evt.detail.issueRequest
+      // Hold every other request; we decide when (or whether) it is sent.
+      evt.preventDefault()
+      const issue = () => {
+        unmarkQueued(elt)
+        realIssue(true)
+      }
+      if (getLimiter().request(issue) === 'queued') {
+        markQueued(elt)
+      }
+    } else if (name === 'htmx:afterRequest') {
+      getLimiter().release()
+    }
+  },
+})

package/src/limiter.js ADDED Viewed

@@ -0,0 +1,70 @@
+// Pure concurrency limiter: a counter + FIFO queue, with no DOM or htmx dependency.
+// All the risk-bearing logic lives here so it can be unit-tested with `node --test`.
+/**
+ * Parse a max-concurrency value, falling back when missing/empty/<1/NaN.
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+export function parseMax(value, fallback) {
+  const n = parseInt(value, 10)
+  return Number.isInteger(n) && n > 0 ? n : fallback
+}
+/**
+ * Create a limiter allowing at most `max` concurrent "issued" units.
+ *
+ * @param {number} max
+ * @returns {{
+ *   request: (issue: () => void) => 'active' | 'queued',
+ *   release: () => void,
+ *   readonly active: number,
+ *   readonly pending: number,
+ * }}
+ */
+export function createLimiter(max) {
+  let active = 0
+  const queue = []
+  // Issue one unit and account for it; on throw, undo the slot so we never leak it.
+  function run(issue) {
+    active++
+    try {
+      issue()
+    } catch {
+      active--
+      return false
+    }
+    return true
+  }
+  function request(issue) {
+    if (active < max) {
+      run(issue)
+      return 'active'
+    }
+    queue.push(issue)
+    return 'queued'
+  }
+  function release() {
+    if (active > 0) active--
+    // Fill every freed slot (normally one). A throwing unit frees its slot again,
+    // so the loop simply continues to the next queued unit — no deadlock.
+    while (queue.length > 0 && active < max) {
+      run(queue.shift())
+    }
+  }
+  return {
+    request,
+    release,
+    get active() {
+      return active
+    },
+    get pending() {
+      return queue.length
+    },
+  }
+}