How a click reaches a database and comes back

{
  "name": "vending-machine-ts",
  "private": true,
  "type": "module",

  "scripts": {
    "setup-db": "node src/setup-db.ts",
    "build": "tsc -p client",
    "check": "tsc -p src",
    "start": "node src/server.ts"
  },

  "devDependencies": {
    "@types/node": "^22.20.5",
    "typescript": "^7.0.2"
  }
}

// Create the vending machine database and fill it with a few snacks.
//
// Run this file once before you start the server.
// Running it again resets the machine to its starting state.

import path from "node:path";
import { DatabaseSync } from "node:sqlite";

// The database is one ordinary file in the project folder.
// import.meta.dirname is the folder that holds this file, which is src,
// so ".." leads to the project folder above it.
const DATABASE_FILE = path.join(import.meta.dirname, "..", "vending.db");

// The schema describes the shape of our data: one table with four columns.
// The comments after the double dashes are SQL comments.
const SCHEMA = `
DROP TABLE IF EXISTS inventory;

CREATE TABLE inventory (
    slot_id     TEXT    PRIMARY KEY,                           -- identifies one slot, for example A1
    item_name   TEXT    NOT NULL,                              -- every slot must have a name
    price_cents INTEGER NOT NULL CHECK (price_cents >= 0),     -- whole cents, never decimals
    stock       INTEGER NOT NULL CHECK (stock >= 0)            -- the database refuses negative stock
);
`;

// Each entry is one row: [slot_id, item_name, price_cents, stock].
// The type after the colon says "a list of lists, each holding two strings
// and two numbers". The Oat Biscuits start with no stock so that we can test
// a sold-out slot.
const STARTING_STOCK: [string, string, number, number][] = [
  ["A1", "Sparkling Water", 175, 8],
  ["A2", "Salted Peanuts", 125, 5],
  ["B1", "Chocolate Bar", 200, 3],
  ["B2", "Oat Biscuits", 150, 0],
];

// Opening the database opens the file, and creates it if it does not exist.
const database = new DatabaseSync(DATABASE_FILE);

// A transaction groups the work: either all of it happens or none of it does.
database.exec("BEGIN");
database.exec(SCHEMA);

// A prepared statement is SQL that the database reads once and can run many
// times. The question marks are placeholders, and the values travel to the
// database separately from the SQL text.
const insertSlot = database.prepare(
  "INSERT INTO inventory (slot_id, item_name, price_cents, stock) VALUES (?, ?, ?, ?)",
);
for (const slotRow of STARTING_STOCK) {
  // The three dots spread the four values of the row into four arguments.
  insertSlot.run(...slotRow);
}
database.exec("COMMIT");

// Read the rows back so that we can see what was stored.
const storedRows = database
  .prepare("SELECT slot_id, item_name, price_cents, stock FROM inventory ORDER BY slot_id")
  .all();
for (const storedRow of storedRows) {
  console.log(Object.values(storedRow));
}

database.close();

// A small web server that sells snacks from a SQLite database.
//
// The file has four layers, from the bottom of the program to the top:
//   1. The data layer talks to the database. It knows nothing about HTTP.
//   2. The route layer connects URLs to data functions and checks the input.
//   3. The HTTP layer reads requests and writes responses.
//   4. The last lines start the server.

// Modules whose names start with "node:" are built into Node, so nothing needs installing.
import { readFileSync } from "node:fs";
import { createServer } from "node:http";
import type { IncomingMessage, ServerResponse } from "node:http";
import path from "node:path";
import { DatabaseSync } from "node:sqlite";

// The shape of one slot. It matches one row of the inventory table and the
// JSON that we send to the browser. A type exists only while we write and
// check the program. Node removes it before the program runs.
type Slot = {
  slot_id: string;
  item_name: string;
  price_cents: number;
  stock: number;
};

// --- Settings ----------------------------------------------------------------

// 127.0.0.1 means "this computer", so only programs on your own machine can connect.
const HOST = "127.0.0.1";

// The port decides which program on this computer receives the request.
const PORT = 8000;

// import.meta.dirname is the folder that holds this file, which is src,
// so ".." leads to the project folder above it.
const PROJECT_FOLDER = path.join(import.meta.dirname, "..");
const DATABASE_FILE = path.join(PROJECT_FOLDER, "vending.db");
const PUBLIC_FOLDER = path.join(PROJECT_FOLDER, "public");

