@aria-framework/kit 0.6.0 → 0.7.0

package/asyncHandler.js

@@ -13,12 +13,22 @@
  *
  * 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.
+ *
+ * IT RETURNS THE PROMISE, and that `return` is load-bearing even though Express ignores it.
+ * TEST HARNESSES AWAIT THE HANDLER. Both consuming apps drive real route handlers directly —
+ * `await callback(req, res, next)` — to exercise a flow without standing up a server. Drop the
+ * return and `await undefined` resolves immediately, so every assertion runs BEFORE the handler
+ * has finished and a suite that was proving something starts proving nothing.
+ *
+ * This was found the hard way: 0.6.0 shipped without it, because the original was a one-line
+ * arrow whose implicit return was invisible when it was rewritten as a named function. Eight
+ * checks in one app's Entra suite failed, all of them looking like authorisation bugs.
  */
 
 'use strict';
 
 module.exports = function asyncHandler(fn) {
   return function (req, res, next) {
-    Promise.resolve(fn(req, res, next)).catch(next);
+    return Promise.resolve(fn(req, res, next)).catch(next);
   };
 };

package/index.js

@@ -10,6 +10,7 @@
  *   fullName(first, last) / splitName(full)         — person-name helpers
  *   fileSniff.sniff(path) / fileSniff.matches(path, mime)
  *   trackingId.generate() / trackingId.generateUnique(isTaken, maxAttempts)
+ *   publicId.generate(prefix) / publicId.isValid(value, prefix)  — prefixed permanent ids
  *   asyncHandler(fn)                                — Express async-rejection wrapper
  *   dbTime.parseDbTimestampAsUtc / dbTime.partsInTimezone — a stored timestamp, in a timezone
  */
@@ -26,6 +27,7 @@ module.exports = {
   splitName,
   fileSniff: require('./fileSniff'),
   trackingId: require('./trackingId'),
+  publicId: require('./publicId'),
   // 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aria-framework/kit",
-  "version": "0.6.0",
+  "version": "0.7.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,
@@ -15,12 +15,13 @@
     "isEmail.js",
     "fileSniff.js",
     "trackingId.js",
+    "publicId.js",
     "personName.js",
     "paginate.js",
     "asyncHandler.js",
     "dbTime.js"
   ],
   "scripts": {
-    "test": "node test/smoke.js && node test/paginate.js && node test/dbTime.js"
+    "test": "node test/smoke.js && node test/paginate.js && node test/dbTime.js && node test/publicId.js"
   }
 }

package/publicId.js

@@ -0,0 +1,69 @@
+/**
+ * Public identifiers — prefix_XXXXXXXXXXXXXXXX, sixteen Crockford base32 characters.
+ *
+ * The THIRD identifier kind, beside the integer primary key and the caller's own external ref.
+ * The integer id is the database's key (joins, foreign keys) and never leaves the building — it is
+ * enumerable and it counts your rows for anyone who sees it. The external ref is the CALLER'S key,
+ * agreed at onboarding, optional and editable. This is OURS and permanent: how an API, a URL or a
+ * log names an entity, assigned once at creation and never changed. A `cnt_…` in a log line says
+ * what it is before anyone looks it up.
+ *
+ * This is the RAW primitive — it takes a prefix string and knows nothing of any app's entities.
+ * The registry of which prefix means which entity (customer, invoice, …) is per-app policy and
+ * lives in the app, exactly as `trackingId` leaves the storage existence-check to its caller. The
+ * two things every consumer shares — the alphabet and the length — are single-sourced HERE, so no
+ * two apps can drift on what a public id physically is.
+ *
+ * Crockford base32 (no I, L, O, U — same alphabet as trackingId) so ids survive being read aloud
+ * and retyped. crypto.randomInt gives an unbiased draw. Sixteen characters is 32^16 ≈ 1.2 × 10^24
+ * of space: at that size a check-the-database-first loop buys nothing, so generation is a plain
+ * draw and a UNIQUE index on the storing column is the collision backstop — if the astronomically
+ * unlikely happens, the INSERT fails loudly instead of two rows sharing a name.
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'; // Crockford base32 (no I L O U)
+const DEFAULT_LENGTH = 16;
+
+/** A prefix is a short token that names the KIND — it must not contain the `_` separator. */
+function assertPrefix(prefix) {
+  if (typeof prefix !== 'string' || prefix.length === 0 || prefix.includes('_')) {
+    throw new Error('publicId: prefix must be a non-empty string with no "_" separator');
+  }
+}
+
+/**
+ * A well-formed public id for the given prefix, e.g. generate('cnt') → 'cnt_8HW3PB6XK2M94TQZ'.
+ * @param {string} prefix     - the KIND token (no underscore)
+ * @param {{length?: number}} [opts]
+ * @returns {string}
+ */
+function generate(prefix, { length = DEFAULT_LENGTH } = {}) {
+  assertPrefix(prefix);
+  let body = '';
+  for (let i = 0; i < length; i++) body += ALPHABET[crypto.randomInt(ALPHABET.length)];
+  return `${prefix}_${body}`;
+}
+
+/**
+ * True when `value` is a well-formed public id for exactly this prefix.
+ *
+ * The prefix is REQUIRED: this primitive validates against one known prefix, because it has no
+ * registry to tell it which prefixes are legitimate. An app that wants "any of my entities" ORs
+ * this over its own prefix set (or precompiles a single regex from the exported ALPHABET).
+ *
+ * @param {string} value
+ * @param {string} prefix
+ * @param {{length?: number}} [opts]
+ * @returns {boolean}
+ */
+function isValid(value, prefix, { length = DEFAULT_LENGTH } = {}) {
+  assertPrefix(prefix);
+  const re = new RegExp(`^${prefix}_[${ALPHABET}]{${length}}$`);
+  return re.test(String(value == null ? '' : value));
+}
+
+module.exports = { generate, isValid, ALPHABET, DEFAULT_LENGTH };