Filtering, Search, Sorting & Pagination

TaskFlow Phase 15 reference snapshot

This snapshot contains only the files changed or emphasized by Phase 15 and assumes Phase 14 is complete.

Implemented collection behavior:
- validated query parameters
- project/status/priority/assignee filters
- case-insensitive title/description substring search
- allow-listed sorting
- stable id tiebreaker
- offset pagination with metadata
- total-count query grouped with the page query
- Next.js server-side query-state example

Cursor pagination is taught conceptually but not used as the primary API contract because the current TaskFlow UI is page-number oriented.

import { z } from "zod";
import {
  TaskPriority,
  TaskStatus,
} from "../generated/prisma/client";

export const taskSortFieldSchema = z.enum([
  "createdAt",
  "updatedAt",
  "dueAt",
  "title",
]);

export const sortOrderSchema = z.enum(["asc", "desc"]);

export const taskListQuerySchema = z.strictObject({
  projectId: z.uuid().optional(),
  assigneeId: z.uuid().optional(),
  status: z.enum(TaskStatus).optional(),
  priority: z.enum(TaskPriority).optional(),

import {
  Controller,
  Get,
  Param,
  Query,
} from "@nestjs/common";
import { StandardSchemaValidationPipe } from "@nestjs/common";
import { TasksService } from "./tasks.service";
import {
  taskIdSchema,
} from "./tasks.schemas";
import {
  taskListQuerySchema,
  TaskListQueryDto,
} from "./tasks-query.schemas";

@Controller("tasks")
export class TasksController {
  constructor(private readonly tasksService: TasksService) {}

import { Injectable } from "@nestjs/common";
import {
  Prisma,
  TaskStatus,
} from "../generated/prisma/client";
import { PrismaService } from "../prisma/prisma.service";
import {
  TaskNotFoundException,
} from "../common/errors/application.exceptions";
import {
  TaskListQueryDto,
  TaskSortField,
  SortOrder,
} from "./tasks-query.schemas";

@Injectable()
export class TasksService {
  constructor(private readonly prisma: PrismaService) {}

  async findAll(query: TaskListQueryDto) {

import { fetchTasks } from "@/lib/api/tasks";

type SearchParams = Record<
  string,
  string | string[] | undefined
>;

type TasksPageProps = {
  searchParams: Promise<SearchParams>;
};

function first(value: string | string[] | undefined) {
  return Array.isArray(value) ? value[0] : value;
}

export default async function TasksPage({ searchParams }: TasksPageProps) {
  const params = await searchParams;

  const result = await fetchTasks({
    status: first(params.status),

export type TaskListMeta = {
  page: number;
  pageSize: number;
  totalItems: number;
  totalPages: number;
  hasPreviousPage: boolean;
  hasNextPage: boolean;
};

export type TaskListResponse<TTask> = {
  data: TTask[];
  meta: TaskListMeta;
};

export type TaskListParams = {
  projectId?: string;
  assigneeId?: string;
  status?: string;
  priority?: string;
  search?: string;

# Phase 15 index notes

Do not add every conceivable index.

Start from actual queries and EXPLAIN output.

The existing TaskFlow model already has:

```prisma
@@index([projectId, status])
@@index([assigneeId, status])
```

A frequently measured project listing such as:

- WHERE projectId = ?
- ORDER BY createdAt DESC

may justify an additional index such as:

// Concept-only example: cursor pagination needs a deliberately stable cursor strategy.
// TaskFlow implements offset pagination first because the current UI uses page numbers.

const page = await prisma.task.findMany({
  take: 20,
  cursor: cursorId ? { id: cursorId } : undefined,
  skip: cursorId ? 1 : 0,
  orderBy: { id: "asc" },
});

// Real production feeds often need a cursor aligned with the desired ordering.
// With random UUID ids and createdAt ordering, design the cursor intentionally
// instead of assuming offset and cursor pagination are interchangeable.

# Phase 15 collection API smoke checks.
$api = "http://127.0.0.1:4000"

# Defaults: page=1, pageSize=20, sort=createdAt, order=desc
Invoke-RestMethod -Uri "$api/tasks"

# Filter by status and priority.
Invoke-RestMethod -Uri "$api/tasks?status=IN_PROGRESS&priority=HIGH"

# Case-insensitive substring search.
Invoke-RestMethod -Uri "$api/tasks?search=payroll"

# Stable sorting with page metadata.
Invoke-RestMethod -Uri "$api/tasks?sort=title&order=asc&page=1&pageSize=10"

# Invalid page should fail validation.
try {
  Invoke-RestMethod -Uri "$api/tasks?page=0"
} catch {
  $_.ErrorDetails.Message