@longzai-intelligence/pagination 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,117 @@
+import { FindManyOptions, FindOptionsOrder, ObjectLiteral, Repository, SelectQueryBuilder } from "typeorm";
+
+//#region src/types/pagination.types.d.ts
+type PaginationParams = {
+  page?: number;
+  pageSize?: number;
+};
+type OffsetPaginationParams = {
+  limit?: number;
+  offset?: number;
+};
+type CursorPaginationParams = {
+  cursor?: string;
+  limit?: number;
+};
+declare const PAGINATION_DEFAULTS: {
+  readonly page: 1;
+  readonly pageSize: 20;
+  readonly maxPageSize: 100;
+  readonly minPageSize: 1;
+};
+type PaginationDefaults = typeof PAGINATION_DEFAULTS;
+//#endregion
+//#region src/types/result.types.d.ts
+type PaginatedResult<T> = {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+};
+type OffsetPaginatedResult<T> = {
+  items: T[];
+  total: number;
+  limit: number;
+  offset: number;
+  hasMore: boolean;
+};
+type CursorPaginatedResult<T> = {
+  items: T[];
+  nextCursor: string | null;
+  previousCursor: string | null;
+  hasMore: boolean;
+};
+//#endregion
+//#region src/types/sort.types.d.ts
+type SortOrder = 'asc' | 'desc';
+type SortParams<T extends string = string> = {
+  sortBy?: T;
+  sortOrder?: SortOrder;
+};
+type SortItem<T extends string = string> = {
+  field: T;
+  order: SortOrder;
+};
+type MultiSortParams<T extends string = string> = {
+  sort?: SortItem<T>[];
+};
+//#endregion
+//#region src/utils/pagination.util.d.ts
+type OffsetPaginationResult = {
+  page: number;
+  pageSize: number;
+};
+type PagePaginationResult = {
+  offset: number;
+  limit: number;
+};
+declare function normalizePagination(params?: PaginationParams): Required<PaginationParams>;
+declare function normalizeOffsetPagination(params?: OffsetPaginationParams): Required<OffsetPaginationParams>;
+declare function calculateOffset(page: number, pageSize: number): number;
+declare function calculateTotalPages(total: number, pageSize: number): number;
+declare function hasNextPage(page: number, totalPages: number): boolean;
+declare function hasPreviousPage(page: number): boolean;
+declare function offsetToPage(offset: number, limit: number): OffsetPaginationResult;
+declare function pageToOffset(page: number, pageSize: number): PagePaginationResult;
+declare function createPaginatedResult<T>(items: T[], total: number, page: number, pageSize: number): PaginatedResult<T>;
+//#endregion
+//#region src/utils/validation.util.d.ts
+type PaginationValidationResult = {
+  page: number;
+  pageSize: number;
+};
+type OffsetPaginationValidationResult = {
+  limit: number;
+  offset: number;
+};
+declare function isValidPage(page: unknown): page is number;
+declare function isValidPageSize(pageSize: unknown): pageSize is number;
+declare function isValidOffset(offset: unknown): offset is number;
+declare function isValidLimit(limit: unknown): limit is number;
+declare function isValidPagination(params: unknown): params is PaginationValidationResult;
+declare function isValidOffsetPagination(params: unknown): params is OffsetPaginationValidationResult;
+//#endregion
+//#region src/adapters/typeorm.adapter.d.ts
+type EntityMapper<TEntity, TDto> = (entity: TEntity) => TDto | Promise<TDto>;
+type TypeOrmPaginateOptionsWithMapper<TEntity extends ObjectLiteral, TDto> = {
+  mapper: EntityMapper<TEntity, TDto>;
+  order?: FindOptionsOrder<TEntity>;
+  where?: FindManyOptions<TEntity>['where'];
+  relations?: FindManyOptions<TEntity>['relations'];
+  select?: FindManyOptions<TEntity>['select'];
+};
+type TypeOrmPaginateOptionsNoMapper<TEntity extends ObjectLiteral> = {
+  order?: FindOptionsOrder<TEntity>;
+  where?: FindManyOptions<TEntity>['where'];
+  relations?: FindManyOptions<TEntity>['relations'];
+  select?: FindManyOptions<TEntity>['select'];
+};
+type TypeOrmPaginateOptions<TEntity extends ObjectLiteral, TDto = TEntity> = TypeOrmPaginateOptionsWithMapper<TEntity, TDto> | TypeOrmPaginateOptionsNoMapper<TEntity>;
+declare function paginateWithRepository<TEntity extends ObjectLiteral, TDto = TEntity>(repository: Repository<TEntity>, params: PaginationParams, options?: TypeOrmPaginateOptions<TEntity, TDto>): Promise<PaginatedResult<TEntity | TDto>>;
+declare function paginateWithQueryBuilder<TEntity extends ObjectLiteral, TDto = TEntity>(queryBuilder: SelectQueryBuilder<TEntity>, params: PaginationParams, mapper?: EntityMapper<TEntity, TDto>): Promise<PaginatedResult<TEntity | TDto>>;
+declare function createPaginationQueryBuilder<TEntity extends ObjectLiteral>(repository: Repository<TEntity>, alias?: string): SelectQueryBuilder<TEntity>;
+//#endregion
+export { type CursorPaginatedResult, type CursorPaginationParams, type EntityMapper, type MultiSortParams, type OffsetPaginatedResult, type OffsetPaginationParams, type OffsetPaginationResult, type OffsetPaginationValidationResult, PAGINATION_DEFAULTS, type PagePaginationResult, type PaginatedResult, type PaginationDefaults, type PaginationParams, type PaginationValidationResult, type SortItem, type SortOrder, type SortParams, type TypeOrmPaginateOptions, calculateOffset, calculateTotalPages, createPaginatedResult, createPaginationQueryBuilder, hasNextPage, hasPreviousPage, isValidLimit, isValidOffset, isValidOffsetPagination, isValidPage, isValidPageSize, isValidPagination, normalizeOffsetPagination, normalizePagination, offsetToPage, pageToOffset, paginateWithQueryBuilder, paginateWithRepository };

