@r5v/mongoose-paginate 1.0.16 → 1.0.18

package/README.md

@@ -6,6 +6,11 @@ Simple, Fast, Efficient
 
 This project was designed to accomodate more than 80% of your daily workflow to remove the overhead of boilerplate code in handling each endpoint and keeping queries and query params simple. We didn't want you to have to learn a new language to use this product
 
+## Requirements
+- Node.js >= 20
+- mongoose >= 8.0.0 (peer dependency)
+  - Tested with: 8.16.0, 9.1.4
+
 ## Basic Usage
 
 ### PagingQuery
@@ -307,6 +312,52 @@ $ yarn run start
 9. Apply pagination (`$skip`, `$limit`) and options
 
 
+## Versioning and releasing
+
+The package follows [semver](https://semver.org). The version in `package.json` is the only version; it is bumped in its own commit (`chore: bump version to X.Y.Z`) and every release gets an entry in the changelog below.
+
+**What each part means**
+
+| Bump | When | Examples |
+|:--|:--|:--|
+| patch `1.0.x` | Bug fixes, docs, and type fixes that do not narrow what consumers can already write | `exec()` returns `Promise<any>` again; a regex bug in populate parsing |
+| minor `1.x.0` | New options, parameters, exports or utilities; anything additive | a new `allowedOperators` option |
+| major `x.0.0` | Anything that can break a consumer's build **or** behaviour | removing a parameter (`$includes`), changing a default, raising the minimum `mongoose` or Node version, **narrowing a public type** (`any` to `unknown`, a stricter argument type) |
+
+Types are part of the public API. A change that makes a consumer's TypeScript stop compiling is a breaking change even if the runtime is identical. Consumers pin `^1.0.x`, so a breaking change shipped as a patch reaches them on the next install.
+
+**Release steps** (from a clean `main`, after the PR is merged)
+
+```text
+$ git checkout main && git pull
+$ npm version patch --no-git-tag-version      # or: minor / major
+$ git commit -am "chore: bump version to X.Y.Z"
+$ git push
+$ npm install
+$ npm test                                    # must be green
+$ npm run build                               # prebuild clears dist/, postbuild copies package.json + README into it
+$ npm pack --dry-run                          # check the file list: package.json, README.md, dist/**
+$ npm login                                   # once per machine; opens the browser
+$ npm publish --access public                 # add --otp=123456 if npm asks for a code
+$ npm view @r5v/mongoose-paginate version     # confirm X.Y.Z is live
+```
+
+Notes:
+- Publish only after `npm run build`. There is no `prepublishOnly` script, and `dist/` is what consumers get (`files` in `package.json`).
+- Update the changelog in the same PR as the change, under the version it will ship as.
+- Before a release that touches types or parsing, run the consuming app (`theshopkeeper`) against the built `dist/`: copy it over `node_modules/@r5v/mongoose-paginate/dist`, then run its `tsc` and tests. The 1.0.14 narrowing of `exec()` to `unknown` was only caught this way.
+- A published version cannot be changed or re-used. If a release is wrong, publish a fixed patch and `npm deprecate @r5v/mongoose-paginate@X.Y.Z "use X.Y.Z+1"`.
+- Optional: `git tag vX.Y.Z && git push --tags` after publishing. There are no tags in the repository yet.
+
+## Changelog
+
+### 1.0.18
+  - **Fixed `exec()` return type** - `PagingQuery.exec()` and `AggregationPagingQuery.exec()` return `Promise<any>` again. 1.0.14 through 1.0.17 narrowed it to `Promise<unknown>`, which stopped consumers that use the result (for example `res.send(await query.exec())` typed against a response body) from compiling. Runtime behaviour is unchanged.
+
+### 1.0.17
+  - **Moved mongoose to peerDependencies** - Reduces bundle size for consumers who already have mongoose installed
+  - Supports mongoose >= 8.0.0 (tested with 8.16.0 and 9.1.4)
+
 ### 1.0.15
   - **Re-enabled `removeProtected` option** for `AggregationPagingQuery` (EXPERIMENTAL) - Automatically excludes fields marked with `select: false` in your schema (e.g., passwords, secret keys) from aggregation results. Use with caution and test thoroughly in your environment.
   - Uses refactored `findProtectedPaths` utility which safely traverses schemas without JSON serialization

package/dist/README.md

@@ -6,6 +6,11 @@ Simple, Fast, Efficient
 
 This project was designed to accomodate more than 80% of your daily workflow to remove the overhead of boilerplate code in handling each endpoint and keeping queries and query params simple. We didn't want you to have to learn a new language to use this product
 
+## Requirements
+- Node.js >= 20
+- mongoose >= 8.0.0 (peer dependency)
+  - Tested with: 8.16.0, 9.1.4
+
 ## Basic Usage
 
 ### PagingQuery
@@ -307,6 +312,52 @@ $ yarn run start
 9. Apply pagination (`$skip`, `$limit`) and options
 
 
+## Versioning and releasing
+
+The package follows [semver](https://semver.org). The version in `package.json` is the only version; it is bumped in its own commit (`chore: bump version to X.Y.Z`) and every release gets an entry in the changelog below.
+
+**What each part means**
+
+| Bump | When | Examples |
+|:--|:--|:--|
+| patch `1.0.x` | Bug fixes, docs, and type fixes that do not narrow what consumers can already write | `exec()` returns `Promise<any>` again; a regex bug in populate parsing |
+| minor `1.x.0` | New options, parameters, exports or utilities; anything additive | a new `allowedOperators` option |
+| major `x.0.0` | Anything that can break a consumer's build **or** behaviour | removing a parameter (`$includes`), changing a default, raising the minimum `mongoose` or Node version, **narrowing a public type** (`any` to `unknown`, a stricter argument type) |
+
+Types are part of the public API. A change that makes a consumer's TypeScript stop compiling is a breaking change even if the runtime is identical. Consumers pin `^1.0.x`, so a breaking change shipped as a patch reaches them on the next install.
+
+**Release steps** (from a clean `main`, after the PR is merged)
+
+```text
+$ git checkout main && git pull
+$ npm version patch --no-git-tag-version      # or: minor / major
+$ git commit -am "chore: bump version to X.Y.Z"
+$ git push
+$ npm install
+$ npm test                                    # must be green
+$ npm run build                               # prebuild clears dist/, postbuild copies package.json + README into it
+$ npm pack --dry-run                          # check the file list: package.json, README.md, dist/**
+$ npm login                                   # once per machine; opens the browser
+$ npm publish --access public                 # add --otp=123456 if npm asks for a code
+$ npm view @r5v/mongoose-paginate version     # confirm X.Y.Z is live
+```
+
+Notes:
+- Publish only after `npm run build`. There is no `prepublishOnly` script, and `dist/` is what consumers get (`files` in `package.json`).
+- Update the changelog in the same PR as the change, under the version it will ship as.
+- Before a release that touches types or parsing, run the consuming app (`theshopkeeper`) against the built `dist/`: copy it over `node_modules/@r5v/mongoose-paginate/dist`, then run its `tsc` and tests. The 1.0.14 narrowing of `exec()` to `unknown` was only caught this way.
+- A published version cannot be changed or re-used. If a release is wrong, publish a fixed patch and `npm deprecate @r5v/mongoose-paginate@X.Y.Z "use X.Y.Z+1"`.
+- Optional: `git tag vX.Y.Z && git push --tags` after publishing. There are no tags in the repository yet.
+
+## Changelog
+
+### 1.0.18
+  - **Fixed `exec()` return type** - `PagingQuery.exec()` and `AggregationPagingQuery.exec()` return `Promise<any>` again. 1.0.14 through 1.0.17 narrowed it to `Promise<unknown>`, which stopped consumers that use the result (for example `res.send(await query.exec())` typed against a response body) from compiling. Runtime behaviour is unchanged.
+
+### 1.0.17
+  - **Moved mongoose to peerDependencies** - Reduces bundle size for consumers who already have mongoose installed
+  - Supports mongoose >= 8.0.0 (tested with 8.16.0 and 9.1.4)
+
 ### 1.0.15
   - **Re-enabled `removeProtected` option** for `AggregationPagingQuery` (EXPERIMENTAL) - Automatically excludes fields marked with `select: false` in your schema (e.g., passwords, secret keys) from aggregation results. Use with caution and test thoroughly in your environment.
   - Uses refactored `findProtectedPaths` utility which safely traverses schemas without JSON serialization

package/dist/aggregationPagingQuery.d.ts

@@ -19,6 +19,6 @@ export declare class AggregationPagingQuery {
     initQuery: () => Promise<void>;
     typeCastObject: <T>(strOrObj: T) => T;
     private removeProtectedFields;
-    exec: () => Promise<unknown>;
+    exec: () => Promise<any>;
 }
 //# sourceMappingURL=aggregationPagingQuery.d.ts.map

package/dist/aggregationPagingQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregationPagingQuery.d.ts","sourceRoot":"","sources":["../src/aggregationPagingQuery.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,EACL,SAAS,EAKZ,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAC,qBAAqB,EAAE,iCAAiC,EAAE,WAAW,EAAC,MAAM,SAAS,CAAA;AAQlG,qBAAa,sBAAsB;IAC/B,MAAM,EAAG,iCAAiC,CAYzC;IACD,OAAO,EAAE,qBAAqB,CAM7B;IACD,KAAK,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,CAAA;IACvC,cAAc,EAAE,MAAM,EAAE,CAAK;IAC7B,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;gBACL,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,qBAAqB;IAoB/E,kBAAkB,kCAAqB;IACvC,WAAW,sPAAc;IACzB,iBAAiB,6BAAoB;IACrC,YAAY,2BAAe;IAC3B,eAAe,mEAAkB;IACjC,wBAAwB;;MAA2B;IACnD,YAAY,aAOX;IACD,SAAS,sBAsDR;IACD,cAAc,GAAI,CAAC,EAAE,UAAU,CAAC,KAAG,CAAC,CAmCnC;IAED,OAAO,CAAC,qBAAqB,CAS5B;IACD,IAAI,yBAgCH;CAEJ"}
+{"version":3,"file":"aggregationPagingQuery.d.ts","sourceRoot":"","sources":["../src/aggregationPagingQuery.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,EACL,SAAS,EAKZ,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAC,qBAAqB,EAAE,iCAAiC,EAAE,WAAW,EAAC,MAAM,SAAS,CAAA;AAQlG,qBAAa,sBAAsB;IAC/B,MAAM,EAAG,iCAAiC,CAYzC;IACD,OAAO,EAAE,qBAAqB,CAM7B;IACD,KAAK,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,CAAA;IACvC,cAAc,EAAE,MAAM,EAAE,CAAK;IAC7B,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;gBACL,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,qBAAqB;IAoB/E,kBAAkB,kCAAqB;IACvC,WAAW,sPAAc;IACzB,iBAAiB,6BAAoB;IACrC,YAAY,2BAAe;IAC3B,eAAe,mEAAkB;IACjC,wBAAwB;;MAA2B;IACnD,YAAY,aAOX;IACD,SAAS,sBAsDR;IACD,cAAc,GAAI,CAAC,EAAE,UAAU,CAAC,KAAG,CAAC,CAmCnC;IAED,OAAO,CAAC,qBAAqB,CAS5B;IAED,IAAI,QAAa,OAAO,CAAC,GAAG,CAAC,CAgC5B;CAEJ"}

package/dist/aggregationPagingQuery.js

@@ -151,6 +151,7 @@ class AggregationPagingQuery {
                 this.query.project(projections);
             }
         };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.exec = () => __awaiter(this, void 0, void 0, function* () {
             const { $skip, $limit, $paging, $filter } = this.params;
             const { disablePaging } = this.options;

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@r5v/mongoose-paginate",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -58,13 +58,16 @@
   "engines": {
     "node": ">=20"
   },
+  "peerDependencies": {
+    "mongoose": ">=8.0.0"
+  },
   "dependencies": {
-    "mongoose": "^8.16.1",
     "qs": "^6.14.0"
   },
   "description": "A lightweight Node.js package that seamlessly bridges RESTful API query parameters to Mongoose operations. Automatically parses and transforms URL query strings into valid Mongoose queries, supporting filtering, sorting, pagination, field selection, and population. Simply pass your Express req.query object and get back a fully configured Mongoose query ready for execution. Perfect for rapidly building consistent, feature-rich APIs without repetitive query parsing logic",
   "devDependencies": {
     "@types/express": "^5.0.3",
+    "mongoose": "^9.1.4",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.0.10",
     "concurrently": "^9.2.0",

package/dist/pagingQuery.d.ts

@@ -10,6 +10,6 @@ export declare class PagingQuery {
     private initQuery;
     parseSortString: (sortString: string) => [string, SortOrder][];
     parseParams: (defaultParams: PagingQueryParsedRequestParams | import("./types").AggregateQueryParsedRequestParams, params: import("qs").ParsedQs, isAggregate?: boolean) => PagingQueryParsedRequestParams | import("./types").AggregateQueryParsedRequestParams;
-    exec: () => Promise<unknown>;
+    exec: () => Promise<any>;
 }
 //# sourceMappingURL=pagingQuery.d.ts.map

package/dist/pagingQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagingQuery.d.ts","sourceRoot":"","sources":["../src/pagingQuery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,8BAA8B,EAAE,kBAAkB,EAAE,WAAW,EAAC,MAAM,SAAS,CAAA;AAC5F,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAC,MAAM,UAAU,CAAC;AAS7D,qBAAa,WAAW;IACpB,MAAM,EAAE,8BAA8B,CASrC;IACD,OAAO,EAAE,kBAAkB,CAAK;IAChC,KAAK,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,IAAI,CAAO;IACvD,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;gBAEL,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,GAAE,OAAO,CAAC,kBAAkB,CAAM;IAY1F,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,SAAS,CAqChB;IACD,eAAe,gDAAkB;IACjC,WAAW,sPAAc;IACzB,IAAI,yBAuBH;CACJ"}
+{"version":3,"file":"pagingQuery.d.ts","sourceRoot":"","sources":["../src/pagingQuery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,8BAA8B,EAAE,kBAAkB,EAAE,WAAW,EAAC,MAAM,SAAS,CAAA;AAC5F,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAC,MAAM,UAAU,CAAC;AAS7D,qBAAa,WAAW;IACpB,MAAM,EAAE,8BAA8B,CASrC;IACD,OAAO,EAAE,kBAAkB,CAAK;IAChC,KAAK,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,IAAI,CAAO;IACvD,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;gBAEL,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,GAAE,OAAO,CAAC,kBAAkB,CAAM;IAY1F,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,SAAS,CAqChB;IACD,eAAe,gDAAkB;IACjC,WAAW,sPAAc;IAEzB,IAAI,QAAa,OAAO,CAAC,GAAG,CAAC,CAuB5B;CACJ"}

package/dist/pagingQuery.js

@@ -75,6 +75,7 @@ class PagingQuery {
         };
         this.parseSortString = parseSortString_1.parseSortString;
         this.parseParams = parseParams_1.parseParams;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.exec = () => __awaiter(this, void 0, void 0, function* () {
             const { $skip, $limit, $paging, $filter } = this.params;
             const { staticFilter } = this.options;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@r5v/mongoose-paginate",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -58,13 +58,16 @@
   "engines": {
     "node": ">=20"
   },
+  "peerDependencies": {
+    "mongoose": ">=8.0.0"
+  },
   "dependencies": {
-    "mongoose": "^8.16.1",
     "qs": "^6.14.0"
   },
   "description": "A lightweight Node.js package that seamlessly bridges RESTful API query parameters to Mongoose operations. Automatically parses and transforms URL query strings into valid Mongoose queries, supporting filtering, sorting, pagination, field selection, and population. Simply pass your Express req.query object and get back a fully configured Mongoose query ready for execution. Perfect for rapidly building consistent, feature-rich APIs without repetitive query parsing logic",
   "devDependencies": {
     "@types/express": "^5.0.3",
+    "mongoose": "^9.1.4",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.0.10",
     "concurrently": "^9.2.0",