@aria-framework/kit 0.4.0 → 0.6.0

package/asyncHandler.js

@@ -0,0 +1,24 @@
+/**
+ * Wrap an async Express route handler so a rejected promise reaches the error handler.
+ *
+ * Express 4 does not await a handler, so a rejection inside one becomes an UNHANDLED REJECTION
+ * rather than a 500: the request hangs until the client gives up, and the process may exit if
+ * the app treats unhandled rejections as fatal — which both consumers do. Neither symptom
+ * points at the route that caused it.
+ *
+ * Five identical lines in both apps, differing only in the wording of the comment above them.
+ * Trivial, and free to stop writing twice.
+ *
+ *     router.get('/x', asyncHandler(async (req, res) => { ... }))
+ *
+ * Express 5 handles this natively. Kept anyway: it is a no-op there, and removing it would mean
+ * editing every route the day an app upgrades.
+ */
+
+'use strict';
+
+module.exports = function asyncHandler(fn) {
+  return function (req, res, next) {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+};

package/dbTime.js

@@ -0,0 +1,98 @@
+/**
+ * Reading a SQLite timestamp, and seeing it in somebody's timezone.
+ *
+ * THE THREE PRIMITIVES, AND NOT THE FORMATTERS. Both consuming apps have a `formatDate`, and
+ * they are genuinely different functions: one renders DD/MM/YYYY always, the other assembles by
+ * locale because it invoices across countries where the date order differs. Promoting either
+ * would have imposed a product decision on the other app. What IS the same is everything
+ * underneath — parsing a stored timestamp, and asking what wall-clock it was in a zone — and
+ * that is where the two copies had already drifted.
+ *
+ * THE DRIFT THIS CLOSES: one app cached the `Intl.DateTimeFormat` per timezone and the other
+ * constructed a new one on every call. Construction is milliseconds, and a list page calls this
+ * once per row per column, so the uncached copy quietly cost real time on exactly the pages that
+ * show the most data. Nothing failed; it was just slower in one app than the other, for no
+ * reason anybody had decided.
+ */
+
+'use strict';
+
+/** 'YYYY-MM-DD' with no time component — a labelled calendar day, not a moment. */
+const BARE_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+/**
+ * A SQLite timestamp ('YYYY-MM-DD HH:MM:SS', no offset) as a Date representing that wall-clock
+ * in UTC. Strings that already carry a designator (`Z` or `±HH:MM`) pass through unchanged.
+ *
+ * @returns {Date|null} null when unparseable — the caller shows the raw string rather than
+ *                      "Invalid Date", which at least lets somebody see what was stored.
+ */
+function parseDbTimestampAsUtc(input) {
+  const str = String(input).trim();
+  const hasTzSuffix = /Z$/i.test(str) || /[+-]\d{2}:?\d{2}$/.test(str);
+  // No designator means the value came from SQLite's datetime('now'), which is UTC.
+  const normalised = hasTzSuffix ? str.replace(' ', 'T') : str.replace(' ', 'T') + 'Z';
+  const d = new Date(normalised);
+  return isNaN(d.getTime()) ? null : d;
+}
+
+/**
+ * Date and time parts as observed in an IANA timezone.
+ *
+ * `formatToParts` rather than a formatted string, so the caller controls the output shape
+ * completely — which is what lets two apps with different date orders share this.
+ *
+ * FORMATTERS ARE CACHED PER ZONE. Constructing an `Intl.DateTimeFormat` is millisecond-level
+ * work, and list pages call this once per row per column. The cache is bounded by the number of
+ * distinct zones an app ever renders, which is a handful, and ONLY successful constructions are
+ * stored — caching a failure would turn one bad setting into a permanent one.
+ *
+ * @returns {object|null} null when the timezone is unrecognised.
+ */
+const _fmtCache = new Map();
+function partsInTimezone(date, tz) {
+  try {
+    let fmt = _fmtCache.get(tz);
+    if (!fmt) {
+      fmt = new Intl.DateTimeFormat('en-GB', {
+        timeZone: tz,
+        year: 'numeric', month: '2-digit', day: '2-digit',
+        hour: '2-digit', minute: '2-digit', hourCycle: 'h23'
+      });
+      _fmtCache.set(tz, fmt);
+    }
+    const out = {};
+    for (const p of fmt.formatToParts(date)) {
+      if (p.type !== 'literal') out[p.type] = p.value;
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Warn ONCE per process per zone about a timezone nothing recognises.
+ *
+ * Once, because this is reached from a render path: a misconfigured display timezone would
+ * otherwise write a log line for every row of every page, which buries the one occurrence that
+ * would have told somebody to fix the setting.
+ *
+ * The logger is a parameter rather than a dependency — this package has none, deliberately, and
+ * an app that passes nothing gets silence rather than a crash.
+ */
+const _warned = new Set();
+function warnInvalidTimezone(tz, logger) {
+  if (_warned.has(tz)) return;
+  _warned.add(tz);
+  if (logger && typeof logger.warn === 'function') {
+    logger.warn(`Unknown display timezone "${tz}" — falling back to UTC`);
+  }
+}
+
+/** Test seam: forget which zones have been warned about. */
+const _resetWarned = () => _warned.clear();
+
+module.exports = {
+  BARE_DATE_RE, parseDbTimestampAsUtc, partsInTimezone, warnInvalidTimezone, _resetWarned
+};

package/fileSniff.js

@@ -1,137 +1,210 @@
-/**
- * Magic-byte file-type validation for uploads.
- *
- * multer's `file.mimetype` is the client-declared Content-Type — attacker
- * controlled. This module reads the actual leading bytes and checks they are
- * consistent with the declared MIME's container family, so an HTML file
- * labelled `image/png` is rejected. Office formats can't be distinguished from
- * each other by magic alone (docx/xlsx are both ZIP; doc/xls are both OLE), so
- * we validate the container family, not the exact subtype.
- *
- * ACCEPTS A PATH OR A BUFFER. Both exist in practice: multer's disk storage gives a path, and
- * its memory storage gives a buffer with no path at all — which is what a consumer writing
- * documents into an encrypted database column uses. Sniffing only ever needed the first 16
- * bytes, so a path-only signature meant the memory case could not be checked and simply was
- * not, in the one app that stores uploads inside the database.
- */
-
-const fs = require('fs');
-
-/** The first 16 bytes, from a path or straight from a buffer. */
-function head(input) {
-  if (Buffer.isBuffer(input)) return input.subarray(0, 16);
-  let fd;
-  try {
-    fd = fs.openSync(input, 'r');
-    const buf = Buffer.alloc(16);
-    const n = fs.readSync(fd, buf, 0, 16, 0);
-    return buf.subarray(0, n);
-  } finally {
-    if (fd !== undefined) try { fs.closeSync(fd); } catch (_) { /* noop */ }
-  }
-}
-
-/**
- * Sniff the container/type from the first bytes. Returns a coarse tag or null.
- * @param {string|Buffer} input  a file path, or the bytes themselves
- */
-function sniff(input) {
-  try {
-    const b = head(input);
-    const hex = b.toString('hex').toUpperCase();
-
-    if (hex.startsWith('89504E47')) return 'image/png';
-    if (hex.startsWith('FFD8FF')) return 'image/jpeg';
-    if (hex.startsWith('47494638')) return 'image/gif';
-    if (hex.startsWith('25504446')) return 'application/pdf';
-
-    // RIFF container — disambiguate by the form-type at bytes 8–12.
-    if (hex.startsWith('52494646') && b.length >= 12) {
-      const form = b.subarray(8, 12).toString('ascii');
-      if (form === 'WEBP') return 'image/webp';
-      if (form === 'WAVE') return 'riff-wave';
-      if (form === 'AVI ') return 'riff-avi';
-    }
-
-    // ISO-BMFF (MP4/MOV/M4A/HEIC): 'ftyp' box at bytes 4–8. We don't split the
-    // brand — validate the container family, like we do for zip-based formats.
-    if (b.length >= 8 && b.subarray(4, 8).toString('ascii') === 'ftyp') return 'isobmff';
-    // Matroska/WebM (EBML)
-    if (hex.startsWith('1A45DFA3')) return 'ebml';
-    // Ogg (audio/video)
-    if (hex.startsWith('4F676753')) return 'ogg';
-    // MP3: ID3 tag, or an MPEG audio frame sync (0xFFEx).
-    if (hex.startsWith('494433') || (b.length >= 2 && b[0] === 0xFF && (b[1] & 0xE0) === 0xE0)) return 'mp3';
-
-    // ZIP container (docx/xlsx and plain zip): PK\x03\x04 / PK\x05\x06 / PK\x07\x08
-    if (hex.startsWith('504B0304') || hex.startsWith('504B0506') || hex.startsWith('504B0708')) return 'zip';
-    // OLE compound file (legacy doc/xls)
-    if (hex.startsWith('D0CF11E0A1B11AE1')) return 'ole';
-    // Other archives
-    if (hex.startsWith('377ABCAF271C')) return '7z';
-    if (hex.startsWith('526172211A07')) return 'rar';   // 'Rar!\x1A\x07'
-    if (hex.startsWith('1F8B')) return 'gzip';
-    // No binary signature: treat as text only if there are no NUL bytes.
-    if (b.length > 0 && !b.includes(0)) return 'text';
-    return null;
-  } catch (_) {
-    // A path that cannot be opened, or bytes that cannot be read. "Unknown" rather than a
-    // throw: the caller's next move is to reject the file either way, and a sniffer that can
-    // fail loudly turns an unreadable upload into a 500.
-    return null;
-  }
-}
-
-// Declared MIME → the sniffed tags that are acceptable for it.
-const FAMILY = {
-  'image/png': ['image/png'],
-  'image/jpeg': ['image/jpeg'],
-  'image/gif': ['image/gif'],
-  'image/webp': ['image/webp'],
-  'application/pdf': ['application/pdf'],
-  'text/plain': ['text'],
-  'text/csv': ['text'],
-  'application/msword': ['ole'],
-  'application/vnd.ms-excel': ['ole'],
-  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': ['zip'],
-  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': ['zip'],
-  // images (HEIC/HEIF are ISO-BMFF)
-  'image/heic': ['isobmff'],
-  'image/heif': ['isobmff'],
-  // video
-  'video/mp4': ['isobmff'],
-  'video/quicktime': ['isobmff'],
-  'video/webm': ['ebml'],
-  'video/x-msvideo': ['riff-avi'],
-  'video/ogg': ['ogg'],
-  // audio
-  'audio/mpeg': ['mp3'],
-  'audio/mp4': ['isobmff'],
-  'audio/x-m4a': ['isobmff'],
-  'audio/wav': ['riff-wave'],
-  'audio/x-wav': ['riff-wave'],
-  'audio/ogg': ['ogg'],
-  'audio/webm': ['ebml'],
-  // archives
-  'application/zip': ['zip'],
-  'application/x-zip-compressed': ['zip'],
-  'application/x-7z-compressed': ['7z'],
-  'application/x-rar-compressed': ['rar'],
-  'application/vnd.rar': ['rar'],
-  'application/gzip': ['gzip']
-};
-
-/**
- * True if the file's actual content is consistent with the declared MIME.
- * @param {string|Buffer} input   a file path, or the bytes themselves
- * @param {string} declaredMime
- * @returns {boolean}
- */
-function matches(input, declaredMime) {
-  const allowed = FAMILY[declaredMime];
-  if (!allowed) return false;
-  const sniffed = sniff(input);
-  return !!sniffed && allowed.includes(sniffed);
-}
-
-module.exports = { sniff, matches };
+/**
+ * Magic-byte file-type validation for uploads.
+ *
+ * multer's `file.mimetype` is the client-declared Content-Type — attacker
+ * controlled. This module reads the actual leading bytes and checks they are
+ * consistent with the declared MIME's container family, so an HTML file
+ * labelled `image/png` is rejected. Office formats can't be distinguished from
+ * each other by magic alone (docx/xlsx are both ZIP; doc/xls are both OLE), so
+ * we validate the container family, not the exact subtype.
+ *
+ * ACCEPTS A PATH OR A BUFFER. Both exist in practice: multer's disk storage gives a path, and
+ * its memory storage gives a buffer with no path at all — which is what a consumer writing
+ * documents into an encrypted database column uses. Sniffing only ever needed the first 16
+ * bytes, so a path-only signature meant the memory case could not be checked and simply was
+ * not, in the one app that stores uploads inside the database.
+ */
+
+const fs = require('fs');
+
+/** The first 16 bytes, from a path or straight from a buffer. */
+function head(input) {
+  if (Buffer.isBuffer(input)) return input.subarray(0, 16);
+  let fd;
+  try {
+    fd = fs.openSync(input, 'r');
+    const buf = Buffer.alloc(16);
+    const n = fs.readSync(fd, buf, 0, 16, 0);
+    return buf.subarray(0, n);
+  } finally {
+    if (fd !== undefined) try { fs.closeSync(fd); } catch (_) { /* noop */ }
+  }
+}
+
+/**
+ * Sniff the container/type from the first bytes. Returns a coarse tag or null.
+ * @param {string|Buffer} input  a file path, or the bytes themselves
+ */
+function sniff(input) {
+  try {
+    const b = head(input);
+    const hex = b.toString('hex').toUpperCase();
+
+    if (hex.startsWith('89504E47')) return 'image/png';
+    if (hex.startsWith('FFD8FF')) return 'image/jpeg';
+    if (hex.startsWith('47494638')) return 'image/gif';
+    if (hex.startsWith('25504446')) return 'application/pdf';
+
+    // RIFF container — disambiguate by the form-type at bytes 8–12.
+    if (hex.startsWith('52494646') && b.length >= 12) {
+      const form = b.subarray(8, 12).toString('ascii');
+      if (form === 'WEBP') return 'image/webp';
+      if (form === 'WAVE') return 'riff-wave';
+      if (form === 'AVI ') return 'riff-avi';
+    }
+
+    // ISO-BMFF (MP4/MOV/M4A/HEIC): 'ftyp' box at bytes 4–8. We don't split the
+    // brand — validate the container family, like we do for zip-based formats.
+    if (b.length >= 8 && b.subarray(4, 8).toString('ascii') === 'ftyp') return 'isobmff';
+    // Matroska/WebM (EBML)
+    if (hex.startsWith('1A45DFA3')) return 'ebml';
+    // Ogg (audio/video)
+    if (hex.startsWith('4F676753')) return 'ogg';
+    // MP3: ID3 tag, or an MPEG audio frame sync (0xFFEx).
+    if (hex.startsWith('494433') || (b.length >= 2 && b[0] === 0xFF && (b[1] & 0xE0) === 0xE0)) return 'mp3';
+
+    // ZIP container (docx/xlsx and plain zip): PK\x03\x04 / PK\x05\x06 / PK\x07\x08
+    if (hex.startsWith('504B0304') || hex.startsWith('504B0506') || hex.startsWith('504B0708')) return 'zip';
+    // OLE compound file (legacy doc/xls)
+    if (hex.startsWith('D0CF11E0A1B11AE1')) return 'ole';
+    // Other archives
+    if (hex.startsWith('377ABCAF271C')) return '7z';
+    if (hex.startsWith('526172211A07')) return 'rar';   // 'Rar!\x1A\x07'
+    if (hex.startsWith('1F8B')) return 'gzip';
+    // No binary signature: treat as text only if there are no NUL bytes.
+    if (b.length > 0 && !b.includes(0)) return 'text';
+    return null;
+  } catch (_) {
+    // A path that cannot be opened, or bytes that cannot be read. "Unknown" rather than a
+    // throw: the caller's next move is to reject the file either way, and a sniffer that can
+    // fail loudly turns an unreadable upload into a 500.
+    return null;
+  }
+}
+
+// Declared MIME → the sniffed tags that are acceptable for it.
+const FAMILY = {
+  'image/png': ['image/png'],
+  'image/jpeg': ['image/jpeg'],
+  'image/gif': ['image/gif'],
+  'image/webp': ['image/webp'],
+  'application/pdf': ['application/pdf'],
+  'text/plain': ['text'],
+  'text/csv': ['text'],
+  'application/msword': ['ole'],
+  'application/vnd.ms-excel': ['ole'],
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': ['zip'],
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': ['zip'],
+  // images (HEIC/HEIF are ISO-BMFF)
+  'image/heic': ['isobmff'],
+  'image/heif': ['isobmff'],
+  // video
+  'video/mp4': ['isobmff'],
+  'video/quicktime': ['isobmff'],
+  'video/webm': ['ebml'],
+  'video/x-msvideo': ['riff-avi'],
+  'video/ogg': ['ogg'],
+  // audio
+  'audio/mpeg': ['mp3'],
+  'audio/mp4': ['isobmff'],
+  'audio/x-m4a': ['isobmff'],
+  'audio/wav': ['riff-wave'],
+  'audio/x-wav': ['riff-wave'],
+  'audio/ogg': ['ogg'],
+  'audio/webm': ['ebml'],
+  // archives
+  'application/zip': ['zip'],
+  'application/x-zip-compressed': ['zip'],
+  'application/x-7z-compressed': ['7z'],
+  'application/x-rar-compressed': ['rar'],
+  'application/vnd.rar': ['rar'],
+  'application/gzip': ['gzip']
+};
+
+/**
+ * True if the file's actual content is consistent with the declared MIME.
+ * @param {string|Buffer} input   a file path, or the bytes themselves
+ * @param {string} declaredMime
+ * @returns {boolean}
+ */
+/**
+ * Extension → MIME, for the cases MAGIC BYTES CANNOT SETTLE.
+ *
+ * .docx, .xlsx and a plain .zip are all ZIP containers; .doc and .xls are both OLE; .mp4, .mov,
+ * .m4a and .heic are all ISO-BMFF. The bytes identify the CONTAINER and stop there, so
+ * something else has to choose within it — and the only candidates are client-supplied.
+ *
+ * That is not a flaw in this table, it is the shape of the formats. What matters is that the
+ * caller is TOLD which answer it got: `from: 'content'` was decided by the bytes and cannot be
+ * influenced; `from: 'extension'` was narrowed by a client-supplied name inside a container the
+ * bytes did confirm. An app storing documents may accept the second; one serving them back
+ * inline should think about it.
+ */
+const EXT = {
+  doc: 'application/msword',
+  xls: 'application/vnd.ms-excel',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  zip: 'application/zip',
+  heic: 'image/heic',
+  heif: 'image/heif',
+  mp4: 'video/mp4',
+  m4v: 'video/mp4',
+  mov: 'video/quicktime',
+  m4a: 'audio/x-m4a',
+  webm: 'video/webm',
+  mkv: 'video/webm',
+  avi: 'video/x-msvideo',
+  wav: 'audio/wav',
+  mp3: 'audio/mpeg',
+  txt: 'text/plain',
+  csv: 'text/csv'
+};
+
+/** Tags sniff() returns that ARE the answer, needing no extension to disambiguate. */
+const CONCRETE = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'application/pdf']);
+
+/**
+ * DECIDE the type, rather than checking someone else's claim.
+ *
+ * `matches()` asks "are these bytes consistent with what the client said?" — and then the caller
+ * usually stores what the client said. `resolve()` asks "what ARE these bytes?" and returns the
+ * answer to store. Where magic is unambiguous the client has no say at all; where it is not, the
+ * extension narrows within a container the bytes confirmed, and the result says so.
+ *
+ * Promoted from a consuming app that had written this by hand for five types, because deriving
+ * is strictly stronger than validating: a file whose bytes say nothing recognisable is REJECTED,
+ * rather than accepted under whatever label happened to arrive with it.
+ *
+ * @param {string|Buffer} input     a path or the bytes
+ * @param {string}        filename  the client's name — used ONLY to disambiguate a container
+ * @param {Set}           allow     permitted MIME types; anything outside is rejected
+ * @returns {{mime: string, from: 'content'|'extension'}|null}
+ */
+function resolve(input, { filename = '', allow = null } = {}) {
+  const tag = sniff(input);
+  if (!tag) return null;                       // unrecognised bytes are refused, never guessed
+
+  const permitted = (m) => !allow || allow.has(m);
+
+  // 1. The bytes named it outright. The client's opinion is not consulted.
+  if (CONCRETE.has(tag)) return permitted(tag) ? { mime: tag, from: 'content' } : null;
+
+  // 2. A container. Narrow by extension, but only to something the container can actually hold —
+  //    so a ZIP named .mp4 is refused rather than relabelled.
+  const ext = String(filename).toLowerCase().split('.').pop();
+  const byExt = EXT[ext];
+  if (!byExt) return null;
+  const acceptableTags = FAMILY[byExt] || [];
+  if (!acceptableTags.includes(tag)) return null;
+  return permitted(byExt) ? { mime: byExt, from: 'extension' } : null;
+}
+
+function matches(input, declaredMime) {
+  const allowed = FAMILY[declaredMime];
+  if (!allowed) return false;
+  const sniffed = sniff(input);
+  return !!sniffed && allowed.includes(sniffed);
+}
+
+module.exports = { sniff, matches, resolve };

package/index.js

@@ -1,31 +1,39 @@
-/**
- * @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
-};
+/**
+ * @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)
+ *   asyncHandler(fn)                                — Express async-rejection wrapper
+ *   dbTime.parseDbTimestampAsUtc / dbTime.partsInTimezone — a stored timestamp, in a timezone
+ */
+
+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,
+  asyncHandler: require('./asyncHandler'),
+  // The primitives under a date formatter, NOT the formatter: the two apps render dates
+  // differently on purpose (one is locale-aware because it invoices across countries), while
+  // everything beneath — parsing a stored timestamp, and asking what wall-clock it was in a
+  // zone — was identical and had already drifted on the Intl formatter cache.
+  dbTime: require('./dbTime')
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aria-framework/kit",
-  "version": "0.4.0",
+  "version": "0.6.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,
@@ -16,9 +16,11 @@
     "fileSniff.js",
     "trackingId.js",
     "personName.js",
-    "paginate.js"
+    "paginate.js",
+    "asyncHandler.js",
+    "dbTime.js"
   ],
   "scripts": {
-    "test": "node test/smoke.js && node test/paginate.js"
+    "test": "node test/smoke.js && node test/paginate.js && node test/dbTime.js"
   }
 }

package/paginate.js

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