@zodmon/core 0.3.0 → 0.5.0

package/dist/index.cjs

@@ -37,13 +37,21 @@ __export(index_exports, {
   CollectionHandle: () => CollectionHandle,
   Database: () => Database,
   IndexBuilder: () => IndexBuilder,
+  TypedFindCursor: () => TypedFindCursor,
+  ZodmonNotFoundError: () => ZodmonNotFoundError,
+  ZodmonValidationError: () => ZodmonValidationError,
   collection: () => collection,
   createClient: () => createClient,
   extractDbName: () => extractDbName,
   extractFieldIndexes: () => extractFieldIndexes,
+  find: () => find,
+  findOne: () => findOne,
+  findOneOrThrow: () => findOneOrThrow,
   getIndexMetadata: () => getIndexMetadata,
   getRefMetadata: () => getRefMetadata,
   index: () => index,
+  insertMany: () => insertMany,
+  insertOne: () => insertOne,
   installExtensions: () => installExtensions,
   installRefExtension: () => installRefExtension,
   isOid: () => isOid,
@@ -56,16 +64,344 @@ module.exports = __toCommonJS(index_exports);
 // src/client/client.ts
 var import_mongodb = require("mongodb");
 
+// src/crud/find.ts
+var import_zod2 = require("zod");
+
+// src/errors/not-found.ts
+var ZodmonNotFoundError = class extends Error {
+  name = "ZodmonNotFoundError";
+  /** The MongoDB collection name where the query found no results. */
+  collection;
+  constructor(collection2) {
+    super(`Document not found in "${collection2}"`);
+    this.collection = collection2;
+  }
+};
+
+// src/errors/validation.ts
+var ZodmonValidationError = class extends Error {
+  name = "ZodmonValidationError";
+  /** The MongoDB collection name where the validation failed. */
+  collection;
+  /** The original Zod validation error with detailed issue information. */
+  zodError;
+  constructor(collection2, zodError) {
+    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;
+    this.zodError = zodError;
+  }
+};
+
+// src/query/cursor.ts
+var import_zod = require("zod");
+var TypedFindCursor = class {
+  /** @internal */
+  cursor;
+  /** @internal */
+  schema;
+  /** @internal */
+  collectionName;
+  /** @internal */
+  mode;
+  /** @internal */
+  constructor(cursor, definition, mode) {
+    this.cursor = cursor;
+    this.schema = definition.schema;
+    this.collectionName = definition.name;
+    this.mode = mode;
+  }
+  /**
+   * Set the sort order for the query.
+   *
+   * Only top-level document fields are accepted as sort keys.
+   * Values must be `1` (ascending) or `-1` (descending).
+   *
+   * @param spec - Sort specification mapping field names to sort direction.
+   * @returns `this` for chaining.
+   *
+   * @example
+   * ```ts
+   * find(users, {}).sort({ name: 1, age: -1 }).toArray()
+   * ```
+   */
+  sort(spec) {
+    this.cursor.sort(spec);
+    return this;
+  }
+  /**
+   * Skip the first `n` documents in the result set.
+   *
+   * @param n - Number of documents to skip.
+   * @returns `this` for chaining.
+   *
+   * @example
+   * ```ts
+   * find(users, {}).skip(10).limit(10).toArray() // page 2
+   * ```
+   */
+  skip(n) {
+    this.cursor.skip(n);
+    return this;
+  }
+  /**
+   * Limit the number of documents returned.
+   *
+   * @param n - Maximum number of documents to return.
+   * @returns `this` for chaining.
+   *
+   * @example
+   * ```ts
+   * find(users, {}).limit(10).toArray() // at most 10 docs
+   * ```
+   */
+  limit(n) {
+    this.cursor.limit(n);
+    return this;
+  }
+  /**
+   * Execute the query and return all matching documents as an array.
+   *
+   * Each document is validated against the collection's Zod schema
+   * according to the resolved validation mode.
+   *
+   * @returns Array of validated documents.
+   * @throws {ZodmonValidationError} When a document fails schema validation in strict/strip mode.
+   *
+   * @example
+   * ```ts
+   * const admins = await find(users, { role: 'admin' }).toArray()
+   * ```
+   */
+  async toArray() {
+    const raw2 = await this.cursor.toArray();
+    return raw2.map((doc) => this.validateDoc(doc));
+  }
+  /**
+   * Async iterator for streaming documents one at a time.
+   *
+   * Each yielded document is validated against the collection's Zod schema.
+   * Memory-efficient for large result sets.
+   *
+   * @yields Validated documents one at a time.
+   * @throws {ZodmonValidationError} When a document fails schema validation.
+   *
+   * @example
+   * ```ts
+   * for await (const user of find(users, {})) {
+   *   console.log(user.name)
+   * }
+   * ```
+   */
+  async *[Symbol.asyncIterator]() {
+    for await (const doc of this.cursor) {
+      yield this.validateDoc(doc);
+    }
+  }
+  /** @internal Validate a single raw document against the schema. */
+  validateDoc(raw2) {
+    if (this.mode === false || this.mode === "passthrough") {
+      return raw2;
+    }
+    try {
+      return this.schema.parse(raw2);
+    } catch (err) {
+      if (err instanceof import_zod.z.ZodError) {
+        throw new ZodmonValidationError(this.collectionName, err);
+      }
+      throw err;
+    }
+  }
+};
+
+// src/crud/find.ts
+async function findOne(handle, filter, options) {
+  const findOptions = options?.project ? { projection: options.project } : void 0;
+  const raw2 = await handle.native.findOne(filter, findOptions);
+  if (!raw2) return null;
+  const mode = options?.validate !== void 0 ? options.validate : handle.definition.options.validation;
+  if (mode === false || mode === "passthrough") {
+    return raw2;
+  }
+  try {
+    return handle.definition.schema.parse(raw2);
+  } catch (err) {
+    if (err instanceof import_zod2.z.ZodError) {
+      throw new ZodmonValidationError(handle.definition.name, err);
+    }
+    throw err;
+  }
+}
+async function findOneOrThrow(handle, filter, options) {
+  const doc = await findOne(handle, filter, options);
+  if (!doc) {
+    throw new ZodmonNotFoundError(handle.definition.name);
+  }
+  return doc;
+}
+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);
+}
+
+// src/crud/insert.ts
+var import_zod3 = require("zod");
+async function insertOne(handle, doc) {
+  let parsed;
+  try {
+    parsed = handle.definition.schema.parse(doc);
+  } catch (err) {
+    if (err instanceof import_zod3.z.ZodError) {
+      throw new ZodmonValidationError(handle.definition.name, err);
+    }
+    throw err;
+  }
+  await handle.native.insertOne(parsed);
+  return parsed;
+}
+async function insertMany(handle, docs) {
+  if (docs.length === 0) return [];
+  const parsed = [];
+  for (const doc of docs) {
+    try {
+      parsed.push(handle.definition.schema.parse(doc));
+    } catch (err) {
+      if (err instanceof import_zod3.z.ZodError) {
+        throw new ZodmonValidationError(handle.definition.name, err);
+      }
+      throw err;
+    }
+  }
+  await handle.native.insertMany(parsed);
+  return parsed;
+}
+
 // src/client/handle.ts
 var CollectionHandle = class {
   /** The collection definition containing schema, name, and index metadata. */
   definition;
-  /** The underlying MongoDB driver collection, typed to `TDoc`. */
+  /** The underlying MongoDB driver collection, typed to the inferred document type. */
   native;
   constructor(definition, native) {
     this.definition = definition;
     this.native = native;
   }
+  /**
+   * Insert a single document into the collection.
+   *
+   * Validates the input against the collection's Zod schema before writing.
+   * Schema defaults (including auto-generated `_id`) are applied during
+   * validation. Returns the full document with all defaults filled in.
+   *
+   * @param doc - The document to insert. Fields with `.default()` are optional.
+   * @returns The inserted document with `_id` and all defaults applied.
+   * @throws {ZodmonValidationError} When the document fails schema validation.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const user = await users.insertOne({ name: 'Ada' })
+   * console.log(user._id) // ObjectId (auto-generated)
+   * console.log(user.role) // 'user' (schema default)
+   * ```
+   */
+  async insertOne(doc) {
+    return await insertOne(this, doc);
+  }
+  /**
+   * Insert multiple documents into the collection.
+   *
+   * Validates every document against the collection's Zod schema before
+   * writing any to MongoDB. If any document fails validation, none are
+   * inserted (fail-fast before the driver call).
+   *
+   * @param docs - The documents to insert.
+   * @returns The inserted documents with `_id` and all defaults applied.
+   * @throws {ZodmonValidationError} When any document fails schema validation.
+   *
+   * @example
+   * ```ts
+   * const created = await users.insertMany([
+   *   { name: 'Ada' },
+   *   { name: 'Bob', role: 'admin' },
+   * ])
+   * ```
+   */
+  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);
+  }
 };
 
 // src/client/client.ts
