@aria-framework/kit 0.3.0 → 0.3.1

package/package.json

@@ -1,24 +1,24 @@
-{
-  "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"
-  }
-}
+{
+  "name": "@aria-framework/kit",
+  "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,
+  "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

@@ -1,97 +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];
-
-/**
- * @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 };
+/**
+ * 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 };