@zodmon/core 0.7.0 → 0.9.0

package/dist/index.cjs

@@ -21,30 +21,45 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   $: () => $,
+  $addToSet: () => $addToSet,
   $and: () => $and,
+  $avg: () => $avg,
+  $count: () => $count,
   $eq: () => $eq,
   $exists: () => $exists,
+  $first: () => $first,
   $gt: () => $gt,
   $gte: () => $gte,
   $in: () => $in,
+  $last: () => $last,
   $lt: () => $lt,
   $lte: () => $lte,
+  $max: () => $max,
+  $min: () => $min,
   $ne: () => $ne,
   $nin: () => $nin,
   $nor: () => $nor,
   $not: () => $not,
   $or: () => $or,
+  $push: () => $push,
   $regex: () => $regex,
+  $sum: () => $sum,
+  AggregatePipeline: () => AggregatePipeline,
   CollectionHandle: () => CollectionHandle,
   Database: () => Database,
   IndexBuilder: () => IndexBuilder,
   TypedFindCursor: () => TypedFindCursor,
   ZodmonNotFoundError: () => ZodmonNotFoundError,
   ZodmonValidationError: () => ZodmonValidationError,
+  aggregate: () => aggregate,
+  checkUnindexedFields: () => checkUnindexedFields,
   collection: () => collection,
+  createAccumulatorBuilder: () => createAccumulatorBuilder,
   createClient: () => createClient,
+  createExpressionBuilder: () => createExpressionBuilder,
   deleteMany: () => deleteMany,
   deleteOne: () => deleteOne,
+  extractComparableOptions: () => extractComparableOptions,
   extractDbName: () => extractDbName,
   extractFieldIndexes: () => extractFieldIndexes,
   find: () => find,
