@longzai-intelligence/pagination 0.0.1 → 0.0.3

package/src/adapters/typeorm.adapter.ts

@@ -1,285 +0,0 @@
-/**
- * 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

@@ -1,56 +0,0 @@
-/**
- * 分页包主入口
- */
-
-// 类型导出
-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

@@ -1,16 +0,0 @@
-/**
- * 类型导出入口
- */
-
-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';

package/src/types/pagination.types.ts

@@ -1,69 +0,0 @@
-/**
- * 分页参数类型定义
- */
-
-/**
- * 分页参数（page 风格，推荐使用）
- *
- * 适用于用户界面分页场景
- */
-export type PaginationParams = {
-  /**
-   * 页码（从 1 开始）
-   */
-  page?: number;
-
-  /**
-   * 每页数量
-   */
-  pageSize?: number;
-};
-
-/**
- * 分页参数（offset 风格）
- *
- * 适用于 API 调用、数据库查询等场景
- */
-export type OffsetPaginationParams = {
-  /**
-   * 限制数量
-   */
-  limit?: number;
-
-  /**
-   * 偏移量
-   */
-  offset?: number;
-};
-
-/**
- * 游标分页参数
- *
- * 适用于无限滚动、实时数据流场景
- */
-export type CursorPaginationParams = {
-  /**
-   * 游标
-   */
-  cursor?: string;
-
-  /**
-   * 限制数量
-   */
-  limit?: number;
-};
-
-/**
- * 默认分页配置
- */
-export const PAGINATION_DEFAULTS = {
-  page: 1,
-  pageSize: 20,
-  maxPageSize: 100,
-  minPageSize: 1,
-} as const;
-
-/**
- * 默认分页参数类型
- */
-export type PaginationDefaults = typeof PAGINATION_DEFAULTS;

package/src/types/result.types.ts

@@ -1,110 +0,0 @@
-/**
- * 分页结果类型定义
- */
-
-/**
- * 分页结果
- *
- * 包含分页数据和分页信息的完整结果
- *
- * @typeParam T - 数据项类型
- */
-export type PaginatedResult<T> = {
-  /**
-   * 数据项数组
-   */
-  items: T[];
-
-  /**
-   * 总记录数
-   */
-  total: number;
-
-  /**
-   * 当前页码
-   */
-  page: number;
-
-  /**
-   * 每页数量
-   */
-  pageSize: number;
-
-  /**
-   * 总页数
-   */
-  totalPages: number;
-
-  /**
-   * 是否有下一页
-   */
-  hasNextPage: boolean;
-
-  /**
-   * 是否有上一页
-   */
-  hasPreviousPage: boolean;
-};
-
-/**
- * Offset 风格分页结果
- *
- * 包含偏移量分页数据和分页信息
- *
- * @typeParam T - 数据项类型
- */
-export type OffsetPaginatedResult<T> = {
-  /**
-   * 数据项数组
-   */
-  items: T[];
-
-  /**
-   * 总记录数
-   */
-  total: number;
-
-  /**
-   * 限制数量
-   */
-  limit: number;
-
-  /**
-   * 偏移量
-   */
-  offset: number;
-
-  /**
-   * 是否有更多数据
-   */
-  hasMore: boolean;
-};
-
-/**
- * 游标分页结果
- *
- * 包含游标分页数据和分页信息
- *
- * @typeParam T - 数据项类型
- */
-export type CursorPaginatedResult<T> = {
-  /**
-   * 数据项数组
-   */
-  items: T[];
-
-  /**
-   * 下一页游标
-   */
-  nextCursor: string | null;
-
-  /**
-   * 上一页游标
-   */
-  previousCursor: string | null;
-
-  /**
-   * 是否有更多数据
-   */
-  hasMore: boolean;
-};

package/src/types/sort.types.ts

@@ -1,60 +0,0 @@
-/**
- * 排序类型定义
- */
-
-/**
- * 排序方向
- */
-export type SortOrder = 'asc' | 'desc';
-
-/**
- * 排序参数
- *
- * 单字段排序参数
- *
- * @typeParam T - 排序字段类型
- */
-export type SortParams<T extends string = string> = {
-  /**
-   * 排序字段
-   */
-  sortBy?: T;
-
-  /**
-   * 排序方向
-   */
-  sortOrder?: SortOrder;
-};
-
-/**
- * 多字段排序项
- *
- * 单个排序项定义
- *
- * @typeParam T - 排序字段类型
- */
-export type SortItem<T extends string = string> = {
-  /**
-   * 排序字段
-   */
-  field: T;
-
-  /**
-   * 排序方向
-   */
-  order: SortOrder;
-};
-
-/**
- * 多字段排序参数
- *
- * 支持多个字段的排序
- *
- * @typeParam T - 排序字段类型
- */
-export type MultiSortParams<T extends string = string> = {
-  /**
-   * 排序项数组
-   */
-  sort?: SortItem<T>[];
-};

package/src/types/typeorm.d.ts

@@ -1,37 +0,0 @@
-/**
- * @file typeorm.d.ts
- * TypeORM 类型声明
- * 当 typeorm 未安装时提供类型支持
- * @author Longzai Intelligence
- */
-
-declare module 'typeorm' {
-  export interface ObjectLiteral {
-    [key: string]: unknown;
-  }
-
-  export interface Repository<TEntity extends ObjectLiteral> {
-    findAndCount(options?: FindManyOptions<TEntity>): Promise<[TEntity[], number]>;
-    createQueryBuilder(alias?: string): SelectQueryBuilder<TEntity>;
-    metadata: { name: string };
-  }
-
-  export interface SelectQueryBuilder<TEntity extends ObjectLiteral> {
-    skip(offset: number): this;
-    take(limit: number): this;
-    getManyAndCount(): Promise<[TEntity[], number]>;
-  }
-
-  export interface FindManyOptions<TEntity = unknown> {
-    skip?: number;
-    take?: number;
-    where?: unknown;
-    relations?: unknown;
-    select?: unknown;
-    order?: FindOptionsOrder<TEntity>;
-  }
-
-  export type FindOptionsOrder<TEntity> = {
-    [P in keyof TEntity]?: 'ASC' | 'DESC' | 1 | -1;
-  };
-}

package/src/utils/index.ts

@@ -1,31 +0,0 @@
-/**
- * 工具函数导出入口
- */
-
-export type { OffsetPaginationResult, PagePaginationResult } from './pagination.util';
-
-export type {
-  PaginationValidationResult,
-  OffsetPaginationValidationResult,
-} from './validation.util';
-
-export {
-  normalizePagination,
-  normalizeOffsetPagination,
-  calculateOffset,
-  calculateTotalPages,
-  hasNextPage,
-  hasPreviousPage,
-  offsetToPage,
-  pageToOffset,
-  createPaginatedResult,
-} from './pagination.util';
-
-export {
-  isValidPage,
-  isValidPageSize,
-  isValidOffset,
-  isValidLimit,
-  isValidPagination,
-  isValidOffsetPagination,
-} from './validation.util';