The backend
field guide.

0.1 · Start with something you already know

Imagine ordering pizza on your phone. You see a menu, choose a pizza, tap “Place order,” and get an order number. That is enough to begin; this section needs no code.

The phone app is the client: the software that asks. Its message is a request. The server is the program that receives it and replies (the word can also mean its computer). The reply is the response.

The frontend is what you see and touch; the backend is the work behind it: receive, check, do the work, reply. This course teaches the backend.

0.2 · Two kinds of asking

Reading the menu and placing an order are different actions. Each request names its action with a method and its subject with a path.

• An API is the agreed way to ask: which requests the server supports, what to send, and what each reply means.
• HTTP is the format every web request and response follows.
• JSON is a common way to write structured data. The order’s body is two labeled facts: pizza is cheese, quantity is one.
• REST is a set of conventions for designing an API around resources, such as menus and orders.

0.3 · Open the kitchen door

Inside the server, roles share the work like kitchen stations. They are parts of one program, not people or separate computers.

• Route: picks the code that handles the request.
• Middleware: checks the request on the way in. Are the details usable (validation)? Who is asking (authentication)? May they do this (authorization)? A failed check replies at once.
• Controller: reads the request, asks for the work, builds the response.
• Service: applies the rules, such as which pizzas are available.
• Database: keeps records that survive a restart, like a saved order book.
• Model and document: a model is the shape of an order, like a blank form; a document is one saved order in MongoDB.

The course tools:

• JavaScript: the language the code is written in.
• TypeScript: checks value types while you write. It never checks an incoming order, so validation still matters.
• Node.js: runs JavaScript outside the browser; here, the whole server.
• Express: receives requests, runs routes and middleware, sends responses.
• MongoDB: the database that stores the orders.
• Tests: rehearsals. Send a valid order, expect it accepted; send quantity −2, expect it rejected.

0.4 · Say it in your own words

Pause before opening each answer. A rough explanation is enough.

The same pattern fits any app:

• Weather: pick Ann Arbor → the client asks for its forecast → the server replies with data → the client draws rain icons.
• Library: tap “Reserve” → the client sends a reservation request → the server checks the rules and records it → the client shows the reply.

For any example, ask three questions: What does the person want? What message does the client send? What must the server do before it can reply?

New to the terminal? Get your computer ready first.

Continue to Section 1: see how this conversation is written in code. Come back here whenever a new term feels disconnected.

Open a terminal and move around

Connection to Section 0: the pizza story showed a server receiving requests. This section gets your own computer ready to run one.

A terminal is a window where you type a command, press Enter, and read the text the computer prints back. The tools in this course are started by typed commands, so everything begins here.

• macOS: press Cmd+Space, type Terminal, and press Enter.
• Windows: open the Start menu, type PowerShell, and press Enter.

The terminal shows a prompt: a short line that means it is waiting for you. In this guide, a line that starts with $ is a command to type, without the $. Every other line is what the terminal prints.

$ pwd
/Users/you
$ ls
Desktop     Documents   Downloads
$ mkdir si679
$ cd si679
$ pwd
/Users/you/si679

• pwd prints the folder you are in right now.
• ls lists what is inside that folder.
• mkdir si679 makes a new folder named si679.
• cd si679 moves you into that folder. cd .. moves you back up one level.

A path is the address of a folder or file: the folders you pass through to reach it, in order. /Users/you/si679 reads as the Users folder, then your own folder, then si679. The symbol ~ is short for your own folder, so ~/si679 is the same place.

Windows writes a path with a drive letter and backslashes. The same four commands work in PowerShell, where pwd and mkdir print a small table.

PS C:\Users\you> pwd

Path
----
C:\Users\you


PS C:\Users\you> mkdir si679


    Directory: C:\Users\you


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----          9/1/2026   9:14 AM                si679


PS C:\Users\you> cd si679
PS C:\Users\you\si679>

Most setup mistakes are a correct command typed in the wrong folder. When something fails, pwd is the first command to run.

Install Node and check it

Node runs JavaScript on your computer, outside a browser. In this course it runs your server program.

npm is installed together with Node. It downloads packages, which are pieces of code other people wrote, and it runs the scripts a project defines.

1. Download the LTS installer from nodejs.org ↗ and run it. LTS means long-term support: the release meant for everyday use.
2. Close the terminal and open a new one, so it can find the new programs.
3. Ask both programs for their version.

$ node --version
v24.21.0
$ npm --version
11.17.0

A version number from each command means the install worked. The commands and their output are the same on macOS and Windows.

The Week 3 course notes say their code was tested with Node 24.21.0, that a version close to it (22 or newer) will likely work, and that a version below 20 should be upgraded. The notes do not name an npm version. The npm number above is one example from a Node 24 install.

If the terminal answers “command not found”, see the last topic in this section.

Open your project in a code editor

A code editor is a program for writing plain text files such as server.js. A word processor is the wrong tool: it saves hidden formatting that code cannot contain.

This guide uses Visual Studio Code, called VS Code, a free editor from Microsoft. Any code editor works. Download it from code.visualstudio.com ↗ and install it.

1. Open VS Code.
2. Choose File, then Open Folder.
3. Select your si679 folder and confirm.

Open the folder, not a single file. The left panel then lists every file in the project, and a new file you create is saved inside it.

VS Code has a terminal built in: choose Terminal, then New Terminal. It starts inside the folder you opened, so cd is not needed.

You can also open a folder from the terminal. The dot means the folder you are in.

$ cd ~/si679
$ code .

On Windows the installer normally sets up the code command. On macOS, set it up once: in VS Code press Cmd+Shift+P, type shell command, and choose the entry that installs it.

Save and hand in work with git and GitHub

git is a program that records versions of a project folder. A folder that git tracks is called a repository.

A commit is one saved version, with a short message that says what changed. Commits are stored on your computer.

GitHub is a website that keeps a copy of a repository online. To clone is to download a repository from GitHub to your computer. To push is to send your new commits up to GitHub.

$ git --version
git version 2.50.1 (Apple Git-155)

• macOS: the first time you run git, the system offers to install its developer tools. Accept, then run the command again.
• Windows: install Git for Windows from git-scm.com ↗, then open a new terminal.

Create a free account on github.com ↗ before the first assignment.

The course hands out work through Classroom50. The Week 1 page describes the flow: accept the assignment, clone the resulting repository, do the work, and push it. The Week 3 notes add npm install as a step after cloning.

1. Open the assignment link and accept it. GitHub creates a repository for you.
2. On that repository’s page, press the Code button and copy the URL.
3. Clone it, move into the new folder, and install its packages. Paste your own URL in place of the example one.
4. Do the work in your editor and save the files.
5. Stage the files you changed, commit them, and push.

$ cd ~/si679
$ git clone https://github.com/ORGANIZATION/si-679-f-26-week1-nyt-yourname.git
Cloning into 'si-679-f-26-week1-nyt-yourname'...
$ cd si-679-f-26-week1-nyt-yourname
$ npm install

added 68 packages, and audited 69 packages in 3s

$ git add server.js
$ git commit -m "Add catalog route"
[main ee6030f] Add catalog route
 1 file changed, 3 insertions(+)
$ git push
To https://github.com/ORGANIZATION/si-679-f-26-week1-nyt-yourname.git
   e317026..ee6030f  main -> main

• git add server.js stages that file: it marks the change to go into the next commit. Name each file you changed.
• git commit -m "..." saves the staged changes as one commit with your message.
• git push sends your commits to GitHub. Until you push, the work exists only on your computer.
• git status lists what changed and what is staged. Run it whenever you are unsure.

On a new computer the first commit may stop with “Please tell me who you are”. Run the two git config commands it prints, with your own name and email, then commit again. The first push may ask you to sign in to GitHub.

Create a project and install Express

These are the first steps on the Week 1 course page. A project is a folder with a package.json file in it.

$ cd ~/si679
$ mkdir week1hello
$ cd week1hello
$ npm init -y
Wrote to /Users/you/si679/week1hello/package.json:

{
  "name": "week1hello",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "commonjs"
}

$ npm install express@latest

added 68 packages, and audited 69 packages in 3s

28 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
$ ls
node_modules        package-lock.json   package.json

• npm init -y creates package.json, the file that describes the project: its name, its scripts, and the packages it needs. The -y accepts every default answer.
• npm install express@latest downloads Express and the packages Express itself needs. @latest asks for the newest release.
• node_modules is the folder where npm puts downloaded packages. Never edit it.
• package-lock.json records the exact version of every installed package.

Express is the library that helps a Node program receive HTTP requests. Installing it does not start anything yet.

Now open package.json in your editor and make the three changes the Week 1 page makes.

• "type": "module" turns on import, the way your files load other code.
• "main": "server.js" names the file that starts the program.
• The start script tells npm start what to run. node --watch restarts the program each time you save a file.

