@stacksjs/pagination 0.75.447 → 0.75.451

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -17,7 +17,7 @@ shapes the underlying drivers return.
17
17
  ```ts
18
18
  import { isPaginator, toPaginator } from '@stacksjs/pagination'
19
19
 
20
- const page = toPaginator(rows, { page: 2, perPage: 25, total: 413 })
20
+ const page = toPaginator({ data: rows, meta: { page: 2, perPage: 25, total: 413, lastPage: 17 } })
21
21
 
22
22
  if (isPaginator(value))
23
23
  return Response.json(value)
@@ -25,9 +25,16 @@ if (isPaginator(value))
25
25
 
26
26
  ## Shapes
27
27
 
28
- - `Paginator` — knows `total`, so it can offer "jump to page N". Costs a `COUNT(*)`.
29
- - `SimplePaginator` — knows only whether another page exists.
30
- - `CursorPaginator` — opaque cursors, for tables too large to offset into.
28
+ - `Paginator` - knows `total`, so it can offer "jump to page N". Costs a `COUNT(*)`.
29
+ - `SimplePaginator` - knows only whether another page exists.
30
+ - `CursorPaginator` - opaque cursors, for tables too large to offset into.
31
31
 
32
32
  All three are snake_case, matching Laravel's serialized paginator and the REST
33
33
  convention across the Stacks API.
34
+
35
+ Guards validate all required metadata and the types of optional links, including
36
+ positive safe page integers and nullable offsets. They do not validate rows.
37
+
38
+ BigInt cursors use exact decimal strings, also inside composite JSON arrays.
39
+ The ORM request parser restores composite arrays and preserves decimal strings
40
+ for SQL binding. Clients pass tokens unchanged in the next request URL.
package/dist/index.d.ts CHANGED
@@ -1,9 +1,8 @@
1
- /** Duck-typed shape check — used by the response serializer (P4) to
2
- * detect a paginator-shaped return value from an action. */
1
+ /** Validate all required full-paginator metadata before narrowing. */
3
2
  export declare function isPaginator<T = unknown>(value: unknown): value is Paginator<T>;
4
- /** Duck-typed shape check for the simple paginator. */
3
+ /** Validate the simple paginator without claiming knowledge of a total. */
5
4
  export declare function isSimplePaginator<T = unknown>(value: unknown): value is SimplePaginator<T>;
6
- /** Duck-typed shape check for the cursor paginator. */
5
+ /** Validate both cursor directions and the page-size metadata. */
7
6
  export declare function isCursorPaginator<T = unknown>(value: unknown): value is CursorPaginator<T>;
8
7
  /**
9
8
  * Convert bun-query-builder's `paginate()` output (`{ data, meta:
package/dist/index.js CHANGED
@@ -1,2 +1,2 @@
1
1
  // @bun
2
- 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:Math.max(1,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};
2
+ function a(e){return typeof e==="number"&&Number.isSafeInteger(e)&&e>0}function g(e){return e===null||a(e)}function o(e){return[e.prev_page_url,e.next_page_url].every((n)=>n===void 0||n===null||typeof n==="string")&&(e.path===void 0||typeof e.path==="string")}function f(e){if(e===null||typeof e!=="object")return!1;let n=e;return Array.isArray(n.data)&&a(n.current_page)&&a(n.per_page)&&a(n.last_page)&&typeof n.total==="number"&&Number.isSafeInteger(n.total)&&n.total>=0&&g(n.from)&&g(n.to)&&typeof n.has_more_pages==="boolean"&&o(n)&&[n.first_page_url,n.last_page_url].every((r)=>r===void 0||typeof r==="string")}function m(e){if(e===null||typeof e!=="object")return!1;let n=e;return Array.isArray(n.data)&&a(n.current_page)&&a(n.per_page)&&typeof n.has_more_pages==="boolean"&&!("total"in n)&&o(n)}function b(e){if(e===null||typeof e!=="object")return!1;let n=e;return Array.isArray(n.data)&&a(n.per_page)&&typeof n.has_more_pages==="boolean"&&[n.next_cursor,n.prev_cursor].every((r)=>r===null||typeof r==="string")&&o(n)}function c(e){let{data:n}=e,{perPage:r,page:t,total:l,lastPage:p}=e.meta,u=n.length===0,i=u?null:(t-1)*r+1,_=u?null:i+n.length-1;return{data:n,current_page:t,per_page:r,total:l,last_page:Math.max(1,p),from:i,to:_,has_more_pages:t<p}}function d(e){return{data:e.data,current_page:e.meta.page,per_page:e.meta.perPage,has_more_pages:e.meta.hasMore}}function y(e){return{data:e.data,per_page:e.meta.perPage,next_cursor:s(e.meta.nextCursor),prev_cursor:s(e.meta.prevCursor),has_more_pages:e.meta.nextCursor!==null&&e.meta.nextCursor!==void 0}}function s(e){if(e===null||e===void 0)return null;if(typeof e==="string")return e;if(typeof e==="bigint")return e.toString();let n=JSON.stringify(e,(r,t)=>{if(typeof t==="number"&&!Number.isFinite(t))throw TypeError("Cursor numbers must be finite");return typeof t==="bigint"?t.toString():t});if(n===void 0)throw TypeError("Cursor must be JSON serializable");return n}export{b as isCursorPaginator,f as isPaginator,m as isSimplePaginator,y as toCursorPaginator,c as toPaginator,d as toSimplePaginator};
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@stacksjs/pagination",
3
3
  "type": "module",
4
- "version": "0.75.447",
4
+ "version": "0.75.451",
5
5
  "description": "The paginator shapes the ORM produces and the router serializes.",
6
6
  "author": "Chris Breuer",
7
7
  "contributors": [