@zodmon/core 0.9.0 → 0.11.0

package/dist/index.js

@@ -11,30 +11,24 @@ 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 $min(field) {
+  return { __accum: true, expr: { $min: field } };
+}
+function $max(field) {
+  return { __accum: true, expr: { $max: field } };
+}
+function $first(field) {
+  return { __accum: true, expr: { $first: field } };
+}
+function $last(field) {
+  return { __accum: true, expr: { $last: field } };
+}
+function $push(field) {
+  return { __accum: true, expr: { $push: field } };
+}
+function $addToSet(field) {
+  return { __accum: true, expr: { $addToSet: field } };
+}
 function createAccumulatorBuilder() {
   return {
     count: () => ({ __accum: true, expr: { $sum: 1 } }),
@@ -99,6 +93,245 @@ function createExpressionBuilder() {
   };
 }
 
+// src/errors/wrap.ts
+import { MongoBulkWriteError, MongoNetworkError, MongoServerError } from "mongodb";
+
+// src/errors/base.ts
+var ZodmonError = class extends Error {
+  name = "ZodmonError";
+  /** The MongoDB collection name associated with this error. */
+  collection;
+  /** The underlying error that caused this error, if any. */
+  cause;
+  constructor(message, collection2, options) {
+    super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.collection = collection2;
+    if (options?.cause !== void 0) {
+      this.cause = options.cause;
+    }
+  }
+};
+
+// src/errors/auth.ts
+var ZodmonAuthError = class extends ZodmonError {
+  name = "ZodmonAuthError";
+  /** The MongoDB error code (13 or 18). */
+  code;
+  constructor(collection2, code, cause) {
+    const message = code === 18 ? `Authentication failed for "${collection2}": check connection credentials` : `Not authorized to perform this operation on "${collection2}"`;
+    super(message, collection2, { cause });
+    this.code = code;
+  }
+};
+
+// src/errors/bulk-write.ts
+var ZodmonBulkWriteError = class extends ZodmonError {
+  name = "ZodmonBulkWriteError";
+  /** Number of documents successfully inserted. */
+  insertedCount;
+  /** Number of documents matched by update filters. */
+  matchedCount;
+  /** Number of documents actually modified. */
+  modifiedCount;
+  /** Number of documents deleted. */
+  deletedCount;
+  /** Individual write errors with their operation index, code, and message. */
+  writeErrors;
+  constructor(collection2, cause, totalOps) {
+    const bulkErr = cause;
+    const result = bulkErr["result"] ?? {};
+    const rawErrors = bulkErr["writeErrors"] ?? [];
+    const writeErrors = rawErrors.map((e) => ({
+      index: e["index"] ?? 0,
+      code: e["code"] ?? 0,
+      message: e["errmsg"] ?? e["message"] ?? "unknown error"
+    }));
+    const failedMsg = totalOps !== void 0 ? `${writeErrors.length} of ${totalOps} operations failed` : `${writeErrors.length} operations failed`;
+    super(`Bulk write failed on "${collection2}": ${failedMsg}`, collection2, { cause });
+    this.insertedCount = result["insertedCount"] ?? 0;
+    this.matchedCount = result["matchedCount"] ?? 0;
+    this.modifiedCount = result["modifiedCount"] ?? 0;
+    this.deletedCount = result["deletedCount"] ?? 0;
+    this.writeErrors = writeErrors;
+  }
+};
+
+// src/errors/doc-validation.ts
+var ZodmonDocValidationError = class extends ZodmonError {
+  name = "ZodmonDocValidationError";
+  /** Server-provided validation failure details. */
+  errInfo;
+  constructor(collection2, errInfo, cause) {
+    super(
+      `Server-side document validation failed for "${collection2}": ${cause.message}`,
+      collection2,
+      { cause }
+    );
+    this.errInfo = errInfo;
+  }
+};
+
+// src/errors/duplicate-key.ts
+var INDEX_REGEX = /index:\s+(\S+)/;
+var DUP_KEY_FIELD_REGEX = /dup key:\s*\{\s*(\w+):/;
+var ZodmonDuplicateKeyError = class extends ZodmonError {
+  name = "ZodmonDuplicateKeyError";
+  /** The first field that caused the duplicate key violation. */
+  field;
+  /** The duplicate value, or `undefined` if it could not be extracted. */
+  value;
+  /** The name of the index that was violated. */
+  index;
+  /** The key pattern of the violated index (e.g. `{ email: 1 }`). */
+  keyPattern;
+  /** The key values that caused the violation. */
+  keyValue;
+  constructor(collection2, cause) {
+    const serverErr = cause;
+    const kp = serverErr["keyPattern"];
+    const kv = serverErr["keyValue"];
+    let field;
+    let value;
+    let keyPattern;
+    let keyValue;
+    if (kp && kv) {
+      const firstKey = Object.keys(kp)[0] ?? "unknown";
+      field = firstKey;
+      value = kv[firstKey];
+      keyPattern = kp;
+      keyValue = kv;
+    } else {
+      const fieldMatch = cause.message.match(DUP_KEY_FIELD_REGEX);
+      field = fieldMatch?.[1] ?? "unknown";
+      value = void 0;
+      keyPattern = field !== "unknown" ? { [field]: 1 } : {};
+      keyValue = {};
+    }
+    const indexMatch = cause.message.match(INDEX_REGEX);
+    const index2 = indexMatch?.[1] ?? "unknown";
+    const valueStr = typeof value === "string" ? `"${value}"` : String(value);
+    super(
+      `Duplicate key in "${collection2}": ${field} = ${valueStr} (index: ${index2})`,
+      collection2,
+      { cause }
+    );
+    this.field = field;
+    this.value = value;
+    this.index = index2;
+    this.keyPattern = keyPattern;
+    this.keyValue = keyValue;
+  }
+};
+
+// src/errors/index-error.ts
+var ZodmonIndexError = class extends ZodmonError {
+  name = "ZodmonIndexError";
+  /** The MongoDB error code (67, 85, or 86). */
+  code;
+  constructor(collection2, code, errmsg, cause) {
+    const prefix = code === 67 ? "Cannot create index" : code === 85 ? "Index options conflict" : "Index key specs conflict";
+    super(`${prefix} on "${collection2}": ${errmsg}`, collection2, { cause });
+    this.code = code;
+  }
+};
+
+// src/errors/network.ts
+var ZodmonNetworkError = class extends ZodmonError {
+  name = "ZodmonNetworkError";
+  constructor(collection2, cause) {
+    super(`Network error on "${collection2}": ${cause.message}`, collection2, { cause });
+  }
+};
+
+// src/errors/query.ts
+var ZodmonQueryError = class extends ZodmonError {
+  name = "ZodmonQueryError";
+  /** The MongoDB error code (2, 9, or 292). */
+  code;
+  constructor(collection2, code, errmsg, cause) {
+    const message = code === 292 ? `Query exceeded memory limit on "${collection2}": enable allowDiskUse for large sorts or aggregations` : code === 9 ? `Failed to parse query on "${collection2}": ${errmsg}` : `Bad value in query on "${collection2}": ${errmsg}`;
+    super(message, collection2, { cause });
+    this.code = code;
+  }
+};
+
+// src/errors/timeout.ts
+var ZodmonTimeoutError = class extends ZodmonError {
+  name = "ZodmonTimeoutError";
+  /** The MongoDB error code (50 or 262). */
+  code;
+  constructor(collection2, code, cause) {
+    super(`Operation timed out on "${collection2}": exceeded server time limit`, collection2, {
+      cause
+    });
+    this.code = code;
+  }
+};
+
+// src/errors/write-conflict.ts
+var ZodmonWriteConflictError = class extends ZodmonError {
+  name = "ZodmonWriteConflictError";
+  constructor(collection2, cause) {
+    super(
+      `Write conflict in "${collection2}": another operation modified this document concurrently \u2014 retry the transaction`,
+      collection2,
+      { cause }
+    );
+  }
+};
+
+// src/errors/wrap.ts
+function wrapMongoError(err, collection2) {
+  if (err instanceof ZodmonError) {
+    throw err;
+  }
+  if (err instanceof MongoBulkWriteError) {
+    throw new ZodmonBulkWriteError(collection2, err);
+  }
+  if (err instanceof MongoNetworkError) {
+    throw new ZodmonNetworkError(collection2, err);
+  }
+  if (err instanceof MongoServerError) {
+    switch (err.code) {
+      case 11e3:
+      case 11001:
+        throw new ZodmonDuplicateKeyError(collection2, err);
+      case 112:
+        throw new ZodmonWriteConflictError(collection2, err);
+      case 50:
+      case 262:
+        throw new ZodmonTimeoutError(collection2, err.code, err);
+      case 13:
+      case 18:
+        throw new ZodmonAuthError(collection2, err.code, err);
+      case 67:
+      case 85:
+      case 86:
+        throw new ZodmonIndexError(collection2, err.code, err.message, err);
+      case 2:
+      case 9:
+      case 292:
+        throw new ZodmonQueryError(collection2, err.code, err.message, err);
+      case 121:
+        throw new ZodmonDocValidationError(
+          collection2,
+          err.errInfo,
+          err
+        );
+      default:
+        throw new ZodmonError(`MongoDB error on "${collection2}": ${err.message}`, collection2, {
+          cause: err
+        });
+    }
+  }
+  if (err instanceof Error) {
+    throw new ZodmonError(`Unexpected error on "${collection2}": ${err.message}`, collection2, {
+      cause: err
+    });
+  }
+  throw new ZodmonError(`Unexpected error on "${collection2}": ${String(err)}`, collection2);
+}
+
 // src/schema/ref.ts
 import { z } from "zod";
 var refMetadata = /* @__PURE__ */ new WeakMap();
@@ -184,8 +417,12 @@ var AggregatePipeline = class _AggregatePipeline {
    * ```
    */
   async toArray() {
-    const cursor = this.nativeCollection.aggregate(this.stages);
-    return await cursor.toArray();
+    try {
+      const cursor = this.nativeCollection.aggregate(this.stages);
+      return await cursor.toArray();
+    } catch (err) {
+      wrapMongoError(err, this.definition.name);
+    }
   }
   /**
    * Stream pipeline results one document at a time via `for await...of`.
@@ -200,9 +437,13 @@ var AggregatePipeline = class _AggregatePipeline {
    * ```
    */
   async *[Symbol.asyncIterator]() {
-    const cursor = this.nativeCollection.aggregate(this.stages);
-    for await (const doc of cursor) {
-      yield doc;
+    try {
+      const cursor = this.nativeCollection.aggregate(this.stages);
+      for await (const doc of cursor) {
+        yield doc;
+      }
+    } catch (err) {
+      wrapMongoError(err, this.definition.name);
     }
   }
   /**
@@ -222,8 +463,12 @@ var AggregatePipeline = class _AggregatePipeline {
    * ```
    */
   async explain() {
-    const cursor = this.nativeCollection.aggregate(this.stages);
-    return await cursor.explain();
+    try {
+      const cursor = this.nativeCollection.aggregate(this.stages);
+      return await cursor.explain();
+    } catch (err) {
+      wrapMongoError(err, this.definition.name);
+    }
   }
   // ── Shape-preserving stages ──────────────────────────────────────
   /**
@@ -720,7 +965,7 @@ async function processDesiredSpec(spec, existingByKey, native, dryRun, dropOrpha
   const serialized = serializeIndexKey(spec.key);
   const existing = existingByKey.get(serialized);
   if (!existing) {
-    if (!dryRun) await native.createIndex(spec.key, spec.options);
+    if (!dryRun) await safeCreateIndex(native, spec.key, spec.options);
     acc.created.push(resolveSpecName(spec));
     return;
   }
@@ -733,8 +978,8 @@ async function processDesiredSpec(spec, existingByKey, native, dryRun, dropOrpha
   }
   if (dropOrphaned) {
     if (!dryRun) {
-      await native.dropIndex(existingName);
-      await native.createIndex(spec.key, spec.options);
+      await safeDropIndex(native, existingName);
+      await safeCreateIndex(native, spec.key, spec.options);
     }
     acc.dropped.push(existingName);
     acc.created.push(resolveSpecName(spec));
@@ -747,6 +992,20 @@ async function processDesiredSpec(spec, existingByKey, native, dryRun, dropOrpha
     desired: spec.options
   });
 }
+async function safeCreateIndex(native, key, options) {
+  try {
+    await native.createIndex(key, options);
+  } catch (err) {
+    wrapMongoError(err, native.collectionName);
+  }
+}
+async function safeDropIndex(native, name) {
+  try {
+    await native.dropIndex(name);
+  } catch (err) {
+    wrapMongoError(err, native.collectionName);
+  }
+}
 async function processOrphanedIndexes(existingIndexes, desiredKeys, matchedKeys, native, dryRun, dropOrphaned, dropped) {
   for (const idx of existingIndexes) {
     const rawName = idx["name"];
@@ -755,7 +1014,7 @@ async function processOrphanedIndexes(existingIndexes, desiredKeys, matchedKeys,
     const serialized = serializeIndexKey(idx["key"]);
     if (matchedKeys.has(serialized) || desiredKeys.has(serialized)) continue;
     if (dropOrphaned) {
-      if (!dryRun) await native.dropIndex(name);
+      if (!dryRun) await safeDropIndex(native, name);
       dropped.push(name);
     }
   }
@@ -767,7 +1026,7 @@ async function listIndexesSafe(native) {
     if (err instanceof Error && err.message.includes("ns does not exist")) {
       return [];
     }
-    throw err;
+    wrapMongoError(err, native.collectionName);
   }
 }
 async function syncIndexes(handle, options) {
@@ -816,36 +1075,49 @@ async function syncIndexes(handle, options) {
 import { z as z2 } from "zod";
 
 // src/errors/validation.ts
-var ZodmonValidationError = class extends Error {
+var ZodmonValidationError = class extends ZodmonError {
   name = "ZodmonValidationError";
-  /** The MongoDB collection name where the validation failed. */
-  collection;
   /** The original Zod validation error with detailed issue information. */
   zodError;
-  constructor(collection2, zodError) {
+  /** The document that failed validation. */
+  document;
+  constructor(collection2, zodError, document) {
     const fields = zodError.issues.map((issue) => {
       const path = issue.path.join(".") || "(root)";
       return `${path} (${issue.message})`;
     }).join(", ");
-    super(`Validation failed for "${collection2}": ${fields}`);
-    this.collection = collection2;
+    super(`Validation failed for "${collection2}": ${fields}`, collection2, { cause: zodError });
     this.zodError = zodError;
+    this.document = document;
   }
 };
 
 // src/crud/delete.ts
 async function deleteOne(handle, filter) {
-  return await handle.native.deleteOne(filter);
+  try {
+    return await handle.native.deleteOne(filter);
+  } catch (err) {
+    wrapMongoError(err, handle.definition.name);
+  }
 }
 async function deleteMany(handle, filter) {
-  return await handle.native.deleteMany(filter);
+  try {
+    return await handle.native.deleteMany(filter);
+  } catch (err) {
+    wrapMongoError(err, handle.definition.name);
+  }
 }
 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 }
-  );
+  let result;
+  try {
+    result = await handle.native.findOneAndDelete(
+      // biome-ignore lint/suspicious/noExplicitAny: TypedFilter intersection type is not directly assignable to MongoDB's Filter
+      filter,
+      { includeResultMetadata: false }
+    );
+  } catch (err) {
+    wrapMongoError(err, handle.definition.name);
+  }
   if (!result) return null;
   const mode = options?.validate !== void 0 ? options.validate : handle.definition.options.validation;
   if (mode === false || mode === "passthrough") {
@@ -855,7 +1127,7 @@ async function findOneAndDelete(handle, filter, options) {
     return handle.definition.schema.parse(result);
   } catch (err) {
     if (err instanceof z2.ZodError) {
-      throw new ZodmonValidationError(handle.definition.name, err);
+      throw new ZodmonValidationError(handle.definition.name, err, result);
     }
     throw err;
   }
@@ -865,13 +1137,13 @@ async function findOneAndDelete(handle, filter, options) {
 import { z as z4 } from "zod";
 
 // src/errors/not-found.ts
-var ZodmonNotFoundError = class extends Error {
+var ZodmonNotFoundError = class extends ZodmonError {
   name = "ZodmonNotFoundError";
-  /** The MongoDB collection name where the query found no results. */
-  collection;
-  constructor(collection2) {
-    super(`Document not found in "${collection2}"`);
-    this.collection = collection2;
+  /** The filter that produced no results. */
+  filter;
+  constructor(collection2, filter) {
+    super(`Document not found in "${collection2}"`, collection2);
+    this.filter = filter;
   }
 };
 
@@ -962,6 +1234,54 @@ function resolveSortKeys(sortSpec) {
   return entries;
 }
 
+// src/query/projection.ts
+function isIncludeValue(value) {
+  return value === 1 || value === true;
+}
+function isExcludeValue(value) {
+  return value === 0 || value === false;
+}
+function isInclusionProjection(projection) {
+  for (const key of Object.keys(projection)) {
+    if (key === "_id") continue;
+    const value = projection[key];
+    if (value !== void 0 && isIncludeValue(value)) return true;
+  }
+  return false;
+}
+function buildPickMask(projection, schemaKeys) {
+  const mask = {};
+  const idValue = projection._id;
+  if (!(idValue !== void 0 && isExcludeValue(idValue)) && schemaKeys.has("_id")) {
+    mask._id = true;
+  }
+  for (const key of Object.keys(projection)) {
+    if (key === "_id") continue;
+    const value = projection[key];
+    if (value !== void 0 && isIncludeValue(value) && schemaKeys.has(key)) {
+      mask[key] = true;
+    }
+  }
+  return mask;
+}
+function buildOmitMask(projection, schemaKeys) {
+  const mask = {};
+  for (const key of Object.keys(projection)) {
+    const value = projection[key];
+    if (value !== void 0 && isExcludeValue(value) && schemaKeys.has(key)) {
+      mask[key] = true;
+    }
+  }
+  return mask;
+}
+function deriveProjectedSchema(schema, projection) {
+  const schemaKeys = new Set(Object.keys(schema.shape));
+  if (isInclusionProjection(projection)) {
+    return schema.pick(buildPickMask(projection, schemaKeys));
+  }
+  return schema.omit(buildOmitMask(projection, schemaKeys));
+}
+
 // src/query/cursor.ts
 var TypedFindCursor = class {
   /** @internal */
@@ -980,6 +1300,8 @@ var TypedFindCursor = class {
   /** @internal */
   sortSpec;
   /** @internal */
+  projectedSchema;
+  /** @internal */
   constructor(cursor, definition, mode, nativeCollection, filter) {
     this.cursor = cursor;
     this.schema = definition.schema;
@@ -988,6 +1310,7 @@ var TypedFindCursor = class {
     this.nativeCollection = nativeCollection;
     this.filter = filter;
     this.sortSpec = null;
+    this.projectedSchema = null;
   }
   /**
    * Set the sort order for the query.
@@ -1061,6 +1384,40 @@ var TypedFindCursor = class {
     this.cursor.hint(indexName);
     return this;
   }
+  /**
+   * Apply a projection to narrow the returned fields.
+   *
+   * Inclusion projections (`{ name: 1 }`) return only the specified fields
+   * plus `_id` (unless `_id: 0`). Exclusion projections (`{ email: 0 }`)
+   * return all fields except those excluded.
+   *
+   * The cursor's output type is narrowed at compile time. A derived Zod
+   * schema is built for runtime validation of the projected fields.
+   *
+   * Projects from the original document type, not from a previous projection.
+   * Calling `.project()` twice overrides the previous projection.
+   *
+   * @param spec - Type-safe projection document.
+   * @returns A new cursor with the narrowed output type.
+   *
+   * @example
+   * ```ts
+   * const names = await find(users, {})
+   *   .project({ name: 1 })
+   *   .sort({ name: 1 })
+   *   .toArray()
+   * // names[0].name   ✓
+   * // names[0].email  TS error
+   * ```
+   */
+  project(spec) {
+    this.cursor.project(spec);
+    this.projectedSchema = deriveProjectedSchema(
+      this.schema,
+      spec
+    );
+    return this;
+  }
   async paginate(opts) {
     const sortRecord = this.sortSpec ? this.sortSpec : null;
     const sortKeys2 = resolveSortKeys(sortRecord);
@@ -1072,10 +1429,17 @@ var TypedFindCursor = class {
   }
   /** @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()
-    ]);
+    let total;
+    let raw2;
+    try {
+      ;
+      [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()
+      ]);
+    } catch (err) {
+      wrapMongoError(err, this.collectionName);
+    }
     const docs = raw2.map((doc) => this.validateDoc(doc));
     const totalPages = Math.ceil(total / opts.perPage);
     return {
@@ -1099,7 +1463,12 @@ var TypedFindCursor = class {
       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();
+    let raw2;
+    try {
+      raw2 = await this.nativeCollection.find(combinedFilter).sort(effectiveSort).limit(opts.limit + 1).toArray();
+    } catch (err) {
+      wrapMongoError(err, this.collectionName);
+    }
     const hasMore = raw2.length > opts.limit;
     if (hasMore) raw2.pop();
     if (isBackward) raw2.reverse();
@@ -1127,7 +1496,12 @@ var TypedFindCursor = class {
    * ```
    */
   async toArray() {
-    const raw2 = await this.cursor.toArray();
+    let raw2;
+    try {
+      raw2 = await this.cursor.toArray();
+    } catch (err) {
+      wrapMongoError(err, this.collectionName);
+    }
     return raw2.map((doc) => this.validateDoc(doc));
   }
   /**
@@ -1147,8 +1521,12 @@ var TypedFindCursor = class {
    * ```
    */
   async *[Symbol.asyncIterator]() {
-    for await (const doc of this.cursor) {
-      yield this.validateDoc(doc);
+    try {
+      for await (const doc of this.cursor) {
+        yield this.validateDoc(doc);
+      }
+    } catch (err) {
+      wrapMongoError(err, this.collectionName);
     }
   }
   /** @internal Validate a single raw document against the schema. */
@@ -1156,11 +1534,12 @@ var TypedFindCursor = class {
     if (this.mode === false || this.mode === "passthrough") {
       return raw2;
     }
+    const schema = this.projectedSchema ?? this.schema;
     try {
-      return this.schema.parse(raw2);
+      return schema.parse(raw2);
     } catch (err) {
       if (err instanceof z3.ZodError) {
-        throw new ZodmonValidationError(this.collectionName, err);
+        throw new ZodmonValidationError(this.collectionName, err, raw2);
       }
       throw err;
     }
@@ -1170,18 +1549,28 @@ 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);
+  const project = options && "project" in options ? options.project : void 0;
+  const findOptions = project ? { projection: project } : void 0;
+  let raw2;
+  try {
+    raw2 = await handle.native.findOne(filter, findOptions);
+  } catch (err) {
+    wrapMongoError(err, handle.definition.name);
+  }
   if (!raw2) return null;
   const mode = options?.validate !== void 0 ? options.validate : handle.definition.options.validation;
   if (mode === false || mode === "passthrough") {
     return raw2;
   }
+  const schema = project ? deriveProjectedSchema(
+    handle.definition.schema,
+    project
+  ) : handle.definition.schema;
   try {
-    return handle.definition.schema.parse(raw2);
+    return schema.parse(raw2);
   } catch (err) {
     if (err instanceof z4.ZodError) {
-      throw new ZodmonValidationError(handle.definition.name, err);
+      throw new ZodmonValidationError(handle.definition.name, err, raw2);
     }
     throw err;
   }
@@ -1189,7 +1578,7 @@ async function findOne(handle, filter, options) {
 async function findOneOrThrow(handle, filter, options) {
   const doc = await findOne(handle, filter, options);
   if (!doc) {
-    throw new ZodmonNotFoundError(handle.definition.name);
+    throw new ZodmonNotFoundError(handle.definition.name, filter);
   }
   return doc;
 }
@@ -1198,7 +1587,12 @@ function find(handle, filter, options) {
   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, handle.native, filter);
+  const typedCursor = new TypedFindCursor(cursor, handle.definition, mode, handle.native, filter);
+  const project = options && "project" in options ? options.project : void 0;
+  if (project) {
+    return typedCursor.project(project);
+  }
+  return typedCursor;
 }
 
 // src/crud/insert.ts
@@ -1209,11 +1603,15 @@ async function insertOne(handle, doc) {
     parsed = handle.definition.schema.parse(doc);
   } catch (err) {
     if (err instanceof z5.ZodError) {
-      throw new ZodmonValidationError(handle.definition.name, err);
+      throw new ZodmonValidationError(handle.definition.name, err, doc);
     }
     throw err;
   }
-  await handle.native.insertOne(parsed);
+  try {
+    await handle.native.insertOne(parsed);
+  } catch (err) {
+    wrapMongoError(err, handle.definition.name);
+  }
   return parsed;
 }
 async function insertMany(handle, docs) {
@@ -1224,22 +1622,34 @@ async function insertMany(handle, docs) {
       parsed.push(handle.definition.schema.parse(doc));
     } catch (err) {
       if (err instanceof z5.ZodError) {
-        throw new ZodmonValidationError(handle.definition.name, err);
+        throw new ZodmonValidationError(handle.definition.name, err, doc);
       }
       throw err;
     }
   }
-  await handle.native.insertMany(parsed);
+  try {
+    await handle.native.insertMany(parsed);
+  } catch (err) {
+    wrapMongoError(err, handle.definition.name);
+  }
   return parsed;
 }
 
 // src/crud/update.ts
 import { z as z6 } from "zod";
 async function updateOne(handle, filter, update, options) {
-  return await handle.native.updateOne(filter, update, options);
+  try {
+    return await handle.native.updateOne(filter, update, options);
+  } catch (err) {
+    wrapMongoError(err, handle.definition.name);
+  }
 }
 async function updateMany(handle, filter, update, options) {
-  return await handle.native.updateMany(filter, update, options);
+  try {
+    return await handle.native.updateMany(filter, update, options);
+  } catch (err) {
+    wrapMongoError(err, handle.definition.name);
+  }
 }
 async function findOneAndUpdate(handle, filter, update, options) {
   const driverOptions = {
@@ -1249,14 +1659,19 @@ async function findOneAndUpdate(handle, filter, update, options) {
   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
-  );
+  let result;
+  try {
+    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
+    );
+  } catch (err) {
+    wrapMongoError(err, handle.definition.name);
+  }
   if (!result) return null;
   const mode = options?.validate !== void 0 ? options.validate : handle.definition.options.validation;
   if (mode === false || mode === "passthrough") {
@@ -1266,7 +1681,7 @@ async function findOneAndUpdate(handle, filter, update, options) {
     return handle.definition.schema.parse(result);
   } catch (err) {
     if (err instanceof z6.ZodError) {
-      throw new ZodmonValidationError(handle.definition.name, err);
+      throw new ZodmonValidationError(handle.definition.name, err, result);
     }
     throw err;
   }
@@ -1326,70 +1741,12 @@ var CollectionHandle = class {
   async insertMany(docs) {
     return await insertMany(this, docs);
   }
-  /**
-   * Find a single document matching the filter.
-   *
-   * Queries MongoDB, then validates the fetched document against the collection's
-   * Zod schema. Validation mode is resolved from the per-query option, falling
-   * back to the collection-level default (which defaults to `'strict'`).
-   *
-   * @param filter - Type-safe filter to match documents.
-   * @param options - Optional projection and validation overrides.
-   * @returns The matched document, or `null` if no document matches.
-   * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
-   *
-   * @example
-   * ```ts
-   * const users = db.use(Users)
-   * const user = await users.findOne({ name: 'Ada' })
-   * if (user) console.log(user.role)
-   * ```
-   */
   async findOne(filter, options) {
     return await findOne(this, filter, options);
   }
-  /**
-   * Find a single document matching the filter, or throw if none exists.
-   *
-   * Behaves identically to {@link findOne} but throws {@link ZodmonNotFoundError}
-   * instead of returning `null` when no document matches the filter.
-   *
-   * @param filter - Type-safe filter to match documents.
-   * @param options - Optional projection and validation overrides.
-   * @returns The matched document (never null).
-   * @throws {ZodmonNotFoundError} When no document matches the filter.
-   * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
-   *
-   * @example
-   * ```ts
-   * const users = db.use(Users)
-   * const user = await users.findOneOrThrow({ name: 'Ada' })
-   * console.log(user.role) // guaranteed non-null
-   * ```
-   */
   async findOneOrThrow(filter, options) {
     return await findOneOrThrow(this, filter, options);
   }
-  /**
-   * Find all documents matching the filter, returning a chainable typed cursor.
-   *
-   * The cursor is lazy — no query is executed until a terminal method
-   * (`toArray`, `for await`) is called. Use `sort`, `skip`, and `limit`
-   * to shape the query before executing.
-   *
-   * @param filter - Type-safe filter to match documents.
-   * @param options - Optional validation overrides.
-   * @returns A typed cursor for chaining query modifiers.
-   *
-   * @example
-   * ```ts
-   * const users = db.use(Users)
-   * const admins = await users.find({ role: 'admin' })
-   *   .sort({ name: 1 })
-   *   .limit(10)
-   *   .toArray()
-   * ```
-   */
   find(filter, options) {
     return find(this, filter, options);
   }
@@ -1957,8 +2314,18 @@ export {
   Database,
   IndexBuilder,
   TypedFindCursor,
+  ZodmonAuthError,
+  ZodmonBulkWriteError,
+  ZodmonDocValidationError,
+  ZodmonDuplicateKeyError,
+  ZodmonError,
+  ZodmonIndexError,
+  ZodmonNetworkError,
   ZodmonNotFoundError,
+  ZodmonQueryError,
+  ZodmonTimeoutError,
   ZodmonValidationError,
+  ZodmonWriteConflictError,
   aggregate,
   checkUnindexedFields,
   collection,
@@ -1967,6 +2334,7 @@ export {
   createExpressionBuilder,
   deleteMany,
   deleteOne,
+  deriveProjectedSchema,
   extractComparableOptions,
   extractDbName,
   extractFieldIndexes,
@@ -1981,6 +2349,7 @@ export {
   index,
   insertMany,
   insertOne,
+  isInclusionProjection,
   isOid,
   objectId,
   oid,
@@ -1990,6 +2359,7 @@ export {
   toCompoundIndexSpec,
   toFieldIndexSpec,
   updateMany,
-  updateOne
+  updateOne,
+  wrapMongoError
 };
 //# sourceMappingURL=index.js.map