@aria-framework/kit 0.2.0 → 0.3.0

package/index.js

@@ -1,27 +1,31 @@
-/**
- * @aria-framework/kit — public API.
- *
- * Single-function modules are exported flat; multi-function modules keep a
- * namespace (matching how call sites naturally read):
- *
- *   safeReturnTo(returnTo, {fallback, denyPrefix})  — open-redirect guard
- *   escapeLike(s)                                   — SQL LIKE escaping
- *   isEmail(v)                                      — email-address validator
- *   fullName(first, last) / splitName(full)         — person-name helpers
- *   fileSniff.sniff(path) / fileSniff.matches(path, mime)
- *   trackingId.generate() / trackingId.generateUnique(isTaken, maxAttempts)
- */
-
-const { escapeLike } = require('./likeEscape');
-const { isEmail } = require('./isEmail');
-const { fullName, splitName } = require('./personName');
-
-module.exports = {
-  safeReturnTo: require('./safeReturnTo'),
-  escapeLike,
-  isEmail,
-  fullName,
-  splitName,
-  fileSniff: require('./fileSniff'),
-  trackingId: require('./trackingId')
-};
+/**
+ * @aria-framework/kit — public API.
+ *
+ * Single-function modules are exported flat; multi-function modules keep a
+ * namespace (matching how call sites naturally read):
+ *
+ *   safeReturnTo(returnTo, {fallback, denyPrefix})  — open-redirect guard
+ *   escapeLike(s)                                   — SQL LIKE escaping
+ *   isEmail(v)                                      — email-address validator
+ *   fullName(first, last) / splitName(full)         — person-name helpers
+ *   fileSniff.sniff(path) / fileSniff.matches(path, mime)
+ *   trackingId.generate() / trackingId.generateUnique(isTaken, maxAttempts)
+ */
+
+const { escapeLike } = require('./likeEscape');
+const { isEmail } = require('./isEmail');
+const { fullName, splitName } = require('./personName');
+
+module.exports = {
+  safeReturnTo: require('./safeReturnTo'),
+  escapeLike,
+  isEmail,
+  fullName,
+  splitName,
+  fileSniff: require('./fileSniff'),
+  trackingId: require('./trackingId'),
+  // Page arithmetic for list views: the clamp, the past-the-end correction and the page-link
+  // window, which are the three things every hand-rolled paginator here got wrong or omitted.
+  paginate: require('./paginate').paginate,
+  PAGE_SIZES: require('./paginate').DEFAULT_SIZES
+};

package/package.json

@@ -1,20 +1,24 @@
-{
-  "name": "@aria-framework/kit",
-  "version": "0.2.0",
-  "description": "Aria App Framework — kit module. Small dependency-free server utilities: open-redirect guard (safeReturnTo), SQL LIKE escaping, magic-byte upload validation (fileSniff), Crockford base32 tracking IDs, and person-name compose/split helpers.",
-  "license": "UNLICENSED",
-  "private": false,
-  "publishConfig": {
-    "access": "public"
-  },
-  "main": "index.js",
-  "files": [
-    "index.js",
-    "safeReturnTo.js",
-    "likeEscape.js",
-    "isEmail.js",
-    "fileSniff.js",
-    "trackingId.js",
-    "personName.js"
-  ]
-}
+{
+  "name": "@aria-framework/kit",
+  "version": "0.3.0",
+  "description": "Aria App Framework — kit module. Small dependency-free server utilities: open-redirect guard (safeReturnTo), SQL LIKE escaping, magic-byte upload validation (fileSniff), Crockford base32 tracking IDs, and person-name compose/split helpers.",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "safeReturnTo.js",
+    "likeEscape.js",
+    "isEmail.js",
+    "fileSniff.js",
+    "trackingId.js",
+    "personName.js",
+    "paginate.js"
+  ],
+  "scripts": {
+    "test": "node test/smoke.js && node test/paginate.js"
+  }
+}

package/paginate.js

