@longzai-intelligence/pagination 0.0.1

package/src/__tests__/typeorm.adapter.test.ts

@@ -0,0 +1,214 @@
+/**
+ * @file typeorm.adapter.test.ts
+ * TypeORM 适配器测试
+ * @author Longzai Intelligence
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  paginateWithRepository,
+  paginateWithQueryBuilder,
+  createPaginationQueryBuilder,
+} from '@/adapters/typeorm.adapter';
+import type { Repository, SelectQueryBuilder, FindOptionsOrder } from 'typeorm';
+
+/**
+ * 测试实体类型
+ *
+ * 用于测试的简单实体定义
+ */
+type TestEntity = {
+  id: number;
+  name?: string;
+  status?: string;
+  createdAt?: Date;
+};
+
+/**
+ * 映射后的 DTO 类型
+ */
+type MappedDto = {
+  mapped: TestEntity;
+};
+
+/**
+ * 创建模拟的 Repository
+ *
+ * @returns 模拟的 Repository 对象
+ */
+function createMockRepository(): Repository<TestEntity> {
+  return {
+    findAndCount: vi.fn(),
+    createQueryBuilder: vi.fn(),
+    metadata: {
+      name: 'TestEntity',
+    },
+  } as Repository<TestEntity>;
+}
+
+/**
+ * 创建模拟的 QueryBuilder
+ *
+ * @returns 模拟的 QueryBuilder 对象
+ */
+function createMockQueryBuilder(): SelectQueryBuilder<TestEntity> {
+  return {
+    skip: vi.fn().mockReturnThis(),
+    take: vi.fn().mockReturnThis(),
+    getManyAndCount: vi.fn(),
+  } as SelectQueryBuilder<TestEntity>;
+}
+
+describe('paginateWithRepository', () => {
+  it('应正确执行分页查询', async () => {
+    const mockRepository = createMockRepository();
+
+    const mockEntities: TestEntity[] = [{ id: 1 }, { id: 2 }];
+    vi.mocked(mockRepository.findAndCount).mockResolvedValue([mockEntities, 10]);
+
+    const result = await paginateWithRepository(mockRepository, { page: 1, pageSize: 10 });
+
+    expect(result).toEqual({
+      items: mockEntities,
+      total: 10,
+      page: 1,
+      pageSize: 10,
+      totalPages: 1,
+      hasNextPage: false,
+      hasPreviousPage: false,
+    });
+  });
+
+  it('应正确使用自定义映射函数', async () => {
+    const mockRepository = createMockRepository();
+
+    const mockEntities: TestEntity[] = [{ id: 1 }, { id: 2 }];
+    vi.mocked(mockRepository.findAndCount).mockResolvedValue([mockEntities, 10]);
+
+    const mapper = (entity: TestEntity): MappedDto => ({ mapped: entity });
+    const result = await paginateWithRepository(
+      mockRepository,
+      { page: 1, pageSize: 10 },
+      {
+        mapper,
+      },
+    );
+
+    expect(result.items).toEqual([{ mapped: { id: 1 } }, { mapped: { id: 2 } }]);
+  });
+
+  it('应正确处理分页参数', async () => {
+    const mockRepository = createMockRepository();
+
+    const mockEntities: TestEntity[] = [{ id: 1 }];
+    vi.mocked(mockRepository.findAndCount).mockResolvedValue([mockEntities, 100]);
+
+    const result = await paginateWithRepository(mockRepository, { page: 2, pageSize: 20 });
+
+    expect(result.page).toBe(2);
+    expect(result.pageSize).toBe(20);
+    expect(result.totalPages).toBe(5);
+    expect(result.hasNextPage).toBe(true);
+    expect(result.hasPreviousPage).toBe(true);
+  });
+
+  it('应正确使用查询选项', async () => {
+    const mockRepository = createMockRepository();
+
+    const mockEntities: TestEntity[] = [{ id: 1 }];
+    vi.mocked(mockRepository.findAndCount).mockResolvedValue([mockEntities, 10]);
+
+    const options = {
+      where: { status: 'active' },
+      order: { createdAt: 'DESC' } as FindOptionsOrder<TestEntity>,
+      relations: ['user'],
+      select: ['id', 'name'],
+    };
+
+    await paginateWithRepository(mockRepository, { page: 1, pageSize: 10 }, options);
+
+    expect(mockRepository.findAndCount).toHaveBeenCalledWith(
+      expect.objectContaining({
+        skip: 0,
+        take: 10,
+        where: options.where,
+        order: options.order,
+        relations: options.relations,
+        select: options.select,
+      }),
+    );
+  });
+});
+
+describe('paginateWithQueryBuilder', () => {
+  it('应正确执行分页查询', async () => {
+    const mockQueryBuilder = createMockQueryBuilder();
+
+    const mockEntities: TestEntity[] = [{ id: 1 }, { id: 2 }];
+    vi.mocked(mockQueryBuilder.getManyAndCount).mockResolvedValue([mockEntities, 10]);
+
+    const result = await paginateWithQueryBuilder(mockQueryBuilder, { page: 1, pageSize: 10 });
+
+    expect(result).toEqual({
+      items: mockEntities,
+      total: 10,
+      page: 1,
+      pageSize: 10,
+      totalPages: 1,
+      hasNextPage: false,
+      hasPreviousPage: false,
+    });
+  });
+
+  it('应正确使用自定义映射函数', async () => {
+    const mockQueryBuilder = createMockQueryBuilder();
+
+    const mockEntities: TestEntity[] = [{ id: 1 }, { id: 2 }];
+    vi.mocked(mockQueryBuilder.getManyAndCount).mockResolvedValue([mockEntities, 10]);
+
+    const mapper = (entity: TestEntity): MappedDto => ({ mapped: entity });
+    const result = await paginateWithQueryBuilder(
+      mockQueryBuilder,
+      { page: 1, pageSize: 10 },
+      mapper,
+    );
+
+    expect(result.items).toEqual([{ mapped: { id: 1 } }, { mapped: { id: 2 } }]);
+  });
+
+  it('应正确设置 skip 和 take', async () => {
+    const mockQueryBuilder = createMockQueryBuilder();
+
+    vi.mocked(mockQueryBuilder.getManyAndCount).mockResolvedValue([[], 0]);
+
+    await paginateWithQueryBuilder(mockQueryBuilder, { page: 2, pageSize: 20 });
+
+    expect(mockQueryBuilder.skip).toHaveBeenCalledWith(20);
+    expect(mockQueryBuilder.take).toHaveBeenCalledWith(20);
+  });
+});
+
+describe('createPaginationQueryBuilder', () => {
+  it('应正确创建 QueryBuilder', () => {
+    const mockQueryBuilder = createMockQueryBuilder();
+
+    const mockRepository = createMockRepository();
+    vi.mocked(mockRepository.createQueryBuilder).mockReturnValue(mockQueryBuilder);
+
+    const result = createPaginationQueryBuilder(mockRepository);
+
+    expect(result).toBe(mockQueryBuilder);
+    expect(mockRepository.createQueryBuilder).toHaveBeenCalled();
+  });
+
+  it('应使用自定义别名', () => {
+    const mockQueryBuilder = createMockQueryBuilder();
+
+    const mockRepository = createMockRepository();
+    vi.mocked(mockRepository.createQueryBuilder).mockReturnValue(mockQueryBuilder);
+
+    createPaginationQueryBuilder(mockRepository, 'custom_alias');
+
+    expect(mockRepository.createQueryBuilder).toHaveBeenCalledWith('custom_alias');
+  });
+});

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