// The only files that the server will send. Each URL path maps to a file name
// and a Content-Type. A fixed list stops visitors from asking for other files,
// such as server.ts or vending.db, by typing a path like /../src/server.ts.
const STATIC_FILES = new Map([
  ["/", { fileName: "index.html", contentType: "text/html; charset=utf-8" }],
  ["/style.css", { fileName: "style.css", contentType: "text/css; charset=utf-8" }],
  ["/app.js", { fileName: "app.js", contentType: "text/javascript; charset=utf-8" }],
]);

// A valid slot id is one capital letter followed by one digit, such as A1 or B2.
const SLOT_ID_PATTERN = /^[A-Z][0-9]$/;

// --- Errors ------------------------------------------------------------------
// The data layer reports problems by throwing these errors. Each name
// describes a problem in the language of the vending machine, and the HTTP
// layer decides which status code each problem deserves.

class BadRequest extends Error {}
class NoSuchSlot extends Error {}
class SoldOut extends Error {}

// --- Data layer --------------------------------------------------------------
// These functions are the only place where the program talks to the database.

// We open one connection for the whole program. Node runs our code on a single
// thread, so only one request touches the connection at a time. The Python
// edition opens a new connection for every request because its server uses
// several threads.
const database = new DatabaseSync(DATABASE_FILE);

// A prepared statement is SQL that the database has already read and checked.
// We prepare each statement once, when the server starts, and run it many
// times. If a table or column name were wrong, the error would appear here at
// startup and not on the first click. The ? is a placeholder for a value that
// travels separately from the SQL text, so a visitor can never change what the
// SQL means (SQL injection).
const selectAllSlots = database.prepare(
  "SELECT slot_id, item_name, price_cents, stock FROM inventory ORDER BY slot_id",
);
const selectOneSlot = database.prepare(
  "SELECT slot_id, item_name, price_cents, stock FROM inventory WHERE slot_id = ?",
);
// One statement checks the stock and changes it. If two buyers arrive at the
// same moment, the database handles them one after the other, so they cannot
// both take the last item.
const decrementStockIfAvailable = database.prepare(
  "UPDATE inventory SET stock = stock - 1 WHERE slot_id = ? AND stock > 0",
);

// Run some work as a transaction: all of it happens, or none of it does.
// The <T> means "whatever type the work returns", and the function returns the
// same type.
function runInTransaction<T>(work: () => T): T {
  database.exec("BEGIN");
  try {
    const result = work();
    database.exec("COMMIT");
    return result;
  } catch (error) {
    // Something went wrong, so undo every change made since BEGIN.
    database.exec("ROLLBACK");
    throw error;
  }
}

function getAllSlots(): Slot[] {
  // "as Slot[]" is a promise to the compiler. The compiler cannot see inside
  // the database, so it takes our word for the shape of the rows.
  return selectAllSlots.all() as Slot[];
}

function getSlot(slotId: string): Slot {
  const slot = selectOneSlot.get(slotId) as Slot | undefined;
  if (slot === undefined) {
    throw new NoSuchSlot(`No slot called ${slotId}.`);
  }
  return slot;
}

// Take one item from a slot and return the updated slot.
function buySlot(slotId: string): Slot {
  return runInTransaction(() => {
    const updateResult = decrementStockIfAvailable.run(slotId);

    // Read the slot inside the same transaction, so that the numbers we report
    // agree with the change we just made. This line throws NoSuchSlot when the
    // slot does not exist.
    const slot = getSlot(slotId);

    // "changes" is the number of rows that the UPDATE changed.
    if (updateResult.changes === 0) {
      throw new SoldOut(`${slot.item_name} is sold out.`);
    }
    return slot;
  });
}

// --- Route layer -------------------------------------------------------------
// A handler connects one URL to one data function. It checks the input, calls
// the data layer and returns data. It contains no SQL and no HTTP details.

// Tidy up a slot id from the URL and check that it has the right shape.
function validateSlotId(rawSlotId: string): string {
  // toUpperCase lets a visitor type a1 and mean A1.
  const slotId = rawSlotId.toUpperCase();
  if (!SLOT_ID_PATTERN.test(slotId)) {
    throw new BadRequest("Slot ids look like A1 or B2.");
  }
  return slotId;
}

