@blamejs/core 0.5.7 → 0.5.9

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.5.x
 
+- **0.5.8** (2026-04-30) — b.uuid: RFC 4122 v4 + RFC 9562 v7
+- **0.5.7** (2026-04-30) — defensive validation + queue closure capture + audit context
 - **0.5.6** (2026-04-30) — break-glass: trustProxy honored, cache require hoisted
 - **0.5.5** (2026-04-30) — strict default CSP + IPv6 special-range expansion
 - **0.5.4** (2026-04-30) — close SSRF DNS-rebinding window with pinned outbound DNS

package/index.js

@@ -106,6 +106,8 @@ var forms = require("./lib/forms");
 var app = require("./lib/app");
 var jobs = require("./lib/jobs");
 var breakGlass = require("./lib/break-glass");
+var csv = require("./lib/csv");
+var uuid = require("./lib/uuid");
 var mail = require("./lib/mail");
 var mailBounce = require("./lib/mail-bounce");
 var websocketChannels = require("./lib/websocket-channels");
@@ -208,6 +210,8 @@ module.exports = {
   createApp:        app.createApp,
   jobs:             jobs,
   breakGlass:       breakGlass,
+  csv:              csv,
+  uuid:             uuid,
   mail:             mail,
   mailBounce:       mailBounce,
   websocketChannels: websocketChannels,

package/lib/csv.js

@@ -0,0 +1,229 @@
+"use strict";
+/**
+ * csv — RFC 4180 parser + serializer.
+ *
+ * Public API:
+ *
+ *   b.csv.parse(text, opts?)        → { headers, rows }  (or { rows } if no header)
+ *   b.csv.stringify(rows, opts?)    → string
+ *
+ * Opts (parse):
+ *   delimiter:    ","   default
+ *   header:       true  default — first row becomes column names; rows
+ *                       are objects keyed by header
+ *   maxBytes:     8 MiB default — refuses parse-bombs the same way
+ *                       safeJson does
+ *   onBadRow:     "throw" default | "skip" — what to do when a row has
+ *                       a different column count than the header
+ *
+ * Opts (stringify):
+ *   delimiter:    ","   default
+ *   header:       true  default — emit a header row from object keys
+ *   columns:      array of explicit column order (default: first row's keys)
+ *   eol:          "\r\n" default — RFC 4180 mandates CRLF; some parsers
+ *                       want LF. Operators choose.
+ *
+ * Format support:
+ *   - Quoted fields with embedded commas, quotes ("" → "), newlines.
+ *   - Optional BOM at file start (consumed silently if present).
+ *   - Trailing newline tolerated (RFC 4180 says SHOULD; we tolerate).
+ *
+ * Throws CsvError (FrameworkError) on shape violations.
+ */
+var C = require("./constants");
+var { defineClass } = require("./framework-error");
+
+var CsvError = defineClass("CsvError", { alwaysPermanent: true });
+
+var DEFAULT_MAX_BYTES = C.BYTES.mib(8);
+var DEFAULT_DELIMITER = ",";
+var DEFAULT_EOL       = "\r\n";
+
+// ---- parse ----
+
+function parse(text, opts) {
+  opts = opts || {};
+  if (typeof text !== "string" && !Buffer.isBuffer(text)) {
+    throw new CsvError("csv/bad-input",
+      "parse: input must be a string or Buffer, got " + typeof text);
+  }
+  var s = Buffer.isBuffer(text) ? text.toString("utf8") : text;
+  var maxBytes = opts.maxBytes != null ? opts.maxBytes : DEFAULT_MAX_BYTES;
+  if (Buffer.byteLength(s, "utf8") > maxBytes) {
+    throw new CsvError("csv/too-large",
+      "parse: input exceeds maxBytes (" + maxBytes + ")");
+  }
+  var delimiter = opts.delimiter || DEFAULT_DELIMITER;
+  if (typeof delimiter !== "string" || delimiter.length !== 1) {
+    throw new CsvError("csv/bad-delimiter",
+      "parse: delimiter must be a single character, got " + JSON.stringify(delimiter));
+  }
+  if (delimiter === "\"" || delimiter === "\r" || delimiter === "\n") {
+    throw new CsvError("csv/bad-delimiter",
+      "parse: delimiter cannot be quote / CR / LF");
+  }
+  var hasHeader = opts.header !== false;
+  var onBadRow = opts.onBadRow || "throw";
+  if (onBadRow !== "throw" && onBadRow !== "skip") {
+    throw new CsvError("csv/bad-opt",
+      "parse: onBadRow must be 'throw' or 'skip'");
+  }
+
+  // Strip BOM if present.
+  if (s.charCodeAt(0) === 0xfeff) s = s.slice(1);
+
+  var rows = [];
+  var field = "";
+  var row = [];
+  var inQuotes = false;
+  var i = 0;
+  var len = s.length;
+  while (i < len) {
+    var c = s.charAt(i);
+    if (inQuotes) {
+      if (c === "\"") {
+        if (i + 1 < len && s.charAt(i + 1) === "\"") {
+          field += "\"";    // escaped quote
+          i += 2;
+          continue;
+        }
+        inQuotes = false;
+        i++;
+        continue;
+      }
+      field += c;
+      i++;
+      continue;
+    }
+    if (c === "\"") {
+      // Quote at the start of a field (or anywhere — treat as start of
+      // quoted run). RFC 4180 says quoted fields begin with a quote;
+      // fields that contain a quote not at the start are technically
+      // malformed but we tolerate by appending literally.
+      if (field.length === 0) {
+        inQuotes = true;
+        i++;
+        continue;
+      }
+      field += "\"";
+      i++;
+      continue;
+    }
+    if (c === delimiter) {
+      row.push(field);
+      field = "";
+      i++;
+      continue;
+    }
+    if (c === "\r") {
+      // CRLF or bare CR — treat both as row terminator.
+      row.push(field);
+      rows.push(row);
+      field = "";
+      row = [];
+      if (i + 1 < len && s.charAt(i + 1) === "\n") i += 2;
+      else i++;
+      continue;
+    }
+    if (c === "\n") {
+      row.push(field);
+      rows.push(row);
+      field = "";
+      row = [];
+      i++;
+      continue;
+    }
+    field += c;
+    i++;
+  }
+  // Flush any trailing field/row (no trailing newline case)
+  if (field.length > 0 || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+
+  if (!hasHeader) {
+    return { rows: rows };
+  }
+  if (rows.length === 0) {
+    return { headers: [], rows: [] };
+  }
+  var headers = rows[0];
+  var out = [];
+  for (var r = 1; r < rows.length; r++) {
+    var current = rows[r];
+    if (current.length === 1 && current[0] === "") continue;   // skip blank lines
+    if (current.length !== headers.length) {
+      if (onBadRow === "skip") continue;
+      throw new CsvError("csv/row-length-mismatch",
+        "parse: row " + r + " has " + current.length + " columns, expected " + headers.length);
+    }
+    var obj = {};
+    for (var k = 0; k < headers.length; k++) obj[headers[k]] = current[k];
+    out.push(obj);
+  }
+  return { headers: headers, rows: out };
+}
+
+// ---- stringify ----
+
+function stringify(rows, opts) {
+  opts = opts || {};
+  if (!Array.isArray(rows)) {
+    throw new CsvError("csv/bad-input",
+      "stringify: rows must be an array");
+  }
+  var delimiter = opts.delimiter || DEFAULT_DELIMITER;
+  var eol       = opts.eol || DEFAULT_EOL;
+  var hasHeader = opts.header !== false;
+  if (rows.length === 0) return "";
+
+  var columns;
+  if (Array.isArray(opts.columns)) {
+    columns = opts.columns.slice();
+  } else if (Array.isArray(rows[0])) {
+    // Array-of-arrays input — no headers to derive; emit as-is.
+    columns = null;
+  } else if (rows[0] && typeof rows[0] === "object") {
+    columns = Object.keys(rows[0]);
+  } else {
+    throw new CsvError("csv/bad-input",
+      "stringify: rows[0] must be an object or array");
+  }
+
+  var lines = [];
+  if (hasHeader && columns) lines.push(columns.map(_quoteCell).join(delimiter));
+
+  for (var r = 0; r < rows.length; r++) {
+    var row = rows[r];
+    var cells;
+    if (Array.isArray(row)) {
+      cells = row.map(_quoteCell);
+    } else if (row && typeof row === "object") {
+      cells = (columns || Object.keys(row)).map(function (col) {
+        return _quoteCell(row[col]);
+      });
+    } else {
+      throw new CsvError("csv/bad-input",
+        "stringify: rows[" + r + "] must be an object or array");
+    }
+    lines.push(cells.join(delimiter));
+  }
+  return lines.join(eol) + eol;
+}
+
+function _quoteCell(value) {
+  if (value === null || value === undefined) return "";
+  var s = typeof value === "string" ? value : String(value);
+  if (s.indexOf("\"") !== -1 || s.indexOf(",") !== -1 ||
+      s.indexOf("\r") !== -1 || s.indexOf("\n") !== -1) {
+    return "\"" + s.replace(/"/g, "\"\"") + "\"";
+  }
+  return s;
+}
+
+module.exports = {
+  parse:     parse,
+  stringify: stringify,
+  CsvError:  CsvError,
+};

package/lib/uuid.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * uuid — RFC 4122 v4 (random) + RFC 9562 v7 (time-ordered).
+ *
+ * Two flavors:
+ *
+ *   b.uuid.v4()           — fully random 128-bit UUID. Standard, portable,
+ *                           the default choice when ordering doesn't matter.
+ *
+ *   b.uuid.v7()           — Unix-millisecond timestamp prefix + 74 random
+ *                           bits. Time-ordered (sorts by creation time even
+ *                           lexicographically), ideal as a database PK
+ *                           because B-tree inserts stay near the right edge
+ *                           — no random scattering across the index.
+ *
+ *   b.uuid.parse(str)     — { ok, version, bytes }. Validates the canonical
+ *                           8-4-4-4-12 hex form and the version + variant
+ *                           bits. Returns ok:false (no throw) on bad input.
+ *
+ *   b.uuid.isValid(str)   — boolean shorthand. No version/variant check
+ *                           beyond shape — operators who care use parse().
+ *
+ * All entropy comes from `b.crypto.generateBytes`, which routes through
+ * `node:crypto.randomBytes` — same source as `crypto.randomUUID()`.
+ *
+ * Why ship v7 ourselves? Native `crypto.randomUUID()` only emits v4.
+ * v7 is the modern recommendation for any UUID landing in a sortable
+ * column (jobs queue, audit chain extensions, anything where insertion
+ * order matters for index locality).
+ */
+var { generateBytes } = require("./crypto");
+
+// Canonical UUID layout: 8-4-4-4-12 hex digits, version nibble at byte
+// 6 high-nibble, variant bits at byte 8 high two bits (must be 10).
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+// Loose form for `isValid` shape-only check — accepts any version 1-8 and
+// any variant top-2-bit value. Operators wanting strict version+variant
+// gating use `parse()`.
+var UUID_LOOSE_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function _bytesToString(bytes) {
+  var hex = bytes.toString("hex");
+  return hex.slice(0, 8) + "-" +
+         hex.slice(8, 12) + "-" +
+         hex.slice(12, 16) + "-" +
+         hex.slice(16, 20) + "-" +
+         hex.slice(20, 32);
+}
+
+function v4() {
+  var b = generateBytes(16);
+  // version = 4 (0100): high nibble of byte 6
+  b[6] = (b[6] & 0x0f) | 0x40;
+  // variant = RFC 4122 (10xx): top two bits of byte 8
+  b[8] = (b[8] & 0x3f) | 0x80;
+  return _bytesToString(b);
+}
+
+function v7(opts) {
+  // RFC 9562 §5.7 layout:
+  //   bytes 0-5  : 48-bit big-endian Unix timestamp in milliseconds
+  //   bytes 6-7  : version nibble (7) + 12 bits random_a
+  //   bytes 8-15 : variant bits + 62 bits random_b
+  var ms = (opts && typeof opts.now === "number") ? opts.now : Date.now();
+  var b = generateBytes(16);
+  // 48-bit ms timestamp (big-endian) into bytes 0-5
+  // ms can exceed 2^32 (we're in 2026, ms is ~1.78e12), so use Math + bit ops carefully
+  var msHi = Math.floor(ms / 0x100000000);    // top 16 bits live in low 16 of msHi
+  var msLo = ms >>> 0;                        // bottom 32 bits unsigned
+  b[0] = (msHi >> 8) & 0xff;
+  b[1] = msHi & 0xff;
+  b[2] = (msLo >>> 24) & 0xff;
+  b[3] = (msLo >>> 16) & 0xff;
+  b[4] = (msLo >>> 8) & 0xff;
+  b[5] = msLo & 0xff;
+  // version = 7 (0111) in high nibble of byte 6, random_a in low nibble + byte 7
+  b[6] = (b[6] & 0x0f) | 0x70;
+  // variant = RFC 4122 (10xx) in top two bits of byte 8
+  b[8] = (b[8] & 0x3f) | 0x80;
+  return _bytesToString(b);
+}
+
+function parse(str) {
+  if (typeof str !== "string") return { ok: false, reason: "not-a-string" };
+  if (!UUID_RE.test(str))      return { ok: false, reason: "malformed" };
+  var hex = str.replace(/-/g, "");
+  var bytes = Buffer.from(hex, "hex");
+  // Version is the high nibble of byte 6.
+  var version = (bytes[6] >> 4) & 0x0f;
+  // Variant: top two bits of byte 8 must be 10 for RFC 4122 / 9562.
+  var variant = (bytes[8] >> 6) & 0x03;
+  if (variant !== 0b10) return { ok: false, reason: "bad-variant" };
+  return { ok: true, version: version, bytes: bytes };
+}
+
+function isValid(str) {
+  return typeof str === "string" && UUID_LOOSE_RE.test(str);
+}
+
+module.exports = {
+  v4:      v4,
+  v7:      v7,
+  parse:   parse,
+  isValid: isValid,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",