@zodmon/core 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -2977,11 +2977,222 @@ declare function insertOne<TDef extends AnyCollection>(handle: CollectionHandle<
  */
 declare function insertMany<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, docs: InferInsert<TDef>[]): Promise<InferDocument<TDef>[]>;
 
+/**
+ * Base error class for all Zodmon errors.
+ *
+ * Every error thrown by Zodmon extends this class, making it easy to catch all
+ * Zodmon-related errors in a single `catch` block while still allowing more
+ * specific handling via subclass checks.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.insertOne({ name: 123 })
+ * } catch (err) {
+ *   if (err instanceof ZodmonError) {
+ *     console.log(err.name)       // => 'ZodmonError' (or a subclass name)
+ *     console.log(err.collection) // => 'users'
+ *     console.log(err.cause)      // => original Error, if provided
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonError extends Error {
+    readonly name: string;
+    /** The MongoDB collection name associated with this error. */
+    readonly collection: string;
+    /** The underlying error that caused this error, if any. */
+    readonly cause?: Error;
+    constructor(message: string, collection: string, options?: {
+        cause?: Error;
+    });
+}
+
+/**
+ * Thrown when MongoDB rejects an operation due to authentication or authorization failure.
+ *
+ * Corresponds to MongoDB error codes 13 (Unauthorized) and 18 (AuthenticationFailed).
+ * Inspect `.code` to distinguish between authorization and authentication failures.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.insertOne({ name: 'Alice' })
+ * } catch (err) {
+ *   if (err instanceof ZodmonAuthError) {
+ *     console.log(err.message)    // => 'Not authorized to perform this operation on "users"'
+ *     console.log(err.code)       // => 13 or 18
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonAuthError extends ZodmonError {
+    readonly name = "ZodmonAuthError";
+    /** The MongoDB error code (13 or 18). */
+    readonly code: number;
+    constructor(collection: string, code: number, cause: Error);
+}
+
+/**
+ * Thrown when a bulk write operation partially or fully fails.
+ *
+ * Exposes partial result counts (`.insertedCount`, `.matchedCount`, etc.) alongside
+ * an array of `.writeErrors` describing each individual failure. Use this to determine
+ * which operations succeeded and which failed.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.insertMany([{ name: 'Alice' }, { name: 'Alice' }]) // duplicate
+ * } catch (err) {
+ *   if (err instanceof ZodmonBulkWriteError) {
+ *     console.log(err.insertedCount) // => 1
+ *     console.log(err.writeErrors)   // => [{ index: 1, code: 11000, message: '...' }]
+ *     console.log(err.collection)    // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonBulkWriteError extends ZodmonError {
+    readonly name = "ZodmonBulkWriteError";
+    /** Number of documents successfully inserted. */
+    readonly insertedCount: number;
+    /** Number of documents matched by update filters. */
+    readonly matchedCount: number;
+    /** Number of documents actually modified. */
+    readonly modifiedCount: number;
+    /** Number of documents deleted. */
+    readonly deletedCount: number;
+    /** Individual write errors with their operation index, code, and message. */
+    readonly writeErrors: Array<{
+        index: number;
+        code: number;
+        message: string;
+    }>;
+    constructor(collection: string, cause: Error, totalOps?: number);
+}
+
+/**
+ * Thrown when a document fails server-side JSON Schema validation (MongoDB error code 121).
+ *
+ * This is distinct from {@link ZodmonValidationError}, which validates against Zod schemas
+ * on the client side. This error surfaces when MongoDB's own document validation rejects
+ * a write. Inspect `.errInfo` for the server's detailed validation failure information.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.insertOne({ name: 'Alice', age: -1 })
+ * } catch (err) {
+ *   if (err instanceof ZodmonDocValidationError) {
+ *     console.log(err.message)    // => 'Server-side document validation failed for "users": ...'
+ *     console.log(err.errInfo)    // => { failingDocumentId: ..., details: ... }
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonDocValidationError extends ZodmonError {
+    readonly name = "ZodmonDocValidationError";
+    /** Server-provided validation failure details. */
+    readonly errInfo: unknown;
+    constructor(collection: string, errInfo: unknown, cause: Error);
+}
+
+/**
+ * Thrown when a MongoDB insert or update violates a unique index constraint (E11000).
+ *
+ * Parses the duplicate key information from the MongoDB driver error to expose
+ * structured fields: `.field` (first conflicting key), `.value`, `.index` (index name),
+ * `.keyPattern`, and `.keyValue`. Falls back to regex parsing for older drivers.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.insertOne({ email: 'alice@example.com' })
+ * } catch (err) {
+ *   if (err instanceof ZodmonDuplicateKeyError) {
+ *     console.log(err.field)      // => 'email'
+ *     console.log(err.value)      // => 'alice@example.com'
+ *     console.log(err.index)      // => 'email_1'
+ *     console.log(err.keyPattern) // => { email: 1 }
+ *     console.log(err.keyValue)   // => { email: 'alice@example.com' }
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonDuplicateKeyError extends ZodmonError {
+    readonly name = "ZodmonDuplicateKeyError";
+    /** The first field that caused the duplicate key violation. */
+    readonly field: string;
+    /** The duplicate value, or `undefined` if it could not be extracted. */
+    readonly value: unknown;
+    /** The name of the index that was violated. */
+    readonly index: string;
+    /** The key pattern of the violated index (e.g. `{ email: 1 }`). */
+    readonly keyPattern: Record<string, number>;
+    /** The key values that caused the violation. */
+    readonly keyValue: Record<string, unknown>;
+    constructor(collection: string, cause: Error);
+}
+
+/**
+ * Thrown when a MongoDB index operation fails.
+ *
+ * Corresponds to MongoDB error codes 67 (CannotCreateIndex), 85 (IndexOptionsConflict),
+ * and 86 (IndexKeySpecsConflict). Inspect `.code` to determine the specific failure reason.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await syncIndexes(db, [Users])
+ * } catch (err) {
+ *   if (err instanceof ZodmonIndexError) {
+ *     console.log(err.message)    // => 'Index options conflict on "users": ...'
+ *     console.log(err.code)       // => 67, 85, or 86
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonIndexError extends ZodmonError {
+    readonly name = "ZodmonIndexError";
+    /** The MongoDB error code (67, 85, or 86). */
+    readonly code: number;
+    constructor(collection: string, code: number, errmsg: string, cause: Error);
+}
+
+/**
+ * Thrown when a MongoDB operation fails due to a network error.
+ *
+ * Wraps `MongoNetworkError` from the MongoDB driver with the collection name
+ * and the original error message for easier debugging.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.find({ status: 'active' })
+ * } catch (err) {
+ *   if (err instanceof ZodmonNetworkError) {
+ *     console.log(err.message)    // => 'Network error on "users": connection refused'
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonNetworkError extends ZodmonError {
+    readonly name = "ZodmonNetworkError";
+    constructor(collection: string, cause: Error);
+}
+
 /**
  * Thrown when a query expected to find a document returns no results.
  *
  * Used by {@link findOneOrThrow} when no document matches the provided filter.
- * Callers can inspect `.collection` to identify which collection the query targeted.
+ * Callers can inspect `.collection` to identify which collection the query targeted,
+ * and `.filter` to see the query that produced no results.
  *
  * @example
  * ```ts
@@ -2991,15 +3202,68 @@ declare function insertMany<TDef extends AnyCollection>(handle: CollectionHandle
  *   if (err instanceof ZodmonNotFoundError) {
  *     console.log(err.message)    // => 'Document not found in "users"'
  *     console.log(err.collection) // => 'users'
+ *     console.log(err.filter)     // => { name: 'nonexistent' }
  *   }
  * }
  * ```
  */
