@longzai-intelligence/pagination 0.0.1 → 0.0.2

package/dist/typeorm.d.cts

@@ -0,0 +1,26 @@
+import { T as PaginationParams, m as PaginatedResult } from "./index-CMiyhlfm.cjs";
+import { FindManyOptions, FindOptionsOrder, ObjectLiteral, Repository, SelectQueryBuilder } from "typeorm";
+
+//#region src/adapters/typeorm/types.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>;
+//#endregion
+//#region src/adapters/typeorm/adapter.d.ts
+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 EntityMapper, type TypeOrmPaginateOptions, createPaginationQueryBuilder, paginateWithQueryBuilder, paginateWithRepository };

package/dist/typeorm.d.mts

@@ -0,0 +1,26 @@
+import { T as PaginationParams, m as PaginatedResult } from "./index-C8FaNzej.mjs";
+import { FindManyOptions, FindOptionsOrder, ObjectLiteral, Repository, SelectQueryBuilder } from "typeorm";
+
+//#region src/adapters/typeorm/types.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>;
+//#endregion
+//#region src/adapters/typeorm/adapter.d.ts
+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 EntityMapper, type TypeOrmPaginateOptions, createPaginationQueryBuilder, paginateWithQueryBuilder, paginateWithRepository };

package/dist/typeorm.mjs

@@ -0,0 +1 @@
+import{c as e,d as t,p as n,s as r,u as i}from"./utils-CV6Ovku6.mjs";function a(e){return e!==void 0&&`mapper`in e}function o(n,r,a,o){let s=e(r,o);return{items:n,total:r,page:a,pageSize:o,totalPages:s,hasNextPage:i(a,s),hasPreviousPage:t(a)}}async function s(e,t,i){let{page:s,pageSize:c}=n(t),l={skip:r(s,c),take:c,where:i?.where,relations:i?.relations,select:i?.select,order:i?.order??{createdAt:`DESC`}},[u,d]=await e.findAndCount(l);return a(i)?o(await Promise.all(u.map(i.mapper)),d,s,c):o(u,d,s,c)}async function c(e,t,i){let{page:a,pageSize:s}=n(t),c=r(a,s);e.skip(c).take(s);let[l,u]=await e.getManyAndCount();return o(i?await Promise.all(l.map(i)):l,u,a,s)}function l(e,t){return e.createQueryBuilder(t??e.metadata.name.toLowerCase())}export{l as createPaginationQueryBuilder,c as paginateWithQueryBuilder,s as paginateWithRepository};

package/dist/utils-CV6Ovku6.mjs