@@ -52,6 +67,7 @@ __export(index_exports, {
   findOneAndDelete: () => findOneAndDelete,
   findOneAndUpdate: () => findOneAndUpdate,
   findOneOrThrow: () => findOneOrThrow,
+  generateIndexName: () => generateIndexName,
   getIndexMetadata: () => getIndexMetadata,
   getRefMetadata: () => getRefMetadata,
   index: () => index,
@@ -61,16 +77,831 @@ __export(index_exports, {
   objectId: () => objectId,
   oid: () => oid,
   raw: () => raw,
+  serializeIndexKey: () => serializeIndexKey,
+  syncIndexes: () => syncIndexes,
+  toCompoundIndexSpec: () => toCompoundIndexSpec,
+  toFieldIndexSpec: () => toFieldIndexSpec,
   updateMany: () => updateMany,
   updateOne: () => updateOne
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/aggregate/expressions.ts
+var $count = () => ({
+  __accum: true,
+  expr: { $sum: 1 }
+});
+var $sum = (field) => ({
+  __accum: true,
+  expr: { $sum: field }
+});
+var $avg = (field) => ({
+  __accum: true,
+  expr: { $avg: field }
+});
+var $min = (field) => ({
+  __accum: true,
+  expr: { $min: field }
+});
+var $max = (field) => ({
+  __accum: true,
+  expr: { $max: field }
+});
+var $first = (field) => ({
+  __accum: true,
+  expr: { $first: field }
+});
+var $last = (field) => ({
+  __accum: true,
+  expr: { $last: field }
+});
+var $push = (field) => ({
+  __accum: true,
+  expr: { $push: field }
+});
+var $addToSet = (field) => ({
+  __accum: true,
+  expr: { $addToSet: field }
+});
+function createAccumulatorBuilder() {
+  return {
+    count: () => ({ __accum: true, expr: { $sum: 1 } }),
+    sum: (field) => ({
+      __accum: true,
+      expr: { $sum: typeof field === "number" ? field : `$${field}` }
+    }),
+    avg: (field) => ({ __accum: true, expr: { $avg: `$${field}` } }),
+    min: (field) => ({ __accum: true, expr: { $min: `$${field}` } }),
+    max: (field) => ({ __accum: true, expr: { $max: `$${field}` } }),
+    first: (field) => ({ __accum: true, expr: { $first: `$${field}` } }),
+    last: (field) => ({ __accum: true, expr: { $last: `$${field}` } }),
+    push: (field) => ({ __accum: true, expr: { $push: `$${field}` } }),
+    addToSet: (field) => ({ __accum: true, expr: { $addToSet: `$${field}` } })
+    // biome-ignore lint/suspicious/noExplicitAny: Runtime implementation uses string field names and returns plain objects — TypeScript cannot verify that the runtime Accumulator objects match the generic AccumulatorBuilder<T> return types. Safe because type resolution happens at compile time via AccumulatorBuilder<T>, and runtime values are identical to what the standalone $min/$max/etc. produce.
+  };
+}
+function createExpressionBuilder() {
+  const $2 = (field) => `$${field}`;
+  const val = (v) => typeof v === "number" ? v : `$${v}`;
+  const expr = (value) => ({ __expr: true, value });
+  return {
+    // Arithmetic
+    add: (field, value) => expr({ $add: [$2(field), val(value)] }),
+    subtract: (field, value) => expr({ $subtract: [$2(field), val(value)] }),
+    multiply: (field, value) => expr({ $multiply: [$2(field), val(value)] }),
+    divide: (field, value) => expr({ $divide: [$2(field), val(value)] }),
+    mod: (field, value) => expr({ $mod: [$2(field), val(value)] }),
+    abs: (field) => expr({ $abs: $2(field) }),
+    ceil: (field) => expr({ $ceil: $2(field) }),
+    floor: (field) => expr({ $floor: $2(field) }),
+    round: (field, place = 0) => expr({ $round: [$2(field), place] }),
+    // String
+    concat: (...parts) => {
+      const resolved = parts.map((p) => {
+        if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(p)) return $2(p);
+        return p;
+      });
+      return expr({ $concat: resolved });
+    },
+    toLower: (field) => expr({ $toLower: $2(field) }),
+    toUpper: (field) => expr({ $toUpper: $2(field) }),
+    trim: (field) => expr({ $trim: { input: $2(field) } }),
+    substr: (field, start, length) => expr({ $substrBytes: [$2(field), start, length] }),
+    // Comparison
+    eq: (field, value) => expr({ $eq: [$2(field), value] }),
+    gt: (field, value) => expr({ $gt: [$2(field), value] }),
+    gte: (field, value) => expr({ $gte: [$2(field), value] }),
+    lt: (field, value) => expr({ $lt: [$2(field), value] }),
+    lte: (field, value) => expr({ $lte: [$2(field), value] }),
+    ne: (field, value) => expr({ $ne: [$2(field), value] }),
+    // Date
+    year: (field) => expr({ $year: $2(field) }),
+    month: (field) => expr({ $month: $2(field) }),
+    dayOfMonth: (field) => expr({ $dayOfMonth: $2(field) }),
+    // Array
+    size: (field) => expr({ $size: $2(field) }),
+    // Conditional
+    cond: (condition, thenValue, elseValue) => expr({ $cond: [condition.value, thenValue, elseValue] }),
+    ifNull: (field, fallback) => expr({ $ifNull: [$2(field), fallback] })
+    // biome-ignore lint/suspicious/noExplicitAny: Runtime implementation uses string field names — TypeScript cannot verify generic ExpressionBuilder<T> return types match. Safe because type resolution happens at compile time.
+  };
+}
+
+// src/schema/ref.ts
+var import_zod = require("zod");
+var refMetadata = /* @__PURE__ */ new WeakMap();
+function getRefMetadata(schema) {
+  if (typeof schema !== "object" || schema === null) return void 0;
+  return refMetadata.get(schema);
+}
+var REF_GUARD = /* @__PURE__ */ Symbol.for("zodmon_ref");
+function installRefExtension() {
+  const proto = import_zod.z.ZodType.prototype;
+  if (REF_GUARD in proto) return;
+  Object.defineProperty(proto, "ref", {
+    value(collection2) {
+      refMetadata.set(this, { collection: collection2 });
+      return this;
+    },
+    enumerable: true,
+    configurable: true,
+    writable: true
+  });
+  Object.defineProperty(proto, REF_GUARD, {
+    value: true,
+    enumerable: false,
+    configurable: false,
+    writable: false
+  });
+}
+
+// src/aggregate/pipeline.ts
+var AggregatePipeline = class _AggregatePipeline {
+  definition;
+  nativeCollection;
+  stages;
+  constructor(definition, nativeCollection, stages) {
+    this.definition = definition;
+    this.nativeCollection = nativeCollection;
+    this.stages = stages;
+  }
+  /**
+   * Append an arbitrary aggregation stage to the pipeline (escape hatch).
+   *
+   * Returns a new pipeline instance with the stage appended — the
+   * original pipeline is not modified.
+   *
+   * Optionally accepts a type parameter `TNew` to change the output
+   * type when the stage transforms the document shape.
+   *
+   * @typeParam TNew - The output type after this stage. Defaults to the current output type.
+   * @param stage - A raw MongoDB aggregation stage document (e.g. `{ $match: { ... } }`).
+   * @returns A new pipeline with the stage appended.
+   *
+   * @example
+   * ```ts
+   * const admins = aggregate(users)
+   *   .raw({ $match: { role: 'admin' } })
+   *   .toArray()
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Change output type with a $project stage
+   * const names = aggregate(users)
+   *   .raw<{ name: string }>({ $project: { name: 1, _id: 0 } })
+   *   .toArray()
+   * ```
+   */
+  raw(stage) {
+    return new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      stage
+    ]);
+  }
+  /**
+   * Execute the pipeline and return all results as an array.
+   *
+   * @returns A promise resolving to the array of output documents.
+   *
+   * @example
+   * ```ts
+   * const results = await aggregate(users)
+   *   .raw({ $match: { age: { $gte: 18 } } })
+   *   .toArray()
+   * ```
+   */
+  async toArray() {
+    const cursor = this.nativeCollection.aggregate(this.stages);
+    return await cursor.toArray();
+  }
+  /**
+   * Stream pipeline results one document at a time via `for await...of`.
+   *
+   * @returns An async generator yielding output documents.
+   *
+   * @example
+   * ```ts
+   * for await (const user of aggregate(users).raw({ $match: { role: 'admin' } })) {
+   *   console.log(user.name)
+   * }
+   * ```
+   */
+  async *[Symbol.asyncIterator]() {
+    const cursor = this.nativeCollection.aggregate(this.stages);
+    for await (const doc of cursor) {
+      yield doc;
+    }
+  }
+  /**
+   * Return the query execution plan without running the pipeline.
+   *
+   * Useful for debugging and understanding how MongoDB will process
+   * the pipeline stages.
+   *
+   * @returns A promise resolving to the explain output document.
+   *
+   * @example
+   * ```ts
+   * const plan = await aggregate(users)
+   *   .raw({ $match: { role: 'admin' } })
+   *   .explain()
+   * console.log(plan)
+   * ```
+   */
+  async explain() {
+    const cursor = this.nativeCollection.aggregate(this.stages);
+    return await cursor.explain();
+  }
+  // ── Shape-preserving stages ──────────────────────────────────────
+  /**
+   * Filter documents using a type-safe match expression.
+   *
+   * Appends a `$match` stage to the pipeline. The filter is constrained
+   * to the current output type, so only valid fields and operators are accepted.
+   *
+   * Supports two forms of type narrowing:
+   *
+   * **Tier 1 — Explicit type parameter:**
+   * ```ts
+   * .match<{ role: 'engineer' | 'designer' }>({ role: { $in: ['engineer', 'designer'] } })
+   * // role narrows to 'engineer' | 'designer'
+   * ```
+   *
+   * **Tier 2 — Automatic inference from filter literals:**
+   * ```ts
+   * .match({ role: 'engineer' })           // role narrows to 'engineer'
+   * .match({ role: { $ne: 'intern' } })    // role narrows to Exclude<Role, 'intern'>
+   * .match({ role: { $in: ['engineer', 'designer'] as const } })  // needs as const
+   * ```
+   *
+   * When no type parameter is provided and the filter doesn't contain
+   * inferrable literals, the output type is unchanged (backward compatible).
+   *
+   * @typeParam TNarrow - Optional object mapping field names to narrowed types. Must be a subtype of the corresponding fields in TOutput.
+   * @typeParam F - Inferred from the filter argument. Do not provide explicitly.
+   * @param filter - A type-safe filter for the current output type.
+   * @returns A new pipeline with the `$match` stage appended and output type narrowed.
+   *
+   * @example
+   * ```ts
+   * // Explicit narrowing
+   * const filtered = await users.aggregate()
+   *   .match<{ role: 'engineer' }>({ role: 'engineer' })
+   *   .toArray()
+   * // filtered[0].role → 'engineer'
+   *
+   * // Automatic narrowing with $in (requires as const)
+   * const subset = await users.aggregate()
+   *   .match({ role: { $in: ['engineer', 'designer'] as const } })
+   *   .toArray()
+   * // subset[0].role → 'engineer' | 'designer'
+   * ```
+   */
+  match(filter) {
+    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      { $match: filter }
+    ]);
+    return pipeline;
+  }
+  /**
+   * Sort documents by one or more fields.
+   *
+   * Appends a `$sort` stage. Keys are constrained to `keyof TOutput & string`
+   * and values must be `1` (ascending) or `-1` (descending).
+   *
+   * @param spec - A sort specification mapping field names to sort direction.
+   * @returns A new pipeline with the `$sort` stage appended.
+   *
+   * @example
+   * ```ts
+   * const sorted = await aggregate(users)
+   *   .sort({ age: -1, name: 1 })
+   *   .toArray()
+   * ```
+   */
+  sort(spec) {
+    return new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      { $sort: spec }
+    ]);
+  }
+  /**
+   * Skip a number of documents in the pipeline.
+   *
+   * Appends a `$skip` stage. Commonly used with {@link limit} for pagination.
+   *
+   * @param n - The number of documents to skip.
+   * @returns A new pipeline with the `$skip` stage appended.
+   *
+   * @example
+   * ```ts
+   * // Page 2 (10 items per page)
+   * const page2 = await aggregate(users)
+   *   .sort({ name: 1 })
+   *   .skip(10)
+   *   .limit(10)
+   *   .toArray()
+   * ```
+   */
+  skip(n) {
+    return new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      { $skip: n }
+    ]);
+  }
+  /**
+   * Limit the number of documents passing through the pipeline.
+   *
+   * Appends a `$limit` stage. Commonly used with {@link skip} for pagination,
+   * or after {@link sort} to get top/bottom N results.
+   *
+   * @param n - The maximum number of documents to pass through.
+   * @returns A new pipeline with the `$limit` stage appended.
+   *
+   * @example
+   * ```ts
+   * const top5 = await aggregate(users)
+   *   .sort({ score: -1 })
+   *   .limit(5)
+   *   .toArray()
+   * ```
+   */
+  limit(n) {
+    return new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      { $limit: n }
+    ]);
+  }
+  // ── Shape-transforming projection stages ─────────────────────────
+  /**
+   * Include only specified fields in the output.
+   *
+   * Appends a `$project` stage with inclusion (`1`) for each key.
+   * The `_id` field is always included. The output type narrows to
+   * `Pick<TOutput, K | '_id'>`.
+   *
+   * @param spec - An object mapping field names to `1` for inclusion.
+   * @returns A new pipeline with the `$project` stage appended.
+   *
+   * @example
+   * ```ts
+   * const namesOnly = await aggregate(users)
+   *   .project({ name: 1 })
+   *   .toArray()
+   * // [{ _id: ..., name: 'Ada' }, ...]
+   * ```
+   */
+  project(spec) {
+    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      { $project: spec }
+    ]);
+    return pipeline;
+  }
+  /**
+   * Variadic shorthand for {@link project} — pick fields to include.
+   *
+   * Generates a `$project` stage that includes only the listed fields
+   * (plus `_id`). Equivalent to `.project({ field1: 1, field2: 1 })`.
+   *
+   * @param fields - Field names to include in the output.
+   * @returns A new pipeline with the `$project` stage appended.
+   *
+   * @example
+   * ```ts
+   * const namesAndRoles = await aggregate(users)
+   *   .pick('name', 'role')
+   *   .toArray()
+   * ```
+   */
+  pick(...fields) {
+    const spec = Object.fromEntries(fields.map((f) => [f, 1]));
+    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      { $project: spec }
+    ]);
+    return pipeline;
+  }
+  /**
+   * Exclude specified fields from the output.
+   *
+   * Appends a `$project` stage with exclusion (`0`) for each key.
+   * All other fields pass through. The output type becomes `Omit<TOutput, K>`.
+   *
+   * @param fields - Field names to exclude from the output.
+   * @returns A new pipeline with the `$project` stage appended.
+   *
+   * @example
+   * ```ts
+   * const noAge = await aggregate(users)
+   *   .omit('age')
+   *   .toArray()
+   * ```
+   */
+  omit(...fields) {
+    const spec = Object.fromEntries(fields.map((f) => [f, 0]));
+    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      { $project: spec }
+    ]);
+    return pipeline;
+  }
+  groupBy(field, accumulators) {
+    const resolved = typeof accumulators === "function" ? accumulators(createAccumulatorBuilder()) : accumulators;
+    const _id = Array.isArray(field) ? Object.fromEntries(field.map((f) => [f, `$${f}`])) : `$${field}`;
+    const accumExprs = Object.fromEntries(
+      Object.entries(resolved).map(([key, acc]) => [key, acc.expr])
+    );
+    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      { $group: { _id, ...accumExprs } }
+    ]);
+    return pipeline;
+  }
+  // Implementation
+  addFields(fields) {
+    const resolved = typeof fields === "function" ? fields(createExpressionBuilder()) : fields;
+    const stage = Object.fromEntries(
+      Object.entries(resolved).map(([k, v]) => [
+        k,
+        v && typeof v === "object" && "__expr" in v ? v.value : v
+      ])
+    );
+    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      { $addFields: stage }
+    ]);
+    return pipeline;
+  }
+  // ── unwind stage ─────────────────────────────────────────────────
+  /**
+   * Deconstruct an array field, outputting one document per array element.
+   *
+   * Appends an `$unwind` stage. The unwound field's type changes from
+   * `T[]` to `T` in the output type. Documents with empty or missing
+   * arrays are dropped unless `preserveEmpty` is `true`.
+   *
+   * @param field - The name of the array field to unwind.
+   * @param options - Optional settings for the unwind stage.
+   * @param options.preserveEmpty - If `true`, documents with null, missing, or empty arrays are preserved.
+   * @returns A new pipeline with the `$unwind` stage appended.
+   *
+   * @example
+   * ```ts
+   * const flat = await aggregate(orders)
+   *   .unwind('items')
+   *   .toArray()
+   * // Each result has a single `items` value instead of an array
+   * ```
+   */
+  unwind(field, options) {
+    const stage = options?.preserveEmpty ? { $unwind: { path: `$${field}`, preserveNullAndEmptyArrays: true } } : { $unwind: `$${field}` };
+    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      stage
+    ]);
+    return pipeline;
+  }
+  lookup(fieldOrFrom, options) {
+    const stages = [...this.stages];
+    if (typeof fieldOrFrom === "object") {
+      const foreignName = fieldOrFrom.name;
+      const foreignField = options?.on;
+      if (!foreignField) {
+        throw new Error(
+          `[zodmon] lookup: reverse lookup on '${foreignName}' requires an 'on' option specifying which field on the foreign collection references this collection.`
+        );
+      }
+      const asField = options?.as ?? foreignName;
+      stages.push({
+        $lookup: {
+          from: foreignName,
+          localField: "_id",
+          foreignField,
+          as: asField
+        }
+      });
+      if (options?.unwind) {
+        stages.push({ $unwind: { path: `$${asField}`, preserveNullAndEmptyArrays: true } });
+      }
+    } else {
+      const shape = this.definition.shape;
+      const fieldSchema = shape[fieldOrFrom];
+      const ref = getRefMetadata(fieldSchema);
+      if (!ref) {
+        throw new Error(
+          `[zodmon] lookup: field '${fieldOrFrom}' has no .ref() metadata. Use .lookup(CollectionDef, { on: foreignKey }) for reverse lookups, or add .ref(TargetCollection) to the field schema.`
+        );
+      }
+      const targetName = ref.collection.name;
+      const asField = options?.as ?? targetName;
+      stages.push({
+        $lookup: {
+          from: targetName,
+          localField: fieldOrFrom,
+          foreignField: "_id",
+          as: asField
+        }
+      });
+      if (options?.unwind) {
+        stages.push({ $unwind: { path: `$${asField}`, preserveNullAndEmptyArrays: true } });
+      }
+    }
+    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, stages);
+    return pipeline;
+  }
+  // ── Convenience shortcuts ────────────────────────────────────────
+  /**
+   * Count documents per group, sorted by count descending.
+   *
+   * Shorthand for `.groupBy(field, { count: $count() }).sort({ count: -1 })`.
+   *
+   * @param field - The field to group and count by.
+   * @returns A new pipeline producing `{ _id: TOutput[K], count: number }` results.
+   *
+   * @example
+   * ```ts
+   * const roleCounts = await aggregate(users)
+   *   .countBy('role')
+   *   .toArray()
+   * // [{ _id: 'user', count: 3 }, { _id: 'admin', count: 2 }]
+   * ```
+   */
+  countBy(field) {
+    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      { $group: { _id: `$${field}`, count: { $sum: 1 } } },
+      { $sort: { count: -1 } }
+    ]);
+    return pipeline;
+  }
+  /**
+   * Sum a numeric field per group, sorted by total descending.
+   *
+   * Shorthand for `.groupBy(field, { total: $sum('$sumField') }).sort({ total: -1 })`.
+   *
+   * @param field - The field to group by.
+   * @param sumField - The numeric field to sum.
+   * @returns A new pipeline producing `{ _id: TOutput[K], total: number }` results.
+   *
+   * @example
+   * ```ts
+   * const revenueByCategory = await aggregate(orders)
+   *   .sumBy('category', 'amount')
+   *   .toArray()
+   * // [{ _id: 'electronics', total: 5000 }, ...]
+   * ```
+   */
+  sumBy(field, sumField) {
+    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      { $group: { _id: `$${field}`, total: { $sum: `$${sumField}` } } },
+      { $sort: { total: -1 } }
+    ]);
+    return pipeline;
+  }
+  /**
+   * Sort by a single field with a friendly direction name.
+   *
+   * Shorthand for `.sort({ [field]: direction === 'desc' ? -1 : 1 })`.
+   *
+   * @param field - The field to sort by.
+   * @param direction - Sort direction: `'asc'` (default) or `'desc'`.
+   * @returns A new pipeline with the `$sort` stage appended.
+   *
+   * @example
+   * ```ts
+   * const youngest = await aggregate(users)
+   *   .sortBy('age')
+   *   .toArray()
+   * ```
+   */
+  sortBy(field, direction = "asc") {
+    return new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      { $sort: { [field]: direction === "desc" ? -1 : 1 } }
+    ]);
+  }
+  /**
+   * Return the top N documents sorted by a field descending.
+   *
+   * Shorthand for `.sort({ [by]: -1 }).limit(n)`.
+   *
+   * @param n - The number of documents to return.
+   * @param options - An object with a `by` field specifying the sort key.
+   * @returns A new pipeline with `$sort` and `$limit` stages appended.
+   *
+   * @example
+   * ```ts
+   * const top3 = await aggregate(users)
+   *   .top(3, { by: 'score' })
+   *   .toArray()
+   * ```
+   */
+  top(n, options) {
+    return new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      { $sort: { [options.by]: -1 } },
+      { $limit: n }
+    ]);
+  }
+  /**
+   * Return the bottom N documents sorted by a field ascending.
+   *
+   * Shorthand for `.sort({ [by]: 1 }).limit(n)`.
+   *
+   * @param n - The number of documents to return.
+   * @param options - An object with a `by` field specifying the sort key.
+   * @returns A new pipeline with `$sort` and `$limit` stages appended.
+   *
+   * @example
+   * ```ts
+   * const bottom3 = await aggregate(users)
+   *   .bottom(3, { by: 'score' })
+   *   .toArray()
+   * ```
+   */
+  bottom(n, options) {
+    return new _AggregatePipeline(this.definition, this.nativeCollection, [
+      ...this.stages,
+      { $sort: { [options.by]: 1 } },
+      { $limit: n }
+    ]);
+  }
+};
+function aggregate(handle) {
+  return new AggregatePipeline(handle.definition, handle.native, []);
+}
+
 // 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");
