@longzai-intelligence/pagination 0.0.2 → 0.0.3

package/src/__tests__/sort.schemas.test.ts

@@ -1,157 +0,0 @@
-/**
- * 排序参数 Schema 测试
- */
-
-import { describe, it, expect } from 'vitest';
-import {
-  SortOrderSchema,
-  createSortParamsSchema,
-  SortParamsSchema,
-  createSortItemSchema,
-  SortItemSchema,
-  createMultiSortParamsSchema,
-  MultiSortParamsSchema,
-} from '@/schemas/sort.schemas';
-
-describe('SortOrderSchema', () => {
-  it('应接受有效的排序方向', () => {
-    expect(SortOrderSchema.parse('asc')).toBe('asc');
-    expect(SortOrderSchema.parse('desc')).toBe('desc');
-  });
-
-  it('应拒绝无效的排序方向', () => {
-    expect(() => SortOrderSchema.parse('invalid')).toThrow();
-  });
-});
-
-describe('createSortParamsSchema', () => {
-  it('应正确验证有效的排序参数', () => {
-    const schema = createSortParamsSchema(['name', 'createdAt', 'updatedAt'] as const);
-    const result = schema.parse({
-      sortBy: 'name',
-      sortOrder: 'asc',
-    });
-
-    expect(result.sortBy).toBe('name');
-    expect(result.sortOrder).toBe('asc');
-  });
-
-  it('应支持可选的排序参数', () => {
-    const schema = createSortParamsSchema(['name', 'createdAt'] as const);
-    const result = schema.parse({});
-
-    expect(result.sortBy).toBeUndefined();
-    expect(result.sortOrder).toBeUndefined();
-  });
-
-  it('应拒绝无效的排序字段', () => {
-    const schema = createSortParamsSchema(['name', 'createdAt'] as const);
-
-    expect(() =>
-      schema.parse({
-        sortBy: 'invalid',
-        sortOrder: 'asc',
-      }),
-    ).toThrow();
-  });
-});
-
-describe('SortParamsSchema', () => {
-  it('应正确验证默认排序参数', () => {
-    const result = SortParamsSchema.parse({
-      sortBy: 'anyField',
-      sortOrder: 'desc',
-    });
-
-    expect(result.sortBy).toBe('anyField');
-    expect(result.sortOrder).toBe('desc');
-  });
-});
-
-describe('createSortItemSchema', () => {
-  it('应正确验证有效的排序项', () => {
-    const schema = createSortItemSchema(['name', 'createdAt'] as const);
-    const result = schema.parse({
-      field: 'name',
-      order: 'desc',
-    });
-
-    expect(result.field).toBe('name');
-    expect(result.order).toBe('desc');
-  });
-
-  it('应拒绝无效的排序字段', () => {
-    const schema = createSortItemSchema(['name', 'createdAt'] as const);
-
-    expect(() =>
-      schema.parse({
-        field: 'invalid',
-        order: 'asc',
-      }),
-    ).toThrow();
-  });
-
-  it('应拒绝缺少必需字段', () => {
-    const schema = createSortItemSchema(['name', 'createdAt'] as const);
-
-    expect(() => schema.parse({ field: 'name' })).toThrow();
-  });
-});
-
-describe('SortItemSchema', () => {
-  it('应正确验证默认排序项', () => {
-    const result = SortItemSchema.parse({
-      field: 'anyField',
-      order: 'asc',
-    });
-
-    expect(result.field).toBe('anyField');
-    expect(result.order).toBe('asc');
-  });
-});
-
-describe('createMultiSortParamsSchema', () => {
-  it('应正确验证有效的多字段排序参数', () => {
-    const schema = createMultiSortParamsSchema(['name', 'createdAt', 'updatedAt'] as const);
-    const result = schema.parse({
-      sort: [
-        { field: 'name', order: 'asc' },
-        { field: 'createdAt', order: 'desc' },
-      ],
-    });
-
-    expect(result.sort).toHaveLength(2);
-    expect(result.sort?.[0]?.field).toBe('name');
-    expect(result.sort?.[1]?.field).toBe('createdAt');
-  });
-
-  it('应支持可选的排序参数', () => {
-    const schema = createMultiSortParamsSchema(['name', 'createdAt'] as const);
-    const result = schema.parse({});
-
-    expect(result.sort).toBeUndefined();
-  });
-
-  it('应拒绝无效的排序字段', () => {
-    const schema = createMultiSortParamsSchema(['name', 'createdAt'] as const);
-
-    expect(() =>
-      schema.parse({
-        sort: [{ field: 'invalid', order: 'asc' }],
-      }),
-    ).toThrow();
-  });
-});
-
-describe('MultiSortParamsSchema', () => {
-  it('应正确验证默认多字段排序参数', () => {
-    const result = MultiSortParamsSchema.parse({
-      sort: [
-        { field: 'field1', order: 'asc' },
-        { field: 'field2', order: 'desc' },
-      ],
-    });
-
-    expect(result.sort).toHaveLength(2);
-  });
-});

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

@@ -1,212 +0,0 @@
-/**
- * TypeORM 适配器测试
- */
-
-import { describe, it, expect, vi } from 'vitest';
-import {
-  paginateWithRepository,
-  paginateWithQueryBuilder,
-  createPaginationQueryBuilder,
-} from '@/adapters/typeorm';
-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

@@ -1,120 +0,0 @@
-/**
- * 分页参数验证工具函数测试
- */
-
-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/typeorm/adapter.ts

@@ -1,203 +0,0 @@
-/**
- * TypeORM 分页适配器实现
- *
- * 提供 TypeORM 分页查询的核心实现功能
- */
-
-import type {
-  Repository,
-  SelectQueryBuilder,
-  ObjectLiteral,
-  FindManyOptions,
-  FindOptionsOrder,
-} from 'typeorm';
-import type { PaginationParams, PaginatedResult } from '@/types';
-import type {
-  EntityMapper,
-  TypeOrmPaginateOptions,
-  TypeOrmPaginateOptionsWithMapper,
-  TypeOrmPaginateOptionsNoMapper,
-} from './types';
-import {
-  normalizePagination,
-  calculateOffset,
-  calculateTotalPages,
-  hasNextPage,
-  hasPreviousPage,
-} from '@/utils';
-
-/**
- * 类型守卫：检查选项是否包含映射器
- *
- * @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/adapters/typeorm/index.ts

@@ -1,23 +0,0 @@
-/**
- * TypeORM 适配器入口
- *
- * 提供 TypeORM 分页查询功能，需要安装 typeorm 作为 peerDependency。
- *
- * @example
- * ```typescript
- * import { paginateWithRepository } from '@longzai-intelligence/pagination/typeorm';
- *
- * const result = await paginateWithRepository(userRepository, {
- *   page: 1,
- *   pageSize: 20,
- * });
- * ```
- */
-
-export type { EntityMapper, TypeOrmPaginateOptions } from './types';
-
-export {
-  paginateWithRepository,
-  paginateWithQueryBuilder,
-  createPaginationQueryBuilder,
-} from './adapter';