@zodmon/core 0.6.0 → 0.8.0

package/dist/index.js

@@ -1,19 +1,170 @@
 // src/client/client.ts
 import { MongoClient } from "mongodb";
 
-// src/crud/find.ts
-import { z as z2 } from "zod";
+// 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/errors/not-found.ts
-var ZodmonNotFoundError = class extends Error {
-  name = "ZodmonNotFoundError";
-  /** The MongoDB collection name where the query found no results. */
-  collection;
-  constructor(collection2) {
-    super(`Document not found in "${collection2}"`);
-    this.collection = collection2;
+// 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
+import { z } from "zod";
 
 // src/errors/validation.ts
 var ZodmonValidationError = class extends Error {
@@ -33,8 +184,136 @@ var ZodmonValidationError = class extends Error {
   }
 };
 
+// src/crud/delete.ts
+async function deleteOne(handle, filter) {
+  return await handle.native.deleteOne(filter);
+}
+async function deleteMany(handle, filter) {
+  return await handle.native.deleteMany(filter);
+}
+async function findOneAndDelete(handle, filter, options) {
+  const result = await handle.native.findOneAndDelete(
+    // biome-ignore lint/suspicious/noExplicitAny: TypedFilter intersection type is not directly assignable to MongoDB's Filter
+    filter,
+    { includeResultMetadata: false }
+  );
+  if (!result) return null;
+  const mode = options?.validate !== void 0 ? options.validate : handle.definition.options.validation;
+  if (mode === false || mode === "passthrough") {
+    return result;
+  }
+  try {
+    return handle.definition.schema.parse(result);
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      throw new ZodmonValidationError(handle.definition.name, err);
+    }
+    throw err;
+  }
+}
+
+// src/crud/find.ts
+import { z as z3 } from "zod";
+
+// src/errors/not-found.ts
+var ZodmonNotFoundError = class extends Error {
+  name = "ZodmonNotFoundError";
+  /** The MongoDB collection name where the query found no results. */
+  collection;
+  constructor(collection2) {
+    super(`Document not found in "${collection2}"`);
+    this.collection = collection2;
+  }
+};
+
+// 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
+import { z as z2 } from "zod";
+
+// src/crud/paginate.ts
+import { ObjectId } from "mongodb";
+function serializeValue(value) {
+  if (value instanceof ObjectId) return { $oid: value.toHexString() };
+  if (value instanceof Date) return { $date: value.getTime() };
+  return value;
+}
+function deserializeValue(value) {
+  if (value != null && typeof value === "object") {
+    if ("$oid" in value) return new ObjectId(value.$oid);
+    if ("$date" in value) return new Date(value.$date);
+  }
+  return value;
+}
+function encodeCursor(doc, sortKeys2, direction) {
+  const values = sortKeys2.map(([field]) => serializeValue(doc[field]));
+  return btoa(JSON.stringify([direction, ...values]));
+}
+function decodeCursor(cursor) {
+  let parsed;
+  try {
+    parsed = JSON.parse(atob(cursor));
+  } catch {
+    throw new Error("Invalid cursor: malformed encoding");
+  }
+  if (!Array.isArray(parsed) || parsed.length < 1) {
+    throw new Error("Invalid cursor: expected non-empty array");
+  }
+  const [direction, ...rawValues] = parsed;
+  if (direction !== "f" && direction !== "b") {
+    throw new Error("Invalid cursor: unknown direction flag");
+  }
+  return { direction, values: rawValues.map(deserializeValue) };
+}
+function buildCursorFilter(sortKeys2, values, isBackward) {
+  const clauses = [];
+  for (let i = 0; i < sortKeys2.length; i++) {
+    const clause = {};
+    for (let j = 0; j < i; j++) {
+      clause[sortKeys2[j][0]] = values[j];
+    }
+    const [field, direction] = sortKeys2[i];
+    const isAsc = direction === 1;
+    const op = isAsc !== isBackward ? "$gt" : "$lt";
+    if (values[i] === null) {
+      clause[field] = { $ne: null };
+    } else {
+      clause[field] = { [op]: values[i] };
+    }
+    clauses.push(clause);
+  }
+  return { $or: clauses };
+}
+function resolveSortKeys(sortSpec) {
+  const entries = sortSpec ? Object.entries(sortSpec) : [];
+  if (!entries.some(([field]) => field === "_id")) {
+    entries.push(["_id", 1]);
+  }
+  return entries;
+}
+
 // src/query/cursor.ts
-import { z } from "zod";
 var TypedFindCursor = class {
   /** @internal */
   cursor;
@@ -45,11 +324,21 @@ var TypedFindCursor = class {
   /** @internal */
   mode;
   /** @internal */
-  constructor(cursor, definition, mode) {
+  nativeCollection;
+  /** @internal */
+  // biome-ignore lint/suspicious/noExplicitAny: TypedFilter is not assignable to MongoDB's Filter; stored opaquely for paginate
+  filter;
+  /** @internal */
+  sortSpec;
+  /** @internal */
+  constructor(cursor, definition, mode, nativeCollection, filter) {
     this.cursor = cursor;
     this.schema = definition.schema;
     this.collectionName = definition.name;
     this.mode = mode;
+    this.nativeCollection = nativeCollection;
+    this.filter = filter;
+    this.sortSpec = null;
   }
   /**
    * Set the sort order for the query.
@@ -66,6 +355,7 @@ var TypedFindCursor = class {
    * ```
    */
   sort(spec) {
+    this.sortSpec = spec;
     this.cursor.sort(spec);
     return this;
   }
@@ -99,6 +389,80 @@ 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 sortKeys2 = resolveSortKeys(sortRecord);
+    const sort = Object.fromEntries(sortKeys2);
+    if ("page" in opts) {
+      return await this.offsetPaginate(sortKeys2, sort, opts);
+    }
+    return await this.cursorPaginate(sortKeys2, sort, opts);
+  }
+  /** @internal Offset pagination implementation. */
+  async offsetPaginate(_sortKeys, sort, opts) {
+    const [total, raw2] = await Promise.all([
+      this.nativeCollection.countDocuments(this.filter),
+      this.nativeCollection.find(this.filter).sort(sort).skip((opts.page - 1) * opts.perPage).limit(opts.perPage).toArray()
+    ]);
+    const docs = raw2.map((doc) => this.validateDoc(doc));
+    const totalPages = Math.ceil(total / opts.perPage);
+    return {
+      docs,
+      total,
+      page: opts.page,
+      perPage: opts.perPage,
+      totalPages,
+      hasNext: opts.page < totalPages,
+      hasPrev: opts.page > 1
+    };
+  }
+  /** @internal Cursor pagination implementation. */
+  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(sortKeys2, decoded.values, isBackward);
+      combinedFilter = this.filter && Object.keys(this.filter).length > 0 ? { $and: [this.filter, cursorFilter] } : cursorFilter;
+    }
+    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();
+    if (isBackward) raw2.reverse();
+    const docs = raw2.map((doc) => this.validateDoc(doc));
+    return {
+      docs,
+      hasNext: isBackward ? true : hasMore,
+      hasPrev: isBackward ? hasMore : opts.cursor != null,
+      startCursor: docs.length > 0 ? encodeCursor(docs[0], sortKeys2, "b") : null,
+      endCursor: docs.length > 0 ? encodeCursor(docs[docs.length - 1], sortKeys2, "f") : null
+    };
+  }
   /**
    * Execute the query and return all matching documents as an array.
    *
@@ -146,7 +510,7 @@ var TypedFindCursor = class {
     try {
       return this.schema.parse(raw2);
     } catch (err) {
-      if (err instanceof z.ZodError) {
+      if (err instanceof z2.ZodError) {
         throw new ZodmonValidationError(this.collectionName, err);
       }
       throw err;
@@ -156,6 +520,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;
@@ -166,7 +531,7 @@ async function findOne(handle, filter, options) {
   try {
     return handle.definition.schema.parse(raw2);
   } catch (err) {
-    if (err instanceof z2.ZodError) {
+    if (err instanceof z3.ZodError) {
       throw new ZodmonValidationError(handle.definition.name, err);
     }
     throw err;
@@ -180,20 +545,21 @@ 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;
-  return new TypedFindCursor(cursor, handle.definition, mode);
+  return new TypedFindCursor(cursor, handle.definition, mode, handle.native, filter);
 }
 
 // src/crud/insert.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 async function insertOne(handle, doc) {
   let parsed;
   try {
     parsed = handle.definition.schema.parse(doc);
   } catch (err) {
-    if (err instanceof z3.ZodError) {
+    if (err instanceof z4.ZodError) {
       throw new ZodmonValidationError(handle.definition.name, err);
     }
     throw err;
@@ -208,7 +574,7 @@ async function insertMany(handle, docs) {
     try {
       parsed.push(handle.definition.schema.parse(doc));
     } catch (err) {
-      if (err instanceof z3.ZodError) {
+      if (err instanceof z4.ZodError) {
         throw new ZodmonValidationError(handle.definition.name, err);
       }
       throw err;
@@ -218,6 +584,45 @@ async function insertMany(handle, docs) {
   return parsed;
 }
 
+// src/crud/update.ts
+import { z as z5 } from "zod";
+async function updateOne(handle, filter, update, options) {
+  return await handle.native.updateOne(filter, update, options);
+}
+async function updateMany(handle, filter, update, options) {
+  return await handle.native.updateMany(filter, update, options);
+}
+async function findOneAndUpdate(handle, filter, update, options) {
+  const driverOptions = {
+    returnDocument: options?.returnDocument ?? "after",
+    includeResultMetadata: false
+  };
+  if (options?.upsert !== void 0) {
+    driverOptions["upsert"] = options.upsert;
+  }
+  const result = await handle.native.findOneAndUpdate(
+    // biome-ignore lint/suspicious/noExplicitAny: TypedFilter intersection type is not directly assignable to MongoDB's Filter
+    filter,
+    // biome-ignore lint/suspicious/noExplicitAny: TypedUpdateFilter intersection type is not directly assignable to MongoDB's UpdateFilter
+    update,
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic options object is not assignable to driver's FindOneAndUpdateOptions under exactOptionalPropertyTypes
+    driverOptions
+  );
+  if (!result) return null;
+  const mode = options?.validate !== void 0 ? options.validate : handle.definition.options.validation;
+  if (mode === false || mode === "passthrough") {
+    return result;
+  }
+  try {
+    return handle.definition.schema.parse(result);
+  } catch (err) {
+    if (err instanceof z5.ZodError) {
+      throw new ZodmonValidationError(handle.definition.name, err);
+    }
+    throw err;
+  }
+}
+
 // src/client/handle.ts
 var CollectionHandle = class {
   /** The collection definition containing schema, name, and index metadata. */
@@ -339,6 +744,169 @@ var CollectionHandle = class {
   find(filter, options) {
     return find(this, filter, options);
   }
+  /**
+   * Update a single document matching the filter.
+   *
+   * Applies the update operators to the first document that matches the filter.
+   * Does not validate the update against the Zod schema — validation happens
+   * at the field-operator level through {@link TypedUpdateFilter}.
+   *
+   * @param filter - Type-safe filter to match documents.
+   * @param update - Type-safe update operators to apply.
+   * @param options - Optional settings such as `upsert`.
+   * @returns The MongoDB `UpdateResult` with match/modify counts.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const result = await users.updateOne({ name: 'Ada' }, { $set: { role: 'admin' } })
+   * console.log(result.modifiedCount) // 1
+   * ```
+   */
+  async updateOne(filter, update, options) {
+    return await updateOne(this, filter, update, options);
+  }
+  /**
+   * Update all documents matching the filter.
+   *
+   * Applies the update operators to every document that matches the filter.
+   * Does not validate the update against the Zod schema — validation happens
+   * at the field-operator level through {@link TypedUpdateFilter}.
+   *
+   * @param filter - Type-safe filter to match documents.
+   * @param update - Type-safe update operators to apply.
+   * @param options - Optional settings such as `upsert`.
+   * @returns The MongoDB `UpdateResult` with match/modify counts.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const result = await users.updateMany({ role: 'guest' }, { $set: { role: 'user' } })
+   * console.log(result.modifiedCount) // number of guests promoted
+   * ```
+   */
+  async updateMany(filter, update, options) {
+    return await updateMany(this, filter, update, options);
+  }
+  /**
+   * Find a single document matching the filter, apply an update, and return the document.
+   *
+   * By default, returns the document **after** the update is applied. Set
+   * `returnDocument: 'before'` to get the pre-update snapshot. The returned
+   * document is validated against the collection's Zod schema using the same
+   * resolution logic as {@link findOne}.
+   *
+   * @param filter - Type-safe filter to match documents.
+   * @param update - Type-safe update operators to apply.
+   * @param options - Optional settings: `returnDocument`, `upsert`, `validate`.
+   * @returns The matched document (before or after update), or `null` if no document matches.
+   * @throws {ZodmonValidationError} When the returned document fails schema validation in strict mode.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const user = await users.findOneAndUpdate(
+   *   { name: 'Ada' },
+   *   { $set: { role: 'admin' } },
+   * )
+   * if (user) console.log(user.role) // 'admin' (returned after update)
+   * ```
+   */
+  async findOneAndUpdate(filter, update, options) {
+    return await findOneAndUpdate(this, filter, update, options);
+  }
+  /**
+   * Delete a single document matching the filter.
+   *
+   * Removes the first document that matches the filter from the collection.
+   * No validation is performed — the document is deleted directly through
+   * the MongoDB driver.
+   *
+   * @param filter - Type-safe filter to match documents.
+   * @returns The MongoDB `DeleteResult` with the deleted count.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const result = await users.deleteOne({ name: 'Ada' })
+   * console.log(result.deletedCount) // 1
+   * ```
+   */
+  async deleteOne(filter) {
+    return await deleteOne(this, filter);
+  }
+  /**
+   * Delete all documents matching the filter.
+   *
+   * Removes every document that matches the filter from the collection.
+   * No validation is performed — documents are deleted directly through
+   * the MongoDB driver.
+   *
+   * @param filter - Type-safe filter to match documents.
+   * @returns The MongoDB `DeleteResult` with the deleted count.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const result = await users.deleteMany({ role: 'guest' })
+   * console.log(result.deletedCount) // number of guests removed
+   * ```
+   */
+  async deleteMany(filter) {
+    return await deleteMany(this, filter);
+  }
+  /**
+   * Find a single document matching the filter, delete it, and return the document.
+   *
+   * Returns the deleted document, or `null` if no document matches the filter.
+   * The returned document is validated against the collection's Zod schema
+   * using the same resolution logic as {@link findOne}.
+   *
+   * @param filter - Type-safe filter to match documents.
+   * @param options - Optional settings: `validate`.
+   * @returns The deleted document, or `null` if no document matches.
+   * @throws {ZodmonValidationError} When the returned document fails schema validation in strict mode.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const user = await users.findOneAndDelete({ name: 'Ada' })
+   * if (user) console.log(user.name) // 'Ada' (the deleted document)
+   * ```
+   */
+  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
@@ -364,19 +932,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.
@@ -416,14 +1007,14 @@ function createClient(uri, dbNameOrOptions, maybeOptions) {
 }
 
 // src/collection/collection.ts
-import { ObjectId as ObjectId2 } from "mongodb";
-import { z as z7 } from "zod";
+import { ObjectId as ObjectId3 } from "mongodb";
+import { z as z9 } from "zod";
 
 // src/schema/extensions.ts
-import { z as z5 } from "zod";
+import { z as z7 } from "zod";
 
 // src/schema/ref.ts
-import { z as z4 } from "zod";
+import { z as z6 } from "zod";
 var refMetadata = /* @__PURE__ */ new WeakMap();
 function getRefMetadata(schema) {
   if (typeof schema !== "object" || schema === null) return void 0;
@@ -431,7 +1022,7 @@ function getRefMetadata(schema) {
 }
 var REF_GUARD = /* @__PURE__ */ Symbol.for("zodmon_ref");
 function installRefExtension() {
-  const proto = z4.ZodType.prototype;
+  const proto = z6.ZodType.prototype;
   if (REF_GUARD in proto) return;
   Object.defineProperty(proto, "ref", {
     value(collection2) {
@@ -458,7 +1049,7 @@ function getIndexMetadata(schema) {
 }
 var GUARD = /* @__PURE__ */ Symbol.for("zodmon_extensions");
 function installExtensions() {
-  const proto = z5.ZodType.prototype;
+  const proto = z7.ZodType.prototype;
   if (GUARD in proto) return;
   Object.defineProperty(proto, "index", {
     /**
@@ -556,14 +1147,14 @@ function installExtensions() {
 installExtensions();
 
 // src/schema/object-id.ts
-import { ObjectId } from "mongodb";
-import { z as z6 } from "zod";
+import { ObjectId as ObjectId2 } from "mongodb";
+import { z as z8 } from "zod";
 var OBJECT_ID_HEX = /^[a-f\d]{24}$/i;
 function objectId() {
-  return z6.custom((val) => {
-    if (val instanceof ObjectId) return true;
+  return z8.custom((val) => {
+    if (val instanceof ObjectId2) return true;
     return typeof val === "string" && OBJECT_ID_HEX.test(val);
-  }, "Invalid ObjectId").transform((val) => val instanceof ObjectId ? val : ObjectId.createFromHexString(val));
+  }, "Invalid ObjectId").transform((val) => val instanceof ObjectId2 ? val : ObjectId2.createFromHexString(val));
 }
 
 // src/collection/collection.ts
@@ -578,8 +1169,8 @@ function extractFieldIndexes(shape) {
   return result;
 }
 function collection(name, shape, options) {
-  const resolvedShape = "_id" in shape ? shape : { _id: objectId().default(() => new ObjectId2()), ...shape };
-  const schema = z7.object(resolvedShape);
+  const resolvedShape = "_id" in shape ? shape : { _id: objectId().default(() => new ObjectId3()), ...shape };
+  const schema = z9.object(resolvedShape);
   const fieldIndexes = extractFieldIndexes(shape);
   const { indexes: compoundIndexes, validation, ...rest } = options ?? {};
   return {
@@ -591,6 +1182,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",
@@ -615,12 +1208,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 });
   }
@@ -630,14 +1240,14 @@ function index(fields) {
 }
 
 // src/helpers/oid.ts
-import { ObjectId as ObjectId3 } from "mongodb";
+import { ObjectId as ObjectId4 } from "mongodb";
 function oid(value) {
-  if (value === void 0) return new ObjectId3();
-  if (value instanceof ObjectId3) return value;
-  return ObjectId3.createFromHexString(value);
+  if (value === void 0) return new ObjectId4();
+  if (value instanceof ObjectId4) return value;
+  return ObjectId4.createFromHexString(value);
 }
 function isOid(value) {
-  return value instanceof ObjectId3;
+  return value instanceof ObjectId4;
 }
 
 // src/query/operators.ts
@@ -660,7 +1270,27 @@ var $or = (...filters) => ({ $or: filters });
 var $and = (...filters) => ({ $and: filters });
 var $nor = (...filters) => ({ $nor: filters });
 var raw = (filter) => filter;
+
+// src/query/namespace.ts
+var $ = {
+  eq: $eq,
+  ne: $ne,
+  gt: $gt,
+  gte: $gte,
+  lt: $lt,
+  lte: $lte,
+  in: $in,
+  nin: $nin,
+  exists: $exists,
+  regex: $regex,
+  not: $not,
+  or: $or,
+  and: $and,
+  nor: $nor,
+  raw
+};
 export {
+  $,
   $and,
   $eq,
   $exists,
@@ -681,23 +1311,34 @@ export {
   TypedFindCursor,
   ZodmonNotFoundError,
   ZodmonValidationError,
+  checkUnindexedFields,
   collection,
   createClient,
+  deleteMany,
+  deleteOne,
+  extractComparableOptions,
   extractDbName,
   extractFieldIndexes,
   find,
   findOne,
+  findOneAndDelete,
+  findOneAndUpdate,
   findOneOrThrow,
+  generateIndexName,
   getIndexMetadata,
   getRefMetadata,
   index,
   insertMany,
   insertOne,
-  installExtensions,
-  installRefExtension,
   isOid,
   objectId,
   oid,
-  raw
+  raw,
+  serializeIndexKey,
+  syncIndexes,
+  toCompoundIndexSpec,
+  toFieldIndexSpec,
+  updateMany,
+  updateOne
 };
 //# sourceMappingURL=index.js.map