Building a Service Layer

Welcome to an important step in structuring your Task Manager API—building the service layer. This layer forms the core of your backend’s architecture and acts as the central hub for business logic. It ensures that your code remains clean, modular, and easy to scale as the project grows.

In a well-organized backend, each component has a distinct purpose:

• API routes handle HTTP requests and responses.
• The service layer manages all business rules and data operations.
• Data files or databases are responsible for storing information.

By introducing a service layer, you separate what happens from how it’s delivered. Your routes don’t directly manipulate data—they simply call service functions. This separation promotes maintainability and makes your backend easier to test and refactor.

Think of it like a restaurant:

• The waiter (API route) takes the order,
• The kitchen (service layer) prepares the meal, and
• The customer (client) receives the finished dish.

Each role is distinct, and the result is a smooth, organized operation.

Before we dive into building the service layer, let’s review how tasks are currently defined. The file app/lib/tasks.ts holds both the Task type definition and the in-memory data store. This small but important file defines the structure of each task and where the data lives while your app runs.

export type Task = {
  id: number;
  title: string;
  description?: string;
  completed: boolean;
  dueDate?: string;
  createdAt: string;
  updatedAt?: string;
};

export const tasks: Task[] = [
  {
    id: 1,
    title: "Draft course outline",
    description: "First pass on the Task Manager API lesson flow",
    completed: false,
    createdAt: new Date().toISOString()
  }
];

The Task type ensures that every task follows the same structure, making your application predictable and easier to debug. Meanwhile, the tasks array acts as a temporary data store in memory—standing in for a database while we focus on logic. Each task includes timestamps like createdAt and optionally updatedAt, which make tracking changes simple. This setup allows us to work entirely with logic first and worry about persistence later.

The service layer lives in app/lib/services/taskService.ts. It’s where you’ll define pure functions that handle task-related operations such as fetching, creating, updating, and deleting. By isolating this logic, your route files can remain small and focused only on handling HTTP behavior, while your core logic stays centralized.

The file begins by importing dependencies and defining a simple utility function:

import { tasks, type Task } from "~/lib/tasks";

type OptionalTask = Partial<Omit<Task, "id" | "createdAt">>;

function nextId() {
  return tasks.length > 0 ? Math.max(...tasks.map(t => t.id)) + 1 : 1;
}

Here’s what’s happening: the module imports both the tasks array and the Task type from your data module. Then it defines an OptionalTask type, which allows you to create partial updates for tasks—useful for PATCH requests. The helper function nextId() calculates a new ID dynamically by checking the existing maximum. This ensures every new task gets a unique identifier, even in an in-memory store.

Each service function focuses on one job and keeps the logic straightforward. Together, these functions form the backbone of your backend’s data operations.

1. Get All Tasks

export function getAllTasks(): Task[] {
  return [...tasks];
}

This simple function returns a shallow copy of the tasks array. Returning a copy helps prevent accidental modifications to the original data from outside the service. It’s the function your GET /api/tasks route will call to list all existing tasks.

2. Get Task by ID

export function getTaskById(id: number): Task | undefined {
  return tasks.find(t => t.id === id);
}

This function searches for a task whose id matches the provided value. If it finds one, it returns the task; otherwise, it returns undefined. It’s a small but crucial function used by endpoints like GET /api/tasks/:id, helping your API quickly retrieve a single record.

3. Create a New Task

export function createTask(payload: { title: string; description?: string; completed?: boolean; dueDate?: string }): Task {
  const task: Task = {
    id: nextId(),
    title: payload.title.trim(),
    description: payload.description?.trim() || undefined,
    completed: typeof payload.completed === "boolean" ? payload.completed : false,
    dueDate: payload.dueDate,
    createdAt: new Date().toISOString()
  };
  tasks.push(task);
  return task;
}

Creating a task involves transforming raw input into a properly structured Task object. The title and description are trimmed for cleanliness, and completed defaults to false if not provided. Once created, the task is added to the in-memory array and returned so it can be sent back in the API response. This function powers the POST /api/tasks route and demonstrates how the service layer abstracts logic away from routes.

4. Replace (PUT) a Task

export function replaceTask(
  id: number,
  payload: { title: string; description?: string; completed: boolean; dueDate?: string }
): Task | undefined {
  const idx = tasks.findIndex(t => t.id === id);
  if (idx === -1) return undefined;
  const existing = tasks[idx];
  const updated: Task = {
    id,
    title: payload.title.trim(),
    description: payload.description?.trim() || undefined,
    completed: payload.completed,
    dueDate: payload.dueDate,
    createdAt: existing.createdAt,
    updatedAt: new Date().toISOString()
  };
  tasks[idx] = updated;
  return updated;
}

This function performs a full replacement of a task’s data. It first finds the task by id and, if it exists, builds a completely new task object using the incoming payload. The createdAt timestamp remains unchanged to preserve history, while updatedAt reflects the current update time. After replacing the old entry in the array, the function returns the updated task. It’s ideal for PUT requests where you overwrite all fields.

5. Patch (Partial Update) a Task

