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'; } 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

Loading cart items and product data

Next we load cart item rows, then load the referenced products, and build a lookup map so we can attach products onto items efficiently.

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];
    })
  );

Cart items are ordered by created_at so responses are stable: repeated calls return items in the same order, which makes client rendering much simpler and more predictable.
Products are fetched in a separate query because cart item rows only contain product_id. The cart response, however, wants to include product info for display and currency handling.
The productMap avoids O(n²) lookups. Instead of scanning the product array for every item, we do O(1) Map.get(product_id) per item.
Product rows are normalized defensively: currency is forced to 'USD', and status is coerced into the domain union (active/archived) with a safe default. That protects the cart response from inconsistent DB strings.

Hydrating cart items and computing totals

Finally, we attach products onto each cart item and compute subtotal, tax, and total.

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 } };
}

Each returned CartItem includes unit_price_cents, which acts like a “price snapshot” for the cart line. This is important because it means totals are computed from what the cart recorded, not necessarily from the product’s current price.
product is attached as productMap.get(ci.product_id) and can be undefined. That’s intentional defensive coding: if data becomes inconsistent, the cart still loads instead of crashing the entire request.
Totals are computed in cents, which avoids floating-point rounding issues. This is a standard backend practice for money values.
Tax is computed using computeTaxCents(subtotal) (from @/lib/money/tax). That makes tax a pure computation: we don’t store totals in the DB; we derive them when reading the cart.
The currency rule is simple and stable: take it from the first item’s product if available, otherwise default to 'USD'. This ensures empty carts still have a useful currency value.

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