@gruvjs/paginator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saiteja Madha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+<div align="center">
+  <br />
+  <p>
+    <a href="https://github.com/gruvjs/gruvjs"><img src="https://raw.githubusercontent.com/gruvjs/gruvjs/main/assets/logo.svg" width="546" alt="gruvjs" /></a>
+  </p>
+  <br />
+  <p>
+    <a href="https://www.npmjs.com/package/@gruvjs/paginator"><img src="https://img.shields.io/npm/v/@gruvjs/paginator.svg?maxAge=3600" alt="npm version" /></a>
+    <a href="https://www.npmjs.com/package/@gruvjs/paginator"><img src="https://img.shields.io/npm/dt/@gruvjs/paginator.svg?maxAge=3600" alt="npm downloads" /></a>
+  </p>
+</div>
+
+## About
+
+`@gruvjs/paginator` is a universal pagination engine for bots and dashboards.
+
+Node.js 18.0.0 or newer is required.
+
+## Installation
+
+```sh
+npm install @gruvjs/paginator
+yarn add @gruvjs/paginator
+pnpm add @gruvjs/paginator
+```
+
+## Examples
+
+```js
+const { paginate, Paginator, fromQuery } = require("@gruvjs/paginator");
+
+// Slice any array
+const result = paginate(items, { page: 2, limit: 10 });
+result.items;       // → items 11–20
+result.totalPages;  // → 5
+result.hasPrev;     // → true
+result.hasNext;     // → true
+
+// Stateful — Discord buttons
+const p = new Paginator({ total: 50, limit: 10 });
+p.next();
+p.buttons(); // → { prev: { disabled: false }, next: { disabled: false }, label: "Page 2 / 5" }
+p.slice(allItems); // → items for current page
+
+// REST API
+const { skip, limit, meta } = fromQuery(req.query, { total: 200 });
+```
+
+See the [docs](./docs) folder for detailed usage.
+
+## Links
+
+- [npm](https://www.npmjs.com/package/@gruvjs/paginator)
+- [GitHub](https://github.com/gruvjs/gruvjs/tree/main/packages/paginator)
+- [gruvjs monorepo](https://github.com/gruvjs/gruvjs)

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@gruvjs/paginator",
+  "version": "1.0.0",
+  "description": "Universal pagination engine for bots and dashboards. Supports arrays, REST APIs and Discord button state.",
+  "main": "src/index.js",
+  "author": "gruvjs",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "pagination",
+    "paginator",
+    "discord",
+    "bot",
+    "dashboard",
+    "rest",
+    "zero-dependency"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gruvjs/gruvjs.git",
+    "directory": "packages/paginator"
+  },
+  "bugs": {
+    "url": "https://github.com/gruvjs/gruvjs/issues"
+  },
+  "homepage": "https://github.com/gruvjs/gruvjs/tree/main/packages/paginator#readme",
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "scripts": {
+    "test": "node tests/run.js"
+  }
+}

package/src/core/fromQuery.js

@@ -0,0 +1,45 @@
+/**
+ * Converts REST query string params to skip/limit values + metadata.
+ * Useful for REST API routes backed by any database.
+ *
+ * @param {object}  query
+ * @param {string|number} [query.page]
+ * @param {string|number} [query.limit]
+ * @param {object}  options
+ * @param {number}  options.total           Total document count (e.g. from db.count())
+ * @param {number}  [options.defaultLimit=20]
+ * @param {number}  [options.maxLimit=100]   Cap on limit to prevent abuse
+ * @returns {{ skip: number, limit: number, page: number, meta: object }}
+ *
+ * @example
+ *   // GET /users?page=2&limit=20
+ *   const { skip, limit, meta } = fromQuery(req.query, { total: 200 });
+ *   const users = await db.users.find({}).skip(skip).limit(limit);
+ *   res.json({ users, meta });
+ */
+function fromQuery(query = {}, options = {}) {
+  const { total = 0, defaultLimit = 20, maxLimit = 100 } = options;
+
+  const limit      = Math.min(Math.max(1, parseInt(query.limit ?? defaultLimit, 10) || defaultLimit), maxLimit);
+  const totalPages = Math.max(1, Math.ceil(total / limit));
+  const page       = Math.min(Math.max(1, parseInt(query.page ?? 1, 10) || 1), totalPages);
+  const skip       = (page - 1) * limit;
+
+  return {
+    skip,
+    limit,
+    page,
+    meta: {
+      page,
+      limit,
+      total,
+      totalPages,
+      hasPrev: page > 1,
+      hasNext: page < totalPages,
+      from:    total === 0 ? 0 : skip + 1,
+      to:      Math.min(skip + limit, total),
+    },
+  };
+}
+
+module.exports = { fromQuery };

package/src/core/paginate.js

@@ -0,0 +1,42 @@
+/**
+ * Slices an array for the given page and returns full pagination metadata.
+ *
+ * @param {Array}   items
+ * @param {object}  [options]
+ * @param {number}  [options.page=1]    1-indexed page number
+ * @param {number}  [options.limit=10]  Items per page
+ * @returns {PaginateResult}
+ *
+ * @typedef {object} PaginateResult
+ * @property {Array}   items
+ * @property {number}  page
+ * @property {number}  limit
+ * @property {number}  total
+ * @property {number}  totalPages
+ * @property {boolean} hasPrev
+ * @property {boolean} hasNext
+ * @property {number}  from   1-indexed position of first item on this page
+ * @property {number}  to     1-indexed position of last item on this page
+ */
+function paginate(items, options = {}) {
+  const total      = items.length;
+  const limit      = Math.max(1, options.limit ?? 10);
+  const totalPages = Math.max(1, Math.ceil(total / limit));
+  const page       = Math.min(Math.max(1, options.page ?? 1), totalPages);
+  const from       = (page - 1) * limit;
+  const to         = Math.min(from + limit, total);
+
+  return {
+    items:      items.slice(from, to),
+    page,
+    limit,
+    total,
+    totalPages,
+    hasPrev:  page > 1,
+    hasNext:  page < totalPages,
+    from:     total === 0 ? 0 : from + 1,
+    to,
+  };
+}
+
+module.exports = { paginate };

package/src/index.js

@@ -0,0 +1,8 @@
+// Core functions
+const { paginate }  = require("./core/paginate");
+const { fromQuery } = require("./core/fromQuery");
+
+// Stateful
+const { Paginator } = require("./stateful/Paginator");
+
+module.exports = { paginate, fromQuery, Paginator };

package/src/stateful/Paginator.js

@@ -0,0 +1,95 @@
+/**
+ * Stateful paginator. Tracks current page and provides Discord button state.
+ *
+ * @example
+ *   const p = new Paginator({ total: 50, limit: 10 });
+ *   p.next();
+ *   p.buttons(); // → { prev: { disabled: false }, next: { disabled: false }, label: "Page 2 / 5" }
+ *   p.slice(allItems); // → items for the current page
+ */
+class Paginator {
+  /**
+   * @param {object} options
+   * @param {number} options.total       Total item count.
+   * @param {number} [options.limit=10]  Items per page.
+   * @param {number} [options.page=1]    Initial page.
+   */
+  constructor(options = {}) {
+    if (typeof options.total !== "number" || options.total < 0) {
+      throw new TypeError("total must be a non-negative number");
+    }
+    this._limit      = Math.max(1, options.limit ?? 10);
+    this._total      = options.total;
+    this._totalPages = Math.max(1, Math.ceil(this._total / this._limit));
+    this._page       = Math.min(Math.max(1, options.page ?? 1), this._totalPages);
+  }
+
+  // ── Navigation ─────────────────────────────────────────────────────────────
+
+  /** Advance to the next page. No-op if already on the last page. */
+  next()     { if (this._page < this._totalPages) this._page++; return this; }
+
+  /** Go back to the previous page. No-op if already on the first page. */
+  prev()     { if (this._page > 1) this._page--; return this; }
+
+  /** Jump to a specific page. Clamped to [1, totalPages]. */
+  goTo(page) { this._page = Math.min(Math.max(1, page), this._totalPages); return this; }
+
+  /** Jump to the first page. */
+  first()    { return this.goTo(1); }
+
+  /** Jump to the last page. */
+  last()     { return this.goTo(this._totalPages); }
+
+  // ── Getters ────────────────────────────────────────────────────────────────
+
+  get page()       { return this._page; }
+  get limit()      { return this._limit; }
+  get total()      { return this._total; }
+  get totalPages() { return this._totalPages; }
+  get hasPrev()    { return this._page > 1; }
+  get hasNext()    { return this._page < this._totalPages; }
+
+  /** 0-indexed offset for the current page. Useful for array slicing. */
+  get offset()     { return (this._page - 1) * this._limit; }
+
+  // ── Helpers ────────────────────────────────────────────────────────────────
+
+  /**
+   * Returns Discord-ready button state for prev/next navigation.
+   * @param {object} [labels]
+   * @param {string} [labels.prev="◀"]
+   * @param {string} [labels.next="▶"]
+   * @returns {{ prev: { disabled: boolean, label: string }, next: { disabled: boolean, label: string }, label: string }}
+   */
+  buttons(labels = {}) {
+    return {
+      prev:  { disabled: !this.hasPrev, label: labels.prev ?? "◀" },
+      next:  { disabled: !this.hasNext, label: labels.next ?? "▶" },
+      label: labels.label ?? `Page ${this._page} / ${this._totalPages}`,
+    };
+  }
+
+  /**
+   * Slices an array for the current page.
+   * @param {Array} items
+   * @returns {Array}
+   */
+  slice(items) {
+    return items.slice(this.offset, this.offset + this._limit);
+  }
+
+  toJSON() {
+    return {
+      page:       this._page,
+      limit:      this._limit,
+      total:      this._total,
+      totalPages: this._totalPages,
+      hasPrev:    this.hasPrev,
+      hasNext:    this.hasNext,
+      offset:     this.offset,
+    };
+  }
+}
+
+module.exports = { Paginator };