@stacksjs/pagination 0.74.4

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+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,33 @@
+# @stacksjs/pagination
+
+The paginator shapes the ORM produces and the router serializes.
+
+It has no dependencies, and that is the point. Both `@stacksjs/orm` and
+`@stacksjs/router` need to agree on what a page of rows looks like: the ORM
+builds one from a query, the router recognises one in a handler's return value
+and serializes it. When the shape lived in the ORM, the router had to depend on
+the ORM to recognise it, while the ORM depends on the router to register the
+routes its models generate - so the two packages depended on each other, and no
+publish order could put one before the other.
+
+Nothing here knows about queries or requests. It is the contract, three
+duck-typed predicates for recognising it, and the adapters that convert the
+shapes the underlying drivers return.
+
+```ts
+import { isPaginator, toPaginator } from '@stacksjs/pagination'
+
+const page = toPaginator(rows, { page: 2, perPage: 25, total: 413 })
+
+if (isPaginator(value))
+  return Response.json(value)
+```
+
+## Shapes
+
+- `Paginator` — knows `total`, so it can offer "jump to page N". Costs a `COUNT(*)`.
+- `SimplePaginator` — knows only whether another page exists.
+- `CursorPaginator` — opaque cursors, for tables too large to offset into.
+
+All three are snake_case, matching Laravel's serialized paginator and the REST
+convention across the Stacks API.

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+/** Duck-typed shape check — used by the response serializer (P4) to
+ *  detect a paginator-shaped return value from an action. */
+export declare function isPaginator<T = unknown>(value: unknown): value is Paginator<T>;
+/** Duck-typed shape check for the simple paginator. */
+export declare function isSimplePaginator<T = unknown>(value: unknown): value is SimplePaginator<T>;
+/** Duck-typed shape check for the cursor paginator. */
+export declare function isCursorPaginator<T = unknown>(value: unknown): value is CursorPaginator<T>;
+/**
+ * Convert bun-query-builder's `paginate()` output (`{ data, meta:
+ * { perPage, page, total, lastPage } }`) into the canonical Stacks
+ * shape. P1 of the migration — the URL fields stay undefined until
+ * P2 wires the request-context resolver.
+ */
+export declare function toPaginator<T>(result: { data: T[], meta: { perPage: number, page: number, total: number, lastPage: number } }): Paginator<T>;
+/** Convert bqb's `simplePaginate()` output to the canonical
+ *  {@link SimplePaginator} shape. */
+export declare function toSimplePaginator<T>(result: { data: T[], meta: { perPage: number, page: number, hasMore: boolean } }): SimplePaginator<T>;
+/** Convert bqb's `cursorPaginate()` output to the canonical
+ *  {@link CursorPaginator} shape. Cursors are serialized to strings
+ *  via JSON — composite cursors (arrays) survive the round-trip. */
+export declare function toCursorPaginator<T>(result: { data: T[], meta: { perPage: number, nextCursor: unknown, prevCursor: unknown } }): CursorPaginator<T>;
+/**
+ * Canonical paginator types + adapters (stacksjs/stacks#1905, P1 from #1910).
+ *
+ * Four pagination shapes used to ship across the framework — bqb's SQL
+ * client `{ data, meta }`, bqb's sync ORM `{ data, total, page, ... }`,
+ * the search-engine's `{ hits, total, page, perPage }`, and a fifth
+ * declared-but-not-implemented Stacks shape (`{ data, paging, next_cursor }`)
+ * that the runtime never actually produced. This module unifies them
+ * to the Laravel-flavored, snake_case shapes below.
+ *
+ * P1 ships only `data` + counts; the URL fields are declared but left
+ * `undefined` by default. P2 (stacksjs/stacks#1906) wires them in when
+ * a request is in scope.
+ *
+ * Shape choices:
+ *   - snake_case for JSON friendliness (matches Laravel's serialized
+ *     paginator + the existing REST convention across the Stacks API)
+ *   - `from` / `to` are 1-indexed offsets of the first/last row on the
+ *     current page; `null` when the page is empty
+ *   - `has_more_pages` is the cheap boolean apps actually want — saves
+ *     `current_page < last_page` checks everywhere
+ */
+/**
+ * Full paginator — knows the total row count so it can compute
+ * `last_page`, supports "jump to page N" UI patterns. Costs an extra
+ * `COUNT(*)` query; use {@link SimplePaginator} or {@link CursorPaginator}
+ * for very large tables.
+ */
+export declare interface Paginator<T> {
+  data: T[]
+  current_page: number
+  per_page: number
+  total: number
+  last_page: number
+  from: number | null
+  to: number | null
+  has_more_pages: boolean
+  prev_page_url?: string | null
+  next_page_url?: string | null
+  first_page_url?: string
+  last_page_url?: string
+  path?: string
+}
+/**
+ * Simple paginator — drops the `COUNT(*)` query. Faster on large tables
+ * but can't render "jump to page 5" UIs since `last_page` / `total` are
+ * unknown. Suitable for infinite-scroll feeds.
+ */
+export declare interface SimplePaginator<T> {
+  data: T[]
+  current_page: number
+  per_page: number
+  has_more_pages: boolean
+  prev_page_url?: string | null
+  next_page_url?: string | null
+  path?: string
+}
+/**
+ * Cursor (keyset) paginator — uses `WHERE id > :cursor` ordering rather
+ * than `LIMIT/OFFSET`, so query cost stays constant regardless of how
+ * deep the user has paged. The trade-off is no random-access ("jump to
+ * page N"); only prev/next.
+ *
+ * Cursor values are opaque to the caller — serialize as JSON, send to
+ * the client, accept back unchanged. Implementations (cursorPaginate)
+ * decide the cursor shape (single column value, base64 tuple for
+ * composite keys, etc.).
+ */
+export declare interface CursorPaginator<T> {
+  data: T[]
+  per_page: number
+  next_cursor: string | null
+  prev_cursor: string | null
+  has_more_pages: boolean
+  prev_page_url?: string | null
+  next_page_url?: string | null
+  path?: string
+}

