@aria-framework/kit 0.2.0 → 0.3.1

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,6 +1,6 @@
 {
   "name": "@aria-framework/kit",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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,
@@ -15,6 +15,10 @@
     "isEmail.js",
     "fileSniff.js",
     "trackingId.js",
-    "personName.js"
-  ]
+    "personName.js",
+    "paginate.js"
+  ],
+  "scripts": {
+    "test": "node test/smoke.js && node test/paginate.js"
+  }
 }

package/paginate.js

@@ -0,0 +1,124 @@
+/**
+ * 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];
+
+/**
+ * A strict integer, or null.
+ *
+ * parseInt is wrong for query-string input in two ways that both fail QUIETLY: it truncates
+ * ('12abc' -> 12, '1e3' -> 1), so garbage becomes a different page rather than a rejected one;
+ * and given the array Express produces for a repeated parameter it silently reads the FIRST
+ * element, so `?pageSize=200&pageSize=25` keeps 200 and the picker appears not to work.
+ */
+function intOrNull(v) {
+  if (Array.isArray(v)) v = v[v.length - 1];   // a repeat means "the latest wins"
+  if (typeof v === 'number') return Number.isInteger(v) ? v : null;
+  if (typeof v !== 'string' || !/^-?\d+$/.test(v.trim())) return null;
+  const n = Number(v.trim());
+  return Number.isInteger(n) ? n : null;
+}
+
+/**
+ * @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.
+  // `intOrNull`, not parseInt: parseInt('12abc') is 12 and parseInt('1e3') is 1, so garbage
+  // becomes a DIFFERENT page rather than a rejected one. And a repeated query parameter
+  // arrives as an array — Express gives ['200','25'] for `?pageSize=200&pageSize=25` — where
+  // parseInt returns 200, silently ignoring the newer choice.
+  const size = allowed.indexOf(intOrNull(pageSize)) !== -1 ? intOrNull(pageSize) : 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 = intOrNull(page);
+  const current = Math.min(Math.max(1, asked === null ? 1 : asked), 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),
+    // Worth showing the controls at all? Two separate questions, because they have two
+    // different answers and conflating them renders a pager whose only content is one
+    // disabled page number.
+    //
+    //   needed     there is more than one page AT THIS SIZE — i.e. anything to navigate
+    //   resizable  the list is longer than the smallest size, so the picker can still do
+    //              something even when this page shows everything (200-per-page over 100 rows)
+    needed: pages > 1,
+    resizable: 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);
+    // No duplicate check needed: `sorted` comes from a Set, and the only other push is
+    // `prev + 1` in the gap-of-two branch, where n === prev + 2.
+    out.push(n);
+    prev = n;
+  }
+  return out;
+}
+
+module.exports = { paginate, DEFAULT_SIZES };