TypeScript from scratch: types, interfaces, generics

export function subtotal(order) {
  return order.items.reduce((sum, item) => sum + item.price * item.quanity, 0);
}

export function discount(order) {
  return Math.round(subtotal(order) * order.promo.percent / 100);
}

export function statusLabel(status) {
  if (status === "new") return "New";
  if (status === "paid") return "Paid";
  if (status === "shipped") return "Shipped";
}

import { discount, statusLabel, subtotal } from "./orders.js";

const order = {
  id: 1042,
  status: "cancelled",
  items: [{ sku: "CAP-M", name: "Cappuccino", price: 1600, qty: 2 }],
};

console.log(subtotal(order));
console.log(statusLabel(order.status));
console.log(discount(order));

$ node js/main.js
NaN
undefined
…\js\orders.js:6
  return Math.round(subtotal(order) * order.promo.percent / 100);
                                                  ^

TypeError: Cannot read properties of undefined (reading 'percent')
    at discount (…/js/orders.js:6:51)
    at …

Node.js v24.18.0

mkdir orders-ts
cd orders-ts
npm init -y
npm install -D typescript
npx tsc -v

{
  "name": "orders-ts",
  "private": true,
  "type": "module",
  "scripts": {
    "check": "tsc --noEmit",
    "start": "node src/main.ts"
  },
  "devDependencies": {
    "typescript": "^7.0.2"
  }
}

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "target": "es2024",
    "module": "nodenext",
    "noEmit": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "rewriteRelativeImportExtensions": true
  },
  "include": ["src"]
}

import type { Order, OrderStatus } from "./types.ts";

export function subtotal(order: Order): number {
  return order.items.reduce((sum, item) => sum + item.price * item.quanity, 0);
}

export function discount(order: Order): number {
  return Math.round(subtotal(order) * order.promo.percent / 100);
}

export function statusLabel(status: OrderStatus): string {
  if (status === "new") return "New";
  if (status === "paid") return "Paid";
  if (status === "shipped") return "Shipped";
}

$ npm run check

> check
> tsc --noEmit

src/orders.ts(4,68): error TS2339: Property 'quanity' does not exist on type 'OrderItem'.
src/orders.ts(8,39): error TS18048: 'order.promo' is possibly 'undefined'.
src/orders.ts(11,51): error TS2366: Function lacks ending return statement and return type does not include 'undefined'.

let total = 0; // inferred type: number
total = "6540 ₸";

const names = ["Cappuccino", "Cheesecake"]; // string[]
const count = names.length; // number

// parameters need annotations; the return type (number) is inferred
function lineTotal(price: number, qty: number) {
  return price * qty;
}

// without an annotation the parameter would be an implicit any, which strict forbids
function fee(order) {
  return order.delivery.fee;
}

$ npx tsc --noEmit
src/inference.ts(2,1): error TS2322: Type 'string' is not assignable to type 'number'.
src/inference.ts(13,14): error TS7006: Parameter 'order' implicitly has an 'any' type.

export type OrderStatus = "new" | "paid" | "shipped" | "cancelled";

export interface OrderItem {
  readonly sku: string;
  name: string;
  price: number; // tenge per unit
  qty: number;
}

export interface Promo {
  code: string;
  percent: number;
}

export type Delivery =
  | { kind: "pickup" }
  | { kind: "courier"; address: string; fee: number };

export interface Order {
  readonly id: number;
  customer: string;
  status: OrderStatus;
  items: OrderItem[];
  promo?: Promo;
  delivery: Delivery;
}

import type { Order } from "./types.ts";

function renumber(order: Order) {
  order.id = 1; // id is declared readonly
  order.items[0].sku = "NEW"; // sku is readonly too, and item [0] may not exist
  order.promo.percent = 50; // promo is optional
}

$ npx tsc --noEmit
src/readonly.ts(4,9): error TS2540: Cannot assign to 'id' because it is a read-only property.
src/readonly.ts(5,3): error TS2532: Object is possibly 'undefined'.
src/readonly.ts(5,18): error TS2540: Cannot assign to 'sku' because it is a read-only property.
src/readonly.ts(6,3): error TS18048: 'order.promo' is possibly 'undefined'.

import type { Delivery, Order, OrderStatus } from "./types.ts";

export function subtotal(order: Order): number {
  return order.items.reduce((sum, item) => sum + item.price * item.qty, 0);
}

export function discount(order: Order): number {
  if (order.promo === undefined) {
    return 0;
  }
  // here order.promo is already Promo, not Promo | undefined
  return Math.round((subtotal(order) * order.promo.percent) / 100);
}

export function deliveryFee(delivery: Delivery): number {
  switch (delivery.kind) {
    case "pickup":
      return 0;
    case "courier":
      return delivery.fee; // only courier delivery has a fee
  }
}

export function orderTotal(order: Order): number {
  return subtotal(order) - discount(order) + deliveryFee(order.delivery);
}

