@alexify/migronaut 2.2.0 → 2.4.0

package/src/versioning/config.js

@@ -0,0 +1,155 @@
+const { ConfigInvalidError } = require('../errors/index.js');
+const { isPlainObject } = require('./internal.js');
+
+/**
+ * The `versioning` block of a collection definition — one source of truth for
+ * the shape version a collection is at, read by converge (validator, index,
+ * the `min` guard), by the background-migration engine and by the
+ * application's repository layer through `defineShapes`.
+ *
+ * Validated strictly, like every other definition key: a typo (`currnet`)
+ * must not read as "not versioned".
+ */
+
+const VERSIONING_KEYS = ['current', 'min', 'field', 'revision', 'revisionField', 'index'];
+const VERSIONING_KEY_SET = new Set(VERSIONING_KEYS);
+
+const VERSIONING_DEFAULTS = Object.freeze({
+  min: 1,
+  field: '__v',
+  revision: true,
+  revisionField: '__rev',
+  index: true,
+});
+
+/** Longest field name accepted for the version or revision field */
+const MAX_FIELD_NAME = 64;
+
+/**
+ * Why `name` cannot be a system field, or `null`. Top-level only: the engine
+ * writes it with `$set`/`$inc`, so a dot would address a nested path and a
+ * leading `$` an operator; `_id` is immutable.
+ */
+function fieldNameIssue(name) {
+  if (typeof name !== 'string' || name.length === 0) return 'must be a non-empty string';
+  if (name.length > MAX_FIELD_NAME) return `must be at most ${MAX_FIELD_NAME} characters`;
+  if (name.startsWith('$')) return "must not start with '$'";
+  if (name.includes('.')) return "must be a top-level field (no '.')";
+  if (name.includes('\0')) return 'must not contain NUL';
+  if (name === '_id') return 'must not be _id';
+  // As a JavaScript key it names the prototype: every write of it would be lost.
+  if (name === '__proto__') return 'must not be __proto__';
+  return null;
+}
+
+const isCount = (value, floor) => Number.isSafeInteger(value) && value >= floor;
+
+/**
+ * Validate a `versioning` value, returning `{ path, message }` issues (empty
+ * when valid). `path` is where it sits — `collections[2].versioning`,
+ * `orders.ts: versioning`.
+ */
+function versioningIssues(value, path = 'versioning') {
+  if (!isPlainObject(value)) {
+    return [
+      {
+        path,
+        message: 'must be an object: { current, min?, field?, revision?, revisionField?, index? }',
+      },
+    ];
+  }
+  const issues = [];
+  const report = (key, message) => issues.push({ path: `${path}.${key}`, message });
+  for (const key of Object.keys(value)) {
+    if (!VERSIONING_KEY_SET.has(key)) {
+      report(key, `is not a versioning key (expected one of: ${VERSIONING_KEYS.join(', ')})`);
+    }
+  }
+  const { current, min, field, revision, revisionField, index } = value;
+  const currentValid = isCount(current, 1);
+  if (current === undefined) report('current', 'is required');
+  else if (!currentValid) report('current', 'must be an integer ≥ 1');
+  // The default min (1) never exceeds a valid current (≥ 1).
+  if (min !== undefined) {
+    if (!isCount(min, 0)) report('min', 'must be an integer ≥ 0');
+    else if (currentValid && min > current) {
+      report('min', `must not exceed current (${current})`);
+    }
+  }
+  if (field !== undefined) {
+    const issue = fieldNameIssue(field);
+    if (issue) report('field', issue);
+  }
+  if (revision !== undefined && typeof revision !== 'boolean') {
+    report('revision', 'must be a boolean');
+  }
+  if (revisionField !== undefined) {
+    const issue = fieldNameIssue(revisionField);
+    if (issue) report('revisionField', issue);
+    else if (revision === false) report('revisionField', 'has no effect with revision: false');
+  }
+  if (revision !== false) {
+    const versionName = field ?? VERSIONING_DEFAULTS.field;
+    const revisionName = revisionField ?? VERSIONING_DEFAULTS.revisionField;
+    if (versionName === revisionName) {
+      report('revisionField', `must differ from the version field ("${versionName}")`);
+    }
+  }
+  if (index !== undefined && typeof index !== 'boolean') report('index', 'must be a boolean');
+  return issues;
+}
+
+/**
+ * A validated `versioning` value with every default filled in, frozen.
+ * `revisionField` is `null` when revisions are off.
+ *
+ * @throws {ConfigInvalidError} with every issue in `context.issues`
+ */
+function resolveVersioning(value, { path = 'versioning' } = {}) {
+  const issues = versioningIssues(value, path);
+  if (issues.length > 0) {
+    throw new ConfigInvalidError(`Invalid ${path}: ${issues[0].path} ${issues[0].message}`, {
+      issues,
+    });
+  }
+  const revision = value.revision ?? VERSIONING_DEFAULTS.revision;
+  return Object.freeze({
+    current: value.current,
+    min: value.min ?? VERSIONING_DEFAULTS.min,
+    field: value.field ?? VERSIONING_DEFAULTS.field,
+    revision,
+    revisionField: revision ? (value.revisionField ?? VERSIONING_DEFAULTS.revisionField) : null,
+    index: value.index ?? VERSIONING_DEFAULTS.index,
+  });
+}
+
+/**
+ * The resolved versioning of `collection` among `definitions` — an array of
+ * definitions (each with `name`) or a `{ name: definition }` map — or `null`
+ * when it is not declared or not versioned.
+ */
+function versioningOf(definitions, collection) {
+  let definition;
+  if (Array.isArray(definitions)) {
+    for (const candidate of definitions) {
+      if (isPlainObject(candidate) && candidate.name === collection) {
+        definition = candidate;
+        break;
+      }
+    }
+  } else if (isPlainObject(definitions) && Object.hasOwn(definitions, collection)) {
+    definition = definitions[collection];
+  }
+  if (!isPlainObject(definition) || definition.versioning === undefined) return null;
+  return resolveVersioning(definition.versioning, { path: `${collection}.versioning` });
+}
+
+module.exports = {
+  MAX_FIELD_NAME,
+  VERSIONING_DEFAULTS,
+  VERSIONING_KEYS,
+  fieldNameIssue,
+  resolveVersioning,
+  versioningIssues,
+  versioningOf,
+};

