liwi-mongo 13.1.0 → 13.2.0

package/src/indexes/diffIndexes.test.ts

@@ -0,0 +1,290 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { IndexDescriptionInfo } from "mongodb";
+import type { MongoBaseModel } from "../MongoBaseModel.ts";
+import { diffIndexes, isMongoIndexPlanEmpty } from "./diffIndexes.ts";
+import type { MongoIndex, MongoIndexPlan } from "./types.ts";
+
+interface TestModel extends MongoBaseModel {
+  completed: boolean;
+  label: string;
+  status: string;
+  sessionEnd: Date;
+}
+
+const idIndex: IndexDescriptionInfo = {
+  v: 2,
+  key: { _id: 1 },
+  name: "_id_",
+};
+
+interface PlanParams {
+  declaredIndexes?: readonly MongoIndex<TestModel>[];
+  existingIndexes?: readonly IndexDescriptionInfo[];
+  dropUndeclaredIndexes?: boolean;
+}
+
+const plan = ({
+  declaredIndexes = [],
+  existingIndexes = [idIndex],
+  dropUndeclaredIndexes = true,
+}: PlanParams): MongoIndexPlan =>
+  diffIndexes<TestModel>({
+    collectionName: "tasks",
+    declaredIndexes,
+    existingIndexes,
+    dropUndeclaredIndexes,
+  });
+
+describe("diffIndexes", () => {
+  it("creates every declared index on a fresh collection", () => {
+    const result = plan({
+      declaredIndexes: [{ key: { completed: 1, created: 1 } }],
+    });
+
+    assert.deepEqual(
+      result.toCreate.map(({ name }) => name),
+      ["completed_1_created_1"],
+    );
+    assert.deepEqual(result.toDrop, []);
+    assert.equal(isMongoIndexPlanEmpty(result), false);
+  });
+
+  it("never drops or reports the _id index", () => {
+    const result = plan({});
+
+    assert.deepEqual(result.toDrop, []);
+    assert.deepEqual(result.unchanged, []);
+    assert.equal(isMongoIndexPlanEmpty(result), true);
+  });
+
+  it("ignores server managed fields when comparing", () => {
+    const result = plan({
+      declaredIndexes: [{ key: { completed: 1 } }],
+      existingIndexes: [
+        idIndex,
+        {
+          v: 2,
+          key: { completed: 1 },
+          name: "completed_1",
+          ns: "test.tasks",
+          background: true,
+          textIndexVersion: 3,
+        },
+      ],
+    });
+
+    assert.deepEqual(result.unchanged, ["completed_1"]);
+    assert.equal(isMongoIndexPlanEmpty(result), true);
+  });
+
+  it("recreates when the key order changes", () => {
+    const result = plan({
+      declaredIndexes: [
+        { key: { completed: 1, created: 1 }, name: "compound" },
+      ],
+      existingIndexes: [
+        idIndex,
+        { v: 2, key: { created: 1, completed: 1 }, name: "compound" },
+      ],
+    });
+
+    assert.deepEqual(
+      result.toRecreate.map(({ name, differences }) => [
+        name,
+        differences[0]!.field,
+      ]),
+      [["compound", "key"]],
+    );
+  });
+
+  it("recreates when a direction changes", () => {
+    const result = plan({
+      declaredIndexes: [{ key: { created: -1 }, name: "created" }],
+      existingIndexes: [
+        idIndex,
+        { v: 2, key: { created: 1 }, name: "created" },
+      ],
+    });
+
+    assert.equal(result.toRecreate.length, 1);
+  });
+
+  it("recreates when unique is added", () => {
+    const result = plan({
+      declaredIndexes: [{ key: { label: 1 }, unique: true }],
+      existingIndexes: [idIndex, { v: 2, key: { label: 1 }, name: "label_1" }],
+    });
+
+    assert.deepEqual(
+      result.toRecreate.map(({ differences }) => differences[0]!.field),
+      ["unique"],
+    );
+  });
+
+  it("uses collMod when an existing ttl value changes", () => {
+    const result = plan({
+      declaredIndexes: [{ key: { sessionEnd: 1 }, expireAfterSeconds: 60 }],
+      existingIndexes: [
+        idIndex,
+        {
+          v: 2,
+          key: { sessionEnd: 1 },
+          name: "sessionEnd_1",
+          expireAfterSeconds: 3600,
+        },
+      ],
+    });
+
+    assert.deepEqual(result.toRecreate, []);
+    assert.deepEqual(
+      result.toCollMod.map(({ name, changes }) => [name, changes]),
+      [["sessionEnd_1", { expireAfterSeconds: 60 }]],
+    );
+  });
+
+  it("recreates when ttl is added to a non ttl index", () => {
+    const result = plan({
+      declaredIndexes: [{ key: { sessionEnd: 1 }, expireAfterSeconds: 60 }],
+      existingIndexes: [
+        idIndex,
+        { v: 2, key: { sessionEnd: 1 }, name: "sessionEnd_1" },
+      ],
+    });
+
+    assert.deepEqual(result.toCollMod, []);
+    assert.equal(result.toRecreate.length, 1);
+  });
+
+  it("uses collMod when hidden is toggled", () => {
+    const result = plan({
+      declaredIndexes: [{ key: { label: 1 }, hidden: true }],
+      existingIndexes: [idIndex, { v: 2, key: { label: 1 }, name: "label_1" }],
+    });
+
+    assert.deepEqual(
+      result.toCollMod.map(({ changes }) => changes),
+      [{ hidden: true }],
+    );
+  });
+
+  it("drops undeclared indexes by default", () => {
+    const result = plan({
+      existingIndexes: [
+        idIndex,
+        { v: 2, key: { status: 1 }, name: "legacy_status_1" },
+      ],
+    });
+
+    assert.deepEqual(
+      result.toDrop.map(({ name }) => name),
+      ["legacy_status_1"],
+    );
+    assert.deepEqual(result.undeclaredKept, []);
+  });
+
+  it("keeps undeclared indexes when dropUndeclaredIndexes is false", () => {
+    const result = plan({
+      existingIndexes: [
+        idIndex,
+        { v: 2, key: { status: 1 }, name: "legacy_status_1" },
+      ],
+      dropUndeclaredIndexes: false,
+    });
+
+    assert.deepEqual(result.toDrop, []);
+    assert.deepEqual(result.undeclaredKept, ["legacy_status_1"]);
+    assert.equal(isMongoIndexPlanEmpty(result), true);
+  });
+
+  it("treats a reordered partialFilterExpression as unchanged", () => {
+    const result = plan({
+      declaredIndexes: [
+        {
+          key: { label: 1 },
+          partialFilterExpression: { completed: true, status: "open" },
+        },
+      ],
+      existingIndexes: [
+        idIndex,
+        {
+          v: 2,
+          key: { label: 1 },
+          name: "label_1",
+          partialFilterExpression: { status: "open", completed: true },
+        },
+      ],
+    });
+
+    assert.deepEqual(result.unchanged, ["label_1"]);
+  });
+
+  it("compares only the declared collation keys", () => {
+    const result = plan({
+      declaredIndexes: [{ key: { label: 1 }, collation: { locale: "en" } }],
+      existingIndexes: [
+        idIndex,
+        {
+          v: 2,
+          key: { label: 1 },
+          name: "label_1",
+          collation: {
+            locale: "en",
+            caseLevel: false,
+            caseFirst: "off",
+            strength: 3,
+            numericOrdering: false,
+            alternate: "non-ignorable",
+            maxVariable: "punct",
+            normalization: false,
+            backwards: false,
+          },
+        },
+      ],
+    });
+
+    assert.deepEqual(result.unchanged, ["label_1"]);
+  });
+
+  it("treats a text index stored as _fts/_ftsx as unchanged", () => {
+    const result = plan({
+      declaredIndexes: [{ key: { label: "text" } }],
+      existingIndexes: [
+        idIndex,
+        {
+          v: 2,
+          key: { _fts: "text", _ftsx: 1 },
+          name: "label_text",
+          weights: { label: 1 },
+          // eslint-disable-next-line camelcase -- mongo option name
+          default_language: "english",
+          // eslint-disable-next-line camelcase -- mongo option name
+          language_override: "language",
+          textIndexVersion: 3,
+        },
+      ],
+    });
+
+    assert.deepEqual(result.unchanged, ["label_text"]);
+    assert.equal(isMongoIndexPlanEmpty(result), true);
+  });
+
+  it("handles a rename as a drop plus a create", () => {
+    const result = plan({
+      declaredIndexes: [{ key: { label: 1 }, name: "label_new" }],
+      existingIndexes: [
+        idIndex,
+        { v: 2, key: { label: 1 }, name: "label_old" },
+      ],
+    });
+
+    assert.deepEqual(
+      result.toCreate.map(({ name }) => name),
+      ["label_new"],
+    );
+    assert.deepEqual(
+      result.toDrop.map(({ name }) => name),
+      ["label_old"],
+    );
+  });
+});

