@longzai-intelligence/pagination 0.0.1 → 0.0.2

package/src/adapters/{typeorm.adapter.ts → typeorm/adapter.ts}

@@ -1,7 +1,7 @@
 /**
- * TypeORM 分页适配器
+ * TypeORM 分页适配器实现
  *
- * 注意：此模块需要安装 typeorm 作为 peerDependency
+ * 提供 TypeORM 分页查询的核心实现功能
  */
 
 import type {
@@ -11,102 +11,20 @@ import type {
   FindManyOptions,
   FindOptionsOrder,
 } from 'typeorm';
-import type { PaginationParams, PaginatedResult } from '../types';
+import type { PaginationParams, PaginatedResult } from '@/types';
+import type {
+  EntityMapper,
+  TypeOrmPaginateOptions,
+  TypeOrmPaginateOptionsWithMapper,
+  TypeOrmPaginateOptionsNoMapper,
+} 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>;
+} from '@/utils';
 
 /**
  * 类型守卫：检查选项是否包含映射器

package/src/adapters/typeorm/index.ts

@@ -0,0 +1,23 @@
+/**
+ * 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';

package/src/adapters/typeorm/types.ts

@@ -0,0 +1,95 @@
+/**
+ * TypeORM 适配器类型定义
+ *
+ * 提供 TypeORM 分页查询相关的类型定义
+ */
+
+import type { ObjectLiteral, FindManyOptions, FindOptionsOrder } from 'typeorm';
+
+/**
+ * 实体映射器函数类型
+ *
+ * 将实体类型转换为 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>;

package/src/index.ts

@@ -17,6 +17,24 @@ export type { SortOrder, SortParams, SortItem, MultiSortParams } from './types';
 // 常量导出
 export { PAGINATION_DEFAULTS } from './types';
 
+// Zod Schemas 导出
+export {
+  PaginationDefaultsSchema,
+  PaginationParamsSchema,
+  OffsetPaginationParamsSchema,
+  CursorPaginationParamsSchema,
+  SortOrderSchema,
+  SortParamsSchema,
+  SortItemSchema,
+  MultiSortParamsSchema,
+  createSortParamsSchema,
+  createSortItemSchema,
+  createMultiSortParamsSchema,
+  createPaginatedResultSchema,
+  createOffsetPaginatedResultSchema,
+  createCursorPaginatedResultSchema,
+} from './types';
+
 // 工具函数导出
 export type {
   OffsetPaginationResult,
@@ -45,12 +63,3 @@ export {
   isValidPagination,
   isValidOffsetPagination,
 } from './utils';
-
-// 适配器导出
-export type { EntityMapper, TypeOrmPaginateOptions } from './adapters';
-
-export {
-  paginateWithRepository,
-  paginateWithQueryBuilder,
-  createPaginationQueryBuilder,
-} from './adapters';

package/src/schemas/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Zod Schemas 导出
+ *
+ * 类型定义请从 '../types' 导入
+ */
+
+export {
+  PaginationDefaultsSchema,
+  PaginationParamsSchema,
+  OffsetPaginationParamsSchema,
+  CursorPaginationParamsSchema,
+} from './pagination.schemas';
+
+export {
+  SortOrderSchema,
+  SortParamsSchema,
+  SortItemSchema,
+  MultiSortParamsSchema,
+  createSortParamsSchema,
+  createSortItemSchema,
+  createMultiSortParamsSchema,
+} from './sort.schemas';
+
+export {
+  createPaginatedResultSchema,
+  createOffsetPaginatedResultSchema,
+  createCursorPaginatedResultSchema,
+} from './result.schemas';

package/src/schemas/pagination.schemas.ts

@@ -0,0 +1,86 @@
+/**
+ * 分页参数 Zod Schema 定义
+ */
+
+import { z } from 'zod';
+
+/**
+ * 默认分页配置 Schema
+ */
+export const PaginationDefaultsSchema = z.object({
+  page: z.literal(1),
+  pageSize: z.literal(20),
+  maxPageSize: z.literal(100),
+  minPageSize: z.literal(1),
+});
+
+/**
+ * 默认分页参数类型
+ */
+export type PaginationDefaults = z.infer<typeof PaginationDefaultsSchema>;
+
+/**
+ * 分页参数 Schema（page 风格，推荐使用）
+ *
+ * 适用于用户界面分页场景
+ */
+export const PaginationParamsSchema = z.object({
+  /**
+   * 页码（从 1 开始）
+   */
+  page: z.number().int().positive().optional(),
+
+  /**
+   * 每页数量
+   */
+  pageSize: z.number().int().positive().optional(),
+});
+
+/**
+ * 分页参数类型（page 风格）
+ */
+export type PaginationParams = z.infer<typeof PaginationParamsSchema>;
+
+/**
+ * Offset 分页参数 Schema
+ *
+ * 适用于 API 调用、数据库查询等场景
+ */
+export const OffsetPaginationParamsSchema = z.object({
+  /**
+   * 限制数量（正整数）
+   */
+  limit: z.number().int().positive().optional(),
+
+  /**
+   * 偏移量（非负整数）
+   */
+  offset: z.number().int().nonnegative().optional(),
+});
+
+/**
+ * Offset 分页参数类型
+ */
+export type OffsetPaginationParams = z.infer<typeof OffsetPaginationParamsSchema>;
+
+/**
+ * 游标分页参数 Schema
+ *
+ * 适用于无限滚动、实时数据流场景
+ */
+export const CursorPaginationParamsSchema = z.object({
+  /**
+   * 游标
+   */
+  cursor: z.string().optional(),
+
+  /**
+   * 限制数量
+   */
+  limit: z.number().int().positive().optional(),
+});
+
+/**
+ * 游标分页参数类型
+ */
+export type CursorPaginationParams = z.infer<typeof CursorPaginationParamsSchema>;

