Support middleware skip option for cursors and custom hooks

[AbdelrahmanHafez]

re #8768, builds on top of mongoosejs/kareem#46

We left some parts uncovered in #15883, namely statics, methods, and cursors (aggregation, and query).

This PR:

• Applies the existing middleware skip option to query cursors, including both pre find hooks and per-document post find hooks.
• Applies the skip option to aggregate cursors for pre aggregate hooks. Aggregate cursors still don't run post aggregate hooks, so the cursor-specific TS type only exposes middleware: false and { pre: false }.
• Strips the Mongoose-only middleware option before passing cursor options to the MongoDB driver.
• Adds support for skipping middleware on custom statics and methods by reading middleware from the final plain options object.
• Documents the cursor behavior and the recommended custom static/method signature.

For now this pins kareem to the fork commit that adds wrapper getOptions support for custom statics/methods. Once the Kareem change lands and is released, we can switch this back to a normal version range.

A design decision that was made is how we pass the middleware option to statics/methods, I chose to pass them to the last arg if it's POJO, and the docs now have examples with a pattern where users define the last arg as options, following the same pattern as the other mongoose operations.

[Copilot]

Pull request overview

Extends the existing middleware skip option so users can selectively skip user-defined hooks when using query cursors, aggregation cursors, and custom statics/methods, while ensuring the Mongoose-only option is not forwarded to the MongoDB driver.

Changes:

• Add middleware filtering support to query cursors (pre('find') + per-document post('find')) and aggregation cursors (pre('aggregate') only), and strip middleware before calling the MongoDB driver.
• Enable per-call hook skipping for custom statics and methods by reading middleware from the trailing plain-object options argument via Kareem wrapper getOptions.
• Update TypeScript types, docs, and add runtime + type-level tests; pin kareem to a fork commit needed for wrapper getOptions.

Reviewed changes

Copilot reviewed 11 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
types/middlewares.d.ts	Update middleware function return typing to Kareem.OverwriteResult.
types/index.d.ts	Update overwriteMiddlewareResult() return type to Kareem.OverwriteResult.
types/aggregate.d.ts	Add cursor-specific options/types for aggregate cursors, including middleware skipping semantics.
test/types/model.skip.middleware.test.ts	Extend TS type tests to cover cursor middleware options and new aggregate cursor types.
test/model.skip.middleware.test.js	Add runtime tests for cursor middleware skipping, option parsing behavior, and custom statics/methods skipping.
package.json	Pin kareem dependency to a fork commit that supports wrapper getOptions.
lib/query.js	Document cursor hook behavior and cursor-level middleware option.
lib/helpers/model/applyStaticHooks.js	Add Kareem wrapper getOptions for custom statics to support per-call hook skipping.
lib/helpers/model/applyHooks.js	Add Kareem wrapper getOptions for custom document methods to support per-call hook skipping.
lib/helpers/buildMiddlewareFilter.js	Tighten skip detection to only treat strict false as “skip”.
lib/cursor/queryCursor.js	Apply middleware filtering to cursor execPre/execPost('find') and strip middleware before driver call.
lib/cursor/aggregationCursor.js	Apply middleware filtering to execPre('aggregate') and strip middleware before driver calls.
lib/aggregate.js	Document aggregate cursor middleware behavior and plumb cursor-level middleware into aggregate options.
docs/middleware.md	Document cursor behavior and recommended custom static/method signature for options.