@zodmon/core 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  $: () => $,
   $and: () => $and,
   $eq: () => $eq,
   $exists: () => $exists,
@@ -42,41 +43,34 @@ __export(index_exports, {
   ZodmonValidationError: () => ZodmonValidationError,
   collection: () => collection,
   createClient: () => createClient,
+  deleteMany: () => deleteMany,
+  deleteOne: () => deleteOne,
   extractDbName: () => extractDbName,
   extractFieldIndexes: () => extractFieldIndexes,
   find: () => find,
   findOne: () => findOne,
+  findOneAndDelete: () => findOneAndDelete,
+  findOneAndUpdate: () => findOneAndUpdate,
   findOneOrThrow: () => findOneOrThrow,
   getIndexMetadata: () => getIndexMetadata,
   getRefMetadata: () => getRefMetadata,
   index: () => index,
   insertMany: () => insertMany,
   insertOne: () => insertOne,
-  installExtensions: () => installExtensions,
-  installRefExtension: () => installRefExtension,
   isOid: () => isOid,
   objectId: () => objectId,
   oid: () => oid,
-  raw: () => raw
+  raw: () => raw,
+  updateMany: () => updateMany,
+  updateOne: () => updateOne
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/client/client.ts
-var import_mongodb = require("mongodb");
-
-// src/crud/find.ts
-var import_zod2 = require("zod");
+var import_mongodb2 = require("mongodb");
 
-// 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/crud/delete.ts
+var import_zod = require("zod");
 
 // src/errors/validation.ts
 var ZodmonValidationError = class extends Error {
@@ -96,8 +90,113 @@ var ZodmonValidationError = class extends Error {
   }
 };
 
+// src/crud/delete.ts
+async function deleteOne(handle, filter) {
+  return await handle.native.deleteOne(filter);
+}
+async function deleteMany(handle, filter) {
+  return await handle.native.deleteMany(filter);
+}
+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 }
+  );
+  if (!result) return null;
+  const mode = options?.validate !== void 0 ? options.validate : handle.definition.options.validation;
+  if (mode === false || mode === "passthrough") {
+    return result;
+  }
+  try {
+    return handle.definition.schema.parse(result);
+  } catch (err) {
+    if (err instanceof import_zod.z.ZodError) {
+      throw new ZodmonValidationError(handle.definition.name, err);
+    }
+    throw err;
+  }
+}
+
+// src/crud/find.ts
+var import_zod3 = 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/query/cursor.ts
+var import_zod2 = require("zod");
+
+// src/crud/paginate.ts
+var import_mongodb = require("mongodb");
+function serializeValue(value) {
+  if (value instanceof import_mongodb.ObjectId) return { $oid: value.toHexString() };
+  if (value instanceof Date) return { $date: value.getTime() };
+  return value;
+}
+function deserializeValue(value) {
+  if (value != null && typeof value === "object") {
+    if ("$oid" in value) return new import_mongodb.ObjectId(value.$oid);
+    if ("$date" in value) return new Date(value.$date);
+  }
+  return value;
+}
+function encodeCursor(doc, sortKeys, direction) {
+  const values = sortKeys.map(([field]) => serializeValue(doc[field]));
+  return btoa(JSON.stringify([direction, ...values]));
+}
+function decodeCursor(cursor) {
+  let parsed;
+  try {
+    parsed = JSON.parse(atob(cursor));
+  } catch {
+    throw new Error("Invalid cursor: malformed encoding");
+  }
+  if (!Array.isArray(parsed) || parsed.length < 1) {
+    throw new Error("Invalid cursor: expected non-empty array");
+  }
+  const [direction, ...rawValues] = parsed;
+  if (direction !== "f" && direction !== "b") {
+    throw new Error("Invalid cursor: unknown direction flag");
+  }
+  return { direction, values: rawValues.map(deserializeValue) };
+}
+function buildCursorFilter(sortKeys, values, isBackward) {
+  const clauses = [];
+  for (let i = 0; i < sortKeys.length; i++) {
+    const clause = {};
+    for (let j = 0; j < i; j++) {
+      clause[sortKeys[j][0]] = values[j];
+    }
+    const [field, direction] = sortKeys[i];
+    const isAsc = direction === 1;
+    const op = isAsc !== isBackward ? "$gt" : "$lt";
+    if (values[i] === null) {
+      clause[field] = { $ne: null };
+    } else {
+      clause[field] = { [op]: values[i] };
+    }
+    clauses.push(clause);
+  }
+  return { $or: clauses };
+}
+function resolveSortKeys(sortSpec) {
+  const entries = sortSpec ? Object.entries(sortSpec) : [];
+  if (!entries.some(([field]) => field === "_id")) {
+    entries.push(["_id", 1]);
+  }
+  return entries;
+}
+
 // src/query/cursor.ts
