@zodmon/core 0.10.0 → 0.11.0

package/dist/index.cjs

@@ -69,6 +69,7 @@ __export(index_exports, {
   createExpressionBuilder: () => createExpressionBuilder,
   deleteMany: () => deleteMany,
   deleteOne: () => deleteOne,
+  deriveProjectedSchema: () => deriveProjectedSchema,
   extractComparableOptions: () => extractComparableOptions,
   extractDbName: () => extractDbName,
   extractFieldIndexes: () => extractFieldIndexes,
@@ -83,6 +84,7 @@ __export(index_exports, {
   index: () => index,
   insertMany: () => insertMany,
   insertOne: () => insertOne,
+  isInclusionProjection: () => isInclusionProjection,
   isOid: () => isOid,
   objectId: () => objectId,
   oid: () => oid,
@@ -110,30 +112,24 @@ var $avg = (field) => ({
   __accum: true,
   expr: { $avg: field }
 });
-var $min = (field) => ({
-  __accum: true,
-  expr: { $min: field }
-});
-var $max = (field) => ({
-  __accum: true,
-  expr: { $max: field }
-});
-var $first = (field) => ({
-  __accum: true,
-  expr: { $first: field }
-});
-var $last = (field) => ({
-  __accum: true,
-  expr: { $last: field }
-});
-var $push = (field) => ({
-  __accum: true,
-  expr: { $push: field }
-});
-var $addToSet = (field) => ({
-  __accum: true,
-  expr: { $addToSet: field }
-});
+function $min(field) {
+  return { __accum: true, expr: { $min: field } };
+}
+function $max(field) {
+  return { __accum: true, expr: { $max: field } };
+}
+function $first(field) {
+  return { __accum: true, expr: { $first: field } };
+}
+function $last(field) {
+  return { __accum: true, expr: { $last: field } };
+}
+function $push(field) {
+  return { __accum: true, expr: { $push: field } };
+}
+function $addToSet(field) {
+  return { __accum: true, expr: { $addToSet: field } };
+}
 function createAccumulatorBuilder() {
   return {
     count: () => ({ __accum: true, expr: { $sum: 1 } }),
@@ -209,9 +205,9 @@ var ZodmonError = class extends Error {
   /** The underlying error that caused this error, if any. */
   cause;
   constructor(message, collection2, options) {
-    super(message);
+    super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
     this.collection = collection2;
-    if (options?.cause) {
+    if (options?.cause !== void 0) {
       this.cause = options.cause;
     }
   }
@@ -1339,6 +1335,54 @@ function resolveSortKeys(sortSpec) {
   return entries;
 }
 
+// src/query/projection.ts
+function isIncludeValue(value) {
+  return value === 1 || value === true;
+}
+function isExcludeValue(value) {
+  return value === 0 || value === false;
+}
+function isInclusionProjection(projection) {
+  for (const key of Object.keys(projection)) {
+    if (key === "_id") continue;
+    const value = projection[key];
+    if (value !== void 0 && isIncludeValue(value)) return true;
+  }
+  return false;
+}
+function buildPickMask(projection, schemaKeys) {
+  const mask = {};
+  const idValue = projection._id;
+  if (!(idValue !== void 0 && isExcludeValue(idValue)) && schemaKeys.has("_id")) {
+    mask._id = true;
+  }
+  for (const key of Object.keys(projection)) {
+    if (key === "_id") continue;
+    const value = projection[key];
+    if (value !== void 0 && isIncludeValue(value) && schemaKeys.has(key)) {
+      mask[key] = true;
+    }
+  }
+  return mask;
+}
+function buildOmitMask(projection, schemaKeys) {
+  const mask = {};
+  for (const key of Object.keys(projection)) {
+    const value = projection[key];
+    if (value !== void 0 && isExcludeValue(value) && schemaKeys.has(key)) {
+      mask[key] = true;
+    }
+  }
+  return mask;
+}
+function deriveProjectedSchema(schema, projection) {
+  const schemaKeys = new Set(Object.keys(schema.shape));
+  if (isInclusionProjection(projection)) {
+    return schema.pick(buildPickMask(projection, schemaKeys));
+  }
+  return schema.omit(buildOmitMask(projection, schemaKeys));
+}
+
 // src/query/cursor.ts
 var TypedFindCursor = class {
   /** @internal */
@@ -1357,6 +1401,8 @@ var TypedFindCursor = class {
   /** @internal */
   sortSpec;
   /** @internal */
+  projectedSchema;
+  /** @internal */
   constructor(cursor, definition, mode, nativeCollection, filter) {
     this.cursor = cursor;
     this.schema = definition.schema;
@@ -1365,6 +1411,7 @@ var TypedFindCursor = class {
     this.nativeCollection = nativeCollection;
     this.filter = filter;
     this.sortSpec = null;
+    this.projectedSchema = null;
   }
   /**
    * Set the sort order for the query.
@@ -1438,6 +1485,40 @@ var TypedFindCursor = class {
     this.cursor.hint(indexName);
     return this;
   }
+  /**
+   * Apply a projection to narrow the returned fields.
+   *
+   * Inclusion projections (`{ name: 1 }`) return only the specified fields
+   * plus `_id` (unless `_id: 0`). Exclusion projections (`{ email: 0 }`)
+   * return all fields except those excluded.
+   *
+   * The cursor's output type is narrowed at compile time. A derived Zod
+   * schema is built for runtime validation of the projected fields.
+   *
+   * Projects from the original document type, not from a previous projection.
+   * Calling `.project()` twice overrides the previous projection.
+   *
+   * @param spec - Type-safe projection document.
+   * @returns A new cursor with the narrowed output type.
+   *
+   * @example
+   * ```ts
+   * const names = await find(users, {})
+   *   .project({ name: 1 })
+   *   .sort({ name: 1 })
+   *   .toArray()
+   * // names[0].name   ✓
+   * // names[0].email  TS error
+   * ```
+   */
+  project(spec) {
+    this.cursor.project(spec);
+    this.projectedSchema = deriveProjectedSchema(
+      this.schema,
+      spec
+    );
+    return this;
+  }
   async paginate(opts) {
     const sortRecord = this.sortSpec ? this.sortSpec : null;
     const sortKeys2 = resolveSortKeys(sortRecord);
@@ -1554,8 +1635,9 @@ var TypedFindCursor = class {
     if (this.mode === false || this.mode === "passthrough") {
       return raw2;
     }
+    const schema = this.projectedSchema ?? this.schema;
     try {
-      return this.schema.parse(raw2);
+      return schema.parse(raw2);
     } catch (err) {
       if (err instanceof import_zod3.z.ZodError) {
         throw new ZodmonValidationError(this.collectionName, err, raw2);
@@ -1568,7 +1650,8 @@ var TypedFindCursor = class {
 // src/crud/find.ts
 async function findOne(handle, filter, options) {
   checkUnindexedFields(handle.definition, filter);
-  const findOptions = options?.project ? { projection: options.project } : void 0;
+  const project = options && "project" in options ? options.project : void 0;
+  const findOptions = project ? { projection: project } : void 0;
   let raw2;
   try {
     raw2 = await handle.native.findOne(filter, findOptions);
@@ -1580,8 +1663,12 @@ async function findOne(handle, filter, options) {
   if (mode === false || mode === "passthrough") {
     return raw2;
   }
+  const schema = project ? deriveProjectedSchema(
+    handle.definition.schema,
+    project
+  ) : handle.definition.schema;
   try {
-    return handle.definition.schema.parse(raw2);
+    return schema.parse(raw2);
   } catch (err) {
     if (err instanceof import_zod4.z.ZodError) {
       throw new ZodmonValidationError(handle.definition.name, err, raw2);
@@ -1601,7 +1688,12 @@ 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, handle.native, filter);
+  const typedCursor = new TypedFindCursor(cursor, handle.definition, mode, handle.native, filter);
+  const project = options && "project" in options ? options.project : void 0;
+  if (project) {
+    return typedCursor.project(project);
+  }
+  return typedCursor;
 }
 
 // src/crud/insert.ts
@@ -1750,70 +1842,12 @@ var CollectionHandle = class {
   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);
   }
@@ -2402,6 +2436,7 @@ var $ = {
   createExpressionBuilder,
   deleteMany,
   deleteOne,
+  deriveProjectedSchema,
   extractComparableOptions,
   extractDbName,
   extractFieldIndexes,
@@ -2416,6 +2451,7 @@ var $ = {
   index,
   insertMany,
   insertOne,
+  isInclusionProjection,
   isOid,
   objectId,
   oid,