package/dist/index.mjs

@@ -0,0 +1 @@
+const e={page:1,pageSize:20,maxPageSize:100,minPageSize:1};function t(t){return{page:Math.max(1,Math.floor(t?.page??e.page)),pageSize:Math.min(e.maxPageSize,Math.max(e.minPageSize,Math.floor(t?.pageSize??e.pageSize)))}}function n(t){return{limit:Math.min(e.maxPageSize,Math.max(e.minPageSize,Math.floor(t?.limit??e.pageSize))),offset:Math.max(0,Math.floor(t?.offset??0))}}function r(e,t){return(e-1)*t}function i(e,t){return t<=0?0:Math.ceil(e/t)}function a(e,t){return e<t}function o(e){return e>1}function s(e,t){let n=Math.max(1,t);return{page:Math.floor(e/n)+1,pageSize:n}}function c(e,t){let n=Math.max(1,e),r=Math.max(1,t);return{offset:(n-1)*r,limit:r}}function l(e,t,n,r){let s=i(t,r);return{items:e,total:t,page:n,pageSize:r,totalPages:s,hasNextPage:a(n,s),hasPreviousPage:o(n)}}function u(e){return typeof e==`object`&&!!e}function d(e){return typeof e==`number`&&Number.isInteger(e)&&e>=1}function f(t){return typeof t==`number`&&Number.isInteger(t)&&t>=e.minPageSize&&t<=e.maxPageSize}function p(e){return typeof e==`number`&&Number.isInteger(e)&&e>=0}function m(t){return typeof t==`number`&&Number.isInteger(t)&&t>=e.minPageSize&&t<=e.maxPageSize}function h(e){if(!u(e))return!1;let t=e.page,n=e.pageSize;return(t===void 0||d(t))&&(n===void 0||f(n))}function g(e){if(!u(e))return!1;let t=e.limit,n=e.offset;return(t===void 0||m(t))&&(n===void 0||p(n))}function _(e){return e!==void 0&&`mapper`in e}function v(e,t,n,r){let s=i(t,r);return{items:e,total:t,page:n,pageSize:r,totalPages:s,hasNextPage:a(n,s),hasPreviousPage:o(n)}}async function y(e,n,i){let{page:a,pageSize:o}=t(n),s={skip:r(a,o),take:o,where:i?.where,relations:i?.relations,select:i?.select,order:i?.order??{createdAt:`DESC`}},[c,l]=await e.findAndCount(s);return _(i)?v(await Promise.all(c.map(i.mapper)),l,a,o):v(c,l,a,o)}async function b(e,n,i){let{page:a,pageSize:o}=t(n),s=r(a,o);e.skip(s).take(o);let[c,l]=await e.getManyAndCount();return v(i?await Promise.all(c.map(i)):c,l,a,o)}function x(e,t){return e.createQueryBuilder(t??e.metadata.name.toLowerCase())}export{e as PAGINATION_DEFAULTS,r as calculateOffset,i as calculateTotalPages,l as createPaginatedResult,x as createPaginationQueryBuilder,a as hasNextPage,o as hasPreviousPage,m as isValidLimit,p as isValidOffset,g as isValidOffsetPagination,d as isValidPage,f as isValidPageSize,h as isValidPagination,n as normalizeOffsetPagination,t as normalizePagination,s as offsetToPage,c as pageToOffset,b as paginateWithQueryBuilder,y as paginateWithRepository};