function handleListSlots(): Slot[] {
  return getAllSlots();
}

function handleShowSlot(rawSlotId: string): Slot {
  return getSlot(validateSlotId(rawSlotId));
}

function handleBuySlot(rawSlotId: string): Slot {
  return buySlot(validateSlotId(rawSlotId));
}

// One row of the route table: an HTTP method, a pattern for the URL path, and
// the handler for that route.
type Route = {
  httpMethod: string;
  pathPattern: RegExp;
  handler: (...capturedText: string[]) => unknown;
};

// The route table is the API written as data. In a pattern, ([^/]+) captures
// the text between two slashes, and the captured text is passed to the
// handler as an argument.
const ROUTES: Route[] = [
  { httpMethod: "GET", pathPattern: /^\/api\/slots$/, handler: handleListSlots },
  { httpMethod: "GET", pathPattern: /^\/api\/slots\/([^/]+)$/, handler: handleShowSlot },
  { httpMethod: "POST", pathPattern: /^\/api\/slots\/([^/]+)\/buy$/, handler: handleBuySlot },
];

// --- HTTP layer --------------------------------------------------------------

function sendBody(
  response: ServerResponse,
  statusCode: number,
  contentType: string,
  body: string | Buffer,
): void {
  // HTTP requires this order: status line, headers, a blank line, body.
  // writeHead writes the status line and the headers, and end writes the body.
  response.writeHead(statusCode, {
    "Content-Type": contentType, // how to read the body
    // Content-Length counts bytes, and some characters take more than one
    // byte, so we measure the bytes and not the characters.
    "Content-Length": Buffer.byteLength(body),
    "Cache-Control": "no-store", // always ask again while we develop
  });
  response.end(body);
}

function sendJson(response: ServerResponse, statusCode: number, data: unknown): void {
  // JSON.stringify turns the data into text, and the network carries it as bytes.
  sendBody(response, statusCode, "application/json; charset=utf-8", JSON.stringify(data));
}

// Node calls this function once for every request that arrives.
function answerRequest(request: IncomingMessage, response: ServerResponse): void {
  // "??" means "use the value on the right if the one on the left is missing".
  const httpMethod = request.method ?? "GET";

  // request.url holds the path and any query string together. The URL class
  // takes them apart. It needs a base address for a path with no host.
  const urlPath = new URL(request.url ?? "/", `http://${HOST}:${PORT}`).pathname;

  // Print one log line when the response has been sent.
  response.on("finish", () => console.log(`${httpMethod} ${urlPath} ${response.statusCode}`));

  try {
    // First, is the visitor asking for one of our page files?
    const staticFile = STATIC_FILES.get(urlPath);
    if (httpMethod === "GET" && staticFile !== undefined) {
      const body = readFileSync(path.join(PUBLIC_FOLDER, staticFile.fileName));
      sendBody(response, 200, staticFile.contentType, body);
      return;
    }

    // Otherwise look for a matching route. The first match wins.
    for (const route of ROUTES) {
      const pathMatch = route.pathPattern.exec(urlPath);
      if (route.httpMethod === httpMethod && pathMatch !== null) {
        // slice(1) drops the whole match and keeps the captured text, such as "A1".
        sendJson(response, 200, route.handler(...pathMatch.slice(1)));
        return;
      }
    }

    // Nothing matched.
    sendJson(response, 404, { error: "No such route." });
  } catch (error) {
    // These lines turn the errors of the data layer into status codes.
    if (error instanceof BadRequest) {
      sendJson(response, 400, { error: error.message });
    } else if (error instanceof NoSuchSlot) {
      sendJson(response, 404, { error: error.message });
    } else if (error instanceof SoldOut) {
      sendJson(response, 409, { error: error.message });
    } else {
      // Anything else is a bug in our program. We print the details for the
      // developer and tell the visitor very little.
      console.error("Unexpected error:", error);
      sendJson(response, 500, { error: "Something went wrong on the server." });
    }
  }
}

// Create the server and tell it to call answerRequest for every request.
const webServer = createServer(answerRequest);

// Start listening on the host and port. The function runs once the server is ready.
webServer.listen(PORT, HOST, () => {
  console.log(`Vending machine running at http://${HOST}:${PORT}  (press Ctrl+C to stop)`);
});