-var import_zod = require("zod");
 var TypedFindCursor = class {
   /** @internal */
   cursor;
@@ -108,11 +207,21 @@ var TypedFindCursor = class {
   /** @internal */
   mode;
   /** @internal */
-  constructor(cursor, definition, mode) {
+  nativeCollection;
+  /** @internal */
+  // biome-ignore lint/suspicious/noExplicitAny: TypedFilter is not assignable to MongoDB's Filter; stored opaquely for paginate
+  filter;
+  /** @internal */
+  sortSpec;
+  /** @internal */
+  constructor(cursor, definition, mode, nativeCollection, filter) {
     this.cursor = cursor;
     this.schema = definition.schema;
     this.collectionName = definition.name;
     this.mode = mode;
+    this.nativeCollection = nativeCollection;
+    this.filter = filter;
+    this.sortSpec = null;
   }
   /**
    * Set the sort order for the query.
@@ -129,6 +238,7 @@ var TypedFindCursor = class {
    * ```
    */
   sort(spec) {
+    this.sortSpec = spec;
     this.cursor.sort(spec);
     return this;
   }
@@ -162,6 +272,57 @@ var TypedFindCursor = class {
     this.cursor.limit(n);
     return this;
   }
+  async paginate(opts) {
+    const sortRecord = this.sortSpec ? this.sortSpec : null;
+    const sortKeys = resolveSortKeys(sortRecord);
+    const sort = Object.fromEntries(sortKeys);
+    if ("page" in opts) {
+      return await this.offsetPaginate(sortKeys, sort, opts);
+    }
+    return await this.cursorPaginate(sortKeys, sort, opts);
+  }
+  /** @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()
+    ]);
+    const docs = raw2.map((doc) => this.validateDoc(doc));
+    const totalPages = Math.ceil(total / opts.perPage);
+    return {
+      docs,
+      total,
+      page: opts.page,
+      perPage: opts.perPage,
+      totalPages,
+      hasNext: opts.page < totalPages,
+      hasPrev: opts.page > 1
+    };
+  }
+  /** @internal Cursor pagination implementation. */
+  async cursorPaginate(sortKeys, 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);
+      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 raw2 = await this.nativeCollection.find(combinedFilter).sort(effectiveSort).limit(opts.limit + 1).toArray();
+    const hasMore = raw2.length > opts.limit;
+    if (hasMore) raw2.pop();
+    if (isBackward) raw2.reverse();
+    const docs = raw2.map((doc) => this.validateDoc(doc));
+    return {
+      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
+    };
+  }
   /**
    * Execute the query and return all matching documents as an array.
    *
@@ -209,7 +370,7 @@ var TypedFindCursor = class {
     try {
       return this.schema.parse(raw2);
     } catch (err) {
-      if (err instanceof import_zod.z.ZodError) {
+      if (err instanceof import_zod2.z.ZodError) {
         throw new ZodmonValidationError(this.collectionName, err);
       }
       throw err;
@@ -229,7 +390,7 @@ async function findOne(handle, filter, options) {
   try {
     return handle.definition.schema.parse(raw2);
   } catch (err) {
-    if (err instanceof import_zod2.z.ZodError) {
+    if (err instanceof import_zod3.z.ZodError) {
       throw new ZodmonValidationError(handle.definition.name, err);
     }
     throw err;
@@ -246,17 +407,17 @@ 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);
+  return new TypedFindCursor(cursor, handle.definition, mode, handle.native, filter);
 }
 
 // src/crud/insert.ts
-var import_zod3 = require("zod");
+var import_zod4 = 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) {
+    if (err instanceof import_zod4.z.ZodError) {
       throw new ZodmonValidationError(handle.definition.name, err);
     }
     throw err;
@@ -271,7 +432,7 @@ async function insertMany(handle, docs) {
     try {
       parsed.push(handle.definition.schema.parse(doc));
     } 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;
@@ -281,6 +442,45 @@ async function insertMany(handle, docs) {
   return parsed;
 }
 
+// src/crud/update.ts
+var import_zod5 = require("zod");
+async function updateOne(handle, filter, update, options) {
+  return await handle.native.updateOne(filter, update, options);
+}
+async function updateMany(handle, filter, update, options) {
+  return await handle.native.updateMany(filter, update, options);
+}
+async function findOneAndUpdate(handle, filter, update, options) {
+  const driverOptions = {
+    returnDocument: options?.returnDocument ?? "after",
+    includeResultMetadata: false
+  };
+  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
+  );
+  if (!result) return null;
+  const mode = options?.validate !== void 0 ? options.validate : handle.definition.options.validation;
+  if (mode === false || mode === "passthrough") {
+    return result;
+  }
+  try {
+    return handle.definition.schema.parse(result);
+  } catch (err) {
+    if (err instanceof import_zod5.z.ZodError) {
+      throw new ZodmonValidationError(handle.definition.name, err);
+    }
+    throw err;
+  }
+}
+
 // src/client/handle.ts
 var CollectionHandle = class {
   /** The collection definition containing schema, name, and index metadata. */
@@ -402,6 +602,139 @@ var CollectionHandle = class {
   find(filter, options) {
     return find(this, filter, options);
   }
+  /**
+   * Update a single document matching the filter.
+   *
+   * Applies the update operators to the first document that matches the filter.
+   * Does not validate the update against the Zod schema — validation happens
+   * at the field-operator level through {@link TypedUpdateFilter}.
+   *
+   * @param filter - Type-safe filter to match documents.
+   * @param update - Type-safe update operators to apply.
+   * @param options - Optional settings such as `upsert`.
+   * @returns The MongoDB `UpdateResult` with match/modify counts.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const result = await users.updateOne({ name: 'Ada' }, { $set: { role: 'admin' } })
+   * console.log(result.modifiedCount) // 1
+   * ```
+   */
+  async updateOne(filter, update, options) {
+    return await updateOne(this, filter, update, options);
+  }
+  /**
+   * Update all documents matching the filter.
+   *
+   * Applies the update operators to every document that matches the filter.
+   * Does not validate the update against the Zod schema — validation happens
+   * at the field-operator level through {@link TypedUpdateFilter}.
+   *
+   * @param filter - Type-safe filter to match documents.
+   * @param update - Type-safe update operators to apply.
+   * @param options - Optional settings such as `upsert`.
+   * @returns The MongoDB `UpdateResult` with match/modify counts.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const result = await users.updateMany({ role: 'guest' }, { $set: { role: 'user' } })
+   * console.log(result.modifiedCount) // number of guests promoted
+   * ```
+   */
+  async updateMany(filter, update, options) {
+    return await updateMany(this, filter, update, options);
+  }
+  /**
+   * Find a single document matching the filter, apply an update, and return the document.
+   *
+   * By default, returns the document **after** the update is applied. Set
+   * `returnDocument: 'before'` to get the pre-update snapshot. The returned
+   * document is validated against the collection's Zod schema using the same
+   * resolution logic as {@link findOne}.
+   *
+   * @param filter - Type-safe filter to match documents.
+   * @param update - Type-safe update operators to apply.
+   * @param options - Optional settings: `returnDocument`, `upsert`, `validate`.
+   * @returns The matched document (before or after update), or `null` if no document matches.
+   * @throws {ZodmonValidationError} When the returned document fails schema validation in strict mode.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const user = await users.findOneAndUpdate(
+   *   { name: 'Ada' },
+   *   { $set: { role: 'admin' } },
+   * )
+   * if (user) console.log(user.role) // 'admin' (returned after update)
+   * ```
+   */
+  async findOneAndUpdate(filter, update, options) {
+    return await findOneAndUpdate(this, filter, update, options);
+  }
+  /**
+   * Delete a single document matching the filter.
+   *
+   * Removes the first document that matches the filter from the collection.
+   * No validation is performed — the document is deleted directly through
+   * the MongoDB driver.
+   *
+   * @param filter - Type-safe filter to match documents.
+   * @returns The MongoDB `DeleteResult` with the deleted count.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const result = await users.deleteOne({ name: 'Ada' })
+   * console.log(result.deletedCount) // 1
+   * ```
+   */
+  async deleteOne(filter) {
+    return await deleteOne(this, filter);
+  }
+  /**
+   * Delete all documents matching the filter.
+   *
+   * Removes every document that matches the filter from the collection.
+   * No validation is performed — documents are deleted directly through
+   * the MongoDB driver.
+   *
+   * @param filter - Type-safe filter to match documents.
+   * @returns The MongoDB `DeleteResult` with the deleted count.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const result = await users.deleteMany({ role: 'guest' })
+   * console.log(result.deletedCount) // number of guests removed
+   * ```
+   */
+  async deleteMany(filter) {
+    return await deleteMany(this, filter);
+  }
+  /**
+   * Find a single document matching the filter, delete it, and return the document.
+   *
+   * Returns the deleted document, or `null` if no document matches the filter.
+   * The returned document is validated against the collection's Zod schema
+   * using the same resolution logic as {@link findOne}.
+   *
+   * @param filter - Type-safe filter to match documents.
+   * @param options - Optional settings: `validate`.
+   * @returns The deleted document, or `null` if no document matches.
+   * @throws {ZodmonValidationError} When the returned document fails schema validation in strict mode.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * const user = await users.findOneAndDelete({ name: 'Ada' })
+   * if (user) console.log(user.name) // 'Ada' (the deleted document)
+   * ```
+   */
+  async findOneAndDelete(filter, options) {
+    return await findOneAndDelete(this, filter, options);
+  }
 };
 
 // src/client/client.ts
@@ -411,7 +744,7 @@ var Database = class {
   /** Registered collection definitions, keyed by name. Used by syncIndexes(). */
   _collections = /* @__PURE__ */ new Map();
   constructor(uri, dbName, options) {
-    this._client = new import_mongodb.MongoClient(uri, options);
+    this._client = new import_mongodb2.MongoClient(uri, options);
     this._db = this._client.db(dbName);
   }
   /**
@@ -479,14 +812,14 @@ function createClient(uri, dbNameOrOptions, maybeOptions) {
 }
 
 // src/collection/collection.ts
-var import_mongodb3 = require("mongodb");
-var import_zod7 = require("zod");
+var import_mongodb4 = require("mongodb");
+var import_zod9 = require("zod");
 
 // src/schema/extensions.ts
-var import_zod5 = require("zod");
+var import_zod7 = require("zod");
 
 // src/schema/ref.ts
-var import_zod4 = require("zod");
+var import_zod6 = require("zod");
 var refMetadata = /* @__PURE__ */ new WeakMap();
 function getRefMetadata(schema) {
   if (typeof schema !== "object" || schema === null) return void 0;
@@ -494,7 +827,7 @@ function getRefMetadata(schema) {
 }
 var REF_GUARD = /* @__PURE__ */ Symbol.for("zodmon_ref");
 function installRefExtension() {
-  const proto = import_zod4.z.ZodType.prototype;
+  const proto = import_zod6.z.ZodType.prototype;
   if (REF_GUARD in proto) return;
   Object.defineProperty(proto, "ref", {
     value(collection2) {
@@ -521,7 +854,7 @@ function getIndexMetadata(schema) {
 }
 var GUARD = /* @__PURE__ */ Symbol.for("zodmon_extensions");
 function installExtensions() {
-  const proto = import_zod5.z.ZodType.prototype;
+  const proto = import_zod7.z.ZodType.prototype;
   if (GUARD in proto) return;
   Object.defineProperty(proto, "index", {
     /**
@@ -619,14 +952,14 @@ function installExtensions() {
 installExtensions();
 
 // src/schema/object-id.ts
-var import_mongodb2 = require("mongodb");
-var import_zod6 = require("zod");
+var import_mongodb3 = require("mongodb");
+var import_zod8 = require("zod");
 var OBJECT_ID_HEX = /^[a-f\d]{24}$/i;
 function objectId() {
-  return import_zod6.z.custom((val) => {
-    if (val instanceof import_mongodb2.ObjectId) return true;
+  return import_zod8.z.custom((val) => {
+    if (val instanceof import_mongodb3.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));
+  }, "Invalid ObjectId").transform((val) => val instanceof import_mongodb3.ObjectId ? val : import_mongodb3.ObjectId.createFromHexString(val));
 }
 
 // src/collection/collection.ts
@@ -641,8 +974,8 @@ function extractFieldIndexes(shape) {
   return result;
 }
 function collection(name, shape, options) {
-  const resolvedShape = "_id" in shape ? shape : { _id: objectId().default(() => new import_mongodb3.ObjectId()), ...shape };
-  const schema = import_zod7.z.object(resolvedShape);
+  const resolvedShape = "_id" in shape ? shape : { _id: objectId().default(() => new import_mongodb4.ObjectId()), ...shape };
+  const schema = import_zod9.z.object(resolvedShape);
   const fieldIndexes = extractFieldIndexes(shape);
   const { indexes: compoundIndexes, validation, ...rest } = options ?? {};
   return {
@@ -693,14 +1026,14 @@ function index(fields) {
 }
 
 // src/helpers/oid.ts
-var import_mongodb4 = require("mongodb");
+var import_mongodb5 = require("mongodb");
 function oid(value) {
-  if (value === void 0) return new import_mongodb4.ObjectId();
-  if (value instanceof import_mongodb4.ObjectId) return value;
-  return import_mongodb4.ObjectId.createFromHexString(value);
+  if (value === void 0) return new import_mongodb5.ObjectId();
+  if (value instanceof import_mongodb5.ObjectId) return value;
+  return import_mongodb5.ObjectId.createFromHexString(value);
 }
 function isOid(value) {
-  return value instanceof import_mongodb4.ObjectId;
+  return value instanceof import_mongodb5.ObjectId;
 }
 
 // src/query/operators.ts
@@ -723,8 +1056,28 @@ var $or = (...filters) => ({ $or: filters });
 var $and = (...filters) => ({ $and: filters });
 var $nor = (...filters) => ({ $nor: filters });
 var raw = (filter) => filter;
+
+// src/query/namespace.ts
+var $ = {
+  eq: $eq,
+  ne: $ne,
+  gt: $gt,
+  gte: $gte,
+  lt: $lt,
+  lte: $lte,
+  in: $in,
+  nin: $nin,
+  exists: $exists,
+  regex: $regex,
+  not: $not,
+  or: $or,
+  and: $and,
+  nor: $nor,
+  raw
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  $,
   $and,
   $eq,
   $exists,
@@ -747,21 +1100,25 @@ var raw = (filter) => filter;
   ZodmonValidationError,
   collection,
   createClient,
+  deleteMany,
+  deleteOne,
   extractDbName,
   extractFieldIndexes,
   find,
   findOne,
+  findOneAndDelete,
+  findOneAndUpdate,
   findOneOrThrow,
   getIndexMetadata,
   getRefMetadata,
   index,
   insertMany,
   insertOne,
-  installExtensions,
-  installRefExtension,
   isOid,
   objectId,
   oid,
-  raw
+  raw,
+  updateMany,
+  updateOne
 });
 //# sourceMappingURL=index.cjs.map