@zodmon/core 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,16 +1,344 @@
 // src/client/client.ts
 import { MongoClient } from "mongodb";
 
+// src/crud/find.ts
+import { z as z2 } from "zod";
+
+// src/errors/not-found.ts
+var ZodmonNotFoundError = class extends Error {
+  name = "ZodmonNotFoundError";
+  /** The MongoDB collection name where the query found no results. */
+  collection;
+  constructor(collection2) {
+    super(`Document not found in "${collection2}"`);
+    this.collection = collection2;
+  }
+};
+
+// src/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
+import { z } from "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 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 z2.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
+import { z as z3 } from "zod";
+async function insertOne(handle, doc) {
+  let parsed;
+  try {
+    parsed = handle.definition.schema.parse(doc);
+  } catch (err) {
+    if (err instanceof z3.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 z3.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
@@ -37,7 +365,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.
@@ -85,13 +416,14 @@ function createClient(uri, dbNameOrOptions, maybeOptions) {
 }
 
 // src/collection/collection.ts
-import { z as z4 } from "zod";
+import { ObjectId as ObjectId2 } from "mongodb";
+import { z as z7 } from "zod";
 
 // src/schema/extensions.ts
-import { z as z2 } from "zod";
+import { z as z5 } from "zod";
 
 // src/schema/ref.ts
-import { z } from "zod";
+import { z as z4 } from "zod";
 var refMetadata = /* @__PURE__ */ new WeakMap();
 function getRefMetadata(schema) {
   if (typeof schema !== "object" || schema === null) return void 0;
@@ -99,7 +431,7 @@ function getRefMetadata(schema) {
 }
 var REF_GUARD = /* @__PURE__ */ Symbol.for("zodmon_ref");
 function installRefExtension() {
-  const proto = z.ZodType.prototype;
+  const proto = z4.ZodType.prototype;
   if (REF_GUARD in proto) return;
   Object.defineProperty(proto, "ref", {
     value(collection2) {
@@ -126,7 +458,7 @@ function getIndexMetadata(schema) {
 }
 var GUARD = /* @__PURE__ */ Symbol.for("zodmon_extensions");
 function installExtensions() {
-  const proto = z2.ZodType.prototype;
+  const proto = z5.ZodType.prototype;
   if (GUARD in proto) return;
   Object.defineProperty(proto, "index", {
     /**
@@ -225,10 +557,10 @@ installExtensions();
 
 // src/schema/object-id.ts
 import { ObjectId } from "mongodb";
-import { z as z3 } from "zod";
+import { z as z6 } from "zod";
 var OBJECT_ID_HEX = /^[a-f\d]{24}$/i;
 function objectId() {
-  return z3.custom((val) => {
+  return z6.custom((val) => {
     if (val instanceof ObjectId) return true;
     return typeof val === "string" && OBJECT_ID_HEX.test(val);
   }, "Invalid ObjectId").transform((val) => val instanceof ObjectId ? val : ObjectId.createFromHexString(val));
@@ -246,8 +578,8 @@ function extractFieldIndexes(shape) {
   return result;
 }
 function collection(name, shape, options) {
-  const resolvedShape = "_id" in shape ? shape : { _id: objectId(), ...shape };
-  const schema = z4.object(resolvedShape);
+  const resolvedShape = "_id" in shape ? shape : { _id: objectId().default(() => new ObjectId2()), ...shape };
+  const schema = z7.object(resolvedShape);
   const fieldIndexes = extractFieldIndexes(shape);
   const { indexes: compoundIndexes, validation, ...rest } = options ?? {};
   return {
@@ -298,14 +630,14 @@ function index(fields) {
 }
 
 // src/helpers/oid.ts
-import { ObjectId as ObjectId2 } from "mongodb";
+import { ObjectId as ObjectId3 } from "mongodb";
 function oid(value) {
-  if (value === void 0) return new ObjectId2();
-  if (value instanceof ObjectId2) return value;
-  return ObjectId2.createFromHexString(value);
+  if (value === void 0) return new ObjectId3();
+  if (value instanceof ObjectId3) return value;
+  return ObjectId3.createFromHexString(value);
 }
 function isOid(value) {
-  return value instanceof ObjectId2;
+  return value instanceof ObjectId3;
 }
 
 // src/query/operators.ts
@@ -346,13 +678,21 @@ export {
   CollectionHandle,
   Database,
   IndexBuilder,
+  TypedFindCursor,
+  ZodmonNotFoundError,
+  ZodmonValidationError,
   collection,
   createClient,
   extractDbName,
   extractFieldIndexes,
+  find,
+  findOne,
+  findOneOrThrow,
   getIndexMetadata,
   getRefMetadata,
   index,
+  insertMany,
+  insertOne,
   installExtensions,
   installRefExtension,
   isOid,