Creating and Viewing Carts

Welcome! 👋 In this lesson we’ll add the two most important “entry points” for working with carts: creating a cart, and fetching a cart by ID in a predictable, client-friendly shape. You’ll see how the cart is modeled as a real backend resource (not just “a list of products”), and how our codebase builds a fully “hydrated” cart response that includes items and totals —even when the cart is empty. By the end, you’ll understand exactly where persistence happens (repository), where coordination happens (service), and how the API route ties everything together.

A cart is a real resource, not just a list

In this project, a cart has its own identity and lifecycle : It has an id (UUID), a status (open, checked_out, abandoned), and timestamps. It can exist before any items are added. When you fetch a cart, the response is intentionally stable : the API should return items and totals consistently so clients don’t need special “empty cart” logic. That stability is created in the repository layer by composing the cart from multiple queries: the cart row, its item rows, and the referenced product data. The repository file src/lib/repositories/cartsRepo.ts is where we talk to PostgreSQL. It does SQL-in / rows-out, then maps database rows into domain objects.

Database row types and status mapping

This first chunk defines what we expect from the database and how we normalize the status string into the domain union type. TypeScript// src/lib/repositories/cartsRepo.ts export interface CartRow { id: string; status: string; created_at: string; updated_at: string; } function mapCartStatus(status: string): Cart['status'] { return ['open', 'checked_out', 'abandoned'].includes(status) ? (status as Cart['status']) : 'open'; }// src/lib/repositories/cartsRepo.ts export interface CartRow { id: string; status: string; created_at: string; updated_at: string; } function mapCartStatus(status: string): Cart['status'] { return ['open', 'checked_out', 'abandoned'].includes(status) ? (status as Cart['status']) : 'open'; } CartRow mirrors the carts table columns exactly, using string for status because Postgres returns it as text. This keeps the “DB shape” separate from the “domain shape”. mapCartStatus is a small defensive layer: if the DB ever contains an unexpected status string, we fall back to 'open' instead of crashing or leaking invalid data through the API. This mapping is important because the domain type Cart['status'] is a union, and the rest of the app assumes it only ever sees valid values.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

TypeScript

// src/lib/repositories/cartsRepo.ts
export interface CartRow {
  id: string;
  status: string;
  created_at: string;
  updated_at: string;
}

function mapCartStatus(status: string): Cart['status'] {
  return ['open', 'checked_out', 'abandoned'].includes(status) ? (status as Cart['status']) : 'open';
}

TypeScript

// src/lib/repositories/cartsRepo.ts
export async function createCart(id: string): Promise<Cart> {
  const rows = await query<CartRow>(
    `INSERT INTO carts (id) VALUES ($1) RETURNING *`,
    [id]
  );
  const r = rows[0];
  return { id: r.id, status: mapCartStatus(r.status), created_at: r.created_at, updated_at: r.updated_at };
}

// src/lib/repositories/cartsRepo.ts
export async function createCart(id: string): Promise<Cart> {
  const rows = await query<CartRow>(
    `INSERT INTO carts (id) VALUES ($1) RETURNING *`,
    [id]
  );
  const r = rows[0];
  return { id: r.id, status: mapCartStatus(r.status), created_at: r.created_at, updated_at: r.updated_at };
}

TypeScript

// src/lib/repositories/cartsRepo.ts
export async function getCartById(id: string): Promise<Cart | null> {
  const rows = await query<CartRow>('SELECT * FROM carts WHERE id = $1', [id]);
  if (!rows[0]) return null;

  const base: Cart = {
    id: rows[0].id,
    status: mapCartStatus(rows[0].status),
    created_at: rows[0].created_at,
    updated_at: rows[0].updated_at,
  };

  // ...continued below
}

// src/lib/repositories/cartsRepo.ts
export async function getCartById(id: string): Promise<Cart | null> {
  const rows = await query<CartRow>('SELECT * FROM carts WHERE id = $1', [id]);
  if (!rows[0]) return null;

  const base: Cart = {
    id: rows[0].id,
    status: mapCartStatus(rows[0].status),
    created_at: rows[0].created_at,
    updated_at: rows[0].updated_at,
  };

  // ...continued below
}

TypeScript