+var import_zod2 = require("zod");
 
 // src/errors/validation.ts
 var ZodmonValidationError = class extends Error {
@@ -111,7 +942,7 @@ async function findOneAndDelete(handle, filter, options) {
   try {
     return handle.definition.schema.parse(result);
   } catch (err) {
-    if (err instanceof import_zod.z.ZodError) {
+    if (err instanceof import_zod2.z.ZodError) {
       throw new ZodmonValidationError(handle.definition.name, err);
     }
     throw err;
@@ -119,7 +950,7 @@ async function findOneAndDelete(handle, filter, options) {
 }
 
 // src/crud/find.ts
-var import_zod3 = require("zod");
+var import_zod4 = require("zod");
 
 // src/errors/not-found.ts
 var ZodmonNotFoundError = class extends Error {
@@ -132,8 +963,31 @@ 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");
+var import_zod3 = require("zod");
 
 // src/crud/paginate.ts
 var import_mongodb = require("mongodb");
@@ -149,8 +1003,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 +1023,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 +1126,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 +1177,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 +1196,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
     };
   }
   /**
@@ -370,7 +1247,7 @@ var TypedFindCursor = class {
     try {
       return this.schema.parse(raw2);
     } catch (err) {
-      if (err instanceof import_zod2.z.ZodError) {
+      if (err instanceof import_zod3.z.ZodError) {
         throw new ZodmonValidationError(this.collectionName, err);
       }
       throw err;
@@ -380,6 +1257,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;
@@ -390,7 +1268,7 @@ async function findOne(handle, filter, options) {
   try {
     return handle.definition.schema.parse(raw2);
   } catch (err) {
-    if (err instanceof import_zod3.z.ZodError) {
+    if (err instanceof import_zod4.z.ZodError) {
       throw new ZodmonValidationError(handle.definition.name, err);
     }
     throw err;
@@ -404,6 +1282,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;
@@ -411,13 +1290,13 @@ function find(handle, filter, options) {
 }
 
 // src/crud/insert.ts
-var import_zod4 = require("zod");
+var import_zod5 = require("zod");
 async function insertOne(handle, doc) {
   let parsed;
   try {
     parsed = handle.definition.schema.parse(doc);
   } catch (err) {
-    if (err instanceof import_zod4.z.ZodError) {
+    if (err instanceof import_zod5.z.ZodError) {
       throw new ZodmonValidationError(handle.definition.name, err);
     }
     throw err;
@@ -432,7 +1311,7 @@ async function insertMany(handle, docs) {
     try {
       parsed.push(handle.definition.schema.parse(doc));
     } catch (err) {
-      if (err instanceof import_zod4.z.ZodError) {
+      if (err instanceof import_zod5.z.ZodError) {
         throw new ZodmonValidationError(handle.definition.name, err);
       }
       throw err;
@@ -443,7 +1322,7 @@ async function insertMany(handle, docs) {
 }
 
 // src/crud/update.ts
-var import_zod5 = require("zod");
+var import_zod6 = require("zod");
 async function updateOne(handle, filter, update, options) {
   return await handle.native.updateOne(filter, update, options);
 }
@@ -474,7 +1353,7 @@ async function findOneAndUpdate(handle, filter, update, options) {
   try {
     return handle.definition.schema.parse(result);
   } catch (err) {
-    if (err instanceof import_zod5.z.ZodError) {
+    if (err instanceof import_zod6.z.ZodError) {
       throw new ZodmonValidationError(handle.definition.name, err);
     }
     throw err;
@@ -735,6 +1614,57 @@ 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);
+  }
+  /**
+   * Start a type-safe aggregation pipeline on this collection.
+   *
+   * Returns a fluent pipeline builder that tracks the output document
+   * shape through each stage. The pipeline is lazy — no query executes
+   * until a terminal method (`toArray`, `for await`, `explain`) is called.
+   *
+   * @returns A new pipeline builder starting with this collection's document type.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const result = await users.aggregate()
+   *   .match({ role: 'admin' })
+   *   .groupBy('role', { count: $count() })
+   *   .toArray()
+   * ```
+   */
+  aggregate() {
+    return aggregate(this);
+  }
 };
 
 // src/client/client.ts
@@ -767,12 +1697,33 @@ var Database = class {
     );
   }
   /**
-   * 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.
@@ -817,36 +1768,6 @@ var import_zod9 = require("zod");
 
 // src/schema/extensions.ts
 var import_zod7 = require("zod");
-
-// src/schema/ref.ts
-var import_zod6 = require("zod");
-var refMetadata = /* @__PURE__ */ new WeakMap();
-function getRefMetadata(schema) {
-  if (typeof schema !== "object" || schema === null) return void 0;
-  return refMetadata.get(schema);
-}
-var REF_GUARD = /* @__PURE__ */ Symbol.for("zodmon_ref");
-function installRefExtension() {
-  const proto = import_zod6.z.ZodType.prototype;
-  if (REF_GUARD in proto) return;
-  Object.defineProperty(proto, "ref", {
-    value(collection2) {
-      refMetadata.set(this, { collection: collection2 });
-      return this;
-    },
-    enumerable: true,
-    configurable: true,
-    writable: true
-  });
-  Object.defineProperty(proto, REF_GUARD, {
-    value: true,
-    enumerable: false,
-    configurable: false,
-    writable: false
-  });
-}
-
-// src/schema/extensions.ts
 var indexMetadata = /* @__PURE__ */ new WeakMap();
 function getIndexMetadata(schema) {
   if (typeof schema !== "object" || schema === null) return void 0;
@@ -987,6 +1908,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 +1934,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 });
   }
