@aria-framework/kit 0.1.0 → 0.3.0

package/README.md

@@ -70,11 +70,24 @@ splitName('Johan van der Merwe') // { first_name: 'Johan van der', last_name: 'M
 
 `splitName` splits on the **last** space (last word = surname). Compound
 surnames split imperfectly by design. If an app backfills a split in SQL,
-implement the same last-space rule and keep them in step. Also exported
-namespaced as `personName.{fullName,splitName}`.
+implement the same last-space rule and keep them in step.
+
+
+## isEmail — shared email-address validator (since 0.2.0)
+
+One definition of "looks like an email" for every form: trim, non-empty,
+≤254 chars (RFC 5321 cap), one `@` with a dotted domain. Pragmatic by design —
+mail servers are the real validators; this guards forms and lookups.
+
+```js
+if (!isEmail(req.body.email)) errors.push('A valid email is required.');
+```
 
 ## Changelog
 
+- **0.2.0** — added `isEmail(v)` (replaces per-route regex copies that had
+  already diverged on length handling); removed the redundant `personName`
+  namespace export — use the flat `fullName`/`splitName`.
 - **0.1.0** — first release. Extracted from Support101 `lib/` (safeReturnTo,
   likeEscape, fileSniff, trackingId, personName). One API change vs the app
   originals: `trackingId.generateUnique` takes an `isTaken(id)` callback

package/index.js

@@ -1,25 +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
- *   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 { fullName, splitName } = require('./personName');
-
-module.exports = {
-  safeReturnTo: require('./safeReturnTo'),
-  escapeLike,
-  fullName,
-  splitName,
-  fileSniff: require('./fileSniff'),
-  trackingId: require('./trackingId'),
-  personName: { fullName, splitName }
-};
+/**
+ * @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/isEmail.js

@@ -0,0 +1,22 @@
+/**
+ * Shared email-address validator — ONE definition of "looks like an email"
+ * across every form/entry point, so validation can't drift per route (the
+ * exact bug this replaces: four copy-pasted regexes where one form rejected
+ * over-long addresses, two accepted them, and one silently truncated).
+ *
+ * Deliberately pragmatic: the classic no-spaces one-@ shape plus the RFC 5321
+ * 254-char total-length cap. Not an RFC 5322 grammar — mail servers are the
+ * real validators; this guards forms and lookups.
+ *
+ * @param {*} v - candidate value (trimmed before testing; non-strings fail)
+ * @returns {boolean}
+ */
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+function isEmail(v) {
+  const s = typeof v === 'string' ? v.trim() : '';
+  return s.length > 0 && s.length <= 254 && EMAIL_RE.test(s);
+}
+
+module.exports = { isEmail };

package/package.json

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