fix: support nested cursors and projection alias

Author: rockyshi1993

changelogs/unreleased.md

@@ -1,5 +1,6 @@
 # Unreleased
 
+- Fixed `findPage` cursor anchors for nested dot-path sort fields, accepted `project` as a query projection alias across read helpers, and documented process-level Model registration plus ObjectId `maxDepth` conversion boundaries.
 - Fixed `incrementOne` driver-option forwarding, closed runtime-owned Redis cache adapters on `runtime.close()`, made SSH tunnels fail fast for multi-host/SRV MongoDB URIs and post-ready disconnects, enforced slow-query batch `maxBufferSize` during in-flight flushes, wired prewarmed `findPage` bookmarks into page-jump reads, and reduced redundant rebuilds in the memory-server validation matrix.
 - Fixed model mutable defaults cloning, preserved model aggregation-pipeline updates when timestamps/versioning are enabled, restored aggregate/distinct read-through cache plus targeted invalidation, and prevented sync resume tokens from advancing when any eligible target fails.
 - Clarified hooks return-value compatibility and sync transform/delete-event boundaries in bilingual documentation, with regression coverage for the documented behavior.

changelogs/v2.0.7.md

@@ -28,6 +28,7 @@ v2.0.7 closes the release-readiness gap after the v2.0.6 review and hardens the
 - `dropDatabase()` now treats `NODE_ENV=production`, `prod`, and `live` as production-like environments that require `allowProduction: true`.
 - Aggregate pipelines ending in `$out` or `$merge` now bypass aggregate result caching and invalidate the target collection's read caches after successful execution.
 - Fire-and-forget distributed cache invalidation and transaction timeout abort paths now catch/log failures instead of leaving unhandled rejections.
+- `findPage` cursor anchors now read nested dot-path sort fields correctly, query read helpers accept `project` as a projection alias, and documentation clarifies ObjectId `maxDepth` conversion limits plus process-level Model registration.
 
 ## Verification
 

docs/en/chaining-api.md

@@ -347,8 +347,8 @@ Chained methods automatically validate parameter types and values:
 .sort({ price: -1 })
 
 //❌ Error - will throw an exception
-.limit(-1)        // Error: limit() requires a non-negative number
-.skip("5")        // Error: skip() requires a non-negative number
+.limit(-1)        // Error: limit() requires a non-negative integer
+.skip("5")        // Error: skip() requires a non-negative integer
 .sort("invalid")  // Error: sort() requires an object or array
 ```
 

docs/en/chaining-methods.md

@@ -241,8 +241,8 @@ const results = await collection('products')
 .skip(5)
 
 //❌ Error - automatically throw exception
-.limit(-1)        // Error: limit() requires a non-negative number
-.skip("invalid")  // Error: skip() requires a non-negative number
+.limit(-1)        // Error: limit() requires a non-negative integer
+.skip("invalid")  // Error: skip() requires a non-negative integer
 .sort("invalid")  // Error: sort() requires an object or array
 ```
 

docs/en/find-and-count.md

@@ -35,7 +35,7 @@ Query criteria, identical to `find()`.
 ### options (Object)
 Query options:
 
-- `projection` (Object) - field projection
+- `projection` / `project` (Object) - field projection. `project` is an alias for `projection`; `projection` wins when both are provided.
 - `sort` (Object) - sort rules
 - `limit` (Number) - maximum number of returned documents (`undefined` means no limit)
 - `skip` (Number) - number of documents to skip

docs/en/find-by-ids.md

