# Migration Guide: 11.10.x → 11.11.x

## Overview

| Category | Details |
|----------|---------|
| **Breaking Changes** | None |
| **New Features** | **PaginationInfo model** for paginated queries with navigation metadata |
| **Bugfixes** | None |
| **Migration Effort** | Very Low (~5 minutes) - No changes required, opt-in feature |

---

## Quick Migration

```bash
# Update package
npm install @lenne.tech/nest-server@11.11.x

# Verify build
npm run build

# Run tests
npm test
```

**That's it!** This is a non-breaking update. The new `PaginationInfo` feature is opt-in.

---

## What's New in 11.11.x

### 1. PaginationInfo Model for API Navigation

A new `PaginationInfo` model provides pagination metadata for paginated queries, making it easier to implement frontend pagination UI components.

**New Fields Available:**

| Field | Type | Description |
|-------|------|-------------|
| `totalCount` | number | Total number of items across all pages |
| `pageCount` | number | Total number of pages |
| `currentPage` | number | Current page number (1-based) |
| `perPage` | number | Number of items per page |
| `hasNextPage` | boolean | Indicates if there is a next page |
| `hasPreviousPage` | boolean | Indicates if there is a previous page |

**GraphQL Response Structure:**

The `findAndCount` method now returns an additional `pagination` field alongside the existing `items` and `totalCount`:

```graphql
query {
  findAndCountUsers(skip: 0, take: 10) {
    items {
      id
      email
    }
    totalCount
    pagination {
      totalCount
      pageCount
      currentPage
      perPage
      hasNextPage
      hasPreviousPage
    }
  }
}
```

**Example Response:**

```json
{
  "data": {
    "findAndCountUsers": {
      "items": [...],
      "totalCount": 47,
      "pagination": {
        "totalCount": 47,
        "pageCount": 5,
        "currentPage": 1,
        "perPage": 10,
        "hasNextPage": true,
        "hasPreviousPage": false
      }
    }
  }
}
```

### 2. Using PaginationInfo in Custom Outputs

To use `PaginationInfo` in your own `findAndCount` result types, add the pagination field:

```typescript
import { ObjectType } from '@nestjs/graphql';
import { PaginationInfo, UnifiedField } from '@lenne.tech/nest-server';
import { YourModel } from './your.model';

@ObjectType({ description: 'Result of find and count' })
export class FindAndCountYourModelResult {
  @UnifiedField({
    description: 'Found items',
    isArray: true,
    isOptional: true,
    type: () => YourModel,
  })
  items: YourModel[];

  @UnifiedField({
    description: 'Total count (skip/offset and limit/take are ignored)',
    isOptional: false,
  })
  totalCount: number;

  // NEW: Add pagination field
  @UnifiedField({
    description: 'Pagination information',
    isOptional: true,
    type: () => PaginationInfo,
  })
  pagination?: PaginationInfo;
}
```

### 3. PaginationInfo.create() Static Method

The `PaginationInfo` model provides a static `create()` method for generating pagination metadata:

```typescript
import { PaginationInfo } from '@lenne.tech/nest-server';

// Create pagination info from query parameters
const pagination = PaginationInfo.create({
  skip: 20,      // or offset
  take: 10,      // or limit
  totalCount: 47,
});

// Result:
// {
//   totalCount: 47,
//   pageCount: 5,
//   currentPage: 3,
//   perPage: 10,
//   hasNextPage: true,
//   hasPreviousPage: true,
// }
```

**Edge Cases:**

| Scenario | Result |
|----------|--------|
| Empty results (`totalCount: 0`) | `currentPage: 0`, `pageCount: 0`, `hasNextPage: false`, `hasPreviousPage: false` |
| No limit specified (`take: 0`) | All items treated as single page, `perPage: 0` |

---

## Breaking Changes

**None.** This is a fully backward-compatible update.

- Existing `findAndCount` queries continue to work without changes
- The `pagination` field is optional and only included when requested in the GraphQL query
- Existing `items` and `totalCount` fields remain unchanged

---

## Compatibility Notes

### Existing findAndCount Queries

Queries that don't request the `pagination` field continue to work unchanged:

```graphql
# Still works exactly as before
query {
  findAndCountUsers(skip: 0, take: 10) {
    items { id email }
    totalCount
  }
}
```

### CrudService.findAndCount Return Type

The return type of `findAndCount` now includes `pagination`:

```typescript
// Return type
Promise<{
  items: Model[];
  pagination: PaginationInfo;
  totalCount: number;
}>
```

This is backward compatible because:
- The `pagination` property is automatically calculated
- TypeScript will accept the extended return type
- GraphQL clients only receive fields they request

---

## Troubleshooting

### Pagination Field Not Available in GraphQL

**Symptom:** The `pagination` field is not available when querying `findAndCount`.

**Solution:** Ensure your output type includes the `pagination` field:

```typescript
@UnifiedField({
  description: 'Pagination information',
  isOptional: true,
  type: () => PaginationInfo,
})
pagination?: PaginationInfo;
```

### currentPage Shows 0

**Symptom:** `currentPage` returns 0 even with items in the result.

**Cause:** This happens when `totalCount` is 0 (empty result set).

**Expected Behavior:** When there are no results, `currentPage` is 0 to indicate "no page".

---

## Module Documentation

### CrudService

- **Location:** `src/core/common/services/crud.service.ts`
- **Key Method:** `findAndCount()` - Now returns `pagination` alongside `items` and `totalCount`

### PaginationInfo Model

- **Location:** `src/core/common/models/pagination-info.model.ts`
- **Export:** `@lenne.tech/nest-server`
- **Reference Implementation:** `src/server/modules/user/outputs/find-and-count-users-result.output.ts`

---

## New Exports

The following is now exported from `@lenne.tech/nest-server`:

```typescript
// PaginationInfo model (11.11.0)
export { PaginationInfo } from './core/common/models/pagination-info.model';
```

---

## References

- [CrudService](../src/core/common/services/crud.service.ts) - Base service with `findAndCount` method
- [PaginationInfo Model](../src/core/common/models/pagination-info.model.ts) - Pagination metadata model
- [User Output Example](../src/server/modules/user/outputs/find-and-count-users-result.output.ts) - Reference implementation
- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)