package/dist/index.js

@@ -0,0 +1,2 @@
+// @bun
+function i(r){if(r===null||typeof r!=="object")return!1;let e=r;return Array.isArray(e.data)&&typeof e.current_page==="number"&&typeof e.per_page==="number"&&typeof e.total==="number"&&typeof e.last_page==="number"}function l(r){if(r===null||typeof r!=="object")return!1;let e=r;return Array.isArray(e.data)&&typeof e.current_page==="number"&&typeof e.per_page==="number"&&typeof e.has_more_pages==="boolean"&&!("total"in e)}function _(r){if(r===null||typeof r!=="object")return!1;let e=r;return Array.isArray(e.data)&&(typeof e.next_cursor==="string"||e.next_cursor===null)}function m(r){let{data:e}=r,{perPage:a,page:n,total:g,lastPage:t}=r.meta,o=e.length===0,u=o?null:(n-1)*a+1,s=o?null:u+e.length-1;return{data:e,current_page:n,per_page:a,total:g,last_page:t,from:u,to:s,has_more_pages:n<t}}function f(r){return{data:r.data,current_page:r.meta.page,per_page:r.meta.perPage,has_more_pages:r.meta.hasMore}}function c(r){return{data:r.data,per_page:r.meta.perPage,next_cursor:p(r.meta.nextCursor),prev_cursor:p(r.meta.prevCursor),has_more_pages:r.meta.nextCursor!==null&&r.meta.nextCursor!==void 0}}function p(r){if(r===null||r===void 0)return null;if(typeof r==="string")return r;return JSON.stringify(r)}export{_ as isCursorPaginator,i as isPaginator,l as isSimplePaginator,c as toCursorPaginator,m as toPaginator,f as toSimplePaginator};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@stacksjs/pagination",
+  "type": "module",
+  "version": "0.74.4",
+  "description": "The paginator shapes the ORM produces and the router serializes.",
+  "author": "Chris Breuer",
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/pagination#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./storage/framework/core/pagination"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stacks/issues"
+  },
+  "keywords": [
+    "pagination",
+    "paginator",
+    "cursor",
+    "stacks"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./dist/index.js",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "import": "./dist/*"
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build.ts",
+    "typecheck": "bun --bun tsc --noEmit"
+  }
+}