export function patchTask(id: number, patch: OptionalTask): Task | undefined {
  const idx = tasks.findIndex(t => t.id === id);
  if (idx === -1) return undefined;
  const existing = tasks[idx];
  const updated: Task = {
    ...existing,
    ...patch,
    title: typeof patch.title === "string" ? patch.title.trim() : existing.title,
    description: typeof patch.description === "string" ? patch.description.trim() : existing.description,
    updatedAt: new Date().toISOString()
  };
  tasks[idx] = updated;
  return updated;
}

Unlike a full replacement, this method selectively updates only the provided fields. It merges the old task data with new values using object spread syntax, ensuring that unspecified properties remain unchanged. The function also trims strings and updates the timestamp, maintaining consistency. It’s perfect for lightweight updates like marking a task as completed or adjusting a due date.

6. Delete a Task

export function deleteTask(id: number): boolean {
  const idx = tasks.findIndex(t => t.id === id);
  if (idx === -1) return false;
  tasks.splice(idx, 1);
  return true;
}

The delete operation is straightforward but important. It locates a task by its id and removes it from the array if found. The function returns true upon success and false if no such task exists. This keeps deletion logic clean and predictable for routes like DELETE /api/tasks/:id.

7. Filter Tasks by Completion Status

export function filterTasksByCompletion(completed: boolean): Task[] {
  return tasks.filter(t => t.completed === completed);
}

Filtering allows you to quickly view tasks based on their completion state. This function returns all tasks matching the provided completed value, making it easy to build filtered endpoints like /api/tasks?completed=true. By centralizing this logic, your app can reuse it in multiple contexts—routes, tests, or UI interactions.

Before we can safely use these service functions, it’s critical to validate the incoming data. The file app/lib/taskValidation.ts ensures that requests include the right fields and correct data types before they reach the logic layer. This helps prevent runtime errors and keeps your data clean.

export function validateTaskPayload(
  payload: unknown,
  opts: { requireAll?: boolean } = {}
): string[] {
  const requireAll = opts.requireAll ?? false;
  const errors: string[] = [];

  if (typeof payload !== "object" || payload === null) {
    return ["Body must be a JSON object"];
  }

  const p = payload as Record<string, unknown>;

  if (requireAll && typeof p.title !== "string") {
    errors.push("'title' is required and must be a string");
  }

  if ("title" in p && typeof p.title !== "string") {
    errors.push("'title' must be a string");
  } else if (typeof p.title === "string" && p.title.trim().length === 0) {
    errors.push("'title' cannot be empty");
  }

  if ("description" in p && p.description !== undefined && typeof p.description !== "string") {
    errors.push("'description' must be a string");
  }

  if ("completed" in p && typeof p.completed !== "boolean") {
    errors.push("'completed' must be a boolean");
  }

  if ("dueDate" in p) {
    const v = p.dueDate;
    if (v !== undefined && typeof v !== "string") {
      errors.push("'dueDate' must be an ISO date string");
    } else if (typeof v === "string") {
      const d = new Date(v);
      if (Number.isNaN(d.getTime())) errors.push("'dueDate' must be a valid date string");
    }
  }

  return errors;
}

• Object shape and required fields The initial checks ensure the payload is a valid JSON object and, when requireAll is enabled, that required fields like title are present and correctly typed. This allows the same validator to support both full replacements (PUT) and partial updates (PATCH). It prevents invalid request shapes from reaching the service layer.

• Presence vs. validity of optional fields For fields like description, completed, and dueDate, validation only runs if the key is present in the payload. This preserves the distinction between omitting a field and intentionally updating it. Any provided value must still match the expected type.

• Content-level validation Strings are checked not just for type, but for meaningful content (for example, rejecting empty or whitespace-only titles). Date strings are validated by attempting to parse them into real Date objects. This ensures data is both syntactically and semantically valid.

• Collecting all errors at once Instead of stopping at the first failure, the validator accumulates all issues and returns them together. This gives clients clearer, more actionable feedback. It also keeps error handling consistent across routes.

Now that the service and validation logic are ready, your API routes become much simpler and easier to maintain. Here’s an example that shows how clean and readable routes can be once logic is abstracted into services:

import { getAllTasks, createTask } from "~/lib/services/taskService";
import { validateTaskPayload } from "~/lib/taskValidation";

export async function loader() {
  return { status: "success", data: getAllTasks() };
}

export async function action({ request }: { request: Request }) {
  const body = await request.json();
  const errors = validateTaskPayload(body, { requireAll: true });
  if (errors.length > 0) {
    return { status: "error", errors };
  }
  const newTask = createTask(body);
  return { status: "success", data: newTask };
}

Here, the loader() simply calls getAllTasks() to fetch the data, and the action() first validates the request before calling createTask() to add a new record. Notice how the route’s job is limited to coordinating between HTTP requests, validation, and service functions. This kind of separation makes your API easy to test, extend, and debug as your codebase grows.

In this lesson, you learned how introducing a service layer can dramatically improve your backend’s structure. You implemented all core task operations—creating, reading, updating, deleting, and filtering—while keeping logic isolated from routing. You also added robust validation to ensure clean and consistent data handling. With this architecture in place, your backend is more professional, modular, and maintainable.

In the next lesson, you’ll connect these service functions to API routes and see how this layered structure simplifies both development and debugging.