@@ -0,0 +1 @@
+import{z as e}from"zod";const t=e.object({page:e.literal(1),pageSize:e.literal(20),maxPageSize:e.literal(100),minPageSize:e.literal(1)}),n=e.object({page:e.number().int().positive().optional(),pageSize:e.number().int().positive().optional()}),r=e.object({limit:e.number().int().positive().optional(),offset:e.number().int().nonnegative().optional()}),i=e.object({cursor:e.string().optional(),limit:e.number().int().positive().optional()}),a={page:1,pageSize:20,maxPageSize:100,minPageSize:1};function o(t){return e.object({items:e.array(t),total:e.number().int().nonnegative(),page:e.number().int().positive(),pageSize:e.number().int().positive(),totalPages:e.number().int().nonnegative(),hasNextPage:e.boolean(),hasPreviousPage:e.boolean()})}function s(t){return e.object({items:e.array(t),total:e.number().int().nonnegative(),limit:e.number().int().nonnegative(),offset:e.number().int().nonnegative(),hasMore:e.boolean()})}function c(t){return e.object({items:e.array(t),nextCursor:e.string().nullable(),previousCursor:e.string().nullable(),hasMore:e.boolean()})}const l=e.enum([`asc`,`desc`]);function u(t){return e.object({sortBy:e.enum(t).optional(),sortOrder:l.optional()})}const d=e.object({sortBy:e.string().optional(),sortOrder:l.optional()});function f(t){return e.object({field:e.enum(t),order:l})}const p=e.object({field:e.string(),order:l});function m(t){return e.object({sort:e.array(f(t)).optional()})}const h=e.object({sort:e.array(p).optional()});function g(e){return{page:Math.max(1,Math.floor(e?.page??a.page)),pageSize:Math.min(a.maxPageSize,Math.max(a.minPageSize,Math.floor(e?.pageSize??a.pageSize)))}}function _(e){return{limit:Math.min(a.maxPageSize,Math.max(a.minPageSize,Math.floor(e?.limit??a.pageSize))),offset:Math.max(0,Math.floor(e?.offset??0))}}function v(e,t){return(e-1)*t}function y(e,t){return t<=0?0:Math.ceil(e/t)}function b(e,t){return e<t}function x(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 w(e,t,n,r){let i=y(t,r);return{items:e,total:t,page:n,pageSize:r,totalPages:i,hasNextPage:b(n,i),hasPreviousPage:x(n)}}function T(e){return typeof e==`object`&&!!e}function E(e){return typeof e==`number`&&Number.isInteger(e)&&e>=1}function D(e){return typeof e==`number`&&Number.isInteger(e)&&e>=a.minPageSize&&e<=a.maxPageSize}function O(e){return typeof e==`number`&&Number.isInteger(e)&&e>=0}function k(e){return typeof e==`number`&&Number.isInteger(e)&&e>=a.minPageSize&&e<=a.maxPageSize}function A(e){if(!T(e))return!1;let t=e.page,n=e.pageSize;return(t===void 0||E(t))&&(n===void 0||D(n))}function j(e){if(!T(e))return!1;let t=e.limit,n=e.offset;return(t===void 0||k(t))&&(n===void 0||O(n))}export{n as A,c as C,i as D,a as E,r as O,u as S,o as T,p as _,D as a,m as b,y as c,x as d,_ as f,h as g,C as h,E as i,t as k,w as l,S as m,O as n,A as o,g as p,j as r,v as s,k as t,b as u,l as v,s as w,f as x,d as y};

package/dist/utils-D_qD2YAX.cjs

@@ -0,0 +1 @@
+let e=require(`zod`);const t=e.z.object({page:e.z.literal(1),pageSize:e.z.literal(20),maxPageSize:e.z.literal(100),minPageSize:e.z.literal(1)}),n=e.z.object({page:e.z.number().int().positive().optional(),pageSize:e.z.number().int().positive().optional()}),r=e.z.object({limit:e.z.number().int().positive().optional(),offset:e.z.number().int().nonnegative().optional()}),i=e.z.object({cursor:e.z.string().optional(),limit:e.z.number().int().positive().optional()}),a={page:1,pageSize:20,maxPageSize:100,minPageSize:1};function o(t){return e.z.object({items:e.z.array(t),total:e.z.number().int().nonnegative(),page:e.z.number().int().positive(),pageSize:e.z.number().int().positive(),totalPages:e.z.number().int().nonnegative(),hasNextPage:e.z.boolean(),hasPreviousPage:e.z.boolean()})}function s(t){return e.z.object({items:e.z.array(t),total:e.z.number().int().nonnegative(),limit:e.z.number().int().nonnegative(),offset:e.z.number().int().nonnegative(),hasMore:e.z.boolean()})}function c(t){return e.z.object({items:e.z.array(t),nextCursor:e.z.string().nullable(),previousCursor:e.z.string().nullable(),hasMore:e.z.boolean()})}const l=e.z.enum([`asc`,`desc`]);function u(t){return e.z.object({sortBy:e.z.enum(t).optional(),sortOrder:l.optional()})}const d=e.z.object({sortBy:e.z.string().optional(),sortOrder:l.optional()});function f(t){return e.z.object({field:e.z.enum(t),order:l})}const p=e.z.object({field:e.z.string(),order:l});function m(t){return e.z.object({sort:e.z.array(f(t)).optional()})}const h=e.z.object({sort:e.z.array(p).optional()});function g(e){return{page:Math.max(1,Math.floor(e?.page??a.page)),pageSize:Math.min(a.maxPageSize,Math.max(a.minPageSize,Math.floor(e?.pageSize??a.pageSize)))}}function _(e){return{limit:Math.min(a.maxPageSize,Math.max(a.minPageSize,Math.floor(e?.limit??a.pageSize))),offset:Math.max(0,Math.floor(e?.offset??0))}}function v(e,t){return(e-1)*t}function y(e,t){return t<=0?0:Math.ceil(e/t)}function b(e,t){return e<t}function x(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 w(e,t,n,r){let i=y(t,r);return{items:e,total:t,page:n,pageSize:r,totalPages:i,hasNextPage:b(n,i),hasPreviousPage:x(n)}}function T(e){return typeof e==`object`&&!!e}function E(e){return typeof e==`number`&&Number.isInteger(e)&&e>=1}function D(e){return typeof e==`number`&&Number.isInteger(e)&&e>=a.minPageSize&&e<=a.maxPageSize}function O(e){return typeof e==`number`&&Number.isInteger(e)&&e>=0}function k(e){return typeof e==`number`&&Number.isInteger(e)&&e>=a.minPageSize&&e<=a.maxPageSize}function A(e){if(!T(e))return!1;let t=e.page,n=e.pageSize;return(t===void 0||E(t))&&(n===void 0||D(n))}function j(e){if(!T(e))return!1;let t=e.limit,n=e.offset;return(t===void 0||k(t))&&(n===void 0||O(n))}Object.defineProperty(exports,`A`,{enumerable:!0,get:function(){return n}}),Object.defineProperty(exports,`C`,{enumerable:!0,get:function(){return c}}),Object.defineProperty(exports,`D`,{enumerable:!0,get:function(){return i}}),Object.defineProperty(exports,`E`,{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,`O`,{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,`S`,{enumerable:!0,get:function(){return u}}),Object.defineProperty(exports,`T`,{enumerable:!0,get:function(){return o}}),Object.defineProperty(exports,`_`,{enumerable:!0,get:function(){return p}}),Object.defineProperty(exports,`a`,{enumerable:!0,get:function(){return D}}),Object.defineProperty(exports,`b`,{enumerable:!0,get:function(){return m}}),Object.defineProperty(exports,`c`,{enumerable:!0,get:function(){return y}}),Object.defineProperty(exports,`d`,{enumerable:!0,get:function(){return x}}),Object.defineProperty(exports,`f`,{enumerable:!0,get:function(){return _}}),Object.defineProperty(exports,`g`,{enumerable:!0,get:function(){return h}}),Object.defineProperty(exports,`h`,{enumerable:!0,get:function(){return C}}),Object.defineProperty(exports,`i`,{enumerable:!0,get:function(){return E}}),Object.defineProperty(exports,`k`,{enumerable:!0,get:function(){return t}}),Object.defineProperty(exports,`l`,{enumerable:!0,get:function(){return w}}),Object.defineProperty(exports,`m`,{enumerable:!0,get:function(){return S}}),Object.defineProperty(exports,`n`,{enumerable:!0,get:function(){return O}}),Object.defineProperty(exports,`o`,{enumerable:!0,get:function(){return A}}),Object.defineProperty(exports,`p`,{enumerable:!0,get:function(){return g}}),Object.defineProperty(exports,`r`,{enumerable:!0,get:function(){return j}}),Object.defineProperty(exports,`s`,{enumerable:!0,get:function(){return v}}),Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return k}}),Object.defineProperty(exports,`u`,{enumerable:!0,get:function(){return b}}),Object.defineProperty(exports,`v`,{enumerable:!0,get:function(){return l}}),Object.defineProperty(exports,`w`,{enumerable:!0,get:function(){return s}}),Object.defineProperty(exports,`x`,{enumerable:!0,get:function(){return f}}),Object.defineProperty(exports,`y`,{enumerable:!0,get:function(){return d}});

package/docs/specs/spec-20260413-typeorm-subpath-export/checklist.md

@@ -0,0 +1,33 @@
+# 检查清单
+
+## 代码变更
+
+- [ ] `src/typeorm.ts` 文件已创建
+- [ ] `src/index.ts` 已移除 TypeORM 相关导出
+- [ ] `src/adapters/index.ts` 已删除
+- [ ] `src/adapters/typeorm.adapter.ts` 保留不变
+
+## 配置变更
+
+- [ ] `package.json` exports 字段已添加 `./typeorm`
+- [ ] `tsdown.config.ts` 已配置多入口
+
+## 文档变更
+
+- [ ] `README.md` 已更新使用示例
+- [ ] 子路径导入说明已添加
+- [ ] `/docs/user-guides/pagination-user-guide-v1.md` 已更新
+- [ ] TypeORM 适配器导入路径已修改为子路径方式
+
+## 测试验证
+
+- [ ] 单元测试通过
+- [ ] 类型检查通过
+- [ ] 构建成功
+- [ ] Lint 检查通过
+
+## 导出验证
+
+- [ ] 主入口 `@longzai-intelligence/pagination` 只导出核心功能
+- [ ] 子路径 `@longzai-intelligence/pagination/typeorm` 导出 TypeORM 适配器
+- [ ] 类型定义正确生成

package/docs/specs/spec-20260413-typeorm-subpath-export/spec.md

@@ -0,0 +1,104 @@
+# TypeORM 适配器子路径导出规格
+
+## 背景
+
+当前 `@longzai-intelligence/pagination` 包将 TypeORM 适配器直接从主入口导出，这导致：
+
+1. 主入口 `index.ts` 被 TypeORM 特定代码污染
+2. 不使用 TypeORM 的用户也会引入 TypeORM 相关类型
+3. 违反了可选依赖的最佳实践
+
+## 目标
+
+将 TypeORM 适配器改为子路径导出，实现：
+
+1. 主入口保持纯净，只导出分页核心功能
+2. TypeORM 适配器通过 `@longzai-intelligence/pagination/typeorm` 单独导入
+3. 用户按需导入，减少不必要的依赖感知
+
+## 导出结构变更
+
+### 变更前
+
+```typescript
+// 主入口 index.ts 同时导出核心功能和 TypeORM 适配器
+export { paginateWithRepository, paginateWithQueryBuilder } from './adapters';
+```
+
+### 变更后
+
+```typescript
+// 主入口 index.ts - 只导出核心功能
+export { normalizePagination, calculateOffset, ... } from './utils';
+export type { PaginationParams, PaginatedResult, ... } from './types';
+
+// 新增 typeorm.ts 入口 - 单独导出 TypeORM 适配器
+export { paginateWithRepository, paginateWithQueryBuilder, createPaginationQueryBuilder } from './adapters/typeorm.adapter';
+export type { EntityMapper, TypeOrmPaginateOptions } from './adapters/typeorm.adapter';
+```
+
+## package.json exports 配置
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.mts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./typeorm": {
+      "types": {
+        "import": "./dist/typeorm.d.mts",
+        "require": "./dist/typeorm.d.cts"
+      },
+      "import": "./dist/typeorm.mjs",
+      "require": "./dist/typeorm.cjs"
+    }
+  }
+}
+```
+
+## 使用方式变更
+
+### 变更前
+
+```typescript
+import { paginateWithRepository, type PaginationParams } from '@longzai-intelligence/pagination';
+```
+
+### 变更后
+
+```typescript
+// 核心功能 - 从主入口导入
+import { type PaginationParams, type PaginatedResult } from '@longzai-intelligence/pagination';
+
+// TypeORM 适配器 - 从子路径导入
+import { paginateWithRepository } from '@longzai-intelligence/pagination/typeorm';
+```
+
+## 文件变更清单
+
+| 文件 | 操作 | 说明 |
+|------|------|------|
+| `src/index.ts` | 修改 | 移除 TypeORM 适配器导出 |
+| `src/typeorm.ts` | 新增 | TypeORM 适配器独立入口 |
+| `src/adapters/index.ts` | 删除 | 不再需要适配器聚合入口 |
+| `package.json` | 修改 | 添加 `./typeorm` 子路径导出 |
+| `tsdown.config.ts` | 修改 | 添加 typeorm 入口配置 |
+| `README.md` | 修改 | 更新使用文档 |
+| `docs/user-guides/pagination-user-guide-v1.md` | 修改 | 更新 TypeORM 适配器导入路径 |
+
+## 影响范围
+
+1. 现有使用 `@longzai-intelligence/pagination` 导入 TypeORM 适配器的代码需要修改导入路径
+2. 仅使用核心功能的代码无需修改
+
+## 风险评估
+
+- **破坏性变更**: 是，导入路径变更
+- **向后兼容**: 否，需要用户更新导入路径
+- **迁移成本**: 低，仅需修改导入语句

package/docs/specs/spec-20260413-typeorm-subpath-export/tasks.md

@@ -0,0 +1,48 @@
+# 任务列表
+
+## 1. 创建 TypeORM 独立入口文件
+
+- [ ] 创建 `src/typeorm.ts` 文件
+- [ ] 从 `./adapters/typeorm.adapter` 导出所有 TypeORM 相关功能和类型
+
+## 2. 修改主入口文件
+
+- [ ] 从 `src/index.ts` 移除 TypeORM 适配器相关导出
+- [ ] 确保核心功能导出完整
+
+## 3. 清理适配器目录
+
+- [ ] 删除 `src/adapters/index.ts` 文件（不再需要）
+- [ ] 保留 `src/adapters/typeorm.adapter.ts` 文件
+
+## 4. 更新 package.json
+
+- [ ] 在 `exports` 字段添加 `./typeorm` 子路径配置
+- [ ] 确保类型定义文件路径正确
+
+## 5. 更新构建配置
+
+- [ ] 修改 `tsdown.config.ts` 添加多入口配置
+- [ ] 确保 typeorm 入口正确构建
+
+## 6. 更新文档
+
+- [ ] 更新 `README.md` 使用示例
+- [ ] 添加子路径导入说明
+
+## 7. 更新用户指南
+
+- [ ] 更新 `/docs/user-guides/pagination-user-guide-v1.md`
+- [ ] 修改 TypeORM 适配器导入路径为子路径方式
+- [ ] 更新所有相关代码示例
+
+## 8. 更新测试
+
+- [ ] 检查并更新测试文件中的导入路径
+- [ ] 确保测试通过
+
+## 9. 验证构建
+
+- [ ] 运行 `bun run build` 验证构建成功
+- [ ] 运行 `bun run typecheck` 验证类型正确
+- [ ] 运行 `bun run lint:fix` 验证代码规范

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longzai-intelligence/pagination",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.mts",
@@ -12,6 +12,14 @@
       },
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
+    },
+    "./typeorm": {
+      "types": {
+        "import": "./dist/typeorm.d.mts",
+        "require": "./dist/typeorm.d.cts"
+      },
+      "import": "./dist/typeorm.mjs",
+      "require": "./dist/typeorm.cjs"
     }
   },
   "scripts": {
@@ -32,11 +40,15 @@
     "upgrade-deps": "ncu -u"
   },
   "peerDependencies": {
-    "typeorm": "^0.3.0"
+    "typeorm": "^0.3.0",
+    "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "typeorm": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -47,7 +59,7 @@
     "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/vitest-config": "0.0.7",
     "@longzai-intelligence/typescript-config": "0.0.3",
     "tsdown": "^0.21.7",
     "@longzai-intelligence/tsdown-config": "0.0.1"

package/src/__tests__/index.test.ts

@@ -1,7 +1,5 @@
 /**
- * @file index.test.ts
  * 主入口导出测试
- * @author Longzai Intelligence
  */
 
 import { describe, it, expect } from 'vitest';
@@ -42,9 +40,17 @@ describe('pagination 包导出', () => {
     expect(module.isValidOffsetPagination).toBeDefined();
   });
 
-  it('应正确导出所有适配器', async () => {
+  it('主入口不应导出 TypeORM 适配器', async () => {
     const module = await import('@/index');
 
+    expect('paginateWithRepository' in module).toBe(false);
+    expect('paginateWithQueryBuilder' in module).toBe(false);
+    expect('createPaginationQueryBuilder' in module).toBe(false);
+  });
+
+  it('typeorm 子路径应正确导出适配器', async () => {
+    const module = await import('@/typeorm');
+
     expect(module.paginateWithRepository).toBeDefined();
     expect(module.paginateWithQueryBuilder).toBeDefined();
     expect(module.createPaginationQueryBuilder).toBeDefined();

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

@@ -1,7 +1,5 @@
 /**
- * @file pagination.util.test.ts
  * 分页计算工具函数测试
- * @author Longzai Intelligence
  */
 
 import { describe, it, expect } from 'vitest';

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

@@ -0,0 +1,142 @@
+/**
+ * 分页结果 Schema 测试
+ */
+
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import {
+  createPaginatedResultSchema,
+  createOffsetPaginatedResultSchema,
+  createCursorPaginatedResultSchema,
+} from '@/schemas/result.schemas';
+
+/**
+ * 测试实体 Schema
+ */
+const TestItemSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+});
+
+describe('createPaginatedResultSchema', () => {
+  it('应正确验证有效的分页结果', () => {
+    const schema = createPaginatedResultSchema(TestItemSchema);
+    const result = schema.parse({
+      items: [{ id: 1, name: 'test' }],
+      total: 100,
+      page: 1,
+      pageSize: 20,
+      totalPages: 5,
+      hasNextPage: true,
+      hasPreviousPage: false,
+    });
+
+    expect(result.items).toHaveLength(1);
+    expect(result.total).toBe(100);
+    expect(result.page).toBe(1);
+  });
+
+  it('应拒绝无效的分页结果', () => {
+    const schema = createPaginatedResultSchema(TestItemSchema);
+
+    expect(() =>
+      schema.parse({
+        items: [{ id: 'invalid', name: 'test' }],
+        total: 100,
+        page: 1,
+        pageSize: 20,
+        totalPages: 5,
+        hasNextPage: true,
+        hasPreviousPage: false,
+      }),
+    ).toThrow();
+  });
+
+  it('应拒绝缺少必需字段的分页结果', () => {
+    const schema = createPaginatedResultSchema(TestItemSchema);
+
+    expect(() =>
+      schema.parse({
+        items: [{ id: 1, name: 'test' }],
+        total: 100,
+      }),
+    ).toThrow();
+  });
+});
+
+describe('createOffsetPaginatedResultSchema', () => {
+  it('应正确验证有效的 Offset 分页结果', () => {
+    const schema = createOffsetPaginatedResultSchema(TestItemSchema);
+    const result = schema.parse({
+      items: [{ id: 1, name: 'test' }],
+      total: 100,
+      limit: 20,
+      offset: 0,
+      hasMore: true,
+    });
+
+    expect(result.items).toHaveLength(1);
+    expect(result.total).toBe(100);
+    expect(result.limit).toBe(20);
+    expect(result.offset).toBe(0);
+    expect(result.hasMore).toBe(true);
+  });
+
+  it('应拒绝无效的 Offset 分页结果', () => {
+    const schema = createOffsetPaginatedResultSchema(TestItemSchema);
+
+    expect(() =>
+      schema.parse({
+        items: [{ id: 1, name: 'test' }],
+        total: -1,
+        limit: 20,
+        offset: 0,
+        hasMore: true,
+      }),
+    ).toThrow();
+  });
+});
+
+describe('createCursorPaginatedResultSchema', () => {
+  it('应正确验证有效的游标分页结果', () => {
+    const schema = createCursorPaginatedResultSchema(TestItemSchema);
+    const result = schema.parse({
+      items: [{ id: 1, name: 'test' }],
+      nextCursor: 'cursor123',
+      previousCursor: null,
+      hasMore: true,
+    });
+
+    expect(result.items).toHaveLength(1);
+    expect(result.nextCursor).toBe('cursor123');
+    expect(result.previousCursor).toBeNull();
+    expect(result.hasMore).toBe(true);
+  });
+
+  it('应支持 null 游标', () => {
+    const schema = createCursorPaginatedResultSchema(TestItemSchema);
+    const result = schema.parse({
+      items: [],
+      nextCursor: null,
+      previousCursor: null,
+      hasMore: false,
+    });
+
+    expect(result.items).toHaveLength(0);
+    expect(result.nextCursor).toBeNull();
+    expect(result.previousCursor).toBeNull();
+  });
+
+  it('应拒绝无效的游标分页结果', () => {
+    const schema = createCursorPaginatedResultSchema(TestItemSchema);
+
+    expect(() =>
+      schema.parse({
+        items: [{ id: 1, name: 'test' }],
+        nextCursor: 123,
+        previousCursor: null,
+        hasMore: true,
+      }),
+    ).toThrow();
+  });
+});

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

@@ -0,0 +1,157 @@
+/**
+ * 排序参数 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,7 +1,5 @@
 /**
- * @file typeorm.adapter.test.ts
  * TypeORM 适配器测试
- * @author Longzai Intelligence
  */
 
 import { describe, it, expect, vi } from 'vitest';
@@ -9,7 +7,7 @@ import {
   paginateWithRepository,
   paginateWithQueryBuilder,
   createPaginationQueryBuilder,
-} from '@/adapters/typeorm.adapter';
+} from '@/adapters/typeorm';
 import type { Repository, SelectQueryBuilder, FindOptionsOrder } from 'typeorm';
 
 /**

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

@@ -1,7 +1,5 @@
 /**
- * @file validation.util.test.ts
  * 分页参数验证工具函数测试
- * @author Longzai Intelligence
  */
 
 import { describe, it, expect } from 'vitest';