@@ -0,0 +1,97 @@
+/**
+ * Page arithmetic. Pure — no DB, no request, no opinion about how the rows are fetched.
+ *
+ * Every list in these apps that pages has re-derived this, and the parts that get quietly
+ * wrong are always the same three:
+ *
+ *   the clamp     `pageSize` arrives from a query string. Unclamped, `?pageSize=100000` asks
+ *                 the database for everything, which is a denial of service written by the
+ *                 person browsing.
+ *   the last page deleting rows can leave you on page 9 of 4. Returning an empty list there
+ *                 looks like "no records" rather than "you are past the end".
+ *   the window    a list long enough to need paging is long enough that rendering every page
+ *                 link is the same problem as rendering every row. 200 pages is 200 links.
+ *
+ * So those three are here, once.
+ */
+
+'use strict';
+
+const DEFAULT_SIZES = [25, 50, 100, 200];
+
+/**
+ * @param {object} opts
+ * @param {number|string} [opts.page=1]      1-based; garbage becomes 1
+ * @param {number|string} [opts.pageSize]    clamped to `sizes`; defaults to the first
+ * @param {number} opts.total                total matching rows
+ * @param {number[]} [opts.sizes]            the allowed page sizes, smallest first
+ * @param {number} [opts.window=2]           page links either side of the current one
+ * @returns {{page, pageSize, pages, total, offset, limit, from, to, isFirst, isLast,
+ *            sizes, numbers, needed}}
+ */
+function paginate({ page, pageSize, total, sizes = DEFAULT_SIZES, window = 2 } = {}) {
+  const allowed = (Array.isArray(sizes) && sizes.length ? sizes : DEFAULT_SIZES)
+    .map(Number).filter((n) => Number.isFinite(n) && n > 0).sort((a, b) => a - b);
+
+  const t = Math.max(0, Math.floor(Number(total) || 0));
+
+  // CLAMPED TO THE ALLOWED SET, not merely bounded. A max-only check still lets `?pageSize=99`
+  // through, and then the size dropdown shows nothing selected — the control and the data
+  // disagree, which is the kind of small wrongness nobody reports and everybody notices.
+  const askedSize = parseInt(pageSize, 10);
+  const size = allowed.indexOf(askedSize) !== -1 ? askedSize : allowed[0];
+
+  const pages = Math.max(1, Math.ceil(t / size));
+
+  // PAST THE END COMES BACK TO THE END. Deleting rows while someone is on page 9 of 4 must
+  // show them the last page, not an empty one that reads as "no records".
+  const asked = parseInt(page, 10);
+  const current = Math.min(Math.max(1, Number.isFinite(asked) ? asked : 1), pages);
+
+  const offset = (current - 1) * size;
+
+  return {
+    page: current,
+    pageSize: size,
+    pages,
+    total: t,
+    offset,
+    limit: size,
+    // 1-based inclusive, for "showing 26–50 of 1,204". `from` is 0 on an empty list so the
+    // caller can say "no records" rather than "showing 1–0 of 0".
+    from: t === 0 ? 0 : offset + 1,
+    to: Math.min(offset + size, t),
+    isFirst: current === 1,
+    isLast: current === pages,
+    sizes: allowed,
+    numbers: windowed(current, pages, window),
+    // Whether the controls are worth showing at all: a list that fits on one page at the
+    // smallest size does not need a size picker either.
+    needed: t > allowed[0]
+  };
+}
+
+/**
+ * The page links to render: `[1, null, 4, 5, 6, 7, 8, null, 20]`, where null is a gap.
+ *
+ * First and last are always present so the ends stay reachable in one click — the case that
+ * matters is "jump to the oldest", which is otherwise a long walk.
+ */
+function windowed(current, pages, window) {
+  const w = Math.max(0, Math.floor(Number(window) || 0));
+  const keep = new Set([1, pages]);
+  for (let i = current - w; i <= current + w; i++) if (i >= 1 && i <= pages) keep.add(i);
+
+  const sorted = [...keep].sort((a, b) => a - b);
+  const out = [];
+  let prev = 0;
+  for (const n of sorted) {
+    // A gap of exactly one is silly — "1 … 3" is longer than "1 2 3" and harder to click.
+    if (prev && n - prev > 1) out.push(n - prev === 2 ? prev + 1 : null);
+    if (out[out.length - 1] !== n) out.push(n);
+    prev = n;
+  }
+  return out;
+}
+
+module.exports = { paginate, DEFAULT_SIZES };