package/src/indexes/diffIndexes.ts

@@ -0,0 +1,234 @@
+import type { IndexDescriptionInfo } from "mongodb";
+import type { MongoBaseModel } from "../MongoBaseModel.ts";
+import { deepEqualUnordered } from "./deepEqualUnordered.ts";
+import type { NormalizedIndex } from "./normalizeIndex.ts";
+import {
+  normalizeDeclaredIndexes,
+  normalizeExistingIndex,
+} from "./normalizeIndex.ts";
+import type {
+  MongoIndex,
+  MongoIndexCollModChanges,
+  MongoIndexDifference,
+  MongoIndexPlan,
+} from "./types.ts";
+
+const idIndexName = "_id_";
+
+const isSameKey = (
+  declared: NormalizedIndex,
+  existing: NormalizedIndex,
+): boolean =>
+  declared.isText === existing.isText &&
+  declared.keyEntries.length === existing.keyEntries.length &&
+  declared.keyEntries.every(
+    ([field, direction], index) =>
+      existing.keyEntries[index]![0] === field &&
+      existing.keyEntries[index]![1] === direction,
+  );
+
+const isSameCollation = (
+  declared: NormalizedIndex["options"]["collation"],
+  existing: NormalizedIndex["options"]["collation"],
+): boolean => {
+  if (!declared) return !existing;
+  if (!existing) return false;
+
+  return Object.entries(declared).every(([key, value]) =>
+    deepEqualUnordered(value, (existing as any)[key]),
+  );
+};
+
+const diffOptions = (
+  declared: NormalizedIndex,
+  existing: NormalizedIndex,
+): MongoIndexDifference[] => {
+  const differences: MongoIndexDifference[] = [];
+
+  const compare = (
+    field: MongoIndexDifference["field"],
+    declaredValue: unknown,
+    existingValue: unknown,
+    equals: (a: unknown, b: unknown) => boolean = deepEqualUnordered,
+  ): void => {
+    if (!equals(declaredValue, existingValue)) {
+      differences.push({
+        field,
+        declared: declaredValue,
+        existing: existingValue,
+      });
+    }
+  };
+
+  compare("unique", declared.options.unique, existing.options.unique);
+  compare("sparse", declared.options.sparse, existing.options.sparse);
+  compare("hidden", declared.options.hidden, existing.options.hidden);
+  compare(
+    "expireAfterSeconds",
+    declared.options.expireAfterSeconds,
+    existing.options.expireAfterSeconds,
+  );
+  compare(
+    "partialFilterExpression",
+    declared.options.partialFilterExpression,
+    existing.options.partialFilterExpression,
+  );
+  compare(
+    "collation",
+    declared.options.collation,
+    existing.options.collation,
+    (a, b) =>
+      isSameCollation(
+        a as NormalizedIndex["options"]["collation"],
+        b as NormalizedIndex["options"]["collation"],
+      ),
+  );
+  compare("weights", declared.options.weights, existing.options.weights);
+  compare(
+    "default_language",
+    declared.options.defaultLanguage,
+    existing.options.defaultLanguage,
+  );
+  compare(
+    "language_override",
+    declared.options.languageOverride,
+    existing.options.languageOverride,
+  );
+  compare(
+    "wildcardProjection",
+    declared.options.wildcardProjection,
+    existing.options.wildcardProjection,
+  );
+
+  return differences;
+};
+
+const isCollModApplicable = (
+  differences: readonly MongoIndexDifference[],
+): boolean =>
+  differences.length > 0 &&
+  differences.every(
+    (difference) =>
+      difference.field === "hidden" ||
+      (difference.field === "expireAfterSeconds" &&
+        difference.declared !== undefined &&
+        difference.existing !== undefined),
+  );
+
+const buildCollModChanges = (
+  differences: readonly MongoIndexDifference[],
+): MongoIndexCollModChanges => {
+  const changes: MongoIndexCollModChanges = {};
+  differences.forEach((difference) => {
+    if (difference.field === "hidden") {
+      changes.hidden = difference.declared as boolean;
+    } else if (difference.field === "expireAfterSeconds") {
+      changes.expireAfterSeconds = difference.declared as number;
+    }
+  });
+  return changes;
+};
+
+interface DiffIndexesParams<Model extends MongoBaseModel<any>> {
+  collectionName: string;
+  declaredIndexes: readonly MongoIndex<Model>[];
+  existingIndexes: readonly IndexDescriptionInfo[];
+  dropUndeclaredIndexes: boolean;
+}
+
+export const diffIndexes = <Model extends MongoBaseModel<any>>({
+  collectionName,
+  declaredIndexes,
+  existingIndexes,
+  dropUndeclaredIndexes,
+}: DiffIndexesParams<Model>): MongoIndexPlan => {
+  const declared = normalizeDeclaredIndexes({
+    collectionName,
+    indexes: declaredIndexes,
+  });
+
+  const remainingExisting = new Map<
+    string,
+    { normalized: NormalizedIndex; raw: IndexDescriptionInfo }
+  >();
+  existingIndexes.forEach((raw) => {
+    const normalized = normalizeExistingIndex(raw);
+    if (normalized.name === idIndexName) return;
+    remainingExisting.set(normalized.name, { normalized, raw });
+  });
+
+  const plan: MongoIndexPlan = {
+    collectionName,
+    toCreate: [],
+    toRecreate: [],
+    toCollMod: [],
+    toDrop: [],
+    unchanged: [],
+    undeclaredKept: [],
+  };
+
+  declared.forEach((declaredIndex) => {
+    const existing = remainingExisting.get(declaredIndex.name);
+
+    if (!existing) {
+      plan.toCreate.push({
+        name: declaredIndex.name,
+        index: declaredIndex.description,
+      });
+      return;
+    }
+
+    remainingExisting.delete(declaredIndex.name);
+
+    if (!isSameKey(declaredIndex, existing.normalized)) {
+      plan.toRecreate.push({
+        name: declaredIndex.name,
+        index: declaredIndex.description,
+        existing: existing.raw,
+        differences: [
+          {
+            field: "key",
+            declared: declaredIndex.key,
+            existing: existing.normalized.key,
+          },
+        ],
+      });
+      return;
+    }
+
+    const differences = diffOptions(declaredIndex, existing.normalized);
+
+    if (differences.length === 0) {
+      plan.unchanged.push(declaredIndex.name);
+    } else if (isCollModApplicable(differences)) {
+      plan.toCollMod.push({
+        name: declaredIndex.name,
+        changes: buildCollModChanges(differences),
+        differences,
+      });
+    } else {
+      plan.toRecreate.push({
+        name: declaredIndex.name,
+        index: declaredIndex.description,
+        existing: existing.raw,
+        differences,
+      });
+    }
+  });
+
+  remainingExisting.forEach(({ raw }, name) => {
+    if (dropUndeclaredIndexes) {
+      plan.toDrop.push({ name, existing: raw });
+    } else {
+      plan.undeclaredKept.push(name);
+    }
+  });
+
+  return plan;
+};
+
+export const isMongoIndexPlanEmpty = (plan: MongoIndexPlan): boolean =>
+  plan.toCreate.length === 0 &&
+  plan.toRecreate.length === 0 &&
+  plan.toCollMod.length === 0 &&
+  plan.toDrop.length === 0;

