@longzai-intelligence/pagination 0.0.2 → 0.0.3

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

@@ -1,104 +0,0 @@
-# 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

@@ -1,48 +0,0 @@
-# 任务列表
-
-## 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/eslint.config.ts

@@ -1,3 +0,0 @@
-import { defineConfig } from '@longzai-intelligence/eslint-preset-library';
-
-export default defineConfig();

package/src/__tests__/index.test.ts

@@ -1,72 +0,0 @@
-/**
- * 主入口导出测试
- */
-
-import { describe, it, expect } from 'vitest';
-
-describe('pagination 包导出', () => {
-  it('应正确导出所有类型', async () => {
-    const module = await import('@/index');
-
-    expect(module.PAGINATION_DEFAULTS).toBeDefined();
-    expect(module.PAGINATION_DEFAULTS.page).toBe(1);
-    expect(module.PAGINATION_DEFAULTS.pageSize).toBe(20);
-    expect(module.PAGINATION_DEFAULTS.maxPageSize).toBe(100);
-    expect(module.PAGINATION_DEFAULTS.minPageSize).toBe(1);
-  });
-
-  it('应正确导出所有工具函数', async () => {
-    const module = await import('@/index');
-
-    expect(module.normalizePagination).toBeDefined();
-    expect(module.normalizeOffsetPagination).toBeDefined();
-    expect(module.calculateOffset).toBeDefined();
-    expect(module.calculateTotalPages).toBeDefined();
-    expect(module.hasNextPage).toBeDefined();
-    expect(module.hasPreviousPage).toBeDefined();
-    expect(module.offsetToPage).toBeDefined();
-    expect(module.pageToOffset).toBeDefined();
-    expect(module.createPaginatedResult).toBeDefined();
-  });
-
-  it('应正确导出所有验证函数', async () => {
-    const module = await import('@/index');
-
-    expect(module.isValidPage).toBeDefined();
-    expect(module.isValidPageSize).toBeDefined();
-    expect(module.isValidOffset).toBeDefined();
-    expect(module.isValidLimit).toBeDefined();
-    expect(module.isValidPagination).toBeDefined();
-    expect(module.isValidOffsetPagination).toBeDefined();
-  });
-
-  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();
-  });
-
-  it('normalizePagination 应正常工作', async () => {
-    const { normalizePagination } = await import('@/index');
-
-    const result = normalizePagination({ page: 2, pageSize: 50 });
-    expect(result).toEqual({ page: 2, pageSize: 50 });
-  });
-
-  it('calculateOffset 应正常工作', async () => {
-    const { calculateOffset } = await import('@/index');
-
-    expect(calculateOffset(1, 20)).toBe(0);
-    expect(calculateOffset(2, 20)).toBe(20);
-  });
-});

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