{
  "compilerOptions": {
    "target": "ES2023",
    "module": "NodeNext",
    "lib": ["ES2023"],
    "types": ["node"],

    "strict": true,
    "noUncheckedIndexedAccess": true,

    "noEmit": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true
  },
  "include": ["*.ts"]
}

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <!-- Makes the page fit a phone screen instead of shrinking a desktop layout. -->
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Vending Machine</title>
  <link rel="stylesheet" href="/style.css">
</head>

<body>
  <main class="machine">
    <h1>Vending Machine</h1>

    <!-- role="status" makes screen readers announce changes to this text. -->
    <p id="status" class="screen" role="status">Loading...</p>

    <!-- Empty at first. The script adds one card here for each slot. -->
    <section id="slots" class="slots"></section>
  </main>

  <!-- A template is HTML that the browser keeps but does not show. The script
       copies it once for each slot and fills in the copy. -->
  <template id="slot-template">
    <article class="slot">
      <h2 class="item-name"></h2>
      <p class="price"></p>
      <p class="stock"></p>
      <button type="button" class="buy">Buy</button>
    </article>
  </template>

  <!-- The script comes last, so every element it looks for already exists. -->
  <script type="module" src="/app.js"></script>
</body>
</html>

/* Named values that the rest of the file reuses. Change a colour here once. */
:root {
  --page: #eceff1;
  --body: #37474f;
  --screen-bg: #102a12;
  --screen-text: #39ff14;
  --card: #455a64;
  --accent: #ffb300;
  --text: #ffffff;
}

/* Centre the machine horizontally. */
body {
  font-family: system-ui, sans-serif;
  background: var(--page);
  display: flex;
  justify-content: center;
  padding: 24px 16px;
}

/* min() means "480 pixels wide, but never wider than the screen". */
.machine {
  background: var(--body);
  color: var(--text);
  padding: 24px;
  border-radius: 12px;
  width: min(100%, 480px);
}

h1 {
  margin: 0 0 16px;
  font-size: 1.4rem;
}

/* The status line looks like the green display of an old machine. */
.screen {
  background: var(--screen-bg);
  color: var(--screen-text);
  font-family: ui-monospace, Menlo, Consolas, monospace;
  padding: 12px 16px;
  border-radius: 6px;
  margin: 0 0 16px;
}

/* A grid with two equal columns. */
.slots {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 12px;
}

.slot {
  background: var(--card);
  padding: 12px;
  border-radius: 8px;
}

.slot h2 {
  font-size: 1rem;
  margin: 0 0 8px;
}

.slot p {
  margin: 0 0 4px;
}

/* The script only adds or removes the class "sold-out". This stylesheet
   decides what a sold-out card looks like. */
.slot.sold-out {
  opacity: 0.55;
}

button {
  margin-top: 8px;
  width: 100%;
  padding: 10px;
  font-weight: bold;
  background: var(--accent);
  border: none;
  border-radius: 6px;
  cursor: pointer;
}

/* The script sets the disabled property of a button when stock is zero. */
button:disabled {
  background: #90a4ae;
  cursor: not-allowed;
}

// This script runs in the browser. It asks the server for data and changes
// the page to match what the server says.

// The shape of one slot, as the server sends it. This type is a promise about
// the JSON, and nothing checks it while the program runs.
type Slot = {
  slot_id: string;
  item_name: string;
  price_cents: number;
  stock: number;
};

// The shape of an error message from the server.
type ApiError = { error: string };

// Find an element by its id, or stop with a clear message if it is missing.
// getElementById returns "an element or null", and TypeScript makes us deal
// with the null before we use the result.
function findElementById(id: string): HTMLElement {
  const element = document.getElementById(id);
  if (element === null) {
    throw new Error(`The page has no element with id "${id}".`);
  }
  return element;
}

// Find the elements that we need, once, when the script loads.
const slotListElement = findElementById("slots");
const statusElement = findElementById("status");
// "as HTMLTemplateElement" tells the compiler something that we know about our own page.
const slotTemplate = findElementById("slot-template") as HTMLTemplateElement;

// A formatter from the browser that writes prices in euros, so that 1.75
// becomes €1.75.
const euroFormatter = new Intl.NumberFormat("en-IE", { style: "currency", currency: "EUR" });