package/src/schemas/result.schemas.ts

@@ -0,0 +1,213 @@
+/**
+ * 分页结果 Zod Schema 定义
+ */
+
+import { z } from 'zod';
+
+/**
+ * 创建分页结果 Schema
+ *
+ * 包含分页数据和分页信息的完整结果
+ *
+ * @typeParam T - 数据项 Schema 类型
+ */
+export function createPaginatedResultSchema<T extends z.ZodTypeAny>(itemSchema: T) {
+  return z.object({
+    /**
+     * 数据项数组
+     */
+    items: z.array(itemSchema),
+
+    /**
+     * 总记录数
+     */
+    total: z.number().int().nonnegative(),
+
+    /**
+     * 当前页码
+     */
+    page: z.number().int().positive(),
+
+    /**
+     * 每页数量
+     */
+    pageSize: z.number().int().positive(),
+
+    /**
+     * 总页数
+     */
+    totalPages: z.number().int().nonnegative(),
+
+    /**
+     * 是否有下一页
+     */
+    hasNextPage: z.boolean(),
+
+    /**
+     * 是否有上一页
+     */
+    hasPreviousPage: z.boolean(),
+  });
+}
+
+/**
+ * 分页结果类型（泛型版本）
+ */
+export type PaginatedResult<T> = {
+  /**
+   * 数据项数组
+   */
+  items: T[];
+
+  /**
+   * 总记录数
+   */
+  total: number;
+
+  /**
+   * 当前页码
+   */
+  page: number;
+
+  /**
+   * 每页数量
+   */
+  pageSize: number;
+
+  /**
+   * 总页数
+   */
+  totalPages: number;
+
+  /**
+   * 是否有下一页
+   */
+  hasNextPage: boolean;
+
+  /**
+   * 是否有上一页
+   */
+  hasPreviousPage: boolean;
+};
+
+/**
+ * 创建 Offset 风格分页结果 Schema
+ *
+ * 包含偏移量分页数据和分页信息
+ *
+ * @typeParam T - 数据项 Schema 类型
+ */
+export function createOffsetPaginatedResultSchema<T extends z.ZodTypeAny>(itemSchema: T) {
+  return z.object({
+    /**
+     * 数据项数组
+     */
+    items: z.array(itemSchema),
+
+    /**
+     * 总记录数
+     */
+    total: z.number().int().nonnegative(),
+
+    /**
+     * 限制数量
+     */
+    limit: z.number().int().nonnegative(),
+
+    /**
+     * 偏移量
+     */
+    offset: z.number().int().nonnegative(),
+
+    /**
+     * 是否有更多数据
+     */
+    hasMore: z.boolean(),
+  });
+}
+
+/**
+ * Offset 风格分页结果类型（泛型版本）
+ */
+export type OffsetPaginatedResult<T> = {
+  /**
+   * 数据项数组
+   */
+  items: T[];
+
+  /**
+   * 总记录数
+   */
+  total: number;
+
+  /**
+   * 限制数量
+   */
+  limit: number;
+
+  /**
+   * 偏移量
+   */
+  offset: number;
+
+  /**
+   * 是否有更多数据
+   */
+  hasMore: boolean;
+};
+
+/**
+ * 创建游标分页结果 Schema
+ *
+ * 包含游标分页数据和分页信息
+ *
+ * @typeParam T - 数据项 Schema 类型
+ */
+export function createCursorPaginatedResultSchema<T extends z.ZodTypeAny>(itemSchema: T) {
+  return z.object({
+    /**
+     * 数据项数组
+     */
+    items: z.array(itemSchema),
+
+    /**
+     * 下一页游标
+     */
+    nextCursor: z.string().nullable(),
+
+    /**
+     * 上一页游标
+     */
+    previousCursor: z.string().nullable(),
+
+    /**
+     * 是否有更多数据
+     */
+    hasMore: z.boolean(),
+  });
+}
+
+/**
+ * 游标分页结果类型（泛型版本）
+ */
+export type CursorPaginatedResult<T> = {
+  /**
+   * 数据项数组
+   */
+  items: T[];
+
+  /**
+   * 下一页游标
+   */
+  nextCursor: string | null;
+
+  /**
+   * 上一页游标
+   */
+  previousCursor: string | null;
+
+  /**
+   * 是否有更多数据
+   */
+  hasMore: boolean;
+};