// src/lib/repositories/cartsRepo.ts
  const items = await query<CartItemRow>(
    `SELECT ci.* FROM cart_items ci WHERE ci.cart_id = $1 ORDER BY ci.created_at ASC`,
    [id]
  );

  const productRows = await query<Pick<Product, 'id' | 'sku' | 'name' | 'price_cents' | 'currency' | 'status'>>(
    `SELECT id, sku, name, price_cents, currency, status FROM products WHERE id IN (
      SELECT product_id FROM cart_items WHERE cart_id = $1
    )`,
    [id]
  );

  const productMap = new Map(
    productRows.map((p) => {
      const normalized: Pick<Product, 'id' | 'sku' | 'name' | 'price_cents' | 'currency' | 'status'> = {
        ...p,
        currency: 'USD',
        status: ['active', 'archived'].includes(p.status) ? (p.status as Product['status']) : 'active',
      };
      return [normalized.id, normalized];
    })
  );

// src/lib/repositories/cartsRepo.ts
  const items = await query<CartItemRow>(
    `SELECT ci.* FROM cart_items ci WHERE ci.cart_id = $1 ORDER BY ci.created_at ASC`,
    [id]
  );

  const productRows = await query<Pick<Product, 'id' | 'sku' | 'name' | 'price_cents' | 'currency' | 'status'>>(
    `SELECT id, sku, name, price_cents, currency, status FROM products WHERE id IN (
      SELECT product_id FROM cart_items WHERE cart_id = $1
    )`,
    [id]
  );

  const productMap = new Map(
    productRows.map((p) => {
      const normalized: Pick<Product, 'id' | 'sku' | 'name' | 'price_cents' | 'currency' | 'status'> = {
        ...p,
        currency: 'USD',
        status: ['active', 'archived'].includes(p.status) ? (p.status as Product['status']) : 'active',
      };
      return [normalized.id, normalized];
    })
  );

TypeScript

// src/lib/repositories/cartsRepo.ts
  const cartItems: CartItem[] = items.map((ci) => ({
    id: ci.id,
    cart_id: ci.cart_id,
    product_id: ci.product_id,
    quantity: ci.quantity,
    unit_price_cents: ci.unit_price_cents,
    created_at: ci.created_at,
    updated_at: ci.updated_at,
    product: productMap.get(ci.product_id),
  }));

  const subtotal = cartItems.reduce((acc, it) => acc + it.quantity * it.unit_price_cents, 0);
  const tax = computeTaxCents(subtotal);
  const currency = cartItems[0]?.product?.currency ?? 'USD';

  return { ...base, items: cartItems, totals: { subtotal_cents: subtotal, tax_cents: tax, total_cents: subtotal + tax, currency } };
}

// src/lib/repositories/cartsRepo.ts
  const cartItems: CartItem[] = items.map((ci) => ({
    id: ci.id,
    cart_id: ci.cart_id,
    product_id: ci.product_id,
    quantity: ci.quantity,
    unit_price_cents: ci.unit_price_cents,
    created_at: ci.created_at,
    updated_at: ci.updated_at,
    product: productMap.get(ci.product_id),
  }));

  const subtotal = cartItems.reduce((acc, it) => acc + it.quantity * it.unit_price_cents, 0);
  const tax = computeTaxCents(subtotal);
  const currency = cartItems[0]?.product?.currency ?? 'USD';

  return { ...base, items: cartItems, totals: { subtotal_cents: subtotal, tax_cents: tax, total_cents: subtotal + tax, currency } };
}

TypeScript

// src/lib/services/cartsService.ts
export async function createCartService(): Promise<ServiceResult<Cart>> {
  try {
    const cart = await createCart(randomUUID());
    return ok(cart);
  } catch (e: unknown) {
    return handleException(e);
  }
}

// src/lib/services/cartsService.ts
export async function createCartService(): Promise<ServiceResult<Cart>> {
  try {
    const cart = await createCart(randomUUID());
    return ok(cart);
  } catch (e: unknown) {
    return handleException(e);
  }
}

TypeScript

// src/lib/services/cartsService.ts
export async function getCartService(id: string): Promise<ServiceResult<Cart>> {
  try {
    const cart = await getCartById(id);
    if (!cart) return fail({ code: 'NOT_FOUND', message: 'Cart not found', httpStatus: 404 });
    return ok(cart);
  } catch (e: unknown) {
    return handleException(e);
  }
}