package/eslint.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from '@longzai-intelligence/eslint-preset-library';
+
+export default defineConfig();

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@longzai-intelligence/pagination",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.mts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "build:prod": "NODE_ENV=production tsdown",
+    "prepublishOnly": "bun run build:prod",
+    "dev": "tsdown --watch",
+    "clean": "rimraf dist tsconfig/.cache",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "tsc --noEmit -p tsconfig/app.json",
+    "typecheck:node": "tsc --noEmit -p tsconfig/node.json",
+    "typecheck:test": "tsc --noEmit -p tsconfig/test.json",
+    "upgrade-deps": "ncu -u"
+  },
+  "peerDependencies": {
+    "typeorm": "^0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "typeorm": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.11",
+    "@types/node": "^25.6.0",
+    "eslint": "^10.2.0",
+    "rimraf": "^6.1.3",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4",
+    "@longzai-intelligence/eslint-preset-library": "0.0.5",
+    "@longzai-intelligence/vitest-config": "0.0.5",
+    "@longzai-intelligence/typescript-config": "0.0.3",
+    "tsdown": "^0.21.7",
+    "@longzai-intelligence/tsdown-config": "0.0.1"
+  },
+  "keywords": [
+    "pagination",
+    "typeorm",
+    "typescript"
+  ],
+  "license": "UNLICENSED",
+  "module": "./dist/index.mjs"
+}

package/src/__tests__/index.test.ts

@@ -0,0 +1,66 @@
+/**
+ * @file index.test.ts
+ * 主入口导出测试
+ * @author Longzai Intelligence
+ */
+
+import { describe, it, expect } from 'vitest';
+
+describe('pagination 包导出', () => {
+  it('应正确导出所有类型', async () => {
+    const module = await import('@/index');
+
+    expect(module.PAGINATION_DEFAULTS).toBeDefined();
+    expect(module.PAGINATION_DEFAULTS.page).toBe(1);
+    expect(module.PAGINATION_DEFAULTS.pageSize).toBe(20);
+    expect(module.PAGINATION_DEFAULTS.maxPageSize).toBe(100);
+    expect(module.PAGINATION_DEFAULTS.minPageSize).toBe(1);
+  });
+
+  it('应正确导出所有工具函数', async () => {
+    const module = await import('@/index');
+
+    expect(module.normalizePagination).toBeDefined();
+    expect(module.normalizeOffsetPagination).toBeDefined();
+    expect(module.calculateOffset).toBeDefined();
+    expect(module.calculateTotalPages).toBeDefined();
+    expect(module.hasNextPage).toBeDefined();
+    expect(module.hasPreviousPage).toBeDefined();
+    expect(module.offsetToPage).toBeDefined();
+    expect(module.pageToOffset).toBeDefined();
+    expect(module.createPaginatedResult).toBeDefined();
+  });
+
+  it('应正确导出所有验证函数', async () => {
+    const module = await import('@/index');
+
+    expect(module.isValidPage).toBeDefined();
+    expect(module.isValidPageSize).toBeDefined();
+    expect(module.isValidOffset).toBeDefined();
+    expect(module.isValidLimit).toBeDefined();
+    expect(module.isValidPagination).toBeDefined();
+    expect(module.isValidOffsetPagination).toBeDefined();
+  });
+
+  it('应正确导出所有适配器', async () => {
+    const module = await import('@/index');
+
+    expect(module.paginateWithRepository).toBeDefined();
+    expect(module.paginateWithQueryBuilder).toBeDefined();
+    expect(module.createPaginationQueryBuilder).toBeDefined();
+  });
+
+  it('normalizePagination 应正常工作', async () => {
+    const { normalizePagination } = await import('@/index');
+
+    const result = normalizePagination({ page: 2, pageSize: 50 });
+    expect(result).toEqual({ page: 2, pageSize: 50 });
+  });
+
+  it('calculateOffset 应正常工作', async () => {
+    const { calculateOffset } = await import('@/index');
+
+    expect(calculateOffset(1, 20)).toBe(0);
+    expect(calculateOffset(2, 20)).toBe(20);
+  });
+});