-declare class ZodmonNotFoundError extends Error {
+declare class ZodmonNotFoundError extends ZodmonError {
     readonly name = "ZodmonNotFoundError";
-    /** The MongoDB collection name where the query found no results. */
-    readonly collection: string;
-    constructor(collection: string);
+    /** The filter that produced no results. */
+    readonly filter: unknown;
+    constructor(collection: string, filter: unknown);
+}
+
+/**
+ * Thrown when a MongoDB query is malformed or exceeds resource limits.
+ *
+ * Corresponds to MongoDB error codes 2 (BadValue), 9 (FailedToParse), and
+ * 292 (QueryExceededMemoryLimit). Inspect `.code` to determine the specific failure.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.find({ $invalid: true })
+ * } catch (err) {
+ *   if (err instanceof ZodmonQueryError) {
+ *     console.log(err.message)    // => 'Bad value in query on "users": ...'
+ *     console.log(err.code)       // => 2, 9, or 292
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonQueryError extends ZodmonError {
+    readonly name = "ZodmonQueryError";
+    /** The MongoDB error code (2, 9, or 292). */
+    readonly code: number;
+    constructor(collection: string, code: number, errmsg: string, cause: Error);
+}
+
+/**
+ * Thrown when a MongoDB operation exceeds its server time limit.
+ *
+ * Corresponds to MongoDB error codes 50 (MaxTimeMSExpired) and
+ * 262 (ExceededTimeLimit). Inspect `.code` to distinguish between the two.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.find({ status: 'active' })
+ * } catch (err) {
+ *   if (err instanceof ZodmonTimeoutError) {
+ *     console.log(err.message)    // => 'Operation timed out on "users": ...'
+ *     console.log(err.code)       // => 50 or 262
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonTimeoutError extends ZodmonError {
+    readonly name = "ZodmonTimeoutError";
+    /** The MongoDB error code (50 or 262). */
+    readonly code: number;
+    constructor(collection: string, code: number, cause: Error);
 }
 
 /**
@@ -3019,17 +3283,62 @@ declare class ZodmonNotFoundError extends Error {
  *     // => 'Validation failed for "users": name (Expected string, received number)'
  *     console.log(err.collection) // => 'users'
  *     console.log(err.zodError)   // => ZodError with .issues array
+ *     console.log(err.document)   // => the document that failed validation
  *   }
  * }
  * ```
  */
