@zodmon/core 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -20,28 +20,321 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  $and: () => $and,
+  $eq: () => $eq,
+  $exists: () => $exists,
+  $gt: () => $gt,
+  $gte: () => $gte,
+  $in: () => $in,
+  $lt: () => $lt,
+  $lte: () => $lte,
+  $ne: () => $ne,
+  $nin: () => $nin,
+  $nor: () => $nor,
+  $not: () => $not,
+  $or: () => $or,
+  $regex: () => $regex,
+  CollectionHandle: () => CollectionHandle,
+  Database: () => Database,
   IndexBuilder: () => IndexBuilder,
+  ZodmonNotFoundError: () => ZodmonNotFoundError,
+  ZodmonValidationError: () => ZodmonValidationError,
   collection: () => collection,
+  createClient: () => createClient,
+  extractDbName: () => extractDbName,
   extractFieldIndexes: () => extractFieldIndexes,
+  findOne: () => findOne,
+  findOneOrThrow: () => findOneOrThrow,
   getIndexMetadata: () => getIndexMetadata,
   getRefMetadata: () => getRefMetadata,
   index: () => index,
+  insertMany: () => insertMany,
+  insertOne: () => insertOne,
   installExtensions: () => installExtensions,
   installRefExtension: () => installRefExtension,
   isOid: () => isOid,
   objectId: () => objectId,
