@zodmon/core 0.7.0 → 0.8.0

package/dist/index.cjs

@@ -41,10 +41,12 @@ __export(index_exports, {
   TypedFindCursor: () => TypedFindCursor,
   ZodmonNotFoundError: () => ZodmonNotFoundError,
   ZodmonValidationError: () => ZodmonValidationError,
+  checkUnindexedFields: () => checkUnindexedFields,
   collection: () => collection,
   createClient: () => createClient,
   deleteMany: () => deleteMany,
   deleteOne: () => deleteOne,
+  extractComparableOptions: () => extractComparableOptions,
   extractDbName: () => extractDbName,
   extractFieldIndexes: () => extractFieldIndexes,
   find: () => find,
@@ -52,6 +54,7 @@ __export(index_exports, {
   findOneAndDelete: () => findOneAndDelete,
   findOneAndUpdate: () => findOneAndUpdate,
   findOneOrThrow: () => findOneOrThrow,
+  generateIndexName: () => generateIndexName,
   getIndexMetadata: () => getIndexMetadata,
   getRefMetadata: () => getRefMetadata,
   index: () => index,
@@ -61,6 +64,10 @@ __export(index_exports, {
   objectId: () => objectId,
   oid: () => oid,
   raw: () => raw,
+  serializeIndexKey: () => serializeIndexKey,
+  syncIndexes: () => syncIndexes,
+  toCompoundIndexSpec: () => toCompoundIndexSpec,
+  toFieldIndexSpec: () => toFieldIndexSpec,
   updateMany: () => updateMany,
   updateOne: () => updateOne
 });
@@ -69,6 +76,168 @@ module.exports = __toCommonJS(index_exports);
 // src/client/client.ts
 var import_mongodb2 = require("mongodb");
 
+// src/indexes/spec.ts
+function toFieldIndexSpec(def) {
+  const direction = def.text ? "text" : def.descending ? -1 : 1;
+  const key = { [def.field]: direction };
+  const options = {};
+  if (def.unique) options["unique"] = true;
+  if (def.sparse) options["sparse"] = true;
+  if (def.expireAfter !== void 0) options["expireAfterSeconds"] = def.expireAfter;
+  if (def.partial) options["partialFilterExpression"] = def.partial;
+  return { key, options };
+}
+function toCompoundIndexSpec(def) {
+  const key = { ...def.fields };
+  const options = {};
+  if (def.options?.unique) options["unique"] = true;
+  if (def.options?.sparse) options["sparse"] = true;
+  if (def.options?.name) options["name"] = def.options.name;
+  if (def.options?.partial) options["partialFilterExpression"] = def.options.partial;
+  return { key, options };
+}
+function serializeIndexKey(key) {
+  return Object.entries(key).map(([field, dir]) => `${field}:${dir}`).join(",");
+}
+
+// src/indexes/sync.ts
+var COMPARABLE_OPTION_KEYS = [
+  "unique",
+  "sparse",
+  "expireAfterSeconds",
+  "partialFilterExpression"
+];
+function extractComparableOptions(info) {
+  const result = {};
+  for (const key of COMPARABLE_OPTION_KEYS) {
+    if (info[key] !== void 0) {
+      result[key] = info[key];
+    }
+  }
+  return result;
+}
+function generateIndexName(key) {
+  return Object.entries(key).map(([field, dir]) => `${field}_${dir}`).join("_");
+}
+function sortKeys(obj) {
+  const sorted = {};
+  for (const key of Object.keys(obj).sort()) {
+    sorted[key] = obj[key];
+  }
+  return sorted;
+}
+function resolveSpecName(spec) {
+  const specName = spec.options["name"];
+  return typeof specName === "string" ? specName : generateIndexName(spec.key);
+}
+function resolveExistingName(info, key) {
+  const infoName = info["name"];
+  if (typeof infoName === "string") return infoName;
+  return generateIndexName(key);
+}
+function optionsMatch(a, b) {
+  return JSON.stringify(sortKeys(stripName(a))) === JSON.stringify(sortKeys(stripName(b)));
+}
+function stripName(obj) {
+  const { name: _, ...rest } = obj;
+  return rest;
+}
+async function processDesiredSpec(spec, existingByKey, native, dryRun, dropOrphaned, acc) {
+  const serialized = serializeIndexKey(spec.key);
+  const existing = existingByKey.get(serialized);
+  if (!existing) {
+    if (!dryRun) await native.createIndex(spec.key, spec.options);
+    acc.created.push(resolveSpecName(spec));
+    return;
+  }
+  acc.matchedKeys.add(serialized);
+  const existingName = resolveExistingName(existing, spec.key);
+  const existingOpts = extractComparableOptions(existing);
+  if (optionsMatch(existingOpts, spec.options)) {
+    acc.skipped.push(existingName);
+    return;
+  }
+  if (dropOrphaned) {
+    if (!dryRun) {
+      await native.dropIndex(existingName);
+      await native.createIndex(spec.key, spec.options);
+    }
+    acc.dropped.push(existingName);
+    acc.created.push(resolveSpecName(spec));
+    return;
+  }
+  acc.stale.push({
+    name: existingName,
+    key: spec.key,
+    existing: existingOpts,
+    desired: spec.options
+  });
+}
+async function processOrphanedIndexes(existingIndexes, desiredKeys, matchedKeys, native, dryRun, dropOrphaned, dropped) {
+  for (const idx of existingIndexes) {
+    const rawName = idx["name"];
+    const name = typeof rawName === "string" ? rawName : "";
+    if (name === "_id_") continue;
+    const serialized = serializeIndexKey(idx["key"]);
+    if (matchedKeys.has(serialized) || desiredKeys.has(serialized)) continue;
+    if (dropOrphaned) {
+      if (!dryRun) await native.dropIndex(name);
+      dropped.push(name);
+    }
+  }
+}
+async function listIndexesSafe(native) {
+  try {
+    return await native.listIndexes().toArray();
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("ns does not exist")) {
+      return [];
+    }
+    throw err;
+  }
+}
+async function syncIndexes(handle, options) {
+  const { dryRun = false, dropOrphaned = false } = options ?? {};
+  const native = handle.native;
+  const def = handle.definition;
+  const desiredSpecs = [
+    ...def.fieldIndexes.map(toFieldIndexSpec),
+    ...def.compoundIndexes.map(toCompoundIndexSpec)
+  ];
+  const existingIndexes = await listIndexesSafe(native);
+  const existingByKey = /* @__PURE__ */ new Map();
+  for (const idx of existingIndexes) {
+    const serialized = serializeIndexKey(idx["key"]);
+    existingByKey.set(serialized, idx);
+  }
+  const acc = {
+    created: [],
+    dropped: [],
+    skipped: [],
+    stale: [],
+    matchedKeys: /* @__PURE__ */ new Set()
+  };
+  for (const spec of desiredSpecs) {
+    await processDesiredSpec(spec, existingByKey, native, dryRun, dropOrphaned, acc);
+  }
+  const desiredKeys = new Set(desiredSpecs.map((s) => serializeIndexKey(s.key)));
+  await processOrphanedIndexes(
+    existingIndexes,
+    desiredKeys,
+    acc.matchedKeys,
+    native,
+    dryRun,
+    dropOrphaned,
+    acc.dropped
+  );
+  return {
+    created: acc.created,
+    dropped: acc.dropped,
+    skipped: acc.skipped,
+    stale: acc.stale
+  };
+}
+
 // src/crud/delete.ts
 var import_zod = require("zod");
 
@@ -132,6 +301,29 @@ var ZodmonNotFoundError = class extends Error {
   }
 };
 
+// src/indexes/warn.ts
+var SKIP_OPERATORS = /* @__PURE__ */ new Set(["$or", "$and", "$nor", "$text", "$where", "$expr", "$comment"]);
+function checkUnindexedFields(definition, filter) {
+  if (definition.options.warnUnindexedQueries !== true) return;
+  const covered = /* @__PURE__ */ new Set();
+  for (const fi of definition.fieldIndexes) {
+    covered.add(fi.field);
+  }
+  for (const ci of definition.compoundIndexes) {
+    const firstField = Object.keys(ci.fields)[0];
+    if (firstField !== void 0) {
+      covered.add(firstField);
+    }
+  }
+  for (const key of Object.keys(filter)) {
+    if (key === "_id") continue;
+    if (SKIP_OPERATORS.has(key)) continue;
+    if (!covered.has(key)) {
+      console.warn(`[zodmon] warn: query on '${definition.name}' uses unindexed field '${key}'`);
+    }
+  }
+}
+
 // src/query/cursor.ts
 var import_zod2 = require("zod");
 
@@ -149,8 +341,8 @@ function deserializeValue(value) {
   }
   return value;
 }
-function encodeCursor(doc, sortKeys, direction) {
-  const values = sortKeys.map(([field]) => serializeValue(doc[field]));
+function encodeCursor(doc, sortKeys2, direction) {
+  const values = sortKeys2.map(([field]) => serializeValue(doc[field]));
   return btoa(JSON.stringify([direction, ...values]));
 }
 function decodeCursor(cursor) {
@@ -169,14 +361,14 @@ function decodeCursor(cursor) {
   }
   return { direction, values: rawValues.map(deserializeValue) };
 }
-function buildCursorFilter(sortKeys, values, isBackward) {
+function buildCursorFilter(sortKeys2, values, isBackward) {
   const clauses = [];
-  for (let i = 0; i < sortKeys.length; i++) {
+  for (let i = 0; i < sortKeys2.length; i++) {
     const clause = {};
     for (let j = 0; j < i; j++) {
-      clause[sortKeys[j][0]] = values[j];
+      clause[sortKeys2[j][0]] = values[j];
     }
-    const [field, direction] = sortKeys[i];
+    const [field, direction] = sortKeys2[i];
     const isAsc = direction === 1;
     const op = isAsc !== isBackward ? "$gt" : "$lt";
     if (values[i] === null) {
@@ -272,14 +464,37 @@ var TypedFindCursor = class {
     this.cursor.limit(n);
     return this;
   }
+  /**
+   * Force the query optimizer to use the specified index.
+   *
+   * Only accepts index names that were declared via `.name()` in the
+   * collection definition. If no named indexes exist, any string is accepted.
+   *
+   * @param indexName - The name of a declared compound index.
+   * @returns `this` for chaining.
+   *
+   * @example
+   * ```ts
+   * const Users = collection('users', { email: z.string(), role: z.string() }, {
+   *   indexes: [index({ email: 1, role: -1 }).name('email_role_idx')],
+   * })
+   * const admins = await users.find({ role: 'admin' })
+   *   .hint('email_role_idx')
+   *   .toArray()
+   * ```
+   */
+  hint(indexName) {
+    this.cursor.hint(indexName);
+    return this;
+  }
   async paginate(opts) {
     const sortRecord = this.sortSpec ? this.sortSpec : null;
-    const sortKeys = resolveSortKeys(sortRecord);
-    const sort = Object.fromEntries(sortKeys);
+    const sortKeys2 = resolveSortKeys(sortRecord);
+    const sort = Object.fromEntries(sortKeys2);
     if ("page" in opts) {
-      return await this.offsetPaginate(sortKeys, sort, opts);
+      return await this.offsetPaginate(sortKeys2, sort, opts);
     }
-    return await this.cursorPaginate(sortKeys, sort, opts);
+    return await this.cursorPaginate(sortKeys2, sort, opts);
   }
   /** @internal Offset pagination implementation. */
   async offsetPaginate(_sortKeys, sort, opts) {
@@ -300,16 +515,16 @@ var TypedFindCursor = class {
     };
   }
   /** @internal Cursor pagination implementation. */
-  async cursorPaginate(sortKeys, sort, opts) {
+  async cursorPaginate(sortKeys2, sort, opts) {
     let isBackward = false;
     let combinedFilter = this.filter;
     if (opts.cursor) {
       const decoded = decodeCursor(opts.cursor);
       isBackward = decoded.direction === "b";
-      const cursorFilter = buildCursorFilter(sortKeys, decoded.values, isBackward);
+      const cursorFilter = buildCursorFilter(sortKeys2, decoded.values, isBackward);
       combinedFilter = this.filter && Object.keys(this.filter).length > 0 ? { $and: [this.filter, cursorFilter] } : cursorFilter;
     }
-    const effectiveSort = isBackward ? Object.fromEntries(sortKeys.map(([f, d]) => [f, d === 1 ? -1 : 1])) : sort;
+    const effectiveSort = isBackward ? Object.fromEntries(sortKeys2.map(([f, d]) => [f, d === 1 ? -1 : 1])) : sort;
     const raw2 = await this.nativeCollection.find(combinedFilter).sort(effectiveSort).limit(opts.limit + 1).toArray();
     const hasMore = raw2.length > opts.limit;
     if (hasMore) raw2.pop();
@@ -319,8 +534,8 @@ var TypedFindCursor = class {
       docs,
       hasNext: isBackward ? true : hasMore,
       hasPrev: isBackward ? hasMore : opts.cursor != null,
-      startCursor: docs.length > 0 ? encodeCursor(docs[0], sortKeys, "b") : null,
-      endCursor: docs.length > 0 ? encodeCursor(docs[docs.length - 1], sortKeys, "f") : null
+      startCursor: docs.length > 0 ? encodeCursor(docs[0], sortKeys2, "b") : null,
+      endCursor: docs.length > 0 ? encodeCursor(docs[docs.length - 1], sortKeys2, "f") : null
     };
   }
   /**
@@ -380,6 +595,7 @@ var TypedFindCursor = class {
 
 // src/crud/find.ts
 async function findOne(handle, filter, options) {
+  checkUnindexedFields(handle.definition, filter);
   const findOptions = options?.project ? { projection: options.project } : void 0;
   const raw2 = await handle.native.findOne(filter, findOptions);
   if (!raw2) return null;
@@ -404,6 +620,7 @@ async function findOneOrThrow(handle, filter, options) {
   return doc;
 }
 function find(handle, filter, options) {
+  checkUnindexedFields(handle.definition, filter);
   const raw2 = handle.native.find(filter);
   const cursor = raw2;
   const mode = options?.validate !== void 0 ? options.validate : handle.definition.options.validation;
@@ -735,6 +952,36 @@ var CollectionHandle = class {
   async findOneAndDelete(filter, options) {
     return await findOneAndDelete(this, filter, options);
   }
+  /**
+   * Synchronize the indexes declared in this collection's schema with MongoDB.
+   *
+   * Compares the desired indexes (from field-level `.index()` / `.unique()` /
+   * `.text()` / `.expireAfter()` and compound `indexes` in collection options)
+   * with the indexes that currently exist in MongoDB, then creates, drops, or
+   * reports differences depending on the options.
+   *
+   * @param options - Optional sync behavior (dryRun, dropOrphaned).
+   * @returns A summary of created, dropped, skipped, and stale indexes.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const result = await users.syncIndexes()
+   * console.log('Created:', result.created)
+   * console.log('Stale:', result.stale.map(s => s.name))
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Dry run to preview changes without modifying the database
+   * const diff = await users.syncIndexes({ dryRun: true })
+   * console.log('Would create:', diff.created)
+   * console.log('Would drop:', diff.dropped)
+   * ```
+   */
+  async syncIndexes(options) {
+    return await syncIndexes(this, options);
+  }
 };
 
 // src/client/client.ts
@@ -760,19 +1007,42 @@ var Database = class {
    */
   use(def) {
     this._collections.set(def.name, def);
-    const native = this._db.collection(def.name);
+    const native = this._db.collection(
+      def.name
+    );
     return new CollectionHandle(
       def,
       native
     );
   }
   /**
-   * Synchronize indexes defined in registered collections with MongoDB.
+   * Synchronize indexes for all registered collections with MongoDB.
+   *
+   * Iterates every collection registered via {@link use} and calls
+   * {@link syncIndexes} on each one. Returns a record keyed by collection
+   * name with the sync result for each.
+   *
+   * @param options - Optional sync behavior (dryRun, dropOrphaned).
+   * @returns A record mapping collection names to their sync results.
    *
-   * Stub — full implementation in TASK-92.
+   * @example
+   * ```ts
+   * const db = createClient('mongodb://localhost:27017', 'myapp')
+   * db.use(Users)
+   * db.use(Posts)
+   * const results = await db.syncIndexes()
+   * console.log(results['users'].created) // ['email_1']
+   * console.log(results['posts'].created) // ['title_1']
+   * ```
    */
-  syncIndexes() {
-    return Promise.resolve();
+  async syncIndexes(options) {
+    const results = {};
+    for (const [name, def] of this._collections) {
+      const native = this._db.collection(name);
+      const handle = new CollectionHandle(def, native);
+      results[name] = await syncIndexes(handle, options);
+    }
+    return results;
   }
   /**
    * Execute a function within a MongoDB transaction with auto-commit/rollback.
@@ -987,6 +1257,8 @@ function collection(name, shape, options) {
     schema,
     shape,
     fieldIndexes,
+    // Safe cast: compoundIndexes is TIndexes at runtime (or an empty array when
+    // no options provided). The spread into [...TIndexes] preserves the tuple type.
     compoundIndexes: compoundIndexes ?? [],
     options: {
       validation: validation ?? "strict",
@@ -1011,12 +1283,29 @@ var IndexBuilder = class _IndexBuilder {
       options
     });
   }
+  // Safe cast: _clone returns IndexBuilder<TKeys> but `this` may carry an
+  // intersection from .name(). The cast is safe because _clone preserves all fields.
   unique() {
     return this._clone({ ...this.options, unique: true });
   }
+  // Safe cast: same reasoning as unique().
   sparse() {
     return this._clone({ ...this.options, sparse: true });
   }
+  /**
+   * Set a custom name for this index, preserving the literal type.
+   *
+   * The returned builder carries the literal name type via an intersection,
+   * enabling type-safe `.hint()` on cursors that only accepts declared names.
+   *
+   * @param name - The index name.
+   * @returns A new IndexBuilder with the name recorded at the type level.
+   *
+   * @example
+   * ```ts
+   * index({ email: 1, role: -1 }).name('email_role_idx')
+   * ```
+   */
   name(name) {
     return this._clone({ ...this.options, name });
   }
@@ -1098,10 +1387,12 @@ var $ = {
   TypedFindCursor,
   ZodmonNotFoundError,
   ZodmonValidationError,
+  checkUnindexedFields,
   collection,
   createClient,
   deleteMany,
   deleteOne,
+  extractComparableOptions,
   extractDbName,
   extractFieldIndexes,
   find,
@@ -1109,6 +1400,7 @@ var $ = {
   findOneAndDelete,
   findOneAndUpdate,
   findOneOrThrow,
+  generateIndexName,
   getIndexMetadata,
   getRefMetadata,
   index,
@@ -1118,6 +1410,10 @@ var $ = {
   objectId,
   oid,
   raw,
+  serializeIndexKey,
+  syncIndexes,
+  toCompoundIndexSpec,
+  toFieldIndexSpec,
   updateMany,
   updateOne
 });