package/src/versioning/document.js

@@ -0,0 +1,326 @@
+const { ConfigInvalidError, ShapeVersionError } = require('../errors/index.js');
+const { VERSIONING_DEFAULTS, fieldNameIssue, versioningOf } = require('./config.js');
+const {
+  cloneDocument,
+  isPlainObject,
+  sameValue,
+  setOwn,
+  toCount,
+  touchedFields,
+} = require('./internal.js');
+
+/**
+ * The document-level contract shared by everything that writes a versioned
+ * collection — the repository helpers, the Mongoose plugin and the
+ * background-migration engine. They must agree on one model, or a background
+ * update would silently overwrite an application write:
+ *
+ * - a missing (or `null`) version or revision field reads as **0**, so legacy
+ *   documents need no backfill before the first guarded write;
+ * - every write to a collection with revisions bumps the revision by one
+ *   (`$inc`), so an optimistic-concurrency filter `{ _id, rev }` notices any
+ *   write that happened in between;
+ * - the version is set to an exact number, never incremented — two releases
+ *   writing the same shape agree on it.
+ *
+ * `names` below is `{ field, revisionField }` from `resolveFieldNames` (or a
+ * resolved `versioning`); `revisionField` is `null` when revisions are off.
+ */
+
+/**
+ * The system field names, validated: `{ field, revisionField }` with the
+ * defaults filled in and `revisionField: null` under `revision: false`.
+ *
+ * @throws {ConfigInvalidError} on an invalid name, or both naming one field
+ */
+function resolveFieldNames({ field, revisionField, revision } = {}) {
+  const versionName = field ?? VERSIONING_DEFAULTS.field;
+  const revisionName =
+    revision === false ? null : (revisionField ?? VERSIONING_DEFAULTS.revisionField);
+  for (const [key, name] of [
+    ['field', versionName],
+    ['revisionField', revisionName],
+  ]) {
+    if (name === null) continue;
+    const issue = fieldNameIssue(name);
+    if (issue) throw new ConfigInvalidError(`${key} ${issue}`, { key });
+  }
+  if (versionName === revisionName) {
+    throw new ConfigInvalidError('field and revisionField must differ', { key: 'revisionField' });
+  }
+  return { field: versionName, revisionField: revisionName };
+}
+
+/** A document's count field: 0 when missing or `null`, `null` when not a non-negative integer */
+function countOf(doc, field) {
+  if (!isPlainObject(doc)) return null;
+  const value = doc[field];
+  return value === undefined || value === null ? 0 : toCount(value);
+}
+
+/** The shape version of `doc` — 0 when the field is missing, `null` when it is not a count */
+const versionOf = (doc, field = VERSIONING_DEFAULTS.field) => countOf(doc, field);
+
+/** The revision of `doc` — 0 when the field is missing, `null` when it is not a count */
+const revisionOf = (doc, revisionField = VERSIONING_DEFAULTS.revisionField) =>
+  countOf(doc, revisionField);
+
+/**
+ * Whether `doc` is at exactly `version` — a missing or `null` field is
+ * version 0. A document that is not a plain object (a hydrated Mongoose
+ * document) is refused: its fields are not its own properties, and a silent
+ * `false` would read as "an old shape".
+ */
+function isVersion(doc, version, { field = VERSIONING_DEFAULTS.field } = {}) {
+  if (doc === null || doc === undefined) return false;
+  assertPlainDocument(doc);
+  return versionOf(doc, field) === version;
+}
+
+/** A plain document, or a ConfigInvalidError that says how to get one */
+function assertPlainDocument(doc) {
+  if (!isPlainObject(doc)) {
+    throw new ConfigInvalidError(
+      'A plain document is expected — read it with .lean(), or call .toObject() on a Mongoose ' +
+        'document',
+    );
+  }
+}
+
+/**
+ * The revision field alone, validated (`__rev` by default) — for a write
+ * that never sets the version, whose field name it then has no use for: a
+ * caller naming only its revision field (`__v`, as a Mongoose app may keep
+ * it) is not refused over a version field it never touches.
+ */
+function resolveRevisionField(revisionField) {
+  const name = revisionField ?? VERSIONING_DEFAULTS.revisionField;
+  const issue = fieldNameIssue(name);
+  if (issue) throw new ConfigInvalidError(`revisionField ${issue}`, { key: 'revisionField' });
+  return name;
+}
+
+/** The revision after one more write */
+const nextRevision = (revision) => (toCount(revision) ?? 0) + 1;
+
+function assertCount(value, what) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new ConfigInvalidError(`${what} must be an integer ≥ 0`, { [what]: value });
+  }
+}
+
+/** `{ [field]: n }`, or — for 0 — a match on the field being 0, `null` or missing */
+function countFilter(field, value) {
+  return value === 0 ? { [field]: { $in: [null, 0] } } : { [field]: value };
+}
+
+/** Documents at exactly `version` (0 = no version field) */
+function versionFilter(names, version) {
+  assertCount(version, 'version');
+  return countFilter(names.field, version);
+}
+
+/** Documents at exactly `revision` (0 = no revision field) */
+function revisionFilter(names, revision) {
+  assertCount(revision, 'revision');
+  return countFilter(names.revisionField, revision);
+}
+
+/**
+ * Documents below `version`: missing or `null` fields, smaller numbers, and
+ * anything that is not a number at all (which no validator would accept
+ * either). One `$not` range — two intervals of one index scan — rather than
+ * an `$or`. `null` for version 0: nothing is below it.
+ */
+function belowVersionFilter(names, version) {
+  assertCount(version, 'version');
+  return version === 0 ? null : { [names.field]: { $not: { $gte: version } } };
+}
+
+/** The key of the index every version-filtered scan uses */
+const versionIndexKey = (names) => ({ [names.field]: 1, _id: 1 });
+
+/**
+ * The optimistic-concurrency filter for rewriting `prev`: its `_id`, the
+ * exact version it was read at (`from`, by default its own) and — with
+ * revisions — the exact revision. A concurrent write moves the revision (or
+ * the version), so the rewrite then matches nothing instead of losing it.
+ */
+function occFilter(prev, names, { from } = {}) {
+  const version = from ?? versionOf(prev, names.field);
+  const filter = { _id: prev._id };
+  // A value that is not a count is matched as it is stored — `$eq`, so a
+  // stored object with `$`-keys is never read as an operator.
+  if (version === null) filter[names.field] = { $eq: prev[names.field] };
+  else Object.assign(filter, countFilter(names.field, version));
+  if (names.revisionField !== null) {
+    const revision = revisionOf(prev, names.revisionField);
+    if (revision === null) filter[names.revisionField] = { $eq: prev[names.revisionField] };
+    else Object.assign(filter, countFilter(names.revisionField, revision));
+  }
+  return filter;
+}
+
+/** Why `key` cannot be written as a top-level field with `$set`, or `null` */
+function topLevelKeyIssue(key) {
+  if (key.length === 0) return 'an empty field name';
+  if (key.startsWith('$')) return `a field name starting with '$' ("${key}")`;
+  if (key.includes('.')) return `a field name with a dot ("${key}")`;
+  if (key.includes('\0')) return 'a field name with NUL';
+  return null;
+}
+
+function invalidShape(detail, extra) {
+  return new ShapeVersionError(`The transformation returned ${detail}`, {
+    reason: 'invalid',
+    ...extra,
+  });
+}
+
+const hasKeys = (object) => {
+  for (const key in object) if (Object.hasOwn(object, key)) return true;
+  return false;
+};
+
+/**
+ * The operator update that turns `prev` into `next` and stamps it: `$set`
+ * for every top-level field whose BSON value changed, `$unset` for every one
+ * that disappeared (or became `undefined`), the version set to `to` (unset
+ * for `to: 0`), and the revision bumped.
+ *
+ * Fields that did not change are left out — so the stored BSON type of
+ * everything a transformation did not touch survives (a document read with
+ * promoted values and written back whole would turn a `Double 1.0` into an
+ * `Int32`, a `Long` into a number). A changed nested field rewrites its
+ * whole top-level subdocument. `next`'s own version and revision fields are
+ * ignored: the engine owns them.
+ *
+ * @throws {ShapeVersionError} (`reason: 'invalid'`) when `next` is not a
+ *   document, changes `_id`, or names a field `$set` cannot write
+ */
+function stampedDiff(prev, next, names, { to }) {
+  if (!isPlainObject(next)) throw invalidShape('something that is not a document');
+  assertCount(to, 'to');
+  const { field, revisionField } = names;
+  const $set = {};
+  const $unset = {};
+  for (const key of Object.keys(next)) {
+    if (key === '_id') {
+      if (!sameValue(prev._id, next._id)) throw invalidShape('a document with a different _id');
+      continue;
+    }
+    if (key === field || key === revisionField) continue;
+    const issue = topLevelKeyIssue(key);
+    if (issue) throw invalidShape(issue, { field: key });
+    const value = next[key];
+    if (value === undefined) {
+      if (Object.hasOwn(prev, key)) setOwn($unset, key, '');
+    } else if (!Object.hasOwn(prev, key) || !sameValue(prev[key], value)) {
+      setOwn($set, key, value);
+    }
+  }
+  for (const key of Object.keys(prev)) {
+    if (key === '_id' || key === field || key === revisionField) continue;
+    if (!Object.hasOwn(next, key)) setOwn($unset, key, '');
+  }
+  if (to === 0) $unset[field] = '';
+  else $set[field] = to;
+  const update = {};
+  if (hasKeys($set)) update.$set = $set;
+  if (hasKeys($unset)) update.$unset = $unset;
+  if (revisionField !== null) update.$inc = { [revisionField]: 1 };
+  return update;
+}
+
+function refuseTouch(fields, name, role) {
+  if (name !== null && fields.has(name)) {
+    throw new ConfigInvalidError(
+      `The update must not write the ${role} field "${name}" — migronaut sets it`,
+      { field: name },
+    );
+  }
+}
+
+/**
+ * Stamp an update the caller wrote: the version set to `to` (left alone when
+ * `to` is `undefined`; unset for 0) and the revision bumped. Works on an
+ * operator update (merged into its `$set`/`$unset`/`$inc`) and on a pipeline
+ * (one stage appended). A replacement document — or a pipeline that projects
+ * or replaces the root — is refused: it would drop the revision.
+ *
+ * @throws {ConfigInvalidError} on a replacement, or an update that writes a
+ *   system field itself
+ */
+function stampedUpdate(names, { to, update }) {
+  const { field, revisionField } = names;
+  if (to !== undefined) assertCount(to, 'to');
+  if (!Array.isArray(update) && !isPlainObject(update)) {
+    throw new ConfigInvalidError('The update must be an update document or a pipeline');
+  }
+  const touched = touchedFields(update);
+  if (touched.whole) {
+    throw new ConfigInvalidError(
+      Array.isArray(update)
+        ? 'A pipeline that projects or replaces the document cannot keep its revision'
+        : 'A replacement document is not an update — use replaceWithRevision',
+    );
+  }
+  refuseTouch(touched.fields, revisionField, 'revision');
+  if (to !== undefined) refuseTouch(touched.fields, field, 'version');
+
+  if (Array.isArray(update)) {
+    const stage = {};
+    if (to !== undefined && to !== 0) stage[field] = { $literal: to };
+    if (revisionField !== null) {
+      stage[revisionField] = { $add: [{ $ifNull: [`$${revisionField}`, 0] }, 1] };
+    }
+    const out = [...update];
+    if (hasKeys(stage)) out.push({ $set: stage });
+    if (to === 0) out.push({ $unset: field });
+    return out;
+  }
+  const out = { ...update };
+  if (to === 0) out.$unset = { ...update.$unset, [field]: '' };
+  else if (to !== undefined) out.$set = { ...update.$set, [field]: to };
+  if (revisionField !== null) out.$inc = { ...update.$inc, [revisionField]: 1 };
+  return out;
+}
+
+/**
+ * `doc` with its version set to `version` and its revision to 0 — each only
+ * when the document does not carry it yet, so stamping is idempotent and a
+ * document someone already stamped keeps its fields.
+ */
+function stampDocument(doc, names, version) {
+  if (!isPlainObject(doc)) throw new ConfigInvalidError('Only a plain document can be stamped');
+  assertCount(version, 'version');
+  const out = { ...doc };
+  if (out[names.field] === undefined) out[names.field] = version;
+  if (names.revisionField !== null && out[names.revisionField] === undefined) {
+    out[names.revisionField] = 0;
+  }
+  return out;
+}
+
+module.exports = {
+  assertPlainDocument,
+  belowVersionFilter,
+  cloneDocument,
+  fieldNameIssue,
+  isVersion,
+  nextRevision,
+  occFilter,
+  refuseTouch,
+  resolveFieldNames,
+  resolveRevisionField,
+  revisionFilter,
+  revisionOf,
+  sameValue,
+  stampDocument,
+  stampedDiff,
+  stampedUpdate,
+  versionFilter,
+  versionIndexKey,
+  versionOf,
+  versioningOf,
+};