-  oid: () => oid
+  oid: () => oid,
+  raw: () => raw
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/client/client.ts
+var import_mongodb = require("mongodb");
+
+// src/crud/find.ts
+var import_zod = 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/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_zod.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;
+}
+
+// src/crud/insert.ts
+var import_zod2 = require("zod");
+async function insertOne(handle, doc) {
+  let parsed;
+  try {
+    parsed = handle.definition.schema.parse(doc);
+  } catch (err) {
+    if (err instanceof import_zod2.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_zod2.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 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);
+  }
+};
+
+// src/client/client.ts
+var Database = class {
+  _client;
+  _db;
+  /** 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._db = this._client.db(dbName);
+  }
+  /**
+   * Register a collection definition and return a typed {@link CollectionHandle}.
+   *
+   * The handle's `native` property is a MongoDB `Collection<TDoc>` where `TDoc`
+   * is the document type inferred from the definition's Zod schema. Calling
+   * `use()` multiple times with the same definition is safe — each call returns
+   * a new lightweight handle backed by the same underlying driver collection.
+   *
+   * @param def - A collection definition created by `collection()`.
+   * @returns A typed collection handle for CRUD operations.
+   */
+  use(def) {
+    this._collections.set(def.name, def);
+    const native = this._db.collection(def.name);
+    return new CollectionHandle(
+      def,
+      native
+    );
+  }
+  /**
+   * Synchronize indexes defined in registered collections with MongoDB.
+   *
+   * Stub — full implementation in TASK-92.
+   */
+  syncIndexes() {
+    return Promise.resolve();
+  }
+  /**
+   * Execute a function within a MongoDB transaction with auto-commit/rollback.
+   *
+   * Stub — full implementation in TASK-106.
+   */
+  transaction(_fn) {
+    throw new Error("Not implemented");
+  }
+  /**
+   * Close the underlying `MongoClient` connection. Safe to call even if
+   * no connection was established (the driver handles this gracefully).
+   */
+  async close() {
+    await this._client.close();
+  }
+};
+function extractDbName(uri) {
+  const withoutProtocol = uri.replace(/^mongodb(?:\+srv)?:\/\//, "");
+  const withoutQuery = withoutProtocol.split("?")[0];
+  const atIndex = withoutQuery.lastIndexOf("@");
+  const hostAndPath = atIndex === -1 ? withoutQuery : withoutQuery.slice(atIndex + 1);
+  const slashIndex = hostAndPath.indexOf("/");
+  if (slashIndex === -1) return void 0;
+  const dbName = decodeURIComponent(hostAndPath.slice(slashIndex + 1));
+  return dbName || void 0;
+}
+function createClient(uri, dbNameOrOptions, maybeOptions) {
+  if (typeof dbNameOrOptions === "string") {
+    return new Database(uri, dbNameOrOptions, maybeOptions);
+  }
+  const parsed = extractDbName(uri);
+  if (!parsed) {
+    console.warn('[zodmon] No database name provided \u2014 using MongoDB default "test"');
+  }
+  return new Database(uri, parsed ?? "test", dbNameOrOptions);
+}
+
 // src/collection/collection.ts
-var import_zod4 = require("zod");
+var import_mongodb3 = require("mongodb");
+var import_zod6 = require("zod");
 
 // src/schema/extensions.ts
-var import_zod2 = require("zod");
+var import_zod4 = require("zod");
 
 // src/schema/ref.ts
-var import_zod = require("zod");
+var import_zod3 = require("zod");
 var refMetadata = /* @__PURE__ */ new WeakMap();
 function getRefMetadata(schema) {
   if (typeof schema !== "object" || schema === null) return void 0;
@@ -49,7 +342,7 @@ function getRefMetadata(schema) {
 }
 var REF_GUARD = /* @__PURE__ */ Symbol.for("zodmon_ref");
 function installRefExtension() {
-  const proto = import_zod.z.ZodType.prototype;
+  const proto = import_zod3.z.ZodType.prototype;
   if (REF_GUARD in proto) return;
   Object.defineProperty(proto, "ref", {
     value(collection2) {
@@ -76,7 +369,7 @@ function getIndexMetadata(schema) {
 }
 var GUARD = /* @__PURE__ */ Symbol.for("zodmon_extensions");
 function installExtensions() {
-  const proto = import_zod2.z.ZodType.prototype;
+  const proto = import_zod4.z.ZodType.prototype;
   if (GUARD in proto) return;
   Object.defineProperty(proto, "index", {
     /**
@@ -174,14 +467,14 @@ function installExtensions() {
 installExtensions();
 
 // src/schema/object-id.ts
-var import_mongodb = require("mongodb");
-var import_zod3 = require("zod");
+var import_mongodb2 = require("mongodb");
+var import_zod5 = require("zod");
 var OBJECT_ID_HEX = /^[a-f\d]{24}$/i;
 function objectId() {
-  return import_zod3.z.custom((val) => {
-    if (val instanceof import_mongodb.ObjectId) return true;
+  return import_zod5.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_mongodb.ObjectId ? val : import_mongodb.ObjectId.createFromHexString(val));
+  }, "Invalid ObjectId").transform((val) => val instanceof import_mongodb2.ObjectId ? val : import_mongodb2.ObjectId.createFromHexString(val));
 }
 
 // src/collection/collection.ts
@@ -196,8 +489,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_zod6.z.object(resolvedShape);
   const fieldIndexes = extractFieldIndexes(shape);
   const { indexes: compoundIndexes, validation, ...rest } = options ?? {};
   return {
@@ -248,27 +541,73 @@ function index(fields) {
 }
 
 // src/helpers/oid.ts
-var import_mongodb2 = require("mongodb");
+var import_mongodb4 = require("mongodb");
 function oid(value) {
-  if (value === void 0) return new import_mongodb2.ObjectId();
-  if (value instanceof import_mongodb2.ObjectId) return value;
-  return import_mongodb2.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_mongodb2.ObjectId;
+  return value instanceof import_mongodb4.ObjectId;
 }
+
+// src/query/operators.ts
+var $eq = (value) => ({ $eq: value });
+var $ne = (value) => ({ $ne: value });
+var $gt = (value) => ({ $gt: value });
+var $gte = (value) => ({ $gte: value });
+var $lt = (value) => ({ $lt: value });
+var $lte = (value) => ({ $lte: value });
+var $in = (values) => ({ $in: values });
+var $nin = (values) => ({ $nin: values });
+var $exists = (flag = true) => ({ $exists: flag });
+var $regex = (pattern) => ({
+  $regex: pattern
+});
+var $not = (op) => ({
+  $not: op
+});
+var $or = (...filters) => ({ $or: filters });
+var $and = (...filters) => ({ $and: filters });
+var $nor = (...filters) => ({ $nor: filters });
+var raw = (filter) => filter;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  $and,
+  $eq,
+  $exists,
+  $gt,
+  $gte,
+  $in,
+  $lt,
+  $lte,
+  $ne,
+  $nin,
+  $nor,
+  $not,
+  $or,
+  $regex,
+  CollectionHandle,
+  Database,
   IndexBuilder,
+  ZodmonNotFoundError,
+  ZodmonValidationError,
   collection,
+  createClient,
+  extractDbName,
   extractFieldIndexes,
+  findOne,
+  findOneOrThrow,
   getIndexMetadata,
   getRefMetadata,
   index,
+  insertMany,
+  insertOne,
   installExtensions,
   installRefExtension,
   isOid,
   objectId,
-  oid
+  oid,
+  raw
 });
 //# sourceMappingURL=index.cjs.map