@@ -92,7 +428,10 @@ var Database = class {
   use(def) {
     this._collections.set(def.name, def);
     const native = this._db.collection(def.name);
-    return new CollectionHandle(def, native);
+    return new CollectionHandle(
+      def,
+      native
+    );
   }
   /**
    * Synchronize indexes defined in registered collections with MongoDB.
@@ -140,13 +479,14 @@ function createClient(uri, dbNameOrOptions, maybeOptions) {
 }
 
 // src/collection/collection.ts
-var import_zod4 = require("zod");
+var import_mongodb3 = require("mongodb");
+var import_zod7 = require("zod");
 
 // src/schema/extensions.ts
-var import_zod2 = require("zod");
+var import_zod5 = require("zod");
 
 // src/schema/ref.ts
-var import_zod = require("zod");
+var import_zod4 = require("zod");
 var refMetadata = /* @__PURE__ */ new WeakMap();
 function getRefMetadata(schema) {
   if (typeof schema !== "object" || schema === null) return void 0;
@@ -154,7 +494,7 @@ function getRefMetadata(schema) {
 }
 var REF_GUARD = /* @__PURE__ */ Symbol.for("zodmon_ref");
 function installRefExtension() {
-  const proto = import_zod.z.ZodType.prototype;
+  const proto = import_zod4.z.ZodType.prototype;
   if (REF_GUARD in proto) return;
   Object.defineProperty(proto, "ref", {
     value(collection2) {
@@ -181,7 +521,7 @@ function getIndexMetadata(schema) {
 }
 var GUARD = /* @__PURE__ */ Symbol.for("zodmon_extensions");
 function installExtensions() {
-  const proto = import_zod2.z.ZodType.prototype;
+  const proto = import_zod5.z.ZodType.prototype;
   if (GUARD in proto) return;
   Object.defineProperty(proto, "index", {
     /**
@@ -280,10 +620,10 @@ installExtensions();
 
 // src/schema/object-id.ts
 var import_mongodb2 = require("mongodb");
-var import_zod3 = require("zod");
+var import_zod6 = require("zod");
 var OBJECT_ID_HEX = /^[a-f\d]{24}$/i;
 function objectId() {
-  return import_zod3.z.custom((val) => {
+  return import_zod6.z.custom((val) => {
     if (val instanceof import_mongodb2.ObjectId) return true;
     return typeof val === "string" && OBJECT_ID_HEX.test(val);
   }, "Invalid ObjectId").transform((val) => val instanceof import_mongodb2.ObjectId ? val : import_mongodb2.ObjectId.createFromHexString(val));
@@ -301,8 +641,8 @@ function extractFieldIndexes(shape) {
   return result;
 }
 function collection(name, shape, options) {
-  const resolvedShape = "_id" in shape ? shape : { _id: objectId(), ...shape };
-  const schema = import_zod4.z.object(resolvedShape);
+  const resolvedShape = "_id" in shape ? shape : { _id: objectId().default(() => new import_mongodb3.ObjectId()), ...shape };
+  const schema = import_zod7.z.object(resolvedShape);
   const fieldIndexes = extractFieldIndexes(shape);
   const { indexes: compoundIndexes, validation, ...rest } = options ?? {};
   return {
@@ -353,14 +693,14 @@ function index(fields) {
 }
 
 // src/helpers/oid.ts
-var import_mongodb3 = require("mongodb");
+var import_mongodb4 = require("mongodb");
 function oid(value) {
-  if (value === void 0) return new import_mongodb3.ObjectId();
-  if (value instanceof import_mongodb3.ObjectId) return value;
-  return import_mongodb3.ObjectId.createFromHexString(value);
+  if (value === void 0) return new import_mongodb4.ObjectId();
+  if (value instanceof import_mongodb4.ObjectId) return value;
+  return import_mongodb4.ObjectId.createFromHexString(value);
 }
 function isOid(value) {
-  return value instanceof import_mongodb3.ObjectId;
+  return value instanceof import_mongodb4.ObjectId;
 }
 
 // src/query/operators.ts
@@ -402,13 +742,21 @@ var raw = (filter) => filter;
   CollectionHandle,
   Database,
   IndexBuilder,
+  TypedFindCursor,
+  ZodmonNotFoundError,
+  ZodmonValidationError,
   collection,
   createClient,
   extractDbName,
   extractFieldIndexes,
+  find,
+  findOne,
+  findOneOrThrow,
   getIndexMetadata,
   getRefMetadata,
   index,
+  insertMany,
+  insertOne,
   installExtensions,
   installRefExtension,
   isOid,