package/src/versioning/index.js

@@ -0,0 +1,50 @@
+const {
+  ConfigInvalidError,
+  MigronautError,
+  RevisionConflictError,
+  ShapeVersionError,
+} = require('../errors/index.js');
+const {
+  bumpRevision,
+  findOneAndUpdateWithRevision,
+  replaceWithRevision,
+  retryOnConflict,
+  updateWithRevision,
+} = require('./occ.js');
+const { isVersion } = require('./document.js');
+const { versioningPlugin } = require('./mongoose.js');
+const { defineShapes } = require('./registry.js');
+const { upcaster } = require('./upcaster.js');
+
+/**
+ * `@alexify/migronaut/versioning` — document versioning and optimistic
+ * concurrency for an application's repository layer.
+ *
+ * Deliberately small: it requires nothing but its own modules and the error
+ * classes — not the migration engine, not the driver, not mongoose — so a
+ * service that only reads and writes documents pays for nothing else. The
+ * error classes are the package root's own, so `instanceof` agrees whichever
+ * entry point a caller imports them from.
+ */
+module.exports = {
+  // The application's view of its versioned collections
+  defineShapes,
+  upcaster,
+  isVersion,
+
+  // Optimistic concurrency
+  updateWithRevision,
+  replaceWithRevision,
+  findOneAndUpdateWithRevision,
+  retryOnConflict,
+  bumpRevision,
+
+  // Mongoose
+  versioningPlugin,
+
+  // Errors — the same classes the package root exports
+  MigronautError,
+  ConfigInvalidError,
+  RevisionConflictError,
+  ShapeVersionError,
+};