package/src/__tests__/pagination.util.test.ts

@@ -0,0 +1,253 @@
+/**
+ * @file pagination.util.test.ts
+ * 分页计算工具函数测试
+ * @author Longzai Intelligence
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  normalizePagination,
+  normalizeOffsetPagination,
+  calculateOffset,
+  calculateTotalPages,
+  hasNextPage,
+  hasPreviousPage,
+  offsetToPage,
+  pageToOffset,
+  createPaginatedResult,
+} from '@/utils/pagination.util';
+import { PAGINATION_DEFAULTS } from '@/types';
+
+describe('normalizePagination', () => {
+  it('应返回默认值当参数为空时', () => {
+    const result = normalizePagination();
+    expect(result).toEqual({
+      page: PAGINATION_DEFAULTS.page,
+      pageSize: PAGINATION_DEFAULTS.pageSize,
+    });
+  });
+
+  it('应返回默认值当参数为 undefined 时', () => {
+    const result = normalizePagination(undefined);
+    expect(result).toEqual({
+      page: PAGINATION_DEFAULTS.page,
+      pageSize: PAGINATION_DEFAULTS.pageSize,
+    });
+  });
+
+  it('应正确规范化有效的分页参数', () => {
+    const result = normalizePagination({ page: 2, pageSize: 50 });
+    expect(result).toEqual({ page: 2, pageSize: 50 });
+  });
+
+  it('应限制 pageSize 不超过最大值', () => {
+    const result = normalizePagination({ pageSize: 200 });
+    expect(result.pageSize).toBe(PAGINATION_DEFAULTS.maxPageSize);
+  });
+
+  it('应限制 pageSize 不小于最小值', () => {
+    const result = normalizePagination({ pageSize: 0 });
+    expect(result.pageSize).toBe(PAGINATION_DEFAULTS.minPageSize);
+  });
+
+  it('应限制 page 不小于 1', () => {
+    const result = normalizePagination({ page: -1 });
+    expect(result.page).toBe(1);
+  });
+
+  it('应正确处理小数值', () => {
+    const result = normalizePagination({ page: 1.5, pageSize: 10.9 });
+    expect(result).toEqual({ page: 1, pageSize: 10 });
+  });
+
+  it('应正确处理部分参数', () => {
+    const result = normalizePagination({ page: 5 });
+    expect(result).toEqual({ page: 5, pageSize: PAGINATION_DEFAULTS.pageSize });
+  });
+});
+
+describe('normalizeOffsetPagination', () => {
+  it('应返回默认值当参数为空时', () => {
+    const result = normalizeOffsetPagination();
+    expect(result).toEqual({
+      limit: PAGINATION_DEFAULTS.pageSize,
+      offset: 0,
+    });
+  });
+
+  it('应正确规范化有效的 offset 分页参数', () => {
+    const result = normalizeOffsetPagination({ limit: 50, offset: 100 });
+    expect(result).toEqual({ limit: 50, offset: 100 });
+  });
+
+  it('应限制 limit 不超过最大值', () => {
+    const result = normalizeOffsetPagination({ limit: 200 });
+    expect(result.limit).toBe(PAGINATION_DEFAULTS.maxPageSize);
+  });
+
+  it('应限制 limit 不小于最小值', () => {
+    const result = normalizeOffsetPagination({ limit: 0 });
+    expect(result.limit).toBe(PAGINATION_DEFAULTS.minPageSize);
+  });
+
+  it('应限制 offset 不小于 0', () => {
+    const result = normalizeOffsetPagination({ offset: -10 });
+    expect(result.offset).toBe(0);
+  });
+
+  it('应正确处理小数值', () => {
+    const result = normalizeOffsetPagination({ limit: 10.9, offset: 50.5 });
+    expect(result).toEqual({ limit: 10, offset: 50 });
+  });
+});
+
+describe('calculateOffset', () => {
+  it('应正确计算第一页的偏移量', () => {
+    expect(calculateOffset(1, 20)).toBe(0);
+  });
+
+  it('应正确计算第二页的偏移量', () => {
+    expect(calculateOffset(2, 20)).toBe(20);
+  });
+
+  it('应正确计算任意页的偏移量', () => {
+    expect(calculateOffset(5, 10)).toBe(40);
+  });
+
+  it('应正确处理不同的页面大小', () => {
+    expect(calculateOffset(3, 50)).toBe(100);
+  });
+});
+
+describe('calculateTotalPages', () => {
+  it('应正确计算总页数', () => {
+    expect(calculateTotalPages(100, 20)).toBe(5);
+  });
+
+  it('应正确处理有余数的情况', () => {
+    expect(calculateTotalPages(95, 20)).toBe(5);
+  });
+
+  it('应正确处理总数为 0 的情况', () => {
+    expect(calculateTotalPages(0, 20)).toBe(0);
+  });
+
+  it('应正确处理总数小于页面大小的情况', () => {
+    expect(calculateTotalPages(15, 20)).toBe(1);
+  });
+
+  it('应正确处理 pageSize 为 0 的情况', () => {
+    expect(calculateTotalPages(100, 0)).toBe(0);
+  });
+});
+
+describe('hasNextPage', () => {
+  it('应返回 true 当有下一页时', () => {
+    expect(hasNextPage(1, 5)).toBe(true);
+  });
+
+  it('应返回 false 当在最后一页时', () => {
+    expect(hasNextPage(5, 5)).toBe(false);
+  });
+
+  it('应返回 false 当总页数为 0 时', () => {
+    expect(hasNextPage(1, 0)).toBe(false);
+  });
+});
+
+describe('hasPreviousPage', () => {
+  it('应返回 false 当在第一页时', () => {
+    expect(hasPreviousPage(1)).toBe(false);
+  });
+
+  it('应返回 true 当不在第一页时', () => {
+    expect(hasPreviousPage(2)).toBe(true);
+  });
+
+  it('应返回 true 当在大页码时', () => {
+    expect(hasPreviousPage(100)).toBe(true);
+  });
+});
+
+describe('offsetToPage', () => {
+  it('应正确转换 offset 0 到第一页', () => {
+    expect(offsetToPage(0, 20)).toEqual({ page: 1, pageSize: 20 });
+  });
+
+  it('应正确转换 offset 到对应页', () => {
+    expect(offsetToPage(40, 20)).toEqual({ page: 3, pageSize: 20 });
+  });
+
+  it('应正确处理非整除情况', () => {
+    expect(offsetToPage(25, 20)).toEqual({ page: 2, pageSize: 20 });
+  });
+
+  it('应正确处理 limit 为 0 的情况', () => {
+    expect(offsetToPage(0, 0)).toEqual({ page: 1, pageSize: 1 });
+  });
+});
+
+describe('pageToOffset', () => {
+  it('应正确转换第一页到 offset 0', () => {
+    expect(pageToOffset(1, 20)).toEqual({ offset: 0, limit: 20 });
+  });
+
+  it('应正确转换页码到 offset', () => {
+    expect(pageToOffset(3, 20)).toEqual({ offset: 40, limit: 20 });
+  });
+
+  it('应正确处理 page 为 0 的情况', () => {
+    expect(pageToOffset(0, 20)).toEqual({ offset: 0, limit: 20 });
+  });
+
+  it('应正确处理 pageSize 为 0 的情况', () => {
+    expect(pageToOffset(1, 0)).toEqual({ offset: 0, limit: 1 });
+  });
+});
+
+describe('createPaginatedResult', () => {
+  it('应正确创建分页结果', () => {
+    const items = [1, 2, 3];
+    const result = createPaginatedResult(items, 100, 2, 20);
+
+    expect(result).toEqual({
+      items,
+      total: 100,
+      page: 2,
+      pageSize: 20,
+      totalPages: 5,
+      hasNextPage: true,
+      hasPreviousPage: true,
+    });
+  });
+
+  it('应正确处理第一页', () => {
+    const items = [1, 2, 3];
+    const result = createPaginatedResult(items, 100, 1, 20);
+
+    expect(result.hasPreviousPage).toBe(false);
+    expect(result.hasNextPage).toBe(true);
+  });
+
+  it('应正确处理最后一页', () => {
+    const items = [1, 2, 3];
+    const result = createPaginatedResult(items, 100, 5, 20);
+
+    expect(result.hasPreviousPage).toBe(true);
+    expect(result.hasNextPage).toBe(false);
+  });
+
+  it('应正确处理空结果', () => {
+    const result = createPaginatedResult([], 0, 1, 20);
+
+    expect(result).toEqual({
+      items: [],
+      total: 0,
+      page: 1,
+      pageSize: 20,
+      totalPages: 0,
+      hasNextPage: false,
+      hasPreviousPage: false,
+    });
+  });
+});