// src/lib/services/cartsService.ts
export async function getCartService(id: string): Promise<ServiceResult<Cart>> {
  try {
    const cart = await getCartById(id);
    if (!cart) return fail({ code: 'NOT_FOUND', message: 'Cart not found', httpStatus: 404 });
    return ok(cart);
  } catch (e: unknown) {
    return handleException(e);
  }
}

TypeScript

// src/lib/repositories/cartsRepo.ts
export async function createCart(id: string): Promise<Cart> {
  const rows = await query<CartRow>(
    `INSERT INTO carts (id) VALUES ($1) RETURNING *`,
    [id]
  );
  const r = rows[0];
  return { id: r.id, status: mapCartStatus(r.status), created_at: r.created_at, updated_at: r.updated_at };
}

TypeScript

// src/lib/repositories/cartsRepo.ts
export async function getCartById(id: string): Promise<Cart | null> {
  const rows = await query<CartRow>('SELECT * FROM carts WHERE id = $1', [id]);
  if (!rows[0]) return null;

  const base: Cart = {
    id: rows[0].id,
    status: mapCartStatus(rows[0].status),
    created_at: rows[0].created_at,
    updated_at: rows[0].updated_at,
  };

  // ...continued below
}

TypeScript

// src/lib/repositories/cartsRepo.ts
  const items = await query<CartItemRow>(
    `SELECT ci.* FROM cart_items ci WHERE ci.cart_id = $1 ORDER BY ci.created_at ASC`,
    [id]
  );

  const productRows = await query<Pick<Product, 'id' | 'sku' | 'name' | 'price_cents' | 'currency' | 'status'>>(
    `SELECT id, sku, name, price_cents, currency, status FROM products WHERE id IN (
      SELECT product_id FROM cart_items WHERE cart_id = $1
    )`,
    [id]
  );

  const productMap = new Map(
    productRows.map((p) => {
      const normalized: Pick<Product, 'id' | 'sku' | 'name' | 'price_cents' | 'currency' | 'status'> = {
        ...p,
        currency: 'USD',
        status: ['active', 'archived'].includes(p.status) ? (p.status as Product['status']) : 'active',
      };
      return [normalized.id, normalized];
    })
  );

TypeScript

// src/lib/repositories/cartsRepo.ts
  const cartItems: CartItem[] = items.map((ci) => ({
    id: ci.id,
    cart_id: ci.cart_id,
    product_id: ci.product_id,
    quantity: ci.quantity,
    unit_price_cents: ci.unit_price_cents,
    created_at: ci.created_at,
    updated_at: ci.updated_at,
    product: productMap.get(ci.product_id),
  }));

  const subtotal = cartItems.reduce((acc, it) => acc + it.quantity * it.unit_price_cents, 0);
  const tax = computeTaxCents(subtotal);
  const currency = cartItems[0]?.product?.currency ?? 'USD';

  return { ...base, items: cartItems, totals: { subtotal_cents: subtotal, tax_cents: tax, total_cents: subtotal + tax, currency } };
}

TypeScript

// src/lib/services/cartsService.ts
export async function createCartService(): Promise<ServiceResult<Cart>> {
  try {
    const cart = await createCart(randomUUID());
    return ok(cart);
  } catch (e: unknown) {
    return handleException(e);
  }
}

TypeScript

// src/lib/services/cartsService.ts
export async function getCartService(id: string): Promise<ServiceResult<Cart>> {
  try {
    const cart = await getCartById(id);
    if (!cart) return fail({ code: 'NOT_FOUND', message: 'Cart not found', httpStatus: 404 });
    return ok(cart);
  } catch (e: unknown) {
    return handleException(e);
  }
}

Creating and Viewing Carts

A cart is a real resource, not just a list

Database row types and status mapping

Join the 1M+ learners on CodeSignal

Inserting a new cart

Repository: Fetching a “hydrated” cart with items and totals

Loading cart items and product data

Hydrating cart items and computing totals

Service layer: Coordinating IDs and shaping errors

Fetching a cart via the service

Recap