@@ -0,0 +1,122 @@
+/**
+ * @file validation.util.test.ts
+ * 分页参数验证工具函数测试
+ * @author Longzai Intelligence
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  isValidPage,
+  isValidPageSize,
+  isValidOffset,
+  isValidLimit,
+  isValidPagination,
+  isValidOffsetPagination,
+} from '@/utils/validation.util';
+import { PAGINATION_DEFAULTS } from '@/types';
+
+describe('isValidPage', () => {
+  it('应返回 true 对于有效的页码', () => {
+    expect(isValidPage(1)).toBe(true);
+    expect(isValidPage(10)).toBe(true);
+    expect(isValidPage(1000)).toBe(true);
+  });
+
+  it('应返回 false 对于无效的页码', () => {
+    expect(isValidPage(0)).toBe(false);
+    expect(isValidPage(-1)).toBe(false);
+    expect(isValidPage(1.5)).toBe(false);
+    expect(isValidPage('1')).toBe(false);
+    expect(isValidPage(null)).toBe(false);
+    expect(isValidPage(undefined)).toBe(false);
+    expect(isValidPage(NaN)).toBe(false);
+  });
+});
+
+describe('isValidPageSize', () => {
+  it('应返回 true 对于有效的页面大小', () => {
+    expect(isValidPageSize(1)).toBe(true);
+    expect(isValidPageSize(20)).toBe(true);
+    expect(isValidPageSize(PAGINATION_DEFAULTS.maxPageSize)).toBe(true);
+  });
+
+  it('应返回 false 对于无效的页面大小', () => {
+    expect(isValidPageSize(0)).toBe(false);
+    expect(isValidPageSize(-1)).toBe(false);
+    expect(isValidPageSize(PAGINATION_DEFAULTS.maxPageSize + 1)).toBe(false);
+    expect(isValidPageSize(1.5)).toBe(false);
+    expect(isValidPageSize('20')).toBe(false);
+    expect(isValidPageSize(null)).toBe(false);
+    expect(isValidPageSize(undefined)).toBe(false);
+  });
+});
+
+describe('isValidOffset', () => {
+  it('应返回 true 对于有效的偏移量', () => {
+    expect(isValidOffset(0)).toBe(true);
+    expect(isValidOffset(10)).toBe(true);
+    expect(isValidOffset(1000)).toBe(true);
+  });
+
+  it('应返回 false 对于无效的偏移量', () => {
+    expect(isValidOffset(-1)).toBe(false);
+    expect(isValidOffset(1.5)).toBe(false);
+    expect(isValidOffset('10')).toBe(false);
+    expect(isValidOffset(null)).toBe(false);
+    expect(isValidOffset(undefined)).toBe(false);
+  });
+});
+
+describe('isValidLimit', () => {
+  it('应返回 true 对于有效的限制数量', () => {
+    expect(isValidLimit(1)).toBe(true);
+    expect(isValidLimit(20)).toBe(true);
+    expect(isValidLimit(PAGINATION_DEFAULTS.maxPageSize)).toBe(true);
+  });
+
+  it('应返回 false 对于无效的限制数量', () => {
+    expect(isValidLimit(0)).toBe(false);
+    expect(isValidLimit(-1)).toBe(false);
+    expect(isValidLimit(PAGINATION_DEFAULTS.maxPageSize + 1)).toBe(false);
+    expect(isValidLimit(1.5)).toBe(false);
+    expect(isValidLimit('20')).toBe(false);
+    expect(isValidLimit(null)).toBe(false);
+    expect(isValidLimit(undefined)).toBe(false);
+  });
+});
+
+describe('isValidPagination', () => {
+  it('应返回 true 对于有效的分页参数', () => {
+    expect(isValidPagination({ page: 1, pageSize: 20 })).toBe(true);
+    expect(isValidPagination({ page: 5 })).toBe(true);
+    expect(isValidPagination({ pageSize: 50 })).toBe(true);
+    expect(isValidPagination({})).toBe(true);
+  });
+
+  it('应返回 false 对于无效的分页参数', () => {
+    expect(isValidPagination(null)).toBe(false);
+    expect(isValidPagination('string')).toBe(false);
+    expect(isValidPagination(123)).toBe(false);
+    expect(isValidPagination({ page: -1 })).toBe(false);
+    expect(isValidPagination({ pageSize: 0 })).toBe(false);
+    expect(isValidPagination({ page: 1.5 })).toBe(false);
+  });
+});
+
+describe('isValidOffsetPagination', () => {
+  it('应返回 true 对于有效的 offset 分页参数', () => {
+    expect(isValidOffsetPagination({ limit: 20, offset: 0 })).toBe(true);
+    expect(isValidOffsetPagination({ limit: 50 })).toBe(true);
+    expect(isValidOffsetPagination({ offset: 100 })).toBe(true);
+    expect(isValidOffsetPagination({})).toBe(true);
+  });
+
+  it('应返回 false 对于无效的 offset 分页参数', () => {
+    expect(isValidOffsetPagination(null)).toBe(false);
+    expect(isValidOffsetPagination('string')).toBe(false);
+    expect(isValidOffsetPagination(123)).toBe(false);
+    expect(isValidOffsetPagination({ offset: -1 })).toBe(false);
+    expect(isValidOffsetPagination({ limit: 0 })).toBe(false);
+    expect(isValidOffsetPagination({ limit: 1.5 })).toBe(false);
+  });
+});

package/src/adapters/index.ts

@@ -0,0 +1,11 @@
+/**
+ * 适配器导出入口
+ */
+
+export type { EntityMapper, TypeOrmPaginateOptions } from './typeorm.adapter';
+
+export {
+  paginateWithRepository,
+  paginateWithQueryBuilder,
+  createPaginationQueryBuilder,
+} from './typeorm.adapter';