package/src/indexes/formatIndexPlan.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { formatIndexPlan, formatIndexPlans } from "./formatIndexPlan.ts";
+import type { MongoIndexPlan } from "./types.ts";
+
+const emptyPlan = (collectionName: string): MongoIndexPlan => ({
+  collectionName,
+  toCreate: [],
+  toRecreate: [],
+  toCollMod: [],
+  toDrop: [],
+  unchanged: [],
+  undeclaredKept: [],
+});
+
+describe("formatIndexPlan", () => {
+  it("collapses a plan with nothing to do", () => {
+    const plan = { ...emptyPlan("users"), unchanged: ["a_1", "b_1", "c_1"] };
+
+    assert.equal(
+      formatIndexPlan(plan),
+      "users\n  = 3 unchanged, nothing to do",
+    );
+  });
+
+  it("lists every action", () => {
+    const plan: MongoIndexPlan = {
+      ...emptyPlan("tasks"),
+      toCreate: [
+        {
+          name: "completed_1_created_1",
+          index: { key: { completed: 1, created: 1 } },
+        },
+      ],
+      toRecreate: [
+        {
+          name: "label_text",
+          index: { key: { label: "text" } },
+          existing: { key: { title: "text" }, name: "label_text" },
+          differences: [
+            {
+              field: "key",
+              declared: { label: "text" },
+              existing: { title: "text" },
+            },
+          ],
+        },
+      ],
+      toCollMod: [
+        {
+          name: "sessions_ttl",
+          changes: { expireAfterSeconds: 60 },
+          differences: [
+            { field: "expireAfterSeconds", declared: 60, existing: 3600 },
+          ],
+        },
+      ],
+      toDrop: [
+        {
+          name: "legacy_status_1",
+          existing: { key: { status: 1 }, name: "legacy_status_1" },
+        },
+      ],
+      unchanged: ["a_1", "b_1"],
+    };
+
+    assert.equal(
+      formatIndexPlan(plan),
+      [
+        "tasks",
+        '  + create    completed_1_created_1  {"completed":1,"created":1}',
+        '  ~ recreate  label_text             key: {"title":"text"} -> {"label":"text"}',
+        "  ! modify    sessions_ttl           expireAfterSeconds: 3600 -> 60",
+        "  - drop      legacy_status_1",
+        "  = 2 unchanged",
+      ].join("\n"),
+    );
+  });
+
+  it("reports undeclared indexes left in place", () => {
+    const plan = {
+      ...emptyPlan("tasks"),
+      undeclaredKept: ["legacy_status_1"],
+    };
+
+    assert.equal(
+      formatIndexPlan(plan),
+      "tasks\n  ? kept  legacy_status_1  undeclared, not dropped",
+    );
+  });
+});
+
+describe("formatIndexPlans", () => {
+  it("joins one block per collection", () => {
+    assert.equal(
+      formatIndexPlans([emptyPlan("tasks"), emptyPlan("users")]),
+      [
+        "tasks",
+        "  = 0 unchanged, nothing to do",
+        "users",
+        "  = 0 unchanged, nothing to do",
+      ].join("\n"),
+    );
+  });
+});