{
  "name": "week1hello",
  "version": "1.0.0",
  "description": "",
  "main": "server.js",
  "scripts": {
    "start": "node --watch server.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "module",
  "dependencies": {
    "express": "^5.2.1"
  }
}

JSON is strict. Keep the double quotes, put a comma between entries, and put no comma after the last one. The dependencies entry was added by npm install. The Week 1 page shows the same Express version range.

Run the server and visit it

In the week1hello folder, create a file named server.js with the Hello World route from the Week 1 page.

import express from 'express';

const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(port);

Section 1 reads this code line by line. For now, know that the last line starts a program that waits for requests on port 3000.

If this is your first JavaScript, the JavaScript section after setup teaches the language one piece at a time.

$ npm start

> week1hello@1.0.0 start
> node --watch server.js

The terminal prints the script it runs, then waits. No new prompt appears. That is correct: the server is running, and this terminal is busy until you stop it. The Week 1 page starts the same file with node ./server.js, which prints nothing at all.

Go to http://localhost:3000 in a browser.

Hello World!

• localhost is a name for this computer. The request never leaves your machine.
• A port is a numbered door on a computer. A program listens on a port, and only one program can use a port at a time. This server uses 3000, so :3000 ends the address.

To stop the server, click its terminal and press Ctrl+C. Use the Ctrl key on a Mac too. The prompt returns, and the browser can no longer load the page.

If you start the server while an earlier copy is still running, Node stops with this error.

Error: listen EADDRINUSE: address already in use :::3000

It means port 3000 is taken, usually by your own server in another terminal window. Find that terminal, press Ctrl+C, and start again.

Send requests with Postman

Postman is an app that sends an HTTP request you build by hand and shows the whole response: the status, the headers, and the body. Download it from postman.com/downloads ↗ and install it.

You need it because the browser address bar can only send GET. Section 1 explains why a POST route needs a different client.

The Week 1 page sets Postman up like this.

1. Create a collection named SI 679 and, inside it, a folder named Week1. A collection is a saved group of requests.
2. Add a request named hello. Set the method to GET. Use http://localhost:3000/ as the URL.
3. Start your server with npm start, then press Send.

200 OK

Hello World!

200 OK is the status: the server’s short code for success. The body under it is the same text the browser showed.

If Postman cannot connect, the server is not running or the port in the URL is wrong.

Later in Section 1, the same steps send POST with a JSON body.

Before Week 3: install MongoDB

Weeks 1 and 2 do not need this topic. Week 3 uses a database from the start of lecture, and the course prep page asks you to have it working before class.

MongoDB is a database: a program that stores data and keeps it after your server stops. The prep page lists three things to install.

• MongoDB Community Edition is the database server. mongod is the name of its program.
• mongosh is the Mongo shell, a command-line tool for talking to that server.
• MongoDB Compass is an app with windows and buttons for looking at the same data.

1. Follow MongoDB’s installation instructions for your platform ↗. When the prep page was captured, it said the current release was 8.3 and that installing the latest is fine.
2. Run mongosh --version. If the command is not found, install the shell separately: mongosh instructions ↗. Some platforms do not include it with the server.
3. Install Compass for your platform ↗

Nothing can connect until the server program mongod is running. The platform instructions either set it up as a background service that starts with your computer, or have you start it by hand. The prep page prefers the background service where it is offered.

If you start it by hand, or it will not stay running, give it a data folder. Any folder you can write to works.

$ mkdir -p ~/data/mdata
$ mongod --dbpath ~/data/mdata

PS C:\Users\you> mkdir c:\data\mdata
PS C:\Users\you> mongod --dbpath c:\data\mdata

mongod prints many log lines and keeps running, the way your Express server did. Leave that terminal open. It listens on port 27017, the MongoDB default.

Open a second terminal and connect with the shell. It prints a few lines about the connection, then a prompt.

$ mongosh
test> show databases
admin     40.00 KiB
config    72.00 KiB
local     40.00 KiB

A prompt like test> means the shell reached the server. The three databases are admin, config and local. MongoDB creates them itself, so seeing them means a real server answered. Type exit to leave the shell.

MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017

That error means nothing is listening on the port. Check the terminal where you started mongod, or the status of the background service.

Then run the same check in Compass.

1. Open Compass and click Add new connection.
2. The URI field should read mongodb://localhost:27017. Set it if it does not. A URI is the address of the server: the kind of connection, the computer, and the port.
3. Click Connect, then expand the connection in the left sidebar.

You are done when mongosh gives you a prompt and Compass shows admin, config and local. The Week 3 code writes the same address as mongodb://127.0.0.1:27017, because 127.0.0.1 is the numeric form of localhost.

No install is needed to practise the query language: the sandbox at the end of the Week 3 chapter runs find, update and delete in your browser.

When setup goes wrong

Read the first line of an error before anything else. It usually names the problem. These five cover most setup failures.

zsh: command not found: node

npm error enoent Could not read package.json: Error: ENOENT: no such file or directory, open '/Users/you/si679/package.json'

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'express' imported from /Users/you/si679/week1hello/server.js

Error: listen EADDRINUSE: address already in use :::3000

• command not found: the terminal cannot find that program. It is not installed, or this terminal was opened before the install finished. Open a new terminal and try again. PowerShell words the same problem as “is not recognized”.
• Could not read package.json: you are in the wrong folder. Check with pwd, then use cd to enter the project folder.
• Cannot find package: the packages are not downloaded. A cloned starter needs npm install once before it can run.
• The browser cannot connect: no program is listening. Start the server with npm start, keep its terminal open, and check the port in the URL.
• address already in use: another program holds the port, usually an earlier copy of your server. Press Ctrl+C in that terminal, then start again.

The desk reference has a longer table for later weeks.

If you know Python, start here

Most of JavaScript has a Python twin. Each row below pairs the two and names the trap, and every topic after this one shows its example in both languages, side by side. New to both? Start with Run one line of JavaScript instead.

• Braces mark a block, not indentation. Indent anyway, so people can read it.
• Semicolons end statements. JavaScript can usually do without them, but the course writes them, and so does this guide.
• Make every name with const. Switch to let only when the name must take a new value.
• undefined is a real value, not an error. You will meet it in bugs: a misspelled field, a missing await, or a function with no return statement.

const quantity = '2';
console.log(quantity + 1);

Run one line of JavaScript

Connection to setup: Node is installed and your editor can open a folder. This section teaches the language Node runs, one piece at a time.

JavaScript is a language for writing instructions a computer follows. A program is a file of those instructions. Each topic here adds one piece of the course code.

Make a practice folder first. Inside your si679 folder, create a folder named js-primer and open it in your editor, as in setup. Then create a file named hello.js with these four lines and save it.

// A line that starts with // is a comment. Node skips it.
console.log('Order received');
console.log(2 + 3);
console.log('Done');

In the terminal, move into js-primer and ask Node to run the file.

$ node hello.js
Order received
5
Done

# A line that starts with # is a comment. Python skips it.
print('Order received')  # → Order received
print(2 + 3)  # → 5
print('Done')  # → Done

// A line that starts with // is a comment. Node skips it.
console.log('Order received'); // → Order received
console.log(2 + 3); // → 5
console.log('Done'); // → Done

• Each line that ends with ; is a statement: one complete instruction.
• Node runs the statements from top to bottom, one at a time.
• console.log(...) prints whatever is inside the parentheses to the terminal. A program prints nothing unless a statement tells it to.
• Text goes inside quotes. 2 + 3 has no quotes, so Node works it out and prints the result.

If Node answers Cannot find module, it could not find the file. Check the spelling of the name. Then check with pwd and ls that the terminal is in the folder that holds it.

console.log('Take order');
// console.log('Bake pizza');
console.log(4 + 4);

Values: text, numbers, and true or false

A value is one piece of data. Every value has a type, which is the kind of data it is. The course uses five kinds all the time.

• A string is text. 'cheese' is one: the quotes mark where the text starts and ends. Single quotes and double quotes both work, as long as the string starts and ends with the same one.
• A number has no quotes. 2 and 5.99 are numbers, and the signs +, -, * and / add, subtract, multiply and divide them.
• true and false are the two booleans. A boolean answers a yes-or-no question.
• undefined means no value was ever given.
• null means someone deliberately wrote “nothing here”.

typeof reports the type of a value. Save these lines as values.js and run the file.

console.log(typeof 'cheese');
console.log(typeof 2);
console.log(typeof true);
console.log(typeof undefined);

console.log(5 + 5);
console.log('5' + '5');
console.log('5' + 5);
console.log(Number('5') + 5);

$ node values.js
string
number
boolean
undefined
10
55
55
10

print(5 + 5)  # → 10
print('5' + '5')  # → 55
print('5' + 5)  # → TypeError: can only concatenate str (not "int") to str

console.log(5 + 5); // → 10
console.log('5' + '5'); // → 55
console.log('5' + 5); // → 55

The last four lines are why the type matters. With two numbers, + adds. With a string on either side, + joins text instead, so '5' + 5 is the text 55. Python refuses that line with an error instead.

This comes up in Week 1. Everything a client puts in a web address arrives as a string, even when it looks like a number. Number('5') converts the string to a number, and then + adds.

console.log('2' + 3);
console.log(2 + 3);

Names for values: const and let

A variable is a name that holds a value, so later lines can use the value by name. const and let each create one.

const pizza = 'cheese';
let quantity = 1;

quantity = quantity + 1;

console.log(pizza);
console.log(quantity);

$ node names.js
cheese
2

pizza = 'cheese'
quantity = 1

quantity = quantity + 1

print(pizza)  # → cheese
print(quantity)  # → 2

const pizza = 'cheese';
let quantity = 1;

quantity = quantity + 1;

console.log(pizza); // → cheese
console.log(quantity); // → 2

• const pizza = 'cheese'; creates the name pizza and stores the string in it.
• A single = does not mean “is equal to”. It means: work out the right side, then store the result under the name on the left. That is how quantity = quantity + 1 makes sense.
• A name made with const keeps its value. A name made with let can be given a new value later. Python has neither word: any name can change.

Giving a const name a new value stops the program. Put pizza = 'veggie'; on the line after const pizza = 'cheese'; and Node prints this.

TypeError: Assignment to constant variable.

The course uses const almost everywhere, because a name that cannot change is easier to follow. It uses let only when a name gets its value later or gets a new one: the database connection in Week 3, and a book list that is replaced after a delete in Week 2.

let quantity = 2;
const price = 10;
quantity = quantity + 1;
console.log(quantity * price);

Objects: labeled facts

Section 0 read an order as two labeled facts: pizza is cheese, quantity is one. An object is how JavaScript keeps labeled facts together. Each label with its value is called a property. This guide also calls it a field.

const order = { pizza: 'cheese', quantity: 1 };

console.log(order.pizza);
console.log(order.size);

order.quantity = 2;
console.log(order);
console.log(JSON.stringify(order));

$ node objects.js
cheese
undefined
{ pizza: 'cheese', quantity: 2 }
{"pizza":"cheese","quantity":2}

import json
order = {'pizza': 'cheese', 'quantity': 1}

print(order['pizza'])  # → cheese
print(order.get('size'))  # → None

order['quantity'] = 2
print(json.dumps(order))  # → {"pizza": "cheese", "quantity": 2}

const order = { pizza: 'cheese', quantity: 1 };

console.log(order.pizza); // → cheese
console.log(order.size); // → undefined

order.quantity = 2;
console.log(JSON.stringify(order)); // → {"pizza":"cheese","quantity":2}

Python reads a missing key with brackets and stops with a KeyError. JavaScript gives undefined and carries on.

• order.pizza reads one field: the name of the object, a dot, then the name of the field.
• Reading a field that is not there gives undefined. It is not an error, so a misspelled field name fails quietly.
• order.quantity = 2 stores a new value in a field. This works on a const object. const stops the name order from being pointed at a different object. It does not stop the fields from changing.

The last two lines print the same object in two forms. The first is how Node displays an object. The second is JSON: text with stricter rules, such as double quotes around every name, so that it can travel inside a message. JSON.stringify turns an object into JSON text. An object lives in a running program. JSON is text in a request, a response or a file.

A value inside an object can be another object, and the dots chain. order.customer.name reads customer first, then the name field inside it.

const book = { title: 'Dune', year: 1965 };
console.log(book.author);

Arrays: an ordered list

An array is a list of values in order. Square brackets start and end it, with commas between the items.

const menu = ['cheese', 'pepperoni', 'veggie'];

console.log(menu[0]);
console.log(menu.length);
console.log(menu[3]);

menu.push('hawaiian');
console.log(menu.length);
console.log(menu);

const books = [
  { title: 'Dune', year: 1965 },
  { title: 'The Hobbit', year: 1937 }
];
console.log(books[1].title);

$ node arrays.js
cheese
3
undefined
4
[ 'cheese', 'pepperoni', 'veggie', 'hawaiian' ]
The Hobbit

menu = ['cheese', 'pepperoni', 'veggie']

print(menu[0])  # → cheese
print(len(menu))  # → 3
print(menu[3])  # → IndexError: list index out of range

const menu = ['cheese', 'pepperoni', 'veggie'];

console.log(menu[0]); // → cheese
console.log(menu.length); // → 3
console.log(menu[3]); // → undefined

• Each item has a position called an index, and the first index is 0. menu[0] is the first item.
• .length is how many items there are. The last item sits at index length - 1, so in a list of three, menu[3] is past the end and gives undefined, not an error.
• push adds an item to the end. Like the fields of an object, the items of a const array can change.
• An array can hold objects. books[1].title reads the second book, then its title field.

Most data in this course has that last shape: a list of books, menu items or products, each one an object.

const sizes = ['small', 'medium', 'large'];
sizes.push('party');
console.log(sizes[1]);
console.log(sizes.length);

Decisions: if, else, and comparisons

A comparison asks a question and produces a boolean.

• === is true when both sides are the same value of the same type. !== is its opposite.
• <, >, <= and >= compare sizes.

if runs the statements in its braces only when the condition in its parentheses is true. else runs its own braces when the condition is not true. The statements between one pair of braces are called a block.

const order = { pizza: 'cheese', quantity: 0 };

if (order.quantity === 0) {
  console.log('Quantity is zero');
} else {
  console.log('Quantity is not zero');
}

if (!order.quantity) {
  console.log('Looks missing, but it is 0');
}

if (order.size === undefined || order.pizza === '') {
  console.log('Something is missing');
}

console.log(order.quantity < 1 && order.pizza !== 'veggie');
console.log('5' === 5);

$ node decisions.js
Quantity is zero
Looks missing, but it is 0
Something is missing
true
false

order = {'pizza': 'cheese', 'quantity': 0}

if not order['quantity']:
    print('Looks missing, but it is 0')  # → Looks missing, but it is 0

print(order['quantity'] < 1 and order['pizza'] != 'veggie')  # → True
print('5' == 5)  # → False

const order = { pizza: 'cheese', quantity: 0 };

if (!order.quantity) {
  console.log('Looks missing, but it is 0'); // → Looks missing, but it is 0
}

console.log(order.quantity < 1 && order.pizza !== 'veggie'); // → true
console.log('5' === 5); // → false

&& || ! are Python’s and or not. One trap: an empty array is truthy, though an empty Python list is falsy.

Look at the second if. Its condition is not a comparison, only a value. JavaScript then treats the value as true or false. These values count as false and are called falsy: false, 0, '' (a string with nothing in it), null, undefined and NaN (what a failed number conversion gives). Every other value counts as true and is called truthy. Even the string '0' is truthy.

So !order.quantity is true for a missing quantity and also for a quantity of 0. The course trips on this more than once, because a price of 0 or an empty string can be a real answer. When you mean “missing”, compare with undefined directly, as the third if does.

The last line shows why the course writes three equals signs. '5' === 5 is false, because a string is never the same value as a number.

const price = 0;
if (!price) {
  console.log('Price is required');
} else {
  console.log('Price accepted');
}

Loops: repeat for each item

A loop runs the same statements more than once. The course uses two kinds, and only in a few places.

const products = [
  { name: 'Notebook', price: 3 },
  { name: 'Pencil', price: 1 },
  { name: 'Stapler', price: 9 }
];

let total = 0;
for (const product of products) {
  console.log(product.name);
  total = total + product.price;
}
console.log(total);

let count = 3;
while (count > 0) {
  console.log(count);
  count = count - 1;
}

$ node loops.js
Notebook
Pencil
Stapler
13
3
2
1

total = 0
for product in products:
    print(product['name'])  # → Notebook, Pencil, Stapler
    total = total + product['price']

print(total)  # → 13

let total = 0;
for (const product of products) {
  console.log(product.name); // → Notebook, Pencil, Stapler
  total = total + product.price;
}
console.log(total); // → 13

• for (const product of products) runs its block once for each item in the array, in order. Each time, product is the name of the current item.
• total is made with let before the loop, because every pass gives it a new value.
• while (count > 0) runs its block again and again for as long as the condition is true. Something inside must change the condition, or the loop never ends.

You will meet for in the Week 4 tests, where it saves products one at a time, and while once in Week 3, where it reads database results one at a time. Most course code goes through an array another way, with functions. The next two topics build up to that.

const quantities = [2, 1, 3];
let total = 0;
for (const quantity of quantities) {
  total = total + quantity;
}
console.log(total);

Functions: instructions with a name

A function is a group of statements with a name. Writing the function does not run it. Calling it does: the name, then parentheses.

function orderTotal(price, quantity) {
  return price * quantity;
}

const orderTotalArrow = (price, quantity) => {
  return price * quantity;
};

const orderTotalShort = (price, quantity) => price * quantity;

console.log(orderTotal(12, 2));
console.log(orderTotalArrow(12, 2));
console.log(orderTotalShort(12, 2));

const logOrder = (pizza) => {
  console.log('Order: ' + pizza);
};

const result = logOrder('cheese');
console.log(result);

const titleOf = book => book.title;
console.log(titleOf({ title: 'Dune', year: 1965 }));

$ node functions.js
24
24
24
Order: cheese
undefined
Dune

def orderTotal(price, quantity):
    return price * quantity


orderTotalShort = lambda price, quantity: price * quantity

print(orderTotal(12, 2))  # → 24
print(orderTotalShort(12, 2))  # → 24

function orderTotal(price, quantity) {
  return price * quantity;
}

const orderTotalShort = (price, quantity) => price * quantity;

console.log(orderTotal(12, 2)); // → 24
console.log(orderTotalShort(12, 2)); // → 24

Without return, a function gives back undefined, as a Python one gives back None, and that is what result holds. An arrow function is a lambda that can also hold a block.

• price and quantity are parameters: names for the inputs, usable only inside the function.
• orderTotal(12, 2) calls the function. The values 12 and 2 are its arguments, matched to the parameters in order.
• return hands a value back to the caller and ends the function. The call orderTotal(12, 2) becomes the value 24.

The file writes the same function three ways. The first uses the word function. The second is an arrow function: the parameters, then =>, then the body, stored under a name with const. The third is the short arrow form. When the body is a single value, leave out the braces and the word return, and that value is returned.

The course writes arrow functions almost everywhere. With exactly one parameter, the parentheses around it may be left out. book => book.title is a complete function that takes a book and returns its title.

const double = (n) => {
  n * 2;
};
console.log(double(4));

Callbacks: hand a function to another function

A function is a value too. It can be stored under a name, and it can be given to another function as an argument. A function you hand over for other code to call is a callback. You write it. The other code decides when it runs and what it receives.

First with an array. filter is a function that every array has. A function that belongs to a value like this is called a method. filter calls your callback once for each item and keeps the items where the callback returns true.

const books = [
  { title: 'Dune', year: 1965 },
  { title: 'The Hobbit', year: 1937 },
  { title: 'Emma', year: 1815 }
];

const isOld = (book) => book.year < 1960;

const oldBooks = books.filter(isOld);
console.log(oldBooks);

const newBooks = books.filter((book) => book.year >= 1960);
console.log(newBooks);

books.forEach((book) => {
  console.log(book.title);
});

$ node callbacks.js
[ { title: 'The Hobbit', year: 1937 }, { title: 'Emma', year: 1815 } ]
[ { title: 'Dune', year: 1965 } ]
Dune
The Hobbit
Emma

isOld = lambda book: book['year'] < 1960

oldBooks = list(filter(isOld, books))

newBooks = list(filter(lambda book: book['year'] >= 1960, books))
print(newBooks)  # → [{'title': 'Dune', 'year': 1965}]

const isOld = (book) => book.year < 1960;

const oldBooks = books.filter(isOld);

const newBooks = books.filter((book) => book.year >= 1960);
console.log(newBooks); // → [ { title: 'Dune', year: 1965 } ]

• books.filter(isOld) hands over the function itself. There are no parentheses after isOld, because you are not calling it. filter calls it three times, with one book each time.
• The second filter writes the callback in place instead of naming it first. This is the form the course uses most.
• forEach calls its callback once per item and keeps nothing. It does the same job as a for loop.

Now the same idea in Express. This is the server from setup with two console.log lines added. Save it as server.js in your week1hello folder and run it. Then load http://localhost:3000 in a browser twice.

import express from 'express';

const app = express();

app.get('/', (req, res) => {
  console.log('Handler ran');
  res.send('Hello World!');
});

app.listen(3000);
console.log('Waiting for requests');

$ node server.js
Waiting for requests
Handler ran
Handler ran

app.get is called with two arguments: the path '/' and a callback. Read the call as: when a GET request for this path arrives, run this function. Express keeps the callback and calls it once for each matching request. It passes in the request as req and a response to fill in as res. Course pages call this callback a handler. Flask marks one with a decorator instead.

The output shows the timing. Waiting for requests prints first, although it is the last line of the file, because registering the callback does not run it. Handler ran prints only when a request arrives, once per request. Press Ctrl+C to stop the server.

import express from 'express';
const app = express();

app.get('/menu', (req, res) => {
  console.log('B');
  res.send('menu');
});

app.listen(3000);
console.log('A');

Three shortcuts the course uses everywhere

These three are shorter ways to write things you already know. They appear in almost every course file.

const order = { pizza: 'cheese', quantity: 2 };

const { pizza, quantity } = order;
console.log(`Order: ${quantity} ${pizza}`);
console.log(`Total: ${quantity * 12} dollars`);

const size = 'large';
const summary = { pizza, size };
console.log(summary);

const { crust } = order;
console.log(crust);

$ node syntax.js
Order: 2 cheese
Total: 24 dollars
{ pizza: 'cheese', size: 'large' }
undefined

order = {'pizza': 'cheese', 'quantity': 2}

pizza, quantity = order['pizza'], order['quantity']
print(f'Order: {quantity} {pizza}')  # → Order: 2 cheese

size = 'large'
summary = {'pizza': pizza, 'size': size}
print(summary)  # → {'pizza': 'cheese', 'size': 'large'}

const order = { pizza: 'cheese', quantity: 2 };

const { pizza, quantity } = order;
console.log(`Order: ${quantity} ${pizza}`); // → Order: 2 cheese

const size = 'large';
const summary = { pizza, size };
console.log(summary); // → { pizza: 'cheese', size: 'large' }

• Destructuring. const { pizza, quantity } = order; makes two names from two fields with the same names. It means the same as const pizza = order.pizza; followed by const quantity = order.quantity;. A field that is not there gives undefined, as crust shows.
• Template literal. A string written between backticks (`) instead of quotes can hold ${...}. JavaScript works out what is inside the braces and puts the result into the text.
• Property shorthand. { pizza, size } means the same as { pizza: pizza, size: size }. When a field and the variable that holds its value share a name, write the name once.

Week 1 uses the first two together. const { itemid } = req.query; takes one field out of the request, and a template literal puts it into the reply.

Section 2 has a table of the array methods the course uses, such as find and map, and of two more shortcuts, spread and rest.

const book = { title: 'Dune', year: 1965 };
const { title, author } = book;
console.log(`${title} by ${author}`);

Modules: one file uses another

A real project is many files. A module is one file of code. export marks what a file offers to other files, and import brings those names into another file.

A folder that uses import needs one setting first. Do what setup did. In the terminal, inside js-primer, run npm init -y. Then set "type": "module" in the new package.json file and create the two files below.

export const menu = ['cheese', 'pepperoni', 'veggie'];

export const priceOf = (size) => {
  if (size === 'large') {
    return 15;
  }
  return 12;
};

import { menu, priceOf } from './menu.js';

console.log(menu[0]);
console.log(priceOf('large'));

$ node order.js
cheese
15

# order.py, beside menu.py
from menu import menu, priceOf

print(menu[0])  # → cheese
print(priceOf('large'))  # → 15

// order.js, beside menu.js
import { menu, priceOf } from './menu.js';

console.log(menu[0]); // → cheese
console.log(priceOf('large')); // → 15

Python imports by module name, and every top-level name can be imported. JavaScript imports by path, and only the names marked export are offered.

• import { menu, priceOf } from './menu.js'; asks for two names. The names in the braces must match the exported names exactly.
• The part in quotes is a string that says where the code is. ./ means “in the same folder as this file”, and the file name is written in full, with .js at the end.
• A string with no ./ names a package that npm installed in node_modules instead. That is why from 'express' and from './menu.js' look different.

Importing a file runs it once, from top to bottom, and then hands over its exports. A file that only defines things, like menu.js, prints nothing when it is imported.

Leave out the ./ and Node looks for a package instead of your file. order-broken.js is a copy of order.js that says from 'menu.js' instead, and it fails like this.

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'menu.js' imported from /Users/you/si679/js-primer/order-broken.js

// special.js
export const special = 'veggie';
console.log('special.js ran');

// today.js
import { special } from './special.js';
console.log(special);

Waiting for slow work: Promise, async, await

Some work is slow: asking a database, calling another server. JavaScript does not stop and wait for it. A function that starts slow work returns at once, and what it returns is a Promise: an object that stands for a result that is not ready yet. Later the Promise either delivers the value or fails with an error.

await is how you get the value. Written in front of a Promise, it pauses your function until the Promise is done, then gives you the value.

To try it without a database, save this stand-in as db.js. Its findProduct answers after a tenth of a second, the way a database call takes a moment. Then save product.js and run it.

// db.js stands in for a database. Copy it as it is.
const products = [
  { id: 1, name: 'Notebook', price: 3 },
  { id: 2, name: 'Stapler', price: 9 }
];

const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export const findProduct = async (id) => {
  await wait(100);
  for (const product of products) {
    if (product.id === id) {
      return product;
    }
  }
  return null;
};

import { findProduct } from './db.js';

const product = await findProduct(2);
console.log(product.name);

const showName = async (id) => {
  const found = await findProduct(id);
  console.log(found.name);
};
await showName(1);

const forgot = findProduct(2);
console.log(forgot);
console.log(forgot.name);

$ node product.js
Stapler
Notebook
Promise { <pending> }
undefined

import asyncio
from db import findProduct
async def main():
    product = await findProduct(2)
    print(product['name'])  # → Stapler
    forgot = findProduct(2)
    print(forgot)  # → <coroutine object findProduct>
asyncio.run(main())

import { findProduct } from './db.js';

const product = await findProduct(2);
console.log(product.name); // → Stapler

const forgot = findProduct(2);
console.log(forgot); // → Promise { <pending> }

Python’s async def and await work the same way, but only Python warns about a coroutine that was never awaited.

• await findProduct(2) waits for the answer. After that line, product is the product object, so product.name prints Stapler as expected.
• await works at the top of a module, as here, and inside a function marked async. In any other function it is an error. Course handlers that use a database are written async (req, res) => { ... } for this reason.
• Every async function returns a Promise, so the call showName(1) is awaited too.
• The last three lines leave await out, so forgot is the Promise itself. Node shows it as Promise { <pending> }, which means not finished yet. A Promise has no name field, so forgot.name gives undefined without any error.

That last case is the bug to remember for Week 3. Nothing crashes and no error prints. The code carries on with a Promise where it expected a product. When a value from the database is unexpectedly undefined, or prints as Promise, look for an await that is missing.

import { findProduct } from './db.js';
const product = await findProduct(2);
console.log(product.name);
const showName = async (id) => {
  const found = await findProduct(id);
  console.log(found.name);
};
await showName(1);

import { findProduct } from './db.js';

const product = findProduct(1);
console.log(product.price);

When code fails: throw, try, catch

An error stops the program at the line where it happens. The lines after it do not run. Save this as receipt.js and run it. The order has no customer field.

const order = { pizza: 'cheese', quantity: 2 };

const customerName = (order) => {
  return order.customer.name;
};

console.log('Before');
console.log(customerName(order));
console.log('After');

$ node receipt.js
Before
file:///Users/you/si679/js-primer/receipt.js:4
  return order.customer.name;
                        ^

TypeError: Cannot read properties of undefined (reading 'name')
    at customerName (file:///Users/you/si679/js-primer/receipt.js:4:25)
    at file:///Users/you/si679/js-primer/receipt.js:8:13
    at ModuleJob.run (node:internal/modules/esm/module_job:439:25)
    at async node:internal/modules/esm/loader:643:26
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:101:5)

Node.js v24.19.0

order = {'pizza': 'cheese', 'quantity': 2}
def customerName(order):
    return order['customer']['name']

print('Before')  # → Before
print(customerName(order))  # → KeyError: 'customer'
print('After')

const order = { pizza: 'cheese', quantity: 2 };
const customerName = (order) => {
  return order.customer.name;
};
console.log('Before'); // → Before
console.log(customerName(order));
// → TypeError: Cannot read properties of undefined (reading 'name')
console.log('After');

Python stops one step earlier, at the missing key, and its traceback lists the newest call last. Node lists it first.

Before printed and After did not. The program stopped in between. Read what Node printed in this order.

1. Find the line that starts with the kind of error and a colon: TypeError: Cannot read properties of undefined (reading 'name'). It is the first line of the error itself, and it says what went wrong. Here the code tried to read name from a value that turned out to be undefined, which has no fields.
2. Look at the lines above it. They give the file and the line number, receipt.js:4, and show that line with a ^ under the spot.
3. The lines that start with at are the stack trace: the chain of calls that led here, newest first. Find the first ones that name your own file. receipt.js:4:25 is inside customerName. The next one, receipt.js:8:13, is the line that called it. Lines that mention node:internal belong to Node. Skip them.

order.customer was never set, and a value that is undefined has no fields to read. This one message, with a different word in the parentheses, is the error you will see most in this course.

throw lets your own code raise an error, and try with catch lets it catch one.

const checkQuantity = (quantity) => {
  if (quantity < 1) {
    throw new Error('Quantity must be at least 1');
  }
  return quantity;
};

try {
  console.log(checkQuantity(2));
  console.log(checkQuantity(0));
  console.log('This line is skipped');
} catch (error) {
  console.log('Caught: ' + error.message);
}

console.log('Still running');

$ node quantity.js
2
Caught: Quantity must be at least 1
Still running

• throw new Error('...') creates an error with your message and stops the function right there.
• When anything inside the try block throws, the rest of that block is skipped and the catch block runs. error.message is the text of the error.

When a Promise fails, the await in front of it throws at that line, so the same try and catch handle a database call that goes wrong.

try {
  console.log('A');
  throw new Error('stop');
  console.log('B');
} catch (error) {
  console.log('C');
}
console.log('D');

Start with the conversation

Connection to Section 0: the menu conversation now gets its real web names and code. If client, API, or request still feels fuzzy, revisit the pizza story first.

A client asks for something. A server runs code and sends an answer. A browser, Postman, curl, and a Supertest test can all act as clients. An API is the agreement about which requests are allowed and what responses mean.

Node runs JavaScript outside the browser. Express is a library that helps a Node program receive HTTP requests, match routes, parse data, and send responses.

POST /tracks HTTP/1.1
Host: localhost:3000
Content-Type: application/json

{"artist":"Radiohead","title":"Creep","year":1992}

import express from 'express';
const app = express();
app.use(express.json());

app.post('/tracks', (req, res) => {
  const { artist, title, year } = req.body;
  res.json({ artist, title, year });
});

app.listen(3000);

@app.post('/tracks')
def tracks():
    body = request.get_json()
    artist, title, year = body['artist'], body['title'], body['year']
    return {'artist': artist, 'title': title, 'year': year}  # → 200 {"artist":"Radiohead","title":"Creep","year":1992}

app.use(express.json());
app.post('/tracks', (req, res) => {
  const { artist, title, year } = req.body;
  res.json({ artist, title, year });
});

Without the Content-Type header, Flask answers 415 and this route 500: req.body stays undefined.

A URL includes protocol, host, optional port, path, and optional query.

Try it in the playground: build a request like this one and watch a small Express app answer it. Nothing is sent over the network.

Know where the input lives

A colon in /person/:id defines a placeholder. The client uses a real path such as /person/42; it does not literally send :id. URL encoding represents spaces as %20, which Express decodes. Route parameters are text; query values also need checking before you treat them as a single string or number.

In HTML, the form’s action chooses the URL, method chooses POST or GET, and each input’s name chooses the body key. An input’s id connects it to a label; it does not choose the submitted key. Keep ZIP codes as strings so "01234" keeps its first zero.

app.use(express.urlencoded({ extended: true })); // HTML form bodies
app.use(express.json());                        // JSON bodies

app.post('/submitform', (req, res) => {
  const { address, city, zipcode } = req.body;
  res.send(`Ship to ${address}, ${city}, ${zipcode}`);
});

@app.post('/submitform')
def submitform():
    body = request.form or request.get_json()
    address, city, zipcode = body['address'], body['city'], body['zipcode']
    return f'Ship to {address}, {city}, {zipcode}'  # → 200 Ship to 1 Elm St, Troy, 48083

app.use(express.urlencoded({ extended: true })); // HTML form bodies
app.use(express.json());                        // JSON bodies

app.post('/submitform', (req, res) => {
  const { address, city, zipcode } = req.body;
  res.send(`Ship to ${address}, ${city}, ${zipcode}`);
});

Flask has no parser lines: it parses the body when the handler asks for request.form or request.get_json().

JSON is text with a defined syntax. It supports strings, numbers, booleans, null, arrays, and objects. Keys and string values use double quotes. Comments, trailing commas, and undefined are not valid JSON. JSON.parse() converts text to a value; JSON.stringify() converts a value to text.

Try it in the playground: send a path, a query and a JSON body, then see where each one lands on req.

Read a route from left to right

New to JavaScript? The JavaScript section teaches each piece of this code first, and its callbacks topic reads app.get the same way.

import express from 'express';
const app = express();
app.use(express.json());

app.get('/catalog', (req, res) => {
  const { itemid } = req.query;
  if (typeof itemid !== 'string' || itemid.trim() === '' ||
      Number.isNaN(Number(itemid))) {
    res.status(400).send('Error: itemid must be a number');
    return;
  }
  res.send(`You asked for item ${itemid}`);
});

app.listen(3000);

app.get('/catalog', (req, res) => {
  const { itemid } = req.query;
  if (typeof itemid !== 'string' || itemid.trim() === '' ||
      Number.isNaN(Number(itemid))) {
    res.status(400).send('Error: itemid must be a number');
    return;
  }
  res.send(`You asked for item ${itemid}`);
});

from flask import Flask, request
app = Flask(__name__)
# no express.json() twin: request.get_json() parses on demand
@app.get('/catalog')
def catalog():
    itemid = request.args.get('itemid')
    return f'You asked for item {itemid}'  # → 200 You asked for item 222
app.run(port=3000)  # → * Running on http://127.0.0.1:3000

import express from 'express';
const app = express();
app.use(express.json());
app.get('/catalog', (req, res) => {
  const { itemid } = req.query;
  res.send(`You asked for item ${itemid}`);
});
app.listen(3000);

Three ways to answer: res.send() sends text or HTML, while res.json() serializes a value to JSON, and finally res.sendStatus(404) sets a status and sends its text label.

Every Week 1 activity, in one map

The week1hello code-along listens on 1679. The Week 1 Now You Try listens on 3000. Similar concepts do not make their paths interchangeable.

Setup and manual client practice

mkdir week1hello
cd week1hello
npm init -y
npm install express
npm pkg set type="module"
# Create server.js and a start script: node --watch server.js
npm start

In Postman, create an SI 679 collection and week folder, set method and full URL, and send GET /. For POST, choose Body → raw → JSON, enter the data, and check status/body. Add the route before expecting it to work. The lecture uses port 3000, while your saved week1hello uses 1679.

For /people, try letter=c, f, and 3, then no letter or the wrongly named ltr. These expose the difference between “no matching person” and “input cannot safely be indexed.” The notes’ /people/33 example conflicts with their /person/:id route; use /person/33 when testing the actual registered route. The Week 1 product route’s placeholder names are local department/category; the public path examples are electronics/tvs and household/kitchen either way.

What TypeScript changes

TypeScript adds compile-time checking to JavaScript. It helps catch a misspelled field, the wrong argument type, or a possibly missing value before running the program. The compiler emits JavaScript, which Node executes. Type annotations disappear at runtime; they do not validate a request from a client.

def add_order(quantity: int) -> dict:
    return {'quantity': quantity}

print(add_order('-2'))  # → {'quantity': '-2'}

interface Order { quantity: number }
function addOrder(quantity: number): Order {
  return { quantity };
}
addOrder('-2');
// → tsc: error TS2345: Argument of type 'string'
//   is not assignable to parameter of type 'number'.

Python type hints are optional and ignored at runtime, so the Python call runs. The drawing below shows the TypeScript side: annotations are checked by tsc and then erased, so at runtime both languages still need to validate incoming data.

The exercise starts with a working src/index.js book catalog and converts it to src/index.ts while preserving its output. The six numbered tasks are interface, typed array, enum, function signatures, union alias, and generic. You need to understand all six.

enum BookStatus {
  Available = "available",
  CheckedOut = "checked-out",
  Lost = "lost"
}

interface Book {
  title: string;
  author: string;
  year: number;
  status: BookStatus;
}

const catalog: Book[] = [];

function findBookByTitle(catalog: Book[], title: string): Book | undefined {
  return catalog.find(book => book.title === title);
}

Narrow a union before using it

type BookFilter = string | number;

function findBooksBy(catalog: Book[], filter: BookFilter): Book[] {
  if (typeof filter === "number") {
    return catalog.filter(book => book.year === filter);
  }
  return catalog.filter(book => book.author === filter);
}

const maybeBook = findBookByTitle(catalog, "Dune");
if (maybeBook !== undefined) {
  console.log(maybeBook.title);
}
console.log(maybeBook?.status);

BookFilter = str | int

def findBooksBy(catalog: list[Book], filter: BookFilter) -> list[Book]:
    if isinstance(filter, int):
        return [book for book in catalog if book.year == filter]
    return [book for book in catalog if book.author == filter]

print([book.title for book in findBooksBy(catalog, 1965)])  # → ['Dune']

type BookFilter = string | number;

function findBooksBy(catalog: Book[], filter: BookFilter): Book[] {
  if (typeof filter === "number") {
    return catalog.filter(book => book.year === filter);
  }
  return catalog.filter(book => book.author === filter);
}

A failed .find() returns undefined. A failed Mongo findOne() returns null. Both mean absence, but they are distinct values; declare the one the code returns.

Preserve a type with a generic

function getFirstItem<Item>(items: Item[]): Item | undefined {
  return items[0];
}

const firstNumber = getFirstItem([1, 2, 3]); // number | undefined
const firstBook = getFirstItem(catalog);   // Book | undefined

from typing import TypeVar
Item = TypeVar('Item')

def getFirstItem(items: list[Item]) -> Item | None:
    return items[0] if items else None  # [][0] raises IndexError

firstNumber = getFirstItem([1, 2, 3])  # int | None
print(firstNumber, getFirstItem([]))  # → 1 None

function getFirstItem<Item>(items: Item[]): Item | undefined {
  return items[0];
}

const firstNumber = getFirstItem([1, 2, 3]); // number | undefined

If the function used any instead, TypeScript would stop protecting the connection between input and output.

The JavaScript toolbox behind every week

This table builds on the JavaScript section, which teaches values, objects, arrays, functions and callbacks first.

const books = [
  { title: 'The Hobbit', author: 'Tolkien', year: 1937 },
  { title: 'Dune', author: 'Herbert', year: 1965 },
];
const hobbit = books.find(book => book.year === 1937);
const herbert = books.filter(book => book.author === 'Herbert');
const asText = books.some(book => book.year === '1937');
console.log(hobbit.title, herbert.length, asText);

books = [{'title': 'The Hobbit', 'author': 'Tolkien', 'year': 1937},
         {'title': 'Dune', 'author': 'Herbert', 'year': 1965}]
hobbit = next(book for book in books if book['year'] == 1937)
herbert = [book for book in books if book['author'] == 'Herbert']
asText = any(book['year'] == '1937' for book in books)
print(hobbit['title'], len(herbert), asText)  # → The Hobbit 1 False

const hobbit = books.find(book => book.year === 1937);
const herbert = books.filter(book => book.author === 'Herbert');
const asText = books.some(book => book.year === '1937');
console.log(hobbit.title, herbert.length, asText); // → The Hobbit 1 false

With no match, next() raises StopIteration where find returns undefined; pass a default, next(..., None).

async always returns a Promise; await pauses that async function until the Promise settles. It does not freeze the entire Node server.

With these projects’ ES-module/NodeNext setup, local TypeScript imports commonly end in .js, because Node loads the compiled JavaScript. import type brings in declarations erased at runtime; an ordinary import brings in usable runtime code. HW1 uses its supplied extensionless import configuration, so follow the repository’s existing setup.

Explain the catalog’s behavior

addBook pushes a Book. findBookByTitle finds one or returns undefined. checkoutBook succeeds only for an existing available book; a second checkout returns false. returnBook restores an existing book to available. Filtering accepts either an author string or publication year number. The generic returns the first item safely.

The demo has The Hobbit, Dune, Foundation, and Children of Time. Foundation begins lost. Dune’s first checkout is true and its second is false; after returning it, its status is available. Converting to TypeScript should not change those runtime results or the README’s expected output.

The one trick: delete the types

TypeScript is JavaScript plus notes for the checker. When a line looks like a wall of symbols, delete the notes in your head. What is left is the JavaScript that Node runs, and most lines turn out to be short. Types describe your assumptions shows why: the notes are erased before the program runs (the erased-type drawing).

Delete these:

• : string or any other type after a colon that follows a name, a parameter or the () of a function.
• <Product> and anything else in angle brackets after a name, as in Promise<Product>. Delete the brackets too.
• Whole lines that start with import type or type, like type Role = 'customer' | 'staff';. They never run.

Two exceptions trip everyone up:

1. Object-literal colons stay. In { id: user.id } the colon pairs a field with its value. That is JavaScript, not a type.
2. as const goes. It looks like code, but it only tells the checker that a value never changes. import * as name is different: it is a real JavaScript rename, so it stays.

Here is a Week 6 function that makes middleware, before and after:

export const requireRole = (role: Role): Middleware => {
  return (req: Request, res: Response, next: NextFunction): void => {

export const requireRole = (role) => {
  return (req, res, next) => {

And a line where every colon stays, because they are all inside an object literal:

  return { id: user.id, username: user.username, role: user.role };

Types deleted: the same line. It is plain JavaScript.

The twelve shapes

The class code uses the same dozen shapes over and over. They are ordered here by how often each appears in the course’s .ts files; the counts are approximate. Each one shows a real line with its file, how to say it out loud, and the line with its types deleted.

1. Arrow function · about 380 times

export const getJwtSecret = (): string => {

Say it:“Make a function called getJwtSecret. It takes nothing and gives back a string.”

• const name = (…) => means “this name holds a function”.
• : string right after the () is the return type: what comes out.

export const getJwtSecret = () => {

2. Destructuring · about 168 times

  const { title, author, year } = req.query;

Say it:“Take the fields named inside the braces out of req.query, and put each one in a variable of the same name.” It is short for writing const title = req.query.title; once per field.

Types deleted: the same line. It is plain JavaScript.

3. Template literal · about 93 times

      throw new AuthorizationError(`Only ${role} may do this`);

Say it:“Build a string. Where it says ${role}, put in the value of role.” If role is staff, the message reads Only staff may do this. Backticks, not quotes, turn this on.

Types deleted: the same line. It is plain JavaScript.

4. Generics and unions · about 63 times

export const findProduct = async (id: string): Promise<Product | null> => {

Say it:findProduct takes an id that is a string. It gives back a promise that will later hold a Product, or null when nothing matches.

• <…> reads “of”. Promise<Product> is a promise of a product, and Partial<Product> is a product whose fields are all optional.
• | reads “or”.

export const findProduct = async (id) => {

5. import type · about 47 times

import type { NextFunction, Request, Response } from 'express';

Say it:“From Express, bring in three type names. They are used in annotations like req: Request, never as values.” The class tsconfig turns on verbatimModuleSyntax, so an import of types only must say so with the word type.

Types deleted: the whole line goes. It never runs.

6. The ?? operator · about 44 times

  const quantity = changes.quantity ?? existing.quantity;

Say it:“Use the quantity that was sent. If it is missing, meaning undefined or null, keep the existing quantity.” It differs from || on zero, and zero is a real quantity: 0 ?? 5 gives 0, while 0 || 5 gives 5.

Types deleted: the same line. It is plain JavaScript.

7. as, which does two jobs · about 35 times

  it.each(['get', 'patch', 'delete'] as const)('%s answers 400', async (method) => {

Say it:as const tells TypeScript this list is exactly these three words and nothing else. That is what lets request(app)[method] on the next line type-check. Most as lines in the class code do a different job, a renamed import:

import * as productsController from '../controllers/products-controller.js';

Say it:“Bring in everything that file exports, as one object named productsController.” Then productsController.getProducts is one of those exports.

  it.each(['get', 'patch', 'delete'])('%s answers 400', async (method) => {

The as const goes. The import * as line stays exactly as it is.

8. .map, .filter and .find · about 34 times

  return products.filter((product) => product.quantity < threshold);

Say it:“Go through products one at a time, keep only the ones whose quantity is below the threshold, and return that shorter list.”

• .filter(test) keeps the items that pass the test.
• .map(change) turns every item into something new. Week 6’s repository does docs.map((doc) => toProduct(doc)), so every MongoDB document becomes a Product.
• .find(test) returns the first match, or undefined when nothing matches, as in Week 2’s book service.

Types deleted: the same line. It is plain JavaScript.

9. Optional chaining · about 9 times

    req.body?.username,

Say it:“If there is a body, read its username. If there is no body at all, give undefined instead of crashing.” Without ?., reading req.body.username throws when req.body is undefined.

Types deleted: the same line. It is plain JavaScript.

10. Spread and rest · about 9 times

  const { id, ...fields } = productFromFields(productInfo);
  const { insertedId } = await db.addToCollection(db.PRODUCTS, fields);
  return productFromFields({ ...fields, id: insertedId.toString() });

Say it:the first line is rest: “Pull id out, and collect every other field into fields.” The last line is spread: “Make a new object, copy every field of fields into it, then add an id.” Same three dots, opposite directions: on the left of the equals sign they collect, and inside braces on the right they copy out.

Types deleted: the same lines. They are plain JavaScript.

11. class … extends Error · 5 times, and it matters

export class AuthenticationError extends Error {}

Say it:“Make a new kind of error called AuthenticationError. It is an ordinary Error with its own name.” The empty braces are fine: the name is the point, so the error handler can ask err instanceof AuthenticationError and answer with a 401 status.

Types deleted: the same line. It is plain JavaScript.

12. async, await, try and catch

  try {
    res.locals.user = jwt.verify(token, getJwtSecret());
  } catch {
    throw new AuthenticationError('Invalid or expired token');
  }

Say it:“Try to verify the token. If verifying throws any error, catch it and throw our own 401 error instead.”

  const hashedPassword = await bcrypt.hash(password, SALT_ROUNDS);

Say it:“Start hashing, which is slow, wait for it to finish, then put the result in hashedPassword.” await works only inside a function marked async, which is error TS1308 below. Waiting for slow work explains the promise underneath.

Types deleted: the same lines. They are plain JavaScript.

Five more shapes you will meet

A. Controller anatomy

export const getProducts = async (
  req: Request,
  res: Response
): Promise<void> => {

Read it piece by piece:

export const getProducts = async (req, res) => {

B. Object literals and res.status().json()

  return { id: user.id, username: user.username, role: user.role };

    res.status(404).json({ error: 'No product with that id' });

Say it:the first line builds a new object with three fields, which is how hashedPassword is left out on purpose. The second: “Set the status to 404, then send this object as JSON.” res.status(404) returns res itself, which is why .json can follow it on the same line.

Types deleted: the same lines. They are plain JavaScript.

C. import and export with .js

import { productsRouter } from './routes/products-router.js';

Say it:“From my file routes/products-router, bring in what it exports as productsRouter.” The name in braces must match an export const productsRouter in that file. Why .js when the file ends in .ts? Weeks 2 to 6 use Node’s ES modules with "module": "nodenext". Node runs the compiled .js files, so the import names the file that exists after compiling. Leaving it off is error TS2835.

Types deleted: the same line. It is plain JavaScript.

D. describe, it and expect

describe('GET /auth/me', () => {
  // #region valid-token
  it('200s with the username for a token we sign ourselves', async () => {
    const token = jwt.sign(payload, getJwtSecret());

    const res = await request(app)
      .get('/auth/me')
      .set('Authorization', `Bearer ${token}`);

    expect(res.status).toBe(200);
    expect(res.body.username).toBe('ada');
  });

• describe('GET /auth/me', …) is a group of tests about one thing.
• it('200s with …', async () => {…}) is one test. Its text is the promise it checks.
• expect(x).toBe(y) means “x must be exactly y, or this test fails”. .toEqual compares the contents of objects and lists instead; Choose the matcher by what you mean has the full list.

E. Supertest: request(app)

    const res = await request(app)
      .get('/auth/me')
      .set('Authorization', `Bearer ${token}`);

Say it:“Send a pretend GET request to /auth/me on my app, with this Authorization header, and wait for the answer.” No real server or port is needed. res.status and res.body are the answer, which the next lines check with expect.

Read a red TypeScript error

Every error below is real. The mistake was typed into a copy of a class repo, npx tsc --noEmit was run, and its output is pasted unchanged. Then the copy was put back. Every tsc error has the same parts:

src/app.ts(3,28): error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './routes/auth-router.js'?

• src/app.ts is the file, and (3,28) is line 3, column 28.
• TS2835 is the code: a name you can search for.
• The rest is the message.

1. Go to the file and line first. Do not read the whole message yet.
2. Read the message. It usually says X is not Y. Find X on that line.
3. Fix the first error first, then run tsc again. One mistake often causes several errors below it.

Four words come up again and again. A type is what kind of value something is. Assignable means “fits into”. A parameter is the name a function gives its input, like id in (id: string) =>. An argument is the actual value passed in when the function is called.

1. TS2345 · Argument of type … is not assignable to parameter

  const user = await usersService.getUser(caller, req.params.id);

src/controllers/users-controller.ts(6,51): error TS2345: Argument of type 'string | string[]' is not assignable to parameter of type 'string'.
  Type 'string[]' is not assignable to type 'string'.

What it means: Express types a URL parameter as possibly a list of strings, and getUser accepts exactly one string.

Fix: turn it into one string first, as the class code does everywhere:

  const user = await usersService.getUser(caller, String(req.params.id));

2. TS2322 · Type … is not assignable to type …

  const user = await usersRepository.insertUser({
    username,
    hashedPassword,
    role: 'admin'
  });

src/services/auth-service.ts(38,5): error TS2322: Type '"admin"' is not assignable to type 'Role'.

What it means: Role allows only two words, so admin does not fit into the box marked Role:

export type Role = 'customer' | 'staff';

Fix: use one of the allowed words, as the real code does with role: 'customer', or add admin to Role if you really mean a new role.

3. TS2339 · Property … does not exist on type …

  const matches = await bcrypt.compare(password, user.password);

src/services/auth-service.ts(55,55): error TS2339: Property 'password' does not exist on type 'User'.

What it means: a User has no field called password. It has hashedPassword:

export type User = {
  id: string;
  username: string;
  hashedPassword: string;
  role: Role;
};

Fix: use the real field name, user.hashedPassword. This is TypeScript catching a typo for you.

4. TS18048 · … is possibly 'undefined'

  if (authorization.split(' ')[1] === secretKey) {

src/books-router.ts(20,7): error TS18048: 'authorization' is possibly 'undefined'.

What it means: a request may arrive with no Authorization header, so req.headers.authorization is a string or undefined, and you cannot call .split on nothing.

Fix: check first, as Week 2’s real code does:

  if (authorization && authorization.split(' ')[1] === secretKey) {

You may also see TS2532, “Object is possibly undefined”. Same idea, same fix.

5. TS2304 · Cannot find name …

import {
  AuthenticationError,
  AuthorizationError,
  ValidationError
} from '../errors.js';

src/middleware/error-handler.ts(26,22): error TS2304: Cannot find name 'ConflictError'.

What it means: line 26 still says err instanceof ConflictError, but the file never created that name and no longer imports it.

Fix: put ConflictError back in the import list.

6. TS7006 · Parameter … implicitly has an 'any' type

const toUser = (doc): User => {

src/db/users-repository.ts(8,17): error TS7006: Parameter 'doc' implicitly has an 'any' type.

What it means: TypeScript cannot tell what doc is, and the class tsconfig sets "strict": true, which forbids a silent guess.

Fix: say the type:

const toUser = (doc: Document): User => {

A callback such as docs.map((doc) => toProduct(doc)) needs no type on doc, because TypeScript already knows what is inside docs.

7. TS2835 and TS2307 · import path problems

import { authRouter } from './routes/auth-router';

src/app.ts(3,28): error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './routes/auth-router.js'?

import { authRouter } from './routes/auth-routes.js';

src/app.ts(3,28): error TS2307: Cannot find module './routes/auth-routes.js' or its corresponding type declarations.

What it means: the first leaves off the .js, which every local import needs when a repo uses "type": "module" with nodenext. The second names a file that does not exist: the real one is auth-router.ts.

Fix: end with .js and check the spelling against the files in src/routes:

import { authRouter } from './routes/auth-router.js';

8. TS2741 · Property … is missing in type …

  return {
    id: result.insertedId.toString(),
    username: user.username,
    hashedPassword: user.hashedPassword
  };

src/db/users-repository.ts(37,3): error TS2741: Property 'role' is missing in type '{ id: string; username: string; hashedPassword: string; }' but required in type 'User'.

What it means: the function promises to return a User, and every User must have a role.

Fix: add the missing field:

  return {
    id: result.insertedId.toString(),
    username: user.username,
    hashedPassword: user.hashedPassword,
    role: user.role
  };

9. TS1308 · 'await' outside an async function

export const postLogin = (
  req: Request,
  res: Response
): void => {
  const token = await authService.logIn(

src/controllers/auth-controller.ts(22,17): error TS1308: 'await' expressions are only allowed within async functions and at the top levels of modules.

What it means: await works only inside a function marked async, and async was removed.

Fix: put async back, which makes the function return a promise:

export const postLogin = async (
  req: Request,
  res: Response
): Promise<void> => {

Read a Vitest failure

The mistake: in a copy of the Week 2 repo, the GET /books/:id route was changed to answer 400 instead of 404 for a missing book. Then npx vitest run src/__tests__/books.test.ts was run.

booksRouter.get('/:id', (req: Request, res: Response) => {
  const book = getBook(Number(req.params.id));
  if (!book) {
    res.sendStatus(400);
    return;
  }
  res.json(book);
});

This is the test that caught it:

describe('GET /books/:id', () => {
  it('returns the matching book and 404 for a missing id', async () => {
    const posted = await addBook();
    const found = await request(app).get(`/books/${posted.body.id}`);
    const missing = await request(app).get('/books/1');

    expect(found.status).toBe(200);
    expect(found.body.title).toBe('The Hobbit');
    expect(missing.status).toBe(404);
  });
});

The real output, trimmed: the run header and the router’s log lines are cut.

 ❯ src/__tests__/books.test.ts (9 tests | 1 failed) 64ms
   ❯ GET /books/:id (1)
     × returns the matching book and 404 for a missing id 7ms

⎯⎯⎯⎯⎯⎯⎯ Failed Tests 1 ⎯⎯⎯⎯⎯⎯⎯

 FAIL  src/__tests__/books.test.ts > GET /books/:id > returns the matching book and 404 for a missing id
AssertionError: expected 400 to be 404 // Object.is equality

- Expected
+ Received

- 404
+ 400

 ❯ src/__tests__/books.test.ts:70:28
     68|     expect(found.status).toBe(200);
     69|     expect(found.body.title).toBe('The Hobbit');
     70|     expect(missing.status).toBe(404);
       |                            ^
     71|   });
     72| });

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/1]⎯


 Test Files  1 failed (1)
      Tests  1 failed | 8 passed (9)

• (9 tests | 1 failed): eight tests still pass. Only one cares about this route.
• FAIL … > GET /books/:id > returns the matching book and 404 for a missing id: the path is file, then the describe name, then the it name. It tells you which promise broke.
• expected 400 to be 404: the server sent 400 and the test wanted 404. Read it as “expected what we got to be what we wanted”.
• - Expected and + Received: the minus line is what the test wanted, and the plus line is what really happened.
• books.test.ts:70:28 and the caret: the exact expect that failed. Lines 68 and 69 passed, so the found book was fine.

Say it out loud: “The test asked for a book id that does not exist. My route answered 400, but the request was fine and the book is missing, which is a 404. I would change res.sendStatus(400) back to res.sendStatus(404) in the GET /:id route.”

The blank-file drill

Reading a line is half of it. To check that you can also write it, rebuild one file from memory in a copy of a class repo:

1. Copy the whole repo, so your real one is never touched.
2. Save the file you are about to blank somewhere outside the repo.
3. Blank it, but keep its import lines. They tell you what the file uses.
4. Rewrite the rest from memory, without looking.
5. Run tsc, then the tests. Fix the first error first.
6. Diff your version against the original and read every difference.
7. Copy the original back, or delete the copy.

cp -R si-679-f-26-week06-nyt-yourname ~/drill-week06
cd ~/drill-week06
cp src/services/products-service.ts ../products-service.original.ts
# open src/services/products-service.ts, keep the import lines, delete the rest, rewrite it
npx tsc --noEmit
npm test
diff ../products-service.original.ts src/services/products-service.ts
cp ../products-service.original.ts src/services/products-service.ts

In a copy of the Week 6 repo the whole suite, 45 tests, ran in about two seconds, so checking is cheap. One round takes 30 minutes:

• Minutes 0 to 2: copy the repo and blank the file.
• Minutes 2 to 22: rewrite it.
• Minutes 22 to 25: run tsc and the tests until both pass.
• Minutes 25 to 30: diff, write down the two lines you missed, and restore.

Blank the same file again next round until the diff is quiet, then move on. Start with short files such as src/errors.ts and src/config.ts, then a service, a controller, a router and a test. A line that differs from the original while tsc and the tests pass is a second correct answer, not a mistake.

Organize routes without changing the API

Connection to Section 0: this chapter opens the kitchen door. Follow how a ticket is directed, checked, and handed to the code that does the work.

// app.ts
app.use('/books', booksRouter);

// books-router.ts
const booksRouter = express.Router();
booksRouter.get('/:id', handler);
// A client sends GET /books/123, not GET /:id.

# app.py
app.register_blueprint(booksRouter, url_prefix='/books')

# books_router.py
booksRouter = Blueprint('books', __name__)
@booksRouter.get('/<id>')
def handler(id): return f'Book {id}'  # → 200 Book 123

// app.ts
app.use('/books', booksRouter);

// books-router.ts
const booksRouter = express.Router();
booksRouter.get('/:id', handler);

Week 2 separates types.ts (Book shape), books-service.ts (private in-memory catalog and operations), books-router.ts (HTTP handlers), app.ts (assembly), and index.ts (listen on 6790). The service exports addBook, getAllBooks, getBook, updateBook, removeBook, and _resetCatalog. HTTP code asks the service for data rather than owning the array.

Middleware either continues or answers

const logger = (req, res, next) => {
  console.log(req.method, req.path);
  next();
};

booksRouter.use(express.json());
booksRouter.use(logger);
booksRouter.post('/', checkAuth, validateBookParams, handler);

const logger = (req, res, next) => {
  console.log(req.method, req.path);
  next();
};
booksRouter.use(express.json());
booksRouter.use(logger);
booksRouter.post('/', checkAuth, validateBookParams, handler);

@booksRouter.before_request
def logger():
    print(request.method, request.path)  # → GET /books/123

const logger = (req, res, next) => {
  console.log(req.method, req.path);
  next();
};

booksRouter.use(logger);

Flask moves on when a before_request function returns None; Express moves on only when you call next().

An error takes another road: next(err) sends control forward to error middleware.

Week 2’s logger records method, path, and hostname. checkAuth checks the second space-separated Authorization value against SI679 and returns 403 when it fails. It is simpler than HW1’s exact Bearer parser. validateBookParams requires nonblank string title and author, returning 400 otherwise. A valid token plus bad fields reaches validation; bad auth plus bad fields stops at auth.

Try it in the playground: send POST /books with and without the token and see which step answers.

The exact Week 2 contract

Notice that PATCH and DELETE here use /books and a body id. Later weeks use /products/:id. Learn the endpoint actually being studied. Date.now() is a classroom id generator; two calls in the same millisecond can collide, so it is not a general uniqueness guarantee.

The catalog uses let because reset/removal replaces the array. Removing uses filter to keep every other id. Updating finds the book and uses Object.assign to apply supplied properties. A compile-time Omit does not itself remove forbidden fields from an untrusted runtime object.

Try it in the playground: every route in this table takes requests there.

Keep startup separate; put errors last

// app.ts: define and export the app
app.use('/books', booksRouter);
app.use((err, req, res, next) => {
  res.status(500).send('An unexpected error occurred');
});
export { app };

// index.ts: import app, then start the real listener
app.listen(6790);

import express from 'express';
import { productRouter } from './routes/product-routes.js';
import { errorHandler } from './middleware/error-handler.js';
const app = express();
app.use(express.json());
app.use('/products', productRouter);
app.use(errorHandler);
export { app };

# app.py: define the app
app.register_blueprint(booksRouter, url_prefix='/books')
@app.errorhandler(500)
def handleError(err):
    return 'An unexpected error occurred', 500  # → 500 An unexpected error occurred

// app.ts: define and export the app
app.use('/books', booksRouter);
app.use((err, req, res, next) => {
  res.status(500).send('An unexpected error occurred');
});

Flask finds an error handler by status code, so its position does not matter.

A 404 handler is ordinary middleware for requests no route handled; an error handler receives errors passed down the chain.

Tests import app.ts, so no fixed-port listener starts. Supertest opens a temporary one; you do not need npm run dev. Because index.ts never runs in tests, check startup by hand once.

Try it in the playground: ask for GET /books/badroute, then for a path no route handles.

The Week 2 test checklist

The tests demonstrate an empty catalog, exact author filtering, rejected missing/wrong tokens, blank-title validation, 201 creation, GET by id/404, PATCH authentication and validation with unchanged fields, and DELETE authentication plus an empty final list. beforeEach calls _resetCatalog() so previous tests’ books do not affect the next one.

Use res.body for parsed JSON and res.text for plain text. Check both status and response content; seeing a plausible book alone does not prove that the endpoint returned the correct code.

TypeScript setup, headers, and all three NYT blocks

// Important tsconfig.json settings from the lecture:
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "rootDir": "src",
    "outDir": "dist",
    "types": ["node"],
    "strict": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Install Express as a runtime dependency; TypeScript, tsx, @types/node, and @types/express supply development tools/declarations. Vitest, Supertest, and @types/supertest are test dependencies. tsx runs TypeScript during development, but it does not replace tsc --noEmit. Keep generated dist and installed node_modules out of Git with .gitignore.

The request start line contains method/path/protocol, and the response start line contains protocol/status. Both have headers, a blank line, then a body where appropriate. HTTP header names are case-insensitive; Node exposes incoming keys in lowercase. Add My-Header-Field: Woot! in Postman and inspect req.headers['my-header-field']. Compare headers from a browser and Postman; their clients provide different metadata.

The intermediate lecture POST/test initially use 200, then NYT explicitly asks for the appropriate creation status, 201. Your completed Week 2 code and tests use 201. The lecture/local error handler shows a stack trace for learning; HW1 instead sends a generic 500 and logs details on the server.

Keep earlier filtering while adding later middleware/tests. Test route behavior against the finished contract, not an intermediate lecture response. BeforeEach reset is necessary even when every test passes by itself.

Four endpoints; two different roles

HW1 is an in-memory menu/orders API on port 3000. It combines Week 1 inputs with Week 2 routers, middleware, and tests. It has no MongoDB persistence. Menu data is supplied; stored orders get server-created id, status, and timestamp.

The menu ids are hawaiian, meat-lovers, build-your-own, bread-nugz, dipping-sauce, and soda. ?category=pizza returns the three pizzas. Unknown category/status filters are valid collection queries with no matches: 200 and []. An unknown single menu id is 404.

POST /orders
Authorization: Bearer slicedrop-customer-secret
Content-Type: application/json

{
  "customerName": "Ada",
  "items": [{ "menuItemId": "soda", "quantity": 1 }]
}

Staff listing uses Bearer slicedrop-staff-secret. These strings are the assignment’s demonstration credentials, not a design for production authentication. A valid customer token does not grant staff access.

Parsing a credential is different from accepting it

export function parseBearerToken(header: string | undefined): string | null {
  if (header === undefined) return null;
  const match = header.match(/^Bearer ([^\s]+)$/);
  return match === null ? null : match[1];
}

import re
def parseBearerToken(header: str | None) -> str | None:
    if header is None: return None
    match = re.fullmatch(r'Bearer ([^\s]+)', header)  # Python's $ would also accept a final \n
    return None if match is None else match[1]

print(parseBearerToken('Bearer nope'))  # → nope
print(parseBearerToken('Bearer one two'))  # → None

export function parseBearerToken(header: string | undefined): string | null {
  if (header === undefined) return null;
  const match = header.match(/^Bearer ([^\s]+)$/);
  return match === null ? null : match[1];
}

The two middleware functions read the header, compare the candidate with the constant for their role, and either answer 401 or call next.

The app’s chain is JSON parser → menu/orders routers → JSON 404 fallback → four-argument error handler. For POST /orders, the router runs customer auth → handler → validateOrder → addOrder. With no token and valid JSON {}, the result is 401 before field validation.

Validate structure first; collect every safe-to-find error

The handler turns a nonempty errors array into 400 {"errors":[...]}, or creates the order if the array is empty. Keeping the validator plain makes it reusable and easy to test.

If a menu lookup fails, report the id and quantity issues that can be checked, then skip option checks for that item. Returning inside a forEach callback stops that callback for the current item; it does not return from the outer validator.

The supplied helpers use some for offered sizes and includes for offered crusts, sauces, and toppings. A missing options list means the option is not offered. The validator must check runtime values even though NewOrder has TypeScript fields.

// A valid JSON body, but an invalid order:
{
  "customerName": "   ",
  "items": [{ "menuItemId": "not-on-menu", "quantity": 0 }]
}
// With the customer token: 400 and multiple validation errors.
// Without it: 401 before order validation.

function validateOrder(body: any): string[] {
  const errors: string[] = [];
  if (typeof body?.customerName !== 'string' || body.customerName.trim() === '')
    errors.push('customerName is required');
  if (!Array.isArray(body?.items) || body.items.length === 0)
    return [...errors, 'items must be a nonempty array'];
  return errors;
}

def validateOrder(body) -> list[str]:
    errors, fields = [], body if isinstance(body, dict) else {}
    if not isinstance(fields.get('customerName'), str) or fields['customerName'].strip() == '':
        errors.append('customerName is required')
    if not isinstance(fields.get('items'), list) or len(fields['items']) == 0:
        return [*errors, 'items must be a nonempty array']
    return errors
print(validateOrder(None))  # → ['customerName is required', 'items must be a nonempty array']

function validateOrder(body: any): string[] {
  const errors: string[] = [];
  if (typeof body?.customerName !== 'string' || body.customerName.trim() === '')
    errors.push('customerName is required');
  if (!Array.isArray(body?.items) || body.items.length === 0)
    return [...errors, 'items must be a nonempty array'];
  return errors;
}

Python’s .get() needs a dict, hence the isinstance check; body?. works on any value.

State, time, and three different failures

NewOrder describes customer-submitted fields. Order extends NewOrder adds id, status, and createdAt. addOrder creates ids such as "1" and "2", sets status to pending, uses an ISO timestamp, and pushes into the in-memory array. Unfiltered listing preserves insertion order; status filtering keeps exact matches. Restarting Node clears the orders and resets the counter.

The parser error is recognized as a SyntaxError with a body property. An unexpected exception is not relabeled as the client’s validation error. Test a timestamp’s type and whether Date.parse accepts it rather than asserting an exact clock time.

File map and homework test coverage

_resetOrders() runs before each order test. A mock that makes addOrder throw tests the error path without needing a real application fault. Restoring a mock prevents it from affecting later tests. Read the full original homework teaching guide in the source library for its file-by-file walkthrough and 18-question quiz.

Choose a data model; learn the vocabulary

Connection to Section 0: MongoDB takes the saved-order-book role. Focus on the difference between a request asking for data and a stored record holding data.

Not installed yet? Set up MongoDB, mongosh and Compass first.

MongoDB is a document-oriented NoSQL database. SQL databases organize rows into tables and express relationships with keys and joins. They are useful for strongly related data and relational queries. Mongo stores documents in collections, allowing nested objects and arrays and documents with differing fields.

The lecture’s three motivations for NoSQL are scalability (distributing data across machines), flexibility (changing document shapes), and simplicity (object-shaped data and queries). These are design tradeoffs, not a rule that NoSQL is always faster or that SQL cannot scale. Flexible storage still needs application contracts, validation, and care when old documents have different shapes.

Mongo stores BSON, a binary representation supporting additional types such as ObjectId and dates. JSON itself supports several value types; it does not make every value a string. Field names are strings, and nested objects/arrays let one document hold structured data. The Node driver translates between JavaScript values and BSON.

A local Community Edition server is mongod; mongosh is an interactive client, and Compass is a GUI client. The mongodb npm package is a driver, not the server. MongoDB Atlas is a hosted service. Mongo can also support replication/failover and sharding; the class exercise uses one local server.

Connect, choose a database, then a collection

// mongosh setup for the exploration database:
use week3db
db.createCollection("products")
show databases

import { MongoClient, ObjectId } from 'mongodb';
import type { Db, Document } from 'mongodb';

const client = new MongoClient('mongodb://127.0.0.1:27017');
await client.connect();
const db = client.db('week3db');
await db.command({ ping: 1 });
const products = db.collection('products');
// ...operations...
await client.close();

from pymongo import MongoClient

client = MongoClient('mongodb://127.0.0.1:27017')
# no connect() and no await: the client connects by itself
db = client.get_database('week3db')
db.command({'ping': 1})  # → {'ok': 1.0}
products = db.get_collection('products')
client.close()

import { MongoClient, ObjectId } from 'mongodb';

const client = new MongoClient('mongodb://127.0.0.1:27017');
await client.connect();
const db = client.db('week3db');
await db.command({ ping: 1 });
const products = db.collection('products');
await client.close();

A database may not appear in listings until it has stored data/a collection. A long-running app connects at startup and keeps using the connection.

The exploration program uses week3db; the Express Week 3 app uses week3app. Importing records into one does not populate the other. npm run explore runs the scratch file with watch mode. With insertion left on, every save or restart adds duplicates: seed once, then turn it off.

CRUD uses query objects and update operators

const products = db.collection('products');

const inserted = await products.insertOne({ name: 'Duct Tape', price: 5.99, quantity: 120 });
const all = await products.find().toArray();
const one = await products.findOne({ name: 'Duct Tape' });
const pricey = await products.find({ price: { $gte: 5 } }).toArray();

const changed = await products.updateOne(
  { _id: inserted.insertedId },
  { $set: { quantity: 150 } }
);
const removed = await products.deleteOne({ _id: inserted.insertedId });

const deleteOneTest = async () => {
  const query = { _id: new ObjectId('68c06e746d1392af8b22b35f') };
  const result = await db.collection('products').deleteOne(query);
  return result;
};
const main = async () => {
  await connect();
  const result = await deleteOneTest();
  console.log(result);
  await disconnect();
};
main();

inserted = products.insert_one({'name': 'Duct Tape', 'price': 5.99, 'quantity': 120})
all = list(products.find())
pricey = list(products.find({'price': {'$gte': 5}}))
changed = products.update_one(
    {'_id': inserted.inserted_id},
    {'$set': {'quantity': 150}}
)
print(changed.modified_count)  # → 1

const inserted = await products.insertOne({ name: 'Duct Tape', price: 5.99, quantity: 120 });
const all = await products.find().toArray();
const pricey = await products.find({ price: { $gte: 5 } }).toArray();
const changed = await products.updateOne(
  { _id: inserted.insertedId },
  { $set: { quantity: 150 } }
);

pymongo uses snake_case and no await; list() does the job of toArray() on the TypeScript side.

const cursor = db.collection('products').find({ price: { $lt: 5 } });
const results: Document[] = [];
while (await cursor.hasNext()) {
  const doc = await cursor.next();
  if (doc) results.push(doc); // next() can be null
}

Names can be duplicated. A name filter illustrates queries, but targeting a known id is more precise for a one-resource API. Verify an update by reading afterward; the result object does not contain the changed document.

Try it in the sandbox: run these operations on a small products collection and read each result object.

An id’s shape and its existence are separate questions

const id = '507f1f77bcf86cd799439011'; // illustrative shape
const document = await db.collection('products').findOne({
  _id: new ObjectId(id)
});

from bson import ObjectId  # installed with pymongo
id = '507f1f77bcf86cd799439011'  # illustrative shape
document = db.get_collection('products').find_one({
    '_id': ObjectId(id)
})
print(document)  # → None

const id = '507f1f77bcf86cd799439011'; // illustrative shape
const document = await db.collection('products').findOne({
  _id: new ObjectId(id)
});

A standard Mongo-generated ObjectId is a 12-byte value commonly displayed as 24 hexadecimal characters. Mongo can store other _id types, but these exercises use its generated ObjectIds.

Reject malformed ids before constructing ObjectId. badID123 should yield 400 in your completed middleware. A syntactically valid id with no matching document yields 404. An id written in the lecture is only an illustration: copy an actual id from your own POST/list/Compass before expecting a successful lookup.

export const validateId = (req: Request, res: Response, next: NextFunction) => {
  if (!/^[0-9a-f]{24}$/.test(String(req.params.id))) {
    res.status(400).json({ error: 'Malformed id' });
    return;
  }
  next();
};

export const validateId = (req: Request, res: Response, next: NextFunction) => {
  if (!/^[0-9a-f]{24}$/.test(String(req.params.id))) {
    res.status(400).json({ error: 'Malformed id' });
    return;
  }
  next();
};

Try it in the sandbox: look up a well-formed id that no document has, then a malformed one, and compare the two answers.

Wrap Mongo operations with HTTP routes

db.ts owns connect/disconnect and product operations. It accepts URI/database arguments so the same code can use a practice database or a temporary test database. The router owns request fields and HTTP statuses. app.ts parses JSON and mounts /products. index.ts awaits connection before listening on 6790.

productRouter.get('/:id', async (req: Request, res: Response) => {
  const product = await getProduct(String(req.params.id));
  if (!product) {
    res.sendStatus(404);
    return;
  }
  res.json(product);
});

GET/PATCH/DELETE id routes first use validateId, so malformed ids receive 400. Week 3’s Product fields are name, price, and quantity. Its raw document responses expose _id; Week 4 adds the mapping to the public id field. ProductUpdate makes fields optional for PATCH. POST builds the known three-field product; PATCH uses supplied changes. Type annotations alone do not enforce runtime body validation.

_clearProducts() uses deleteMany({}) and is a test helper, not a route. Only call it after deliberately connecting to the isolated test database.

import { app } from './app.js';
import { connect } from './db.js';
const port = 6790;
await connect('mongodb://127.0.0.1:27017', 'week3app');
app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

All Week 3 Now You Try tasks

The current lecture notes say the MongoMemoryServer section was carried into Week 4. This guide groups the testing ideas together in Chapter 7 while preserving both weeks’ activities here and in the practice lab.

Try it in the sandbox: the four direct Now You Try #1 tasks are guided tasks there.

REST is an architectural style

REST means Representational State Transfer, described by Roy Fielding in 2000. Its influence comes from fitting the web’s HTTP model with a consistent client/server interface. The lecture contrasts it with more elaborate distributed-call approaches such as SOAP/CORBA. REST is not simply “an endpoint that returns JSON.”

The Week 4 notes list six guiding principles, also called constraints. The table gives each one in the notes’ order, what it means, and where it shows in this course’s API.

Stateless does not mean “no database.” Products can persist while each request independently says what it needs. A client receives a representation of the resource’s state, not direct control of the stored document. Editing a client-side object does not update Mongo until another request asks the server to do so.

Design entities → representations → endpoints

Begin with the entities and their relationships. Then choose the fields clients see. Then lay out plural resource nouns, using HTTP methods for actions. The database’s storage arrangement should not dictate every public path.

This is a design scenario. The Week 4 exercise implements product GET/list, POST, GET by id, and DELETE stretch; it does not implement the entire customer/order API or PATCH. Scenario policy: decrement stock when an order is submitted, check availability then, and store orders in a top-level collection so they can be queried across customers. Role permissions, searching, payments, and full validation are additional design work, not completed features of this exercise.

Give each layer one responsibility

The request goes route → controller → service → database; the service uses model functions to convert data on the way back. These are folders in one server, not five network services.

Build bottom-up: database operations first, then model, service, controller, router, and app/startup. Database code needs no Express. Routes simply connect paths/middleware to controllers.

const getProducts = async (req: Request, res: Response): Promise<void> => {
  const allProducts = await productService.getAll();
  res.json(allProducts);
};

const getAll = async (): Promise<Product[]> => {
  const productDocs = await db.getAllInCollection(db.PRODUCTS);
  return productDocs.map((pDoc) => productFromDocument(pDoc));
};

def getProducts():
    allProducts = productService.getAll()
    return jsonify(allProducts)
def getAll():
    productDocs = db.getAllInCollection(db.PRODUCTS)
    return [productFromDocument(pDoc) for pDoc in productDocs]
print(getProducts().get_json())  # → [{'id': '66f1a2', 'modelName': 'Kettle'}]

const getProducts = async (req: Request, res: Response): Promise<void> => {
  const allProducts = await productService.getAll();
  res.json(allProducts);
};
const getAll = async (): Promise<Product[]> => {
  const productDocs = await db.getAllInCollection(db.PRODUCTS);
  return productDocs.map((pDoc) => productFromDocument(pDoc));
};

A Flask view returns its response instead of calling res.json.

Trace GET /products/:id all the way through

// Route
productRouter.get('/:id', validateId, productControllers.getProduct);

// Controller: HTTP decisions
const product = await productService.get(String(req.params.id));
if (!product) {
  res.status(404).json({ error: 'No product with that id' });
  return;
}
res.json(product);

// Service: return Product | null, without choosing a status
const doc = await db.getInCollection(db.PRODUCTS, id);
return doc ? productFromDocument(doc) : null;

// Database: string -> ObjectId before the query
return await theDb.collection(collectionName)
  .findOne({ _id: new ObjectId(id) });

// Route
productRouter.get('/:id', validateId, productControllers.getProduct);
// Controller: HTTP decisions
const product = await productService.get(String(req.params.id));
if (!product) {
  res.status(404).json({ error: 'No product with that id' });
  return;
}
res.json(product);
// Service: return Product | null, without choosing a status
const doc = await db.getInCollection(db.PRODUCTS, id);
return doc ? productFromDocument(doc) : null;
// Database: string -> ObjectId before the query
return await theDb.collection(collectionName)
  .findOne({ _id: new ObjectId(id) });

# Controller: HTTP decisions
@productRouter.get('/<id>')
def getProduct(id):
    product = productService.get(str(id))
    if not product:
        return jsonify(error='No product with that id'), 404  # → 404 {"error":"No product with that id"}
    return jsonify(product)

// Controller: HTTP decisions
const product = await productService.get(String(req.params.id));
if (!product) {
  res.status(404).json({ error: 'No product with that id' });
  return;
}
res.json(product);

Flask reads the status from the second value a handler returns.

export const productFromDocument = (productDocument: Document): Product => {
  return {
    id: productDocument._id.toString(),
    modelName: productDocument.modelName,
    modelNumber: productDocument.modelNumber,
    manufacturer: productDocument.manufacturer,
    color: productDocument.color,
    price: productDocument.price,
    quantity: productDocument.quantity
  };
};

The list response comes from the same converter: mapping each document with .map() produces it.

Follow creation and deletion

POST follows the same layers. express.json parses req.body, validation checks supplied values, the service prepares the product fields, Mongo inserts the document and generates _id, and the service turns insertedId into an id string. Read back the product with that id to confirm the stored state.

const addProduct = async (req: Request, res: Response): Promise<void> => {
  const postData = req.body;
  const { id } = await productService.add(postData);
  res.status(201).json({ id });
};

ProductFields = Partial<Product> makes every field optional. productFromFields supplies empty strings and zero defaults using ??, so a supplied zero stays zero. Its fallback id uses Date.now. That id is a placeholder for an object in memory and must not be stored; Mongo generates the real one. The lecture passes an InsertOneResult into the service, a small deliberate leak of Mongo’s type rather than complete database encapsulation.

Your local Week 4 service selects known fields and removes the candidate id before insertion; supplied id/_id do not choose the stored identity. It also materializes defaults before storage. The version typed in class inserted the caller’s fields first and applied defaults afterward; the instructor’s post-class memo corrects the lecture code to this same order. Local body middleware rejects arrays/non-objects and wrong supplied field types; price/quantity must be finite nonnegative numbers and quantity an integer. Omitted fields remain allowed.

The next topic follows that bug step by step.

For DELETE, the database returns deletedCount and the service reports a boolean. A second DELETE returns 404. The lecture allows either a 200 body or 204 no-body success; your local Week 4 uses 204, whereas Week 3 uses 200.

const deleteProduct = async (req: Request, res: Response): Promise<void> => {
  res.sendStatus((await productService.remove(String(req.params.id))) ? 204 : 404);
};

@app.post('/products')
def addProduct():
    created = productService.add(request.get_json())
    return jsonify(id=created['id']), 201  # → 201 {"id":"1"}
@app.delete('/products/<id>')
def deleteProduct(id):
    return ('', 204) if productService.remove(id) else ('', 404)  # → 204, then 404 on a second DELETE

const addProduct = async (req: Request, res: Response): Promise<void> => {
  const postData = req.body;
  const { id } = await productService.add(postData);
  res.status(201).json({ id });
};
const deleteProduct = async (req: Request, res: Response): Promise<void> => {
  res.sendStatus((await productService.remove(String(req.params.id))) ? 204 : 404);
};

A bug story: the product that was stored half-filled

After the Week 4 class, the instructor posted a memo about a bug in the POST /products code the class had typed together. Every function did what its name said. A product could still be stored wrong.

The story has two problems. The fix for the first one creates the second, so read them in order.

What the code did, in order

add() is the service function that creates a product. This is the version the class wrote.

const add = async (productInfo: ProductFields): Promise<Product> => {
  const { insertedId } = await db.addToCollection(db.PRODUCTS, productInfo);
  return productFromFields({ ...productInfo, id: insertedId.toString() });
};

1. The first line inside the function hands productInfo straight to the database. That value is exactly what the caller sent, so a field the caller left out is still missing.
2. The second line calls productFromFields(), the model function that fills in a default for each missing field: an empty string for text, zero for a number.

The order is the bug. The defaults went into the value handed back to the caller. They never went into the stored document.

What got stored

The memo tests this with a product that has four fields. It leaves out modelNumber and quantity.

const partialProduct = {
  modelName: 'My Model',
  manufacturer: 'My Manufacturer',
  color: 'green',
  price: 5.5
};
// no modelNumber, no quantity

With the class version of add(), this is the document that ends up in the database. Mongo generates the _id field.

{
  _id: ObjectId('...'),
  modelName: 'My Model',
  manufacturer: 'My Manufacturer',
  color: 'green',
  price: 5.5
}

The stored document has no modelNumber and no quantity. The database kept a half-filled product.

Why the response looked fine

The memo gives three reasons the bug went unnoticed during class.

• The controller sends back only the id, with res.status(201).json({ id }). Everything productFromFields() filled in was thrown away one line later. The id was the one part that was right.
• Every product posted in class was complete. With no field missing there is nothing to default, so the bug cannot show.
• Postman would not have caught it either. You would have to post a partial product, then open the document in Compass and notice a field that is not there.

First fix: fill in the defaults before the insert

const product = productFromFields(productInfo);
const { insertedId } = await db.addToCollection(db.PRODUCTS, product);

Now productFromFields() runs first, and the filled-in product is what gets inserted. The fields the caller left out are stored with their defaults.

The placeholder id

The first fix creates a quieter problem. Look at what productFromFields() does when it is given no id.

id: fields.id ?? String(Date.now()),

It invents an id from the current time. That is fine for an object in memory. But the first fix hands the whole object to Mongo, so the invented id is stored too.

{
  _id: ObjectId('...'),
  id: '1790716131668',
  modelName: 'My Model',
  modelNumber: '',
  manufacturer: 'My Manufacturer',
  color: 'green',
  price: 5.5,
  quantity: 0
}

Two ids, one real. Mongo generated _id. The id field is a placeholder that should never have been stored.

You would never see it through the API. On the way out, productFromDocument() builds the response id from _id and does not read the stored id field. You would see it only by opening the document in Compass.

Second fix: store the fields, not the id

The memo shows two ways to write it. The first lists the six fields to store, and id is not in the list.

const add = async (productInfo: ProductFields): Promise<string> => {
  const product = productFromFields(productInfo);

  const { insertedId } = await db.addToCollection(db.PRODUCTS, {
    modelName: product.modelName,
    modelNumber: product.modelNumber,
    manufacturer: product.manufacturer,
    color: product.color,
    price: product.price,
    quantity: product.quantity
  });

  return insertedId.toString();
};

The second is shorter and stores the same six fields.

const add = async (productInfo: ProductFields): Promise<string> => {
  const product = productFromFields(productInfo);
  const { id, ...productWithoutId } = product;
  const { insertedId } = await db.addToCollection(
    db.PRODUCTS,
    productWithoutId
  );
  return insertedId.toString();
};

Read this line one piece at a time: const { id, ...productWithoutId } = product;

• const declares new names that cannot be reassigned.
• { } on the left of the equals sign is destructuring: it takes an object apart into variables.
• id pulls the field named id out into its own variable.
• ... is the rest element. It collects every field that was not named before it.
• productWithoutId is the name of the new object that receives the collected fields.
• = product names the object being taken apart.

After that line, productWithoutId holds the six product fields. The variable id holds the placeholder and is not used again. The Week 2 PATCH route used the same pattern to separate an id from the other fields.

The memo says either version is fine. The long one says what it stores. The compact one says what it leaves out.

Return only the id

Both corrected versions end with return insertedId.toString(). The declared return type is now Promise<string>, where the class version had Promise<Product>. The controller only needs the id, so add() returns the id as text and nothing else. The controller line loses its braces.

const id = await productService.add(postData);   // was: const { id } = ...

const add = async (productInfo: ProductFields): Promise<string> => {
  const product = productFromFields(productInfo);
  const { id, ...productWithoutId } = product;
  const { insertedId } = await db.addToCollection(
    db.PRODUCTS,
    productWithoutId
  );
  return insertedId.toString();
};

The same product, stored three ways

What a test that reads the data back catches

The memo’s test posts the partial product, then reads the list back through GET /products and finds the new product by its id.

const created = await request(app).post('/products').send(partialProduct);
const all = await request(app).get('/products');
const stored = all.body.find((p) => p.id === created.body.id);

expect(stored.modelName).toBe(partialProduct.modelName); // ← passed
expect(stored.price).toBe(partialProduct.price);         // ← passed
expect(stored.modelNumber).toBe('');   // ← failed: got undefined
expect(stored.quantity).toBe(0);       // ← would fail but never got here

The first two expectations passed. The third failed: modelNumber came back undefined, not an empty string. That failure is how the first bug was found.

A test that checked only the POST response would have passed, because the status and the id were both right. Reading the data back is what asked about the fields the caller left out.

This read-back goes through the API, so it cannot see the placeholder id. That one shows only in the stored document, which is why the memo points to Compass.

The task changed in class

The memo also records that the last Now You Try was changed during class, with about fifteen minutes left. The revised task is the test above: verify that a partially specified product sent to POST /products is inserted correctly, with the supplied fields in place and the defaults from productFromFields() for the rest. The Week 4 notes still describe the earlier task, two tests for GET /products/:id.

Every Week 4 task, including the test-writing anchor