export function statusLabel(status: OrderStatus): string {
  switch (status) {
    case "new":
      return "New";
    case "paid":
      return "Paid";
    case "shipped":
      return "Shipped";
    case "cancelled":
      return "Cancelled";
    default: {
      // reachable only if a new status is added to OrderStatus
      const unhandled: never = status;
      return unhandled;
    }
  }
}

$ npx tsc --noEmit
src/orders.ts(40,13): error TS2322: Type '"refunded"' is not assignable to type 'never'.

// T is a type parameter: whatever array comes in, an element of the same type comes out
export function first<T>(items: readonly T[]): T | undefined {
  return items[0];
}

// T must have a numeric id field: this is a constraint
export function findById<T extends { id: number }>(
  items: readonly T[],
  id: number,
): T | undefined {
  return items.find((item) => item.id === id);
}

// K can only be an existing key of T; the result is an array of that field's values
export function pluck<T, K extends keyof T>(items: readonly T[], key: K): T[K][] {
  return items.map((item) => item[key]);
}

import type { Order } from "./types.ts";
import { first, pluck } from "./utils.ts";

function report(order: Order) {
  const prices = pluck(order.items, "price"); // number[]
  const titles = pluck(order.items, "title"); // no such field
  const top = first(order.items);
  console.log(top.name); // first may return undefined
}

$ npx tsc --noEmit
src/generic-error.ts(6,37): error TS2345: Argument of type '"title"' is not assignable to parameter of type 'keyof OrderItem'.
src/generic-error.ts(8,15): error TS18048: 'top' is possibly 'undefined'.

const fromAny: any = JSON.parse(`{ "total": 6540 }`);
fromAny.totl.toFixed(); // the compiler stays silent; this crashes at runtime

const fromUnknown: unknown = JSON.parse(`{ "total": 6540 }`);
fromUnknown.total; // error: first prove it's an object with a total field

if (typeof fromUnknown === "object" && fromUnknown !== null && "total" in fromUnknown) {
  console.log(fromUnknown.total); // the field's type here is unknown; check it too
}

$ npx tsc --noEmit
src/unknown.ts(5,1): error TS18046: 'fromUnknown' is of type 'unknown'.

import type { Delivery, Order, OrderItem, OrderStatus, Promo } from "./types.ts";

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null;
}

function isStatus(value: unknown): value is OrderStatus {
  return value === "new" || value === "paid" || value === "shipped" || value === "cancelled";
}

function isItem(value: unknown): value is OrderItem {
  return (
    isRecord(value) &&
    typeof value.sku === "string" &&
    typeof value.name === "string" &&
    typeof value.price === "number" &&
    typeof value.qty === "number"
  );
}

function isPromo(value: unknown): value is Promo {
  return isRecord(value) && typeof value.code === "string" && typeof value.percent === "number";
}

function isDelivery(value: unknown): value is Delivery {
  if (!isRecord(value)) return false;
  if (value.kind === "pickup") return true;
  return (
    value.kind === "courier" &&
    typeof value.address === "string" &&
    typeof value.fee === "number"
  );
}

export function parseOrder(json: string): Order {
  const data: unknown = JSON.parse(json);

  if (
    !isRecord(data) ||
    typeof data.id !== "number" ||
    typeof data.customer !== "string" ||
    !isStatus(data.status) ||
    !Array.isArray(data.items) ||
    !data.items.every(isItem) ||
    !isDelivery(data.delivery)
  ) {
    throw new Error("The server returned an order in an unexpected format");
  }

  const order: Order = {
    id: data.id,
    customer: data.customer,
    status: data.status,
    items: data.items,
    delivery: data.delivery,
  };
  if (isPromo(data.promo)) {
    order.promo = data.promo;
  }
  return order;
}

import { orderTotal, statusLabel } from "./orders.ts";
import { parseOrder } from "./parse.ts";
import { findById, first, pluck } from "./utils.ts";

// what a server response might look like; for now it's just a string
const response = `{
  "id": 1042,
  "customer": "Aliya",
  "status": "paid",
  "items": [
    { "sku": "CAP-M", "name": "Cappuccino", "price": 1600, "qty": 2 },
    { "sku": "CHS-1", "name": "Cheesecake", "price": 2400, "qty": 1 }
  ],
  "promo": { "code": "AUTUMN", "percent": 10 },
  "delivery": { "kind": "courier", "address": "10 Abay Ave", "fee": 1500 }
}`;

const order = parseOrder(response);

console.log(`Order ${order.id}: ${statusLabel(order.status)}`);
console.log(pluck(order.items, "name").join(", "));
console.log(`Total due: ${orderTotal(order)} ₸`);

const top = first(order.items); // type: OrderItem | undefined
console.log(top?.name ?? "cart is empty");

const found = findById([order], 1042); // type: Order | undefined
console.log(found ? "order found" : "no such order");

try {
  parseOrder(`{ "id": "1042" }`);
} catch (error) {
  console.log(error instanceof Error ? error.message : error);
}

$ npm run check && npm start

> check
> tsc --noEmit


> start
> node src/main.ts

Order 1042: Paid
Cappuccino, Cheesecake
Total due: 6540 ₸
Cappuccino
order found
The server returned an order in an unexpected format