@@ -1,251 +0,0 @@
-/**
- * 分页计算工具函数测试
- */
-
-import { describe, it, expect } from 'vitest';
-import {
-  normalizePagination,
-  normalizeOffsetPagination,
-  calculateOffset,
-  calculateTotalPages,
-  hasNextPage,
-  hasPreviousPage,
-  offsetToPage,
-  pageToOffset,
-  createPaginatedResult,
-} from '@/utils/pagination.util';
-import { PAGINATION_DEFAULTS } from '@/types';
-
-describe('normalizePagination', () => {
-  it('应返回默认值当参数为空时', () => {
-    const result = normalizePagination();
-    expect(result).toEqual({
-      page: PAGINATION_DEFAULTS.page,
-      pageSize: PAGINATION_DEFAULTS.pageSize,
-    });
-  });
-
-  it('应返回默认值当参数为 undefined 时', () => {
-    const result = normalizePagination(undefined);
-    expect(result).toEqual({
-      page: PAGINATION_DEFAULTS.page,
-      pageSize: PAGINATION_DEFAULTS.pageSize,
-    });
-  });
-
-  it('应正确规范化有效的分页参数', () => {
-    const result = normalizePagination({ page: 2, pageSize: 50 });
-    expect(result).toEqual({ page: 2, pageSize: 50 });
-  });
-
-  it('应限制 pageSize 不超过最大值', () => {
-    const result = normalizePagination({ pageSize: 200 });
-    expect(result.pageSize).toBe(PAGINATION_DEFAULTS.maxPageSize);
-  });
-
-  it('应限制 pageSize 不小于最小值', () => {
-    const result = normalizePagination({ pageSize: 0 });
-    expect(result.pageSize).toBe(PAGINATION_DEFAULTS.minPageSize);
-  });
-
-  it('应限制 page 不小于 1', () => {
-    const result = normalizePagination({ page: -1 });
-    expect(result.page).toBe(1);
-  });
-
-  it('应正确处理小数值', () => {
-    const result = normalizePagination({ page: 1.5, pageSize: 10.9 });
-    expect(result).toEqual({ page: 1, pageSize: 10 });
-  });
-
-  it('应正确处理部分参数', () => {
-    const result = normalizePagination({ page: 5 });
-    expect(result).toEqual({ page: 5, pageSize: PAGINATION_DEFAULTS.pageSize });
-  });
-});
-
-describe('normalizeOffsetPagination', () => {
-  it('应返回默认值当参数为空时', () => {
-    const result = normalizeOffsetPagination();
-    expect(result).toEqual({
-      limit: PAGINATION_DEFAULTS.pageSize,
-      offset: 0,
-    });
-  });
-
-  it('应正确规范化有效的 offset 分页参数', () => {
-    const result = normalizeOffsetPagination({ limit: 50, offset: 100 });
-    expect(result).toEqual({ limit: 50, offset: 100 });
-  });
-
-  it('应限制 limit 不超过最大值', () => {
-    const result = normalizeOffsetPagination({ limit: 200 });
-    expect(result.limit).toBe(PAGINATION_DEFAULTS.maxPageSize);
-  });
-
-  it('应限制 limit 不小于最小值', () => {
-    const result = normalizeOffsetPagination({ limit: 0 });
-    expect(result.limit).toBe(PAGINATION_DEFAULTS.minPageSize);
-  });
-
-  it('应限制 offset 不小于 0', () => {
-    const result = normalizeOffsetPagination({ offset: -10 });
-    expect(result.offset).toBe(0);
-  });
-
-  it('应正确处理小数值', () => {
-    const result = normalizeOffsetPagination({ limit: 10.9, offset: 50.5 });
-    expect(result).toEqual({ limit: 10, offset: 50 });
-  });
-});
-
-describe('calculateOffset', () => {
-  it('应正确计算第一页的偏移量', () => {
-    expect(calculateOffset(1, 20)).toBe(0);
-  });
-
-  it('应正确计算第二页的偏移量', () => {
-    expect(calculateOffset(2, 20)).toBe(20);
-  });
-
-  it('应正确计算任意页的偏移量', () => {
-    expect(calculateOffset(5, 10)).toBe(40);
-  });
-
-  it('应正确处理不同的页面大小', () => {
-    expect(calculateOffset(3, 50)).toBe(100);
-  });
-});
-
-describe('calculateTotalPages', () => {
-  it('应正确计算总页数', () => {
-    expect(calculateTotalPages(100, 20)).toBe(5);
-  });
-
-  it('应正确处理有余数的情况', () => {
-    expect(calculateTotalPages(95, 20)).toBe(5);
-  });
-
-  it('应正确处理总数为 0 的情况', () => {
-    expect(calculateTotalPages(0, 20)).toBe(0);
-  });
-
-  it('应正确处理总数小于页面大小的情况', () => {
-    expect(calculateTotalPages(15, 20)).toBe(1);
-  });
-
-  it('应正确处理 pageSize 为 0 的情况', () => {
-    expect(calculateTotalPages(100, 0)).toBe(0);
-  });
-});
-
-describe('hasNextPage', () => {
-  it('应返回 true 当有下一页时', () => {
-    expect(hasNextPage(1, 5)).toBe(true);
-  });
-
-  it('应返回 false 当在最后一页时', () => {
-    expect(hasNextPage(5, 5)).toBe(false);
-  });
-
-  it('应返回 false 当总页数为 0 时', () => {
-    expect(hasNextPage(1, 0)).toBe(false);
-  });
-});
-
-describe('hasPreviousPage', () => {
-  it('应返回 false 当在第一页时', () => {
-    expect(hasPreviousPage(1)).toBe(false);
-  });
-
-  it('应返回 true 当不在第一页时', () => {
-    expect(hasPreviousPage(2)).toBe(true);
-  });
-
-  it('应返回 true 当在大页码时', () => {
-    expect(hasPreviousPage(100)).toBe(true);
-  });
-});
-
-describe('offsetToPage', () => {
-  it('应正确转换 offset 0 到第一页', () => {
-    expect(offsetToPage(0, 20)).toEqual({ page: 1, pageSize: 20 });
-  });
-
-  it('应正确转换 offset 到对应页', () => {
-    expect(offsetToPage(40, 20)).toEqual({ page: 3, pageSize: 20 });
-  });
-
-  it('应正确处理非整除情况', () => {
-    expect(offsetToPage(25, 20)).toEqual({ page: 2, pageSize: 20 });
-  });
-
-  it('应正确处理 limit 为 0 的情况', () => {
-    expect(offsetToPage(0, 0)).toEqual({ page: 1, pageSize: 1 });
-  });
-});
-
-describe('pageToOffset', () => {
-  it('应正确转换第一页到 offset 0', () => {
-    expect(pageToOffset(1, 20)).toEqual({ offset: 0, limit: 20 });
-  });
-
-  it('应正确转换页码到 offset', () => {
-    expect(pageToOffset(3, 20)).toEqual({ offset: 40, limit: 20 });
-  });
-
-  it('应正确处理 page 为 0 的情况', () => {
-    expect(pageToOffset(0, 20)).toEqual({ offset: 0, limit: 20 });
-  });
-
-  it('应正确处理 pageSize 为 0 的情况', () => {
-    expect(pageToOffset(1, 0)).toEqual({ offset: 0, limit: 1 });
-  });
-});
-
-describe('createPaginatedResult', () => {
-  it('应正确创建分页结果', () => {
-    const items = [1, 2, 3];
-    const result = createPaginatedResult(items, 100, 2, 20);
-
-    expect(result).toEqual({
-      items,
-      total: 100,
-      page: 2,
-      pageSize: 20,
-      totalPages: 5,
-      hasNextPage: true,
-      hasPreviousPage: true,
-    });
-  });
-
-  it('应正确处理第一页', () => {
-    const items = [1, 2, 3];
-    const result = createPaginatedResult(items, 100, 1, 20);
-
-    expect(result.hasPreviousPage).toBe(false);
-    expect(result.hasNextPage).toBe(true);
-  });
-
-  it('应正确处理最后一页', () => {
-    const items = [1, 2, 3];
-    const result = createPaginatedResult(items, 100, 5, 20);
-
-    expect(result.hasPreviousPage).toBe(true);
-    expect(result.hasNextPage).toBe(false);
-  });
-
-  it('应正确处理空结果', () => {
-    const result = createPaginatedResult([], 0, 1, 20);
-
-    expect(result).toEqual({
-      items: [],
-      total: 0,
-      page: 1,
-      pageSize: 20,
-      totalPages: 0,
-      hasNextPage: false,
-      hasPreviousPage: false,
-    });
-  });
-});

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

@@ -1,142 +0,0 @@
-/**
- * 分页结果 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();
-  });
-});