@@ -1078,30 +2018,45 @@ var $ = {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   $,
+  $addToSet,
   $and,
+  $avg,
+  $count,
   $eq,
   $exists,
+  $first,
   $gt,
   $gte,
   $in,
+  $last,
   $lt,
   $lte,
+  $max,
+  $min,
   $ne,
   $nin,
   $nor,
   $not,
   $or,
+  $push,
   $regex,
+  $sum,
+  AggregatePipeline,
   CollectionHandle,
   Database,
   IndexBuilder,
   TypedFindCursor,
   ZodmonNotFoundError,
   ZodmonValidationError,
+  aggregate,
+  checkUnindexedFields,
   collection,
+  createAccumulatorBuilder,
   createClient,
+  createExpressionBuilder,
   deleteMany,
   deleteOne,
+  extractComparableOptions,
   extractDbName,
   extractFieldIndexes,
   find,
@@ -1109,6 +2064,7 @@ var $ = {
   findOneAndDelete,
   findOneAndUpdate,
   findOneOrThrow,
+  generateIndexName,
   getIndexMetadata,
   getRefMetadata,
   index,
@@ -1118,6 +2074,10 @@ var $ = {
   objectId,
   oid,
   raw,
+  serializeIndexKey,
+  syncIndexes,
+  toCompoundIndexSpec,
+  toFieldIndexSpec,
   updateMany,
   updateOne
 });