// Send a request to our API and return the JSON from the reply. The function
// is async, so it can wait for the network without freezing the page.
// <T> is the type that the caller expects the JSON to have.
async function requestJson<T>(url: string, options?: RequestInit): Promise<T> {
  let response: Response;
  try {
    // fetch sends the request and returns a promise of a response.
    // "await" pauses this function until the response arrives.
    response = await fetch(url, options);
  } catch {
    // fetch fails like this only when no reply arrives at all, for example
    // when the server is not running.
    throw new Error("Cannot reach the server. Is it running?");
  }

  // The body of the reply is JSON text. json() parses it into an object.
  // The compiler cannot know what the server sent, so the type is "unknown".
  const data: unknown = await response.json();

  // A reply can arrive with a bad status such as 404 or 409.
  // response.ok is false for those, so we pass the server's message on.
  if (!response.ok) {
    throw new Error((data as ApiError).error);
  }
  return data as T;
}

// Build one card for one slot. The card is not on the page until we add it.
function createSlotCard(slot: Slot): HTMLElement {
  // Copy the card layout from the template in index.html. The ! says "this is
  // never null", because we wrote the template ourselves.
  const slotCard = slotTemplate.content.firstElementChild!.cloneNode(true) as HTMLElement;
  const isSoldOut = slot.stock === 0;

  // data-slot remembers which slot this card belongs to, for the click handler.
  slotCard.dataset.slot = slot.slot_id;

  // The sold-out class lets the stylesheet decide how a sold-out card looks.
  slotCard.classList.toggle("sold-out", isSoldOut);

  // textContent treats a value as plain text, never as HTML, so data from the
  // server can never run as code in the page.
  slotCard.querySelector(".item-name")!.textContent = `${slot.slot_id}: ${slot.item_name}`;

  // Prices are stored in cents. We divide by 100 only when we show them.
  slotCard.querySelector(".price")!.textContent = euroFormatter.format(slot.price_cents / 100);

  slotCard.querySelector(".stock")!.textContent = isSoldOut ? "Sold out" : `${slot.stock} left`;
  slotCard.querySelector("button")!.disabled = isSoldOut;
  return slotCard;
}

// Ask the server for every slot and show them all on the page.
async function loadAllSlots(): Promise<void> {
  try {
    const slots = await requestJson<Slot[]>("/api/slots");

    // map turns a list of slot data into a list of cards.
    // replaceChildren puts the cards on the page. This changes the DOM, and
    // the browser then redraws the screen.
    slotListElement.replaceChildren(...slots.map(createSlotCard));
    statusElement.textContent = "Choose a snack.";
  } catch (error) {
    // Inside catch, TypeScript treats "error" as unknown, so we say what it is.
    statusElement.textContent = (error as Error).message;
  }
}

// One listener on the whole list handles clicks on every Buy button. This
// technique is called event delegation, and it also covers buttons that the
// script adds later.
slotListElement.addEventListener("click", async (event) => {
  // closest() climbs from the clicked element up to the nearest Buy button.
  // It returns null when the click landed somewhere else.
  const buyButton = (event.target as HTMLElement).closest("button.buy");
  if (buyButton === null) {
    return;
  }

  const slotCard = buyButton.closest("article")!;
  try {
    // POST asks the server to change something. The reply is the updated slot.
    const updatedSlot = await requestJson<Slot>(`/api/slots/${slotCard.dataset.slot}/buy`, {
      method: "POST",
    });

    // Replace only this card, using what the server says and not what we guess.
    slotCard.replaceWith(createSlotCard(updatedSlot));
    statusElement.textContent = `Enjoy your ${updatedSlot.item_name}!`;
  } catch (error) {
    statusElement.textContent = (error as Error).message;
  }
});

// Show the slots as soon as the page opens.
loadAllSlots();

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "Bundler",
    "moduleDetection": "force",

    "lib": ["ES2022", "DOM"],
    "types": [],

    "strict": true,
    "verbatimModuleSyntax": true,
    "outDir": "../public"
  },
  "include": ["*.ts"]
}

POST /api/slots/a1/buy HTTP/1.1

Host: 127.0.0.1:8000
User-Agent: curl/8.5.0
Accept: */*

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Length: 74
Cache-Control: no-store
Date: Sat, 17 Oct 2026 21:55:29 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"slot_id":"A1","item_name":"Sparkling Water","price_cents":175,"stock":7}