package/src/indexes/formatIndexPlan.ts

@@ -0,0 +1,71 @@
+import type { MongoIndexDifference, MongoIndexPlan } from "./types.ts";
+
+const formatDifference = ({
+  field,
+  declared,
+  existing,
+}: MongoIndexDifference): string =>
+  `${field}: ${JSON.stringify(existing) ?? "undefined"} -> ${JSON.stringify(declared) ?? "undefined"}`;
+
+const formatDifferences = (
+  differences: readonly MongoIndexDifference[],
+): string =>
+  differences.map((difference) => formatDifference(difference)).join(", ");
+
+interface PlanLine {
+  action: string;
+  name: string;
+  detail: string;
+}
+
+const buildLines = (plan: MongoIndexPlan): PlanLine[] => [
+  ...plan.toCreate.map(({ name, index }) => ({
+    action: "+ create",
+    name,
+    detail: JSON.stringify(index.key),
+  })),
+  ...plan.toRecreate.map(({ name, differences }) => ({
+    action: "~ recreate",
+    name,
+    detail: formatDifferences(differences),
+  })),
+  ...plan.toCollMod.map(({ name, differences }) => ({
+    action: "! modify",
+    name,
+    detail: formatDifferences(differences),
+  })),
+  ...plan.toDrop.map(({ name }) => ({ action: "- drop", name, detail: "" })),
+  ...plan.undeclaredKept.map((name) => ({
+    action: "? kept",
+    name,
+    detail: "undeclared, not dropped",
+  })),
+];
+
+export const formatIndexPlan = (plan: MongoIndexPlan): string => {
+  const lines = buildLines(plan);
+  const unchangedCount = plan.unchanged.length;
+
+  if (lines.length === 0) {
+    return `${plan.collectionName}\n  = ${unchangedCount} unchanged, nothing to do`;
+  }
+
+  const actionWidth = Math.max(...lines.map(({ action }) => action.length));
+  const nameWidth = Math.max(...lines.map(({ name }) => name.length));
+
+  const formattedLines = lines.map(
+    ({ action, name, detail }) =>
+      `  ${action.padEnd(actionWidth)}  ${detail ? name.padEnd(nameWidth) : name}${detail ? `  ${detail}` : ""}`,
+  );
+
+  if (unchangedCount > 0) {
+    formattedLines.push(`  = ${unchangedCount} unchanged`);
+  }
+
+  return [plan.collectionName, ...formattedLines].join("\n");
+};
+
+export const formatIndexPlans = (plans: readonly MongoIndexPlan[]): string =>
+  plans.map((plan) => formatIndexPlan(plan)).join("\n");
+
+export { isMongoIndexPlanEmpty } from "./diffIndexes.ts";