@antelopejs/dms 0.15.0 → 0.16.0

package/bin/control/json.test.mjs

@@ -0,0 +1,130 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import {
+  arrayOf,
+  decode,
+  firstString,
+  instanceOf,
+  isNumber,
+  isRecord,
+  isString,
+  nullable,
+  objectOf,
+  oneOf,
+  readRecordList,
+  recordOf,
+  stringField,
+} from "./json.mjs";
+
+await test("an object is a record, an array, null and a string are not", () => {
+  assert.equal(isRecord({}), true);
+  assert.equal(isRecord([]), false);
+  assert.equal(isRecord(null), false);
+  assert.equal(isRecord("text"), false);
+});
+
+await test("a string field answers only an own string property", () => {
+  assert.equal(stringField({ access_token: "abc" }, "access_token"), "abc");
+  assert.equal(stringField({ access_token: 4 }, "access_token"), undefined);
+  assert.equal(stringField({}, "access_token"), undefined);
+  assert.equal(stringField(["abc"], "0"), undefined);
+  assert.equal(stringField(null, "access_token"), undefined);
+});
+
+await test("a string field never answers an inherited property", () => {
+  assert.equal(stringField({}, "constructor"), undefined);
+  assert.equal(stringField({}, "toString"), undefined);
+});
+
+await test("the first string of a list is its first element only", () => {
+  assert.equal(firstString(["user-1", "user-2"]), "user-1");
+  assert.equal(firstString([4, "user-2"]), undefined);
+  assert.equal(firstString([]), undefined);
+  assert.equal(firstString({ 0: "user-1" }), undefined);
+});
+
+/**
+ * @param {import("node:test").TestContext} t The test
+ * @param {string} text What the file holds
+ * @returns {string} The file
+ */
+function jsonFile(t, text) {
+  const dir = mkdtempSync(join(tmpdir(), "dms-control-json-test-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  const file = join(dir, "list.json");
+  writeFileSync(file, text);
+  return file;
+}
+
+await test("a list of objects is read as written", (t) => {
+  const file = jsonFile(t, '[{"journey":"smoke","extra":1},{}]');
+  assert.deepEqual(readRecordList(file), [{ journey: "smoke", extra: 1 }, {}]);
+});
+
+await test("a file that is not a list of objects is refused", (t) => {
+  for (const text of ["{}", "null", "[1]", "[null]", "[[]]"]) {
+    assert.throws(
+      () => readRecordList(jsonFile(t, text)),
+      /is not a list of objects/,
+      text,
+    );
+  }
+});
+
+await test("a file that is not JSON is refused", (t) => {
+  assert.throws(() => readRecordList(jsonFile(t, "[")), SyntaxError);
+});
+
+await test("an object guard checks required and optional properties and keeps the rest", () => {
+  const guard = objectOf({ name: isString }, { count: isNumber });
+  assert.equal(guard({ name: "a" }), true);
+  assert.equal(guard({ name: "a", count: 2, extra: true }), true);
+  assert.equal(guard({ name: "a", count: "2" }), false);
+  assert.equal(guard({ count: 2 }), false);
+  assert.equal(guard([]), false);
+  assert.equal(guard(null), false);
+});
+
+await test("an object guard never counts an inherited property", () => {
+  assert.equal(objectOf({ constructor: isString })({}), false);
+  assert.equal(objectOf({}, { toString: isString })({}), true);
+});
+
+await test("list, record, nullable and name guards check what they hold", () => {
+  assert.equal(arrayOf(isString)(["a", 1]), false);
+  assert.equal(arrayOf(isString)([]), true);
+  assert.equal(recordOf(isNumber)({ a: 1, b: "x" }), false);
+  assert.equal(nullable(isString)(null), true);
+  assert.equal(nullable(isString)(3), false);
+  assert.equal(oneOf(["PASS", "FAIL"])("PASSED"), false);
+  assert.equal(instanceOf(RegExp)(/x/), true);
+  assert.equal(instanceOf(RegExp)("x"), false);
+});
+
+await test("decode returns a value that passes and names the source of one that does not", () => {
+  const value = { name: "a" };
+  assert.equal(
+    decode(objectOf({ name: isString }), value, "x.json", "a thing"),
+    value,
+  );
+  assert.throws(
+    () => decode(objectOf({ name: isString }), {}, "x.json", "a thing"),
+    /x\.json is malformed: expected a thing/,
+  );
+});
+
+await test("a record guard refuses what is no object, a list included", () => {
+  assert.equal(recordOf(isString)("abc"), false);
+  assert.equal(recordOf(isNumber)([1, 2]), false);
+  assert.equal(recordOf(isNumber)(null), false);
+  assert.equal(recordOf(isNumber)({}), true);
+});
+
+await test("a nullable guard accepts null and refuses a missing value", () => {
+  assert.equal(nullable(isString)(undefined), false);
+  assert.equal(nullable(isString)(null), true);
+  assert.equal(objectOf({ owner: nullable(isString) })({}), false);
+});

package/bin/control/mail.mjs

@@ -7,24 +7,52 @@ import {
 } from "node:fs";
 import { createServer } from "node:net";
 import { join } from "node:path";
+import { arrayOf, decode, isString, objectOf } from "./json.mjs";
+
+/**
+ * @typedef {{ from: string, to: string[] }} Envelope
+ * @typedef {{ buffer: string, inData: boolean, envelope: Envelope }} SmtpSession
+ */
+
+const isSummary = objectOf({
+  from: isString,
+  to: arrayOf(isString),
+  subject: isString,
+  links: arrayOf(isString),
+  text: isString,
+  receivedAt: isString,
+});
 
 const END_OF_DATA = "\r\n.\r\n";
 const QUOTED_SOFT_BREAK = /=\r?\n/g;
 const QUOTED_BYTE = /=([0-9A-F]{2})/g;
 const HEX = 16;
 
+/**
+ * @param {import("node:net").Socket} socket
+ * @param {string} line
+ */
 function reply(socket, line) {
   socket.write(`${line}\r\n`);
 }
 
+/**
+ * @param {string} text
+ * @returns {string}
+ */
 function decodeQuotedPrintable(text) {
   return text
     .replace(QUOTED_SOFT_BREAK, "")
-    .replace(QUOTED_BYTE, (_match, byte) =>
+    .replace(QUOTED_BYTE, (_match, /** @type {string} */ byte) =>
       String.fromCharCode(Number.parseInt(byte, HEX)),
     );
 }
 
+/**
+ * @param {string} message
+ * @param {string} name
+ * @returns {string}
+ */
 function headerOf(message, name) {
   const match = new RegExp(`^${name}:\\s*(.+(?:\\r?\\n[ \\t].+)*)`, "im").exec(
     message,
@@ -32,6 +60,7 @@ function headerOf(message, name) {
   return match ? match[1].replace(/\r?\n[ \t]+/g, " ").trim() : "";
 }
 
+/** @type {Record<string, string>} */
 const ENTITIES = {
   amp: "&",
   lt: "<",
@@ -41,6 +70,10 @@ const ENTITIES = {
   nbsp: " ",
 };
 
+/**
+ * @param {string} html
+ * @returns {string}
+ */
 function readableText(html) {
   const body = html.slice(html.search(/\r?\n\r?\n/));
   return body
@@ -51,6 +84,11 @@ function readableText(html) {
     .trim();
 }
 
+/**
+ * @param {string} folder
+ * @param {Envelope} envelope
+ * @param {string} raw
+ */
 function saveMessage(folder, envelope, raw) {
   mkdirSync(folder, { recursive: true });
   const index =
@@ -76,6 +114,11 @@ function saveMessage(folder, envelope, raw) {
   );
 }
 
+/**
+ * @param {SmtpSession} state
+ * @param {import("node:net").Socket} socket
+ * @param {string} line
+ */
 function command(state, socket, line) {
   const verb = line.slice(0, 4).toUpperCase();
   if (verb === "EHLO" || verb === "HELO")
@@ -99,11 +142,13 @@ function command(state, socket, line) {
   return reply(socket, "250 OK");
 }
 
+/** @param {string} folder */
 function session(folder) {
-  return (socket) => {
+  return (/** @type {import("node:net").Socket} */ socket) => {
+    /** @type {SmtpSession} */
     const state = { buffer: "", inData: false, envelope: { from: "", to: [] } };
     reply(socket, "220 dms-control mail sink");
-    socket.on("data", (chunk) => {
+    socket.on("data", (/** @type {Buffer} */ chunk) => {
       state.buffer += chunk.toString("latin1");
       while (state.buffer.length > 0) {
         if (state.inData) {
@@ -156,8 +201,13 @@ export function capturedMail(folder) {
   return readdirSync(folder)
     .filter((name) => name.endsWith(".json"))
     .sort()
-    .map((name) => ({
-      file: join(folder, name.replace(/\.json$/, ".eml")),
-      ...JSON.parse(readFileSync(join(folder, name), "utf8")),
-    }));
+    .map((name) => {
+      const summary = join(folder, name);
+      /** @type {unknown} */
+      const stored = JSON.parse(readFileSync(summary, "utf8"));
+      return {
+        file: join(folder, name.replace(/\.json$/, ".eml")),
+        ...decode(isSummary, stored, summary, "a captured message"),
+      };
+    });
 }

package/bin/control/mail.test.mjs

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { capturedMail } from "./mail.mjs";
+
+const SUMMARY = {
+  from: "no-reply@example.com",
+  to: ["a@example.com"],
+  subject: "Welcome",
+  links: ["https://example.com/verify"],
+  text: "Hello",
+  receivedAt: "2026-11-02T00:00:00.000Z",
+};
+
+/**
+ * @param {import("node:test").TestContext} t The test
+ * @param {unknown} summary What the sink stored for its one message
+ * @returns {string} The sink's folder
+ */
+function sink(t, summary) {
+  const folder = mkdtempSync(join(tmpdir(), "dms-control-mail-test-"));
+  t.after(() => rmSync(folder, { recursive: true, force: true }));
+  writeFileSync(join(folder, "001.json"), JSON.stringify(summary));
+  return folder;
+}
+
+await test("a captured message reads back with the path of its raw file", (t) => {
+  const folder = sink(t, SUMMARY);
+  assert.deepEqual(capturedMail(folder), [
+    { file: join(folder, "001.eml"), ...SUMMARY },
+  ]);
+});
+
+await test("a stored summary whose recipients are no list is refused", (t) => {
+  const folder = sink(t, { ...SUMMARY, to: "a@example.com" });
+  assert.throws(
+    () => capturedMail(folder),
+    /001\.json is malformed: expected a captured message/,
+  );
+});
+
+await test("a folder that does not exist holds no mail", () => {
+  assert.deepEqual(
+    capturedMail(join(tmpdir(), "dms-control-no-such-sink")),
+    [],
+  );
+});
+
+await test("a stored summary without its links is refused", (t) => {
+  const { links: _links, ...withoutLinks } = SUMMARY;
+  const folder = sink(t, withoutLinks);
+  assert.throws(() => capturedMail(folder), /001\.json is malformed/);
+});

package/bin/control/mongo.mjs

@@ -3,14 +3,117 @@ import { mkdirSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { arrayOf, decode, isRecord, isString, objectOf } from "./json.mjs";
 import { freePort, startDetached, waitForPort } from "./processes.mjs";
 
+/**
+ * @typedef {(...args: unknown[]) => unknown} Callable A function whose result is read as `unknown`
+ * @typedef {new (...args: unknown[]) => unknown} Constructor A class whose instances are read as `unknown`
+ * @typedef {{ connect: Callable, close: Callable, db: Callable }} Client The calls made on a driver client
+ * @typedef {{ admin: Callable, dropDatabase: Callable }} Database The calls made on a driver database
+ * @typedef {{ listDatabases: Callable }} Admin The call made on a driver's admin handle
+ */
+
 /** The server version the backend test harness pins, already cached by it. */
 const MONGO_VERSION = "8.0.8";
 const READY_TIMEOUT_MS = 30_000;
 
+/**
+ * @param {unknown} value
+ * @returns {value is object} True for an object or a function, which can hold members
+ */
+function isObjectLike(value) {
+  return (
+    (typeof value === "object" && value !== null) || typeof value === "function"
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Callable} True for a function
+ */
+function isCallable(value) {
+  return typeof value === "function";
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Constructor} True for a function that `new` accepts, such as a class or a bound class, and false for an arrow function or a method
+ */
+function isConstructor(value) {
+  if (!isCallable(value)) return false;
+  try {
+    Reflect.construct(Object, [], value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is { getPath: Callable }} True for an object with a `getPath` function
+ */
+function isBinaryResolver(value) {
+  return isObjectLike(value) && "getPath" in value && isCallable(value.getPath);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Client} True for an object with `connect`, `close` and `db` functions
+ */
+function isClient(value) {
+  return (
+    isObjectLike(value) &&
+    "connect" in value &&
+    isCallable(value.connect) &&
+    "close" in value &&
+    isCallable(value.close) &&
+    "db" in value &&
+    isCallable(value.db)
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Database} True for an object with `admin` and `dropDatabase` functions
+ */
+function isDatabase(value) {
+  return (
+    isObjectLike(value) &&
+    "admin" in value &&
+    isCallable(value.admin) &&
+    "dropDatabase" in value &&
+    isCallable(value.dropDatabase)
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Admin} True for an object with a `listDatabases` function
+ */
+function isAdmin(value) {
+  return (
+    isObjectLike(value) &&
+    "listDatabases" in value &&
+    isCallable(value.listDatabases)
+  );
+}
+
+const isDatabaseList = objectOf({
+  databases: arrayOf(objectOf({ name: isString })),
+});
+
+/**
+ * @param {unknown} namespace A module namespace
+ * @returns {Record<string, unknown>} Its exports, with those of a CommonJS `default` added
+ */
 function withDefaultExports(namespace) {
-  return { ...namespace.default, ...namespace };
+  if (!isRecord(namespace))
+    throw new TypeError("A module namespace is not an object");
+  const fallback = namespace.default;
+  const exports = isObjectLike(fallback) ? fallback : {};
+  return { ...exports, ...namespace };
 }
 
 /**
@@ -19,16 +122,18 @@ function withDefaultExports(namespace) {
  *
  * @param {string} name The package name
  * @param {string[]} from Folders to resolve from, in order
- * @returns {Promise<any>} The module namespace
+ * @returns {Promise<Record<string, unknown>>} The module namespace
  * @throws When no folder resolves it, saying which devDependency to add
  */
-export async function importFrom(name, from) {
+async function importNamespace(name, from) {
   for (const folder of from) {
     try {
       const resolved = createRequire(join(folder, "package.json")).resolve(
         name,
       );
-      return withDefaultExports(await import(pathToFileURL(resolved).href));
+      /** @type {unknown} */
+      const namespace = await import(pathToFileURL(resolved).href);
+      return withDefaultExports(namespace);
     } catch {
       continue;
     }
@@ -38,6 +143,20 @@ export async function importFrom(name, from) {
   );
 }
 
+/**
+ * A package's namespace, for the one caller whose use of it cannot be checked
+ * at the import: it launches Playwright's browser and drives it through
+ * Playwright's own declarations.
+ *
+ * @param {string} name The package name
+ * @param {string[]} from Folders to resolve from, in order
+ * @returns {Promise<any>} The module namespace
+ * @throws When no folder resolves it, saying which devDependency to add
+ */
+export async function importFrom(name, from) {
+  return importNamespace(name, from);
+}
+
 function mongodOnPath() {
   return spawnSync("mongod", ["--version"], { stdio: "ignore" }).status === 0
     ? "mongod"
@@ -51,11 +170,21 @@ function mongodOnPath() {
  * @param {string[]} from Folders to resolve mongodb-memory-server-core from
  * @returns {Promise<string>} The binary path
  */
-async function mongodBinary(from) {
+export async function mongodBinary(from) {
   const configured = process.env.DMS_CONTROL_MONGOD ?? mongodOnPath();
   if (configured) return configured;
-  const { MongoBinary } = await importFrom("mongodb-memory-server-core", from);
-  return MongoBinary.getPath({ version: MONGO_VERSION });
+  const namespace = await importNamespace("mongodb-memory-server-core", from);
+  const binary = namespace.MongoBinary;
+  if (!isBinaryResolver(binary))
+    throw new TypeError("mongodb-memory-server-core exports no MongoBinary");
+  /** @type {unknown} */
+  const path = await binary.getPath({ version: MONGO_VERSION });
+  return decode(
+    isString,
+    path,
+    "MongoBinary.getPath",
+    "the path of a mongod binary",
+  );
 }
 
 /**
@@ -89,6 +218,10 @@ export async function startMongod(paths, from) {
   return { url: `mongodb://127.0.0.1:${port}`, record: { ...record, port } };
 }
 
+/**
+ * @param {string[]} from
+ * @returns {string | undefined}
+ */
 function driverBesideMemoryServer(from) {
   for (const folder of from) {
     try {
@@ -103,11 +236,56 @@ function driverBesideMemoryServer(from) {
   return undefined;
 }
 
+/**
+ * @param {string[]} from
+ * @returns {Promise<Record<string, unknown>>}
+ */
 async function mongoDriver(from) {
   const beside = driverBesideMemoryServer(from);
   if (beside)
     return withDefaultExports(await import(pathToFileURL(beside).href));
-  return importFrom("mongodb", from);
+  return importNamespace("mongodb", from);
+}
+
+/**
+ * @param {Client} client A driver client
+ * @param {string} name The database
+ * @returns {Database} Its handle
+ * @throws When the driver answers anything but a database
+ */
+function databaseOf(client, name) {
+  /** @type {unknown} */
+  const database = client.db(name);
+  if (!isDatabase(database))
+    throw new TypeError(`MongoClient.db(${name}) returned no database`);
+  return database;
+}
+
+/**
+ * Runs `use` on a client connected to the server, then closes it.
+ *
+ * @template T
+ * @param {string} url The server URL
+ * @param {string[]} from Folders to resolve the driver from
+ * @param {(client: Client) => Promise<T>} use What to do with the connected client
+ * @returns {Promise<T>} What `use` answered
+ * @throws When the driver exports no `MongoClient` that builds a client
+ */
+async function withClient(url, from, use) {
+  const namespace = await mongoDriver(from);
+  const MongoClient = namespace.MongoClient;
+  if (!isConstructor(MongoClient))
+    throw new TypeError("The MongoDB driver exports no MongoClient");
+  /** @type {unknown} */
+  const client = new MongoClient(url, { serverSelectionTimeoutMS: 5_000 });
+  if (!isClient(client))
+    throw new TypeError("MongoClient built something that is no client");
+  try {
+    await client.connect();
+    return await use(client);
+  } finally {
+    await client.close();
+  }
 }
 
 /**
@@ -120,20 +298,25 @@ async function mongoDriver(from) {
  * @param {string[]} from Folders to resolve the driver from
  * @returns {Promise<string[]>} One line per dropped database
  */
-export async function dropRunDatabases(url, prefix, from) {
-  const { MongoClient } = await mongoDriver(from);
-  const client = new MongoClient(url, { serverSelectionTimeoutMS: 5_000 });
-  try {
-    await client.connect();
-    const { databases } = await client.db("admin").admin().listDatabases();
+export function dropRunDatabases(url, prefix, from) {
+  return withClient(url, from, async (client) => {
+    const admin = databaseOf(client, "admin").admin();
+    if (!isAdmin(admin))
+      throw new TypeError(
+        "The admin handle of the driver has no listDatabases",
+      );
+    const { databases } = decode(
+      isDatabaseList,
+      await admin.listDatabases(),
+      "listDatabases",
+      "a list of databases",
+    );
     const owned = databases
       .map((database) => database.name)
       .filter((name) => name.startsWith(prefix));
-    for (const name of owned) await client.db(name).dropDatabase();
+    for (const name of owned) await databaseOf(client, name).dropDatabase();
     return owned.map((name) => `dropped database ${name}`);
-  } finally {
-    await client.close();
-  }
+  });
 }
 
 /**
@@ -144,13 +327,8 @@ export async function dropRunDatabases(url, prefix, from) {
  * @param {string[]} from Folders to resolve the driver from
  * @returns {Promise<void>} Resolves once dropped
  */
-export async function dropDatabase(url, name, from) {
-  const { MongoClient } = await mongoDriver(from);
-  const client = new MongoClient(url, { serverSelectionTimeoutMS: 5_000 });
-  try {
-    await client.connect();
-    await client.db(name).dropDatabase();
-  } finally {
-    await client.close();
-  }
+export function dropDatabase(url, name, from) {
+  return withClient(url, from, async (client) => {
+    await databaseOf(client, name).dropDatabase();
+  });
 }