package/src/adapters/typeorm.adapter.ts

@@ -0,0 +1,285 @@
+/**
+ * TypeORM 分页适配器
+ *
+ * 注意：此模块需要安装 typeorm 作为 peerDependency
+ */
+
+import type {
+  Repository,
+  SelectQueryBuilder,
+  ObjectLiteral,
+  FindManyOptions,
+  FindOptionsOrder,
+} from 'typeorm';
+import type { PaginationParams, PaginatedResult } from '../types';
+import {
+  normalizePagination,
+  calculateOffset,
+  calculateTotalPages,
+  hasNextPage,
+  hasPreviousPage,
+} from '../utils';
+
+/**
+ * 实体映射器函数类型
+ *
+ * 将实体类型转换为 DTO 类型的映射函数
+ *
+ * @typeParam TEntity - 实体类型
+ * @typeParam TDto - DTO 类型
+ */
+export type EntityMapper<TEntity, TDto> = (entity: TEntity) => TDto | Promise<TDto>;
+
+/**
+ * TypeORM 分页查询选项（带映射器）
+ *
+ * 配置 TypeORM 分页查询的选项，必须提供映射函数
+ *
+ * @typeParam TEntity - 实体类型
+ * @typeParam TDto - DTO 类型
+ */
+export type TypeOrmPaginateOptionsWithMapper<TEntity extends ObjectLiteral, TDto> = {
+  /**
+   * 实体到 DTO 的映射函数
+   *
+   * 必须提供映射函数以确保类型安全
+   */
+  mapper: EntityMapper<TEntity, TDto>;
+
+  /**
+   * 排序规则
+   */
+  order?: FindOptionsOrder<TEntity>;
+
+  /**
+   * 查询条件
+   */
+  where?: FindManyOptions<TEntity>['where'];
+
+  /**
+   * 关联关系
+   */
+  relations?: FindManyOptions<TEntity>['relations'];
+
+  /**
+   * 选择字段
+   */
+  select?: FindManyOptions<TEntity>['select'];
+};
+
+/**
+ * TypeORM 分页查询选项（无映射器）
+ *
+ * 配置 TypeORM 分页查询的选项，返回原始实体
+ *
+ * @typeParam TEntity - 实体类型
+ */
+export type TypeOrmPaginateOptionsNoMapper<TEntity extends ObjectLiteral> = {
+  /**
+   * 排序规则
+   */
+  order?: FindOptionsOrder<TEntity>;
+
+  /**
+   * 查询条件
+   */
+  where?: FindManyOptions<TEntity>['where'];
+
+  /**
+   * 关联关系
+   */
+  relations?: FindManyOptions<TEntity>['relations'];
+
+  /**
+   * 选择字段
+   */
+  select?: FindManyOptions<TEntity>['select'];
+};
+
+/**
+ * TypeORM 分页查询选项
+ *
+ * 配置 TypeORM 分页查询的选项
+ *
+ * @typeParam TEntity - 实体类型
+ * @typeParam TDto - DTO 类型
+ */
+export type TypeOrmPaginateOptions<TEntity extends ObjectLiteral, TDto = TEntity> =
+  | TypeOrmPaginateOptionsWithMapper<TEntity, TDto>
+  | TypeOrmPaginateOptionsNoMapper<TEntity>;
+
+/**
+ * 类型守卫：检查选项是否包含映射器
+ *
+ * @typeParam TEntity - 实体类型
+ * @typeParam TDto - DTO 类型
+ * @param options - 查询选项
+ * @returns 是否包含映射器
+ */
+function hasMapper<TEntity extends ObjectLiteral, TDto>(
+  options:
+    | TypeOrmPaginateOptionsWithMapper<TEntity, TDto>
+    | TypeOrmPaginateOptionsNoMapper<TEntity>
+    | undefined,
+): options is TypeOrmPaginateOptionsWithMapper<TEntity, TDto> {
+  return options !== undefined && 'mapper' in options;
+}
+
+/**
+ * 构建分页结果
+ *
+ * 内部辅助函数，构建分页结果对象
+ *
+ * @typeParam TDto - DTO 类型
+ * @param items - 数据项数组
+ * @param total - 总数
+ * @param page - 当前页
+ * @param pageSize - 每页大小
+ * @returns 分页结果
+ */
+function buildPaginatedResult<TDto>(
+  items: TDto[],
+  total: number,
+  page: number,
+  pageSize: number,
+): PaginatedResult<TDto> {
+  /**
+   * 计算得到的总页数
+   */
+  const totalPages = calculateTotalPages(total, pageSize);
+  return {
+    items,
+    total,
+    page,
+    pageSize,
+    totalPages,
+    hasNextPage: hasNextPage(page, totalPages),
+    hasPreviousPage: hasPreviousPage(page),
+  };
+}
+
+/**
+ * 使用 Repository 进行分页查询
+ *
+ * 通过 TypeORM Repository 进行分页查询，支持实体到 DTO 的映射
+ *
+ * 当提供 mapper 时返回映射后的 DTO，否则返回原始实体
+ *
+ * @typeParam TEntity - 实体类型
+ * @typeParam TDto - DTO 类型
+ * @param repository - TypeORM 仓库
+ * @param params - 分页参数
+ * @param options - 查询选项
+ * @returns 分页结果
+ */
+export async function paginateWithRepository<TEntity extends ObjectLiteral, TDto = TEntity>(
+  repository: Repository<TEntity>,
+  params: PaginationParams,
+  options?: TypeOrmPaginateOptions<TEntity, TDto>,
+): Promise<PaginatedResult<TEntity | TDto>> {
+  /**
+   * 规范化后的分页参数
+   */
+  const { page, pageSize } = normalizePagination(params);
+
+  /**
+   * 计算得到的偏移量
+   */
+  const offset = calculateOffset(page, pageSize);
+
+  /**
+   * 默认排序规则
+   */
+  const defaultOrder: FindOptionsOrder<TEntity> = { createdAt: 'DESC' };
+
+  /**
+   * TypeORM 查询选项配置
+   */
+  const findOptions: FindManyOptions<TEntity> = {
+    skip: offset,
+    take: pageSize,
+    where: options?.where,
+    relations: options?.relations,
+    select: options?.select,
+    order: options?.order ?? defaultOrder,
+  };
+
+  /**
+   * 查询结果：实体数组和总数
+   */
+  const [entities, total] = await repository.findAndCount(findOptions);
+
+  if (hasMapper(options)) {
+    /**
+     * 映射后的 DTO 数组
+     */
+    const items = await Promise.all(entities.map(options.mapper));
+    return buildPaginatedResult(items, total, page, pageSize);
+  }
+
+  return buildPaginatedResult(entities, total, page, pageSize);
+}
+
+/**
+ * 使用 QueryBuilder 进行分页查询
+ *
+ * 通过 TypeORM QueryBuilder 进行分页查询，支持实体到 DTO 的映射
+ *
+ * 当提供 mapper 时返回映射后的 DTO，否则返回原始实体
+ *
+ * @typeParam TEntity - 实体类型
+ * @typeParam TDto - DTO 类型
+ * @param queryBuilder - TypeORM QueryBuilder
+ * @param params - 分页参数
+ * @param mapper - 实体到 DTO 的映射函数（可选）
+ * @returns 分页结果
+ */
+export async function paginateWithQueryBuilder<TEntity extends ObjectLiteral, TDto = TEntity>(
+  queryBuilder: SelectQueryBuilder<TEntity>,
+  params: PaginationParams,
+  mapper?: EntityMapper<TEntity, TDto>,
+): Promise<PaginatedResult<TEntity | TDto>> {
+  /**
+   * 规范化后的分页参数
+   */
+  const { page, pageSize } = normalizePagination(params);
+
+  /**
+   * 计算得到的偏移量
+   */
+  const offset = calculateOffset(page, pageSize);
+
+  queryBuilder.skip(offset).take(pageSize);
+
+  /**
+   * 查询结果：实体数组和总数
+   */
+  const [entities, total] = await queryBuilder.getManyAndCount();
+
+  if (mapper) {
+    /**
+     * 映射后的 DTO 数组
+     */
+    const items = await Promise.all(entities.map(mapper));
+    return buildPaginatedResult(items, total, page, pageSize);
+  }
+
+  return buildPaginatedResult(entities, total, page, pageSize);
+}
+
+/**
+ * 创建分页查询构建器
+ *
+ * 创建一个用于分页查询的 TypeORM QueryBuilder
+ *
+ * @typeParam TEntity - 实体类型
+ * @param repository - TypeORM 仓库
+ * @param alias - 查询别名
+ * @returns QueryBuilder
+ */
+export function createPaginationQueryBuilder<TEntity extends ObjectLiteral>(
+  repository: Repository<TEntity>,
+  alias?: string,
+): SelectQueryBuilder<TEntity> {
+  return repository.createQueryBuilder(alias ?? repository.metadata.name.toLowerCase());
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * 分页包主入口
+ */
+
+// 类型导出
+export type {
+  PaginationParams,
+  OffsetPaginationParams,
+  CursorPaginationParams,
+  PaginationDefaults,
+} from './types';
+
+export type { PaginatedResult, OffsetPaginatedResult, CursorPaginatedResult } from './types';
+
+export type { SortOrder, SortParams, SortItem, MultiSortParams } from './types';
+
+// 常量导出
+export { PAGINATION_DEFAULTS } from './types';
+
+// 工具函数导出
+export type {
+  OffsetPaginationResult,
+  PagePaginationResult,
+  PaginationValidationResult,
+  OffsetPaginationValidationResult,
+} from './utils';
+
+export {
+  normalizePagination,
+  normalizeOffsetPagination,
+  calculateOffset,
+  calculateTotalPages,
+  hasNextPage,
+  hasPreviousPage,
+  offsetToPage,
+  pageToOffset,
+  createPaginatedResult,
+} from './utils';
+
+export {
+  isValidPage,
+  isValidPageSize,
+  isValidOffset,
+  isValidLimit,
+  isValidPagination,
+  isValidOffsetPagination,
+} from './utils';
+
+// 适配器导出
+export type { EntityMapper, TypeOrmPaginateOptions } from './adapters';
+
+export {
+  paginateWithRepository,
+  paginateWithQueryBuilder,
+  createPaginationQueryBuilder,
+} from './adapters';

package/src/types/index.ts

@@ -0,0 +1,16 @@
+/**
+ * 类型导出入口
+ */
+
+export type {
+  PaginationParams,
+  OffsetPaginationParams,
+  CursorPaginationParams,
+  PaginationDefaults,
+} from './pagination.types';
+
+export { PAGINATION_DEFAULTS } from './pagination.types';
+
+export type { PaginatedResult, OffsetPaginatedResult, CursorPaginatedResult } from './result.types';
+
+export type { SortOrder, SortParams, SortItem, MultiSortParams } from './sort.types';