@@ -70,7 +70,7 @@ async findByIds(
 |------|------|------|------|
 | `ids` | Array<string \| ObjectId> | ✅ | _id array (supports mixed string and ObjectId) |
 | `options` | Object | ❌ | Query Options |
-| `options.projection` | Object | ❌ | Field projection (same as find) |
+| `options.projection` / `options.project` | Object | ❌ | Field projection (same as find). `project` is an alias for `projection`; `projection` wins when both are provided. |
 | `options.sort` | Object | ❌ | Sort by |
 | `options.cache` | number | ❌ | cache time (milliseconds) |
 | `options.maxTimeMS` | number | ❌ | Query timeout (milliseconds) |
@@ -652,4 +652,3 @@ const users = await collection('users').findByIds(ids, {
 - [find()](./find.md) - Basic query method
 - [findOne()](./findOne.md) - Query a single document
 - [MongoDB official documentation: $in operator](https://www.mongodb.com/docs/manual/reference/operator/query/in/)
-

docs/en/find-one-by-id.md

@@ -66,7 +66,7 @@ async findOneById(id, options = {})
 
 | Parameters | Type | Required | Default value | Description |
 |------|------|------|--------|------|
-| `projection` | Object/Array | No | - | Field projection configuration |
+| `projection` / `project` | Object/Array | No | - | Field projection configuration. `project` is an alias for `projection`; `projection` wins when both are provided. |
 | `cache` | Number | No | `0` | Cache TTL (milliseconds) |
 | `maxTimeMS` | Number | No | Global configuration | Query timeout (milliseconds) |
 | `comment` | String | No | - | Query comments (for log tracking) |

docs/en/find.md

@@ -134,7 +134,7 @@ MongoDB standard query condition object, supporting all MongoDB query operators.
 
 | Parameters | Type | Required | Default | Source | Description |
 |------|------|------|--------|------|------|
-| `projection` | Object/Array | No | - | MongoDB native ✅ | Field projection configuration, specify the returned fields |
+| `projection` / `project` | Object/Array | No | - | MongoDB native ✅ | Field projection configuration, specify the returned fields. `project` is an alias for `projection`; `projection` wins when both are provided. |
 | `sort` | Object | No | - | MongoDB native ✅ | Collation, such as `{ createdAt: -1, name: 1 }` |
 | `limit` | Number | No | Global Configuration | MongoDB Native ✅ | Limit the number of documents returned |
 | `skip` | Number | No | - | MongoDB native ✅ | Skip the specified number of documents (not recommended for large data volumes) |

docs/en/findOne.md

@@ -45,7 +45,7 @@ MongoDB query criteria object. All MongoDB query operators are supported.
 
 | Parameter | Type | Required | Default | Source | Description |
 |------|------|------|--------|------|------|
-| `projection` | Object/Array | No | - | MongoDB native ✅ | Field projection configuration that controls which fields are returned |
+| `projection` / `project` | Object/Array | No | - | MongoDB native ✅ | Field projection configuration that controls which fields are returned. `project` is an alias for `projection`; `projection` wins when both are provided. |
 | `sort` | Object | No | - | MongoDB native ✅ | Sort rules, such as `{ createdAt: -1, name: 1 }` |
 | `hint` | Object/String | No | - | MongoDB native ✅ | Specifies the index to use for the query |
 | `collation` | Object | No | - | MongoDB native ✅ | Specifies collation rules for string comparison and sorting |

docs/en/findPage.md

@@ -37,7 +37,7 @@ async findPage(options = {})
 | `after` | String | No | - | Cursor paging: Get the data after the specified cursor |
 | `before` | String | No | - | Cursor paging: Get the data before the specified cursor |
 | `page` | Number | No | - | Page jump mode: Specify the page number to be obtained (starting from 1) |
-| `projection` | Object/Array | No | - | Field projection: Specifies the fields returned. Supports inclusive type `{ field: 1 }` and exclusive type `{ field: 0 }`, and also supports array form `['field1', 'field2']`. **NOTE**: The sort field is automatically preserved to ensure the cursor is generated correctly, no manual inclusion is required. |
+| `projection` / `project` | Object/Array | No | - | Field projection: Specifies the fields returned. `project` is an alias for `projection`; `projection` wins when both are provided. Supports inclusive type `{ field: 1 }` and exclusive type `{ field: 0 }`, and also supports array form `['field1', 'field2']`. **NOTE**: The sort field is automatically preserved to ensure the cursor is generated correctly, no manual inclusion is required. |
 | `pipeline` | Array | No | `[]` | Additional MongoDB aggregation pipeline stage (only effective for current page data, executed before projection) |
 | `hint` | Object/String | No | - | Specify the index used by the query |
 | `collation` | Object | No | - | Specify collation |
@@ -212,6 +212,7 @@ const page0 = await collection('orders').findPage({
 - The cursor contains the value of the sorting field, and the sorting rules must be consistent
 - When `cursorSecret` is not configured, the cursor is purely Base64url encoded, and the client can decode the content; after configuration, an HMAC-SHA256 signature is appended, and the tampered cursor will be rejected by the server.
 - Cursor comparison restores JSON-round-tripped values before building the MongoDB filter: by default, 24-character hexadecimal strings are treated as ObjectId values, and ISO timestamp-like strings are treated as Date values. Use `cursorTypes` or `cursorValueNormalizer` when a string sort field intentionally contains ObjectId-like or ISO-like values.
+- Cursor anchors read sort values by dot path, so nested sort fields such as `{ 'metrics.rank': 1 }` are supported.
 - Do not splice or modify the cursor on the client side
 - If you need long-term cross-session persistence of the cursor, please also cooperate with the server's own expiration control.