-declare class ZodmonValidationError extends Error {
+declare class ZodmonValidationError extends ZodmonError {
     readonly name = "ZodmonValidationError";
-    /** The MongoDB collection name where the validation failed. */
-    readonly collection: string;
     /** The original Zod validation error with detailed issue information. */
     readonly zodError: z.ZodError;
-    constructor(collection: string, zodError: z.ZodError);
+    /** The document that failed validation. */
+    readonly document: unknown;
+    constructor(collection: string, zodError: z.ZodError, document: unknown);
+}
+
+/**
+ * Maps a caught MongoDB error to the appropriate Zodmon error subclass and throws it.
+ *
+ * This function always throws — it never returns. Use it in `catch` blocks to convert
+ * raw MongoDB driver errors into structured, typed Zodmon errors. If the error is already
+ * a `ZodmonError`, it is rethrown as-is to prevent double-wrapping.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await db.collection('users').insertOne(doc)
+ * } catch (err) {
+ *   wrapMongoError(err, 'users')
+ * }
+ * ```
+ */
+declare function wrapMongoError(err: unknown, collection: string): never;
+
+/**
+ * Thrown when a transaction encounters a write conflict (MongoDB error code 112).
+ *
+ * This occurs when another operation modifies the same document concurrently during
+ * a transaction. The recommended recovery strategy is to retry the transaction.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await db.transaction(async (tx) => {
+ *     const users = tx.use(Users)
+ *     await users.updateOne({ _id: id }, { $inc: { balance: -100 } })
+ *   })
+ * } catch (err) {
+ *   if (err instanceof ZodmonWriteConflictError) {
+ *     console.log(err.message)    // => 'Write conflict in "users": ...'
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonWriteConflictError extends ZodmonError {
+    readonly name = "ZodmonWriteConflictError";
+    constructor(collection: string, cause: Error);
 }
 
 /**
@@ -3609,4 +3918,4 @@ type UpdateFilterOf<TDef extends AnyCollection> = TypedUpdateFilter<InferDocumen
  */
 type SortOf<TDef extends AnyCollection> = TypedSort<InferDocument<TDef>>;
 
-export { $, $addToSet, $and, $avg, $count, $eq, $exists, $first, $gt, $gte, $in, $last, $lt, $lte, $max, $min, $ne, $nin, $nor, $not, $or, $push, $regex, $sum, type Accumulator, type AccumulatorBuilder, type AddToSetEach, type AddToSetFields, AggregatePipeline, type AnyCollection, type ArrayElement, type CollectionDefinition, CollectionHandle, type CollectionName, type CollectionOptions, type ComparisonOperators, type CompoundIndexDefinition, type CurrentDateFields, type CursorPage, type CursorPaginateOptions, Database, type DotPathType, type DotPaths, type Expression, type ExpressionBuilder, type ExtractRefCollection, type FieldIndexDefinition, type FieldRef, type FieldRefType, type FilterOf, type FindOneAndDeleteOptions, type FindOneAndUpdateOptions, type FindOneOptions, type FindOptions, type GroupByCompoundResult, type GroupByResult, type HandleOf, type IncFields, IndexBuilder, type IndexMetadata, type IndexNames, type IndexOptions, type IndexSpec, type InferAccumulator, type InferAccumulators, type InferAddedFields, type InferDocument, type InferExpression, type InferInsert, type NarrowFromFilter, type OffsetPage, type OffsetPaginateOptions, type PopFields, type Prettify, type PullFields, type PushFields, type PushModifiers, type RefFields, type RefMarker, type RefMetadata, type RenameFields, type ResolvedShape, type SetFields, type SortOf, type StaleIndex, type SyncIndexesOptions, type SyncIndexesResult, type TypedFilter, TypedFindCursor, type TypedSort, type TypedUpdateFilter, type UnsetFields, type UnwindResult, type UpdateFilterOf, type UpdateOptions, type ValidationMode, type ZodObjectId, ZodmonNotFoundError, ZodmonValidationError, aggregate, checkUnindexedFields, collection, createAccumulatorBuilder, createClient, createExpressionBuilder, deleteMany, deleteOne, extractComparableOptions, extractDbName, extractFieldIndexes, find, findOne, findOneAndDelete, findOneAndUpdate, findOneOrThrow, generateIndexName, getIndexMetadata, getRefMetadata, index, insertMany, insertOne, isOid, objectId, oid, raw, serializeIndexKey, syncIndexes, toCompoundIndexSpec, toFieldIndexSpec, updateMany, updateOne };
+export { $, $addToSet, $and, $avg, $count, $eq, $exists, $first, $gt, $gte, $in, $last, $lt, $lte, $max, $min, $ne, $nin, $nor, $not, $or, $push, $regex, $sum, type Accumulator, type AccumulatorBuilder, type AddToSetEach, type AddToSetFields, AggregatePipeline, type AnyCollection, type ArrayElement, type CollectionDefinition, CollectionHandle, type CollectionName, type CollectionOptions, type ComparisonOperators, type CompoundIndexDefinition, type CurrentDateFields, type CursorPage, type CursorPaginateOptions, Database, type DotPathType, type DotPaths, type Expression, type ExpressionBuilder, type ExtractRefCollection, type FieldIndexDefinition, type FieldRef, type FieldRefType, type FilterOf, type FindOneAndDeleteOptions, type FindOneAndUpdateOptions, type FindOneOptions, type FindOptions, type GroupByCompoundResult, type GroupByResult, type HandleOf, type IncFields, IndexBuilder, type IndexMetadata, type IndexNames, type IndexOptions, type IndexSpec, type InferAccumulator, type InferAccumulators, type InferAddedFields, type InferDocument, type InferExpression, type InferInsert, type NarrowFromFilter, type OffsetPage, type OffsetPaginateOptions, type PopFields, type Prettify, type PullFields, type PushFields, type PushModifiers, type RefFields, type RefMarker, type RefMetadata, type RenameFields, type ResolvedShape, type SetFields, type SortOf, type StaleIndex, type SyncIndexesOptions, type SyncIndexesResult, type TypedFilter, TypedFindCursor, type TypedSort, type TypedUpdateFilter, type UnsetFields, type UnwindResult, type UpdateFilterOf, type UpdateOptions, type ValidationMode, type ZodObjectId, ZodmonAuthError, ZodmonBulkWriteError, ZodmonDocValidationError, ZodmonDuplicateKeyError, ZodmonError, ZodmonIndexError, ZodmonNetworkError, ZodmonNotFoundError, ZodmonQueryError, ZodmonTimeoutError, ZodmonValidationError, ZodmonWriteConflictError, aggregate, checkUnindexedFields, collection, createAccumulatorBuilder, createClient, createExpressionBuilder, deleteMany, deleteOne, extractComparableOptions, extractDbName, extractFieldIndexes, find, findOne, findOneAndDelete, findOneAndUpdate, findOneOrThrow, generateIndexName, getIndexMetadata, getRefMetadata, index, insertMany, insertOne, isOid, objectId, oid, raw, serializeIndexKey, syncIndexes, toCompoundIndexSpec, toFieldIndexSpec, updateMany, updateOne, wrapMongoError };