liwi-mongo 13.1.1 → 13.3.0

package/src/indexes/isIndexConflictError.ts

@@ -0,0 +1,20 @@
+const indexOptionsConflict = 85;
+const indexKeySpecsConflict = 86;
+const indexNotFound = 27;
+const namespaceNotFound = 26;
+
+const getErrorCode = (error: unknown): unknown =>
+  typeof error === "object" && error !== null
+    ? (error as { code?: unknown }).code
+    : undefined;
+
+export const isIndexConflictError = (error: unknown): boolean => {
+  const code = getErrorCode(error);
+  return code === indexOptionsConflict || code === indexKeySpecsConflict;
+};
+
+export const isIndexNotFoundError = (error: unknown): boolean =>
+  getErrorCode(error) === indexNotFound;
+
+export const isNamespaceNotFoundError = (error: unknown): boolean =>
+  getErrorCode(error) === namespaceNotFound;

package/src/indexes/normalizeIndex.test.ts

@@ -0,0 +1,154 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { MongoBaseModel } from "../MongoBaseModel.ts";
+import {
+  normalizeDeclaredIndex,
+  normalizeDeclaredIndexes,
+  normalizeExistingIndex,
+} from "./normalizeIndex.ts";
+
+interface TestModel extends MongoBaseModel {
+  completed: boolean;
+  label: string;
+  title: string;
+}
+
+describe("normalizeDeclaredIndex", () => {
+  it("fills boolean defaults and derives the name", () => {
+    const normalized = normalizeDeclaredIndex<TestModel>({
+      key: { completed: 1 },
+    });
+
+    assert.equal(normalized.name, "completed_1");
+    assert.equal(normalized.isText, false);
+    assert.deepEqual(normalized.keyEntries, [["completed", 1]]);
+    assert.equal(normalized.options.unique, false);
+    assert.equal(normalized.options.sparse, false);
+    assert.equal(normalized.options.hidden, false);
+    assert.equal(normalized.options.weights, undefined);
+    assert.equal(normalized.options.defaultLanguage, undefined);
+  });
+
+  it("keeps an explicit name and builds the driver description", () => {
+    const normalized = normalizeDeclaredIndex<TestModel>({
+      key: { completed: 1 },
+      name: "custom",
+      unique: true,
+    });
+
+    assert.equal(normalized.name, "custom");
+    assert.deepEqual(normalized.description, {
+      key: { completed: 1 },
+      name: "custom",
+      unique: true,
+    });
+  });
+
+  it("synthesizes weights and language defaults for a text index", () => {
+    const normalized = normalizeDeclaredIndex<TestModel>({
+      key: { completed: 1, label: "text" },
+    });
+
+    assert.equal(normalized.isText, true);
+    assert.deepEqual(normalized.keyEntries, [["completed", 1]]);
+    assert.deepEqual(normalized.options.weights, { label: 1 });
+    assert.equal(normalized.options.defaultLanguage, "english");
+    assert.equal(normalized.options.languageOverride, "language");
+  });
+
+  it("throws on an empty key", () => {
+    assert.throws(
+      () => normalizeDeclaredIndex<TestModel>({ key: {} }),
+      /at least one field/,
+    );
+  });
+
+  it("throws when the index resolves to the _id index", () => {
+    assert.throws(
+      () => normalizeDeclaredIndex<TestModel>({ key: { _id: 1 } }),
+      /_id is always indexed/,
+    );
+  });
+});
+
+describe("normalizeExistingIndex", () => {
+  it("ignores server managed fields", () => {
+    const normalized = normalizeExistingIndex({
+      v: 2,
+      key: { completed: 1 },
+      name: "completed_1",
+      ns: "test.tasks",
+      background: true,
+    });
+
+    assert.deepEqual(normalized.options, {
+      unique: false,
+      sparse: false,
+      hidden: false,
+      expireAfterSeconds: undefined,
+      partialFilterExpression: undefined,
+      collation: undefined,
+      weights: undefined,
+      defaultLanguage: undefined,
+      languageOverride: undefined,
+      wildcardProjection: undefined,
+    });
+  });
+
+  it("reconstructs a text index from _fts / _ftsx and weights", () => {
+    const normalized = normalizeExistingIndex({
+      v: 2,
+      key: { completed: 1, _fts: "text", _ftsx: 1 },
+      name: "completed_1_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.equal(normalized.isText, true);
+    assert.deepEqual(normalized.keyEntries, [["completed", 1]]);
+    assert.deepEqual(normalized.options.weights, { label: 1 });
+  });
+});
+
+describe("normalizeDeclaredIndexes", () => {
+  it("throws on duplicate names", () => {
+    assert.throws(
+      () =>
+        normalizeDeclaredIndexes<TestModel>({
+          collectionName: "tasks",
+          indexes: [
+            { key: { completed: 1 }, name: "same" },
+            { key: { label: 1 }, name: "same" },
+          ],
+        }),
+      /Duplicate index name "same"/,
+    );
+  });
+
+  it("throws when more than one text index is declared", () => {
+    assert.throws(
+      () =>
+        normalizeDeclaredIndexes<TestModel>({
+          collectionName: "tasks",
+          indexes: [{ key: { label: "text" } }, { key: { title: "text" } }],
+        }),
+      /Only one text index is allowed/,
+    );
+  });
+
+  it("accepts a valid declaration", () => {
+    const normalized = normalizeDeclaredIndexes<TestModel>({
+      collectionName: "tasks",
+      indexes: [{ key: { completed: 1, created: 1 } }, { key: { label: 1 } }],
+    });
+
+    assert.deepEqual(
+      normalized.map(({ name }) => name),
+      ["completed_1_created_1", "label_1"],
+    );
+  });
+});

package/src/indexes/normalizeIndex.ts

@@ -0,0 +1,191 @@
+import type {
+  CollationOptions,
+  Document,
+  IndexDescription,
+  IndexDescriptionInfo,
+} from "mongodb";
+import type { MongoBaseModel } from "../MongoBaseModel.ts";
+import { buildIndexName } from "./buildIndexName.ts";
+import type { MongoIndex, MongoIndexDirection } from "./types.ts";
+
+const textDefaultLanguage = "english";
+const textLanguageOverride = "language";
+
+export interface NormalizedIndexOptions {
+  unique: boolean;
+  sparse: boolean;
+  hidden: boolean;
+  expireAfterSeconds?: number;
+  partialFilterExpression?: Document;
+  collation?: CollationOptions;
+  weights?: Record<string, number>;
+  defaultLanguage?: string;
+  languageOverride?: string;
+  wildcardProjection?: Document;
+}
+
+export interface NormalizedIndex {
+  name: string;
+  key: Record<string, MongoIndexDirection>;
+  keyEntries: [string, MongoIndexDirection][];
+  isText: boolean;
+  options: NormalizedIndexOptions;
+}
+
+export interface NormalizedDeclaredIndex extends NormalizedIndex {
+  description: IndexDescription;
+}
+
+const buildDescription = (
+  index: MongoIndex<any>,
+  name: string,
+): IndexDescription => {
+  const description: IndexDescription = {
+    key: index.key as Record<string, MongoIndexDirection>,
+    name,
+  };
+
+  if (index.unique !== undefined) description.unique = index.unique;
+  if (index.sparse !== undefined) description.sparse = index.sparse;
+  if (index.hidden !== undefined) description.hidden = index.hidden;
+  if (index.expireAfterSeconds !== undefined) {
+    description.expireAfterSeconds = index.expireAfterSeconds;
+  }
+  if (index.partialFilterExpression) {
+    description.partialFilterExpression = index.partialFilterExpression;
+  }
+  if (index.collation) description.collation = index.collation;
+  if (index.weights) description.weights = index.weights;
+  if (index.default_language) {
+    // eslint-disable-next-line camelcase -- mongo option name
+    description.default_language = index.default_language;
+  }
+  if (index.language_override) {
+    // eslint-disable-next-line camelcase -- mongo option name
+    description.language_override = index.language_override;
+  }
+  if (index.wildcardProjection) {
+    description.wildcardProjection = index.wildcardProjection;
+  }
+
+  return description;
+};
+
+export const normalizeDeclaredIndex = <Model extends MongoBaseModel<any>>(
+  index: MongoIndex<Model>,
+): NormalizedDeclaredIndex => {
+  const key = index.key as Record<string, MongoIndexDirection>;
+  const entries = Object.entries(key);
+
+  if (entries.length === 0) {
+    throw new Error("Invalid index: key must have at least one field");
+  }
+
+  const textFields = entries
+    .filter(([, direction]) => direction === "text")
+    .map(([field]) => field);
+  const isText = textFields.length > 0;
+
+  const name = index.name ?? buildIndexName(key);
+  const isIdOnly = entries.length === 1 && entries[0]![0] === "_id";
+  if (name === "_id_" || isIdOnly) {
+    throw new Error(
+      "Invalid index: _id is always indexed by mongo and cannot be declared",
+    );
+  }
+
+  const weights = isText
+    ? {
+        ...Object.fromEntries(textFields.map((field) => [field, 1])),
+        ...index.weights,
+      }
+    : undefined;
+
+  return {
+    name,
+    key,
+    keyEntries: entries.filter(([, direction]) => direction !== "text"),
+    isText,
+    options: {
+      unique: index.unique ?? false,
+      sparse: index.sparse ?? false,
+      hidden: index.hidden ?? false,
+      expireAfterSeconds: index.expireAfterSeconds,
+      partialFilterExpression: index.partialFilterExpression,
+      collation: index.collation,
+      weights,
+      defaultLanguage: isText
+        ? (index.default_language ?? textDefaultLanguage)
+        : undefined,
+      languageOverride: isText
+        ? (index.language_override ?? textLanguageOverride)
+        : undefined,
+      wildcardProjection: index.wildcardProjection,
+    },
+    description: buildDescription(index, name),
+  };
+};
+
+export const normalizeExistingIndex = (
+  existing: IndexDescriptionInfo,
+): NormalizedIndex => {
+  const key = existing.key as Record<string, MongoIndexDirection>;
+  const entries = Object.entries(key);
+  const isText = entries.some(([field]) => field === "_fts");
+
+  return {
+    name: existing.name ?? buildIndexName(key),
+    key,
+    keyEntries: entries.filter(
+      ([field]) => field !== "_fts" && field !== "_ftsx",
+    ),
+    isText,
+    options: {
+      unique: existing.unique ?? false,
+      sparse: existing.sparse ?? false,
+      hidden: existing.hidden ?? false,
+      expireAfterSeconds: existing.expireAfterSeconds,
+      partialFilterExpression: existing.partialFilterExpression,
+      collation: existing.collation,
+      weights: isText ? existing.weights : undefined,
+      defaultLanguage: isText
+        ? (existing.default_language ?? textDefaultLanguage)
+        : undefined,
+      languageOverride: isText
+        ? (existing.language_override ?? textLanguageOverride)
+        : undefined,
+      wildcardProjection: existing.wildcardProjection,
+    },
+  };
+};
+
+interface NormalizeDeclaredIndexesParams<Model extends MongoBaseModel<any>> {
+  collectionName: string;
+  indexes: readonly MongoIndex<Model>[];
+}
+
+export const normalizeDeclaredIndexes = <Model extends MongoBaseModel<any>>({
+  collectionName,
+  indexes,
+}: NormalizeDeclaredIndexesParams<Model>): NormalizedDeclaredIndex[] => {
+  const normalized = indexes.map((index) => normalizeDeclaredIndex(index));
+
+  const names = new Set<string>();
+  normalized.forEach(({ name }) => {
+    if (names.has(name)) {
+      throw new Error(
+        `Duplicate index name "${name}" declared on collection "${collectionName}"`,
+      );
+    }
+    names.add(name);
+  });
+
+  const textIndexes = normalized.filter(({ isText }) => isText);
+  if (textIndexes.length > 1) {
+    throw new Error(
+      `Only one text index is allowed per collection, "${collectionName}" declares ${textIndexes.length}`,
+    );
+  }
+
+  return normalized;
+};

package/src/indexes/runIndexesCli.test.ts

@@ -0,0 +1,119 @@
+import assert from "node:assert/strict";
+import { beforeEach, describe, it } from "node:test";
+import MongoRegistry from "../MongoRegistry.ts";
+import type { MongoRegistryStore } from "../MongoRegistryStore.ts";
+import { runIndexesCli } from "./runIndexesCli.ts";
+import type {
+  MongoIndexPlan,
+  MongoIndexSyncResult,
+  SyncIndexesOptions,
+} from "./types.ts";
+
+const collectionName = "tasks";
+
+interface CreatePlanParams {
+  empty: boolean;
+}
+
+const createPlan = ({ empty }: CreatePlanParams): MongoIndexPlan => ({
+  collectionName,
+  toCreate: empty
+    ? []
+    : [{ name: "completed_1", index: { key: { completed: 1 } } }],
+  toRecreate: [],
+  toCollMod: [],
+  toDrop: [],
+  unchanged: [],
+  undeclaredKept: [],
+});
+
+let receivedOptions: SyncIndexesOptions[];
+let logs: string[];
+let errors: string[];
+
+interface CreateRegistryParams {
+  empty: boolean;
+}
+
+const createRegistry = ({ empty }: CreateRegistryParams): MongoRegistry => {
+  const store: MongoRegistryStore = {
+    collectionName,
+    planIndexes: (options = {}) => {
+      receivedOptions.push(options);
+      return Promise.resolve(createPlan({ empty }));
+    },
+    syncIndexes: (options = {}) => {
+      receivedOptions.push(options);
+      return Promise.resolve<MongoIndexSyncResult>({
+        collectionName,
+        plan: createPlan({ empty }),
+        dryRun: options.dryRun ?? false,
+        created: empty ? [] : ["completed_1"],
+        dropped: [],
+        modified: [],
+      });
+    },
+  };
+
+  return new MongoRegistry([store]);
+};
+
+interface RunParams {
+  argv: string[];
+  empty?: boolean;
+}
+
+const run = ({ argv, empty = false }: RunParams): Promise<number> =>
+  runIndexesCli({
+    registry: createRegistry({ empty }),
+    argv,
+    log: (message) => logs.push(message),
+    logError: (message) => errors.push(message),
+  });
+
+describe("runIndexesCli", () => {
+  beforeEach(() => {
+    receivedOptions = [];
+    logs = [];
+    errors = [];
+  });
+
+  it("plans by default and does not sync", async () => {
+    assert.equal(await run({ argv: [] }), 0);
+    assert.match(logs.join("\n"), /\+ create {2}completed_1/);
+  });
+
+  it("exits 1 with --check when the plan is not empty", async () => {
+    assert.equal(await run({ argv: ["plan", "--check"] }), 1);
+  });
+
+  it("exits 0 with --check when the plan is empty", async () => {
+    assert.equal(await run({ argv: ["plan", "--check"], empty: true }), 0);
+  });
+
+  it("syncs and reports what it did", async () => {
+    assert.equal(await run({ argv: ["sync"] }), 0);
+    assert.match(logs.join("\n"), /tasks: 1 created, 0 modified, 0 dropped$/);
+  });
+
+  it("passes --dry-run to the registry and says nothing was applied", async () => {
+    assert.equal(await run({ argv: ["sync", "--dry-run"] }), 0);
+    assert.deepEqual(receivedOptions, [
+      { dryRun: true, dropUndeclaredIndexes: true },
+    ]);
+    assert.match(logs.join("\n"), /\(dry run, nothing applied\)/);
+  });
+
+  it("passes --keep-undeclared to the registry", async () => {
+    assert.equal(await run({ argv: ["sync", "--keep-undeclared"] }), 0);
+    assert.deepEqual(receivedOptions, [
+      { dryRun: false, dropUndeclaredIndexes: false },
+    ]);
+  });
+
+  it("returns 2 and prints the usage on an unknown command", async () => {
+    assert.equal(await run({ argv: ["migrate"] }), 2);
+    assert.match(errors.join("\n"), /Unknown command "migrate"/);
+    assert.equal(logs.length, 0);
+  });
+});

package/src/indexes/runIndexesCli.ts

@@ -0,0 +1,74 @@
+import type MongoConnection from "../MongoConnection.ts";
+import type MongoRegistry from "../MongoRegistry.ts";
+import { isMongoIndexPlanEmpty } from "./diffIndexes.ts";
+import { formatIndexPlans } from "./formatIndexPlan.ts";
+import type { MongoIndexSyncResult, SyncIndexesOptions } from "./types.ts";
+
+const usage = `Usage: [plan|sync] [options]
+
+  plan               print the plan, changes nothing (default)
+  sync               apply the plan
+
+  --check            with plan, exit 1 when the plan is not empty
+  --dry-run          with sync, compute everything but apply nothing
+  --keep-undeclared  do not drop indexes that are not declared`;
+
+const formatSyncResult = ({
+  collectionName,
+  created,
+  modified,
+  dropped,
+}: MongoIndexSyncResult): string =>
+  `${collectionName}: ${created.length} created, ${modified.length} modified, ${dropped.length} dropped`;
+
+export interface RunIndexesCliParams {
+  registry: MongoRegistry;
+  argv?: readonly string[];
+  connection?: MongoConnection;
+  log?: (message: string) => void;
+  logError?: (message: string) => void;
+}
+
+export const runIndexesCli = async ({
+  registry,
+  argv = process.argv.slice(2),
+  connection,
+  log = console.log,
+  logError = console.error,
+}: RunIndexesCliParams): Promise<number> => {
+  const command = argv.find((arg) => !arg.startsWith("--")) ?? "plan";
+  const options: SyncIndexesOptions = {
+    ...(argv.includes("--keep-undeclared")
+      ? { dropUndeclaredIndexes: false }
+      : {}),
+    dryRun: argv.includes("--dry-run"),
+  };
+
+  try {
+    if (command === "plan") {
+      const plans = await registry.planIndexes(options);
+      log(formatIndexPlans(plans));
+      const hasChanges = !plans.every((plan) => isMongoIndexPlanEmpty(plan));
+      return argv.includes("--check") && hasChanges ? 1 : 0;
+    }
+
+    if (command === "sync") {
+      const results = await registry.syncIndexes(options);
+      log(formatIndexPlans(results.map(({ plan }) => plan)));
+      log(
+        results
+          .map(
+            (result) =>
+              `${formatSyncResult(result)}${result.dryRun ? " (dry run, nothing applied)" : ""}`,
+          )
+          .join("\n"),
+      );
+      return 0;
+    }
+
+    logError(`Unknown command "${command}".\n\n${usage}`);
+    return 2;
+  } finally {
+    await connection?.close();
+  }
+};