# Initialize project
mkdir my-ts-app && cd my-ts-app
npm init -y

# Install dependencies
# -D means devDependency -- TypeScript and type definitions are build tools,
# not runtime code. They should not ship in your production node_modules.
npm install typescript ts-node @types/node -D
npm install express
npm install @types/express -D

# Initialize TypeScript config -- creates tsconfig.json with documented defaults
npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",              // Output JS syntax level -- ES2022 supports top-level await, etc.
    "module": "commonjs",            // Use require/module.exports (standard Node.js module system)
    "lib": ["ES2022"],               // Which built-in type definitions to include
    "outDir": "./dist",              // Compiled .js files go here
    "rootDir": "./src",              // Source .ts files live here
    "strict": true,                  // Enable ALL strict type checks -- always use this
    "esModuleInterop": true,         // Allows 'import express from "express"' syntax
    "skipLibCheck": true,            // Skip type-checking .d.ts files (faster builds)
    "forceConsistentCasingInFileNames": true, // Prevent bugs on case-insensitive file systems
    "resolveJsonModule": true,       // Allow importing .json files
    "declaration": true,             // Generate .d.ts type declaration files
    "declarationMap": true,          // Source maps for declarations (enables "Go to Definition")
    "sourceMap": true,               // Maps compiled JS back to TS for debugging
    "moduleResolution": "node",      // Use Node.js module resolution algorithm
    "baseUrl": "./src",              // Base for path aliases below
    "paths": {                       // Path aliases -- replace ugly relative imports
      "@/*": ["./*"],                // import { foo } from '@/utils' instead of '../../../utils'
      "@config/*": ["config/*"],
      "@controllers/*": ["controllers/*"],
      "@models/*": ["models/*"],
      "@services/*": ["services/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

{
  "scripts": {
    // ts-node-dev watches for file changes and restarts automatically.
    // --respawn: restart on crash instead of exiting.
    // --transpile-only: skip type checking for faster restarts (your IDE handles type checking).
    "dev": "ts-node-dev --respawn --transpile-only src/server.ts",
    "build": "tsc",                    // Compile TypeScript to JavaScript in ./dist
    "start": "node dist/server.js",    // Run the compiled JavaScript in production
    "lint": "eslint src/**/*.ts",
    "test": "jest"
  }
}

// Primitive types -- TypeScript can often infer these automatically,
// but explicit annotations serve as documentation for other developers.
const name: string = 'John';
const age: number = 30;
const isActive: boolean = true;

// Arrays -- two equivalent syntaxes, choose one for consistency
const numbers: number[] = [1, 2, 3];           // Preferred in most codebases
const names: Array<string> = ['Alice', 'Bob'];  // Generic syntax (same result)

// Inline object type -- fine for one-off use, but use an interface for reusable shapes
const user: { name: string; age: number } = {
  name: 'John',
  age: 30
};

// Union types -- the variable can be ONE of the listed types.
// This is incredibly useful for IDs (sometimes strings, sometimes numbers)
// and for function parameters that accept multiple formats.
let id: string | number = 1;
id = 'abc'; // Also valid -- TypeScript tracks the current type through narrowing

// Type aliases -- give a name to a type expression for reuse and readability
type ID = string | number;

// Optional properties -- the ? means the field can be undefined
interface User {
  id: ID;
  name: string;
  email?: string; // Optional -- may or may not be present
}

// Function types -- annotate parameters AND return type.
// The return type annotation is optional (TypeScript can infer it),
// but explicit return types catch mistakes where you accidentally return the wrong thing.
const add = (a: number, b: number): number => a + b;

// Async functions always return a Promise wrapping the actual return type
const fetchUser = async (id: string): Promise<User> => {
  // ...
};

// Void means the function does not return a value
const logMessage = (msg: string): void => {
  console.log(msg);
};

// Interface for objects -- describes "what shape does this data have?"
interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
}

// Extending interfaces -- Admin has all User fields plus its own
interface Admin extends User {
  role: 'admin';
  permissions: string[];
}

// Type for unions -- a value can be one of several options
type UserRole = 'user' | 'admin' | 'moderator';

// Intersection type -- combines two types into one (User AND role)
type UserWithRole = User & {
  role: UserRole;
};

// Generic interfaces -- the T is a placeholder that gets filled in at usage time.
// This is like a template: one definition, many concrete types.
interface ApiResponse<T> {
  success: boolean;
  data: T;
  error?: string;  // The ? means this field is optional
}

// Usage -- T becomes User[] here, so data is typed as User[]
const response: ApiResponse<User[]> = {
  success: true,
  data: users
};

// src/server.ts
import express, { Application } from 'express';
import cors from 'cors';
import helmet from 'helmet';
import { errorHandler } from './middleware/errorHandler';
import userRoutes from './routes/userRoutes';

const app: Application = express();

app.use(helmet());
app.use(cors());
app.use(express.json());

app.use('/api/users', userRoutes);

app.use(errorHandler);

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

export default app;

// src/types/express.d.ts
// This "declaration merging" file extends Express's built-in Request type
// to include a user property. Without this, TypeScript does not know
// about req.user and would flag it as an error.
import { User } from './user';

declare global {
  namespace Express {
    interface Request {
      user?: User;
    }
  }
}

// src/controllers/userController.ts
import { Request, Response, NextFunction } from 'express';
import { User, CreateUserDTO, UpdateUserDTO } from '../types/user';
import * as userService from '../services/userService';

// Response<{ data: User[] }> tells TypeScript that res.json() expects
// an object with a data property containing a User array.
// If you try to send something else, the compiler catches it.
export const getUsers = async (
  req: Request,
  res: Response<{ data: User[] }>,
  next: NextFunction
): Promise<void> => {
  try {
    const users = await userService.findAll();
    res.json({ data: users });
  } catch (error) {
    next(error);
  }
};

// Request<{ id: string }> types req.params -- TypeScript now knows
// req.params.id exists and is a string. Typos like req.params.userId
// are caught at compile time, not discovered in production.
export const getUser = async (
  req: Request<{ id: string }>,
  res: Response<{ data: User }>,
  next: NextFunction
): Promise<void> => {
  try {
    const user = await userService.findById(req.params.id);
    if (!user) {
      res.status(404).json({ error: 'User not found' } as any);
      return;
    }
    res.json({ data: user });
  } catch (error) {
    next(error);
  }
};

// Request<{}, {}, CreateUserDTO> -- the third generic parameter types req.body.
// This ensures req.body.email, req.body.password, req.body.name all have
// the types defined in CreateUserDTO with full autocomplete support.
export const createUser = async (
  req: Request<{}, {}, CreateUserDTO>,
  res: Response<{ data: User }>,
  next: NextFunction
): Promise<void> => {
  try {
    const user = await userService.create(req.body);
    res.status(201).json({ data: user });
  } catch (error) {
    next(error);
  }
};

// src/routes/userRoutes.ts
import { Router } from 'express';
import * as userController from '../controllers/userController';
import { validate } from '../middleware/validate';
import { createUserSchema, updateUserSchema } from '../schemas/userSchema';
import { auth } from '../middleware/auth';

const router = Router();

router.get('/', userController.getUsers);
router.get('/:id', userController.getUser);
router.post('/', validate(createUserSchema), userController.createUser);
router.put('/:id', auth, validate(updateUserSchema), userController.updateUser);
router.delete('/:id', auth, userController.deleteUser);

export default router;

npm install zod

// src/schemas/userSchema.ts
import { z } from 'zod';

export const createUserSchema = z.object({
  body: z.object({
    email: z.string().email('Invalid email'),
    password: z.string().min(8, 'Password must be at least 8 characters'),
    name: z.string().min(2).max(100)
  })
});

export const updateUserSchema = z.object({
  params: z.object({
    id: z.string().uuid()
  }),
  body: z.object({
    name: z.string().min(2).max(100).optional(),
    email: z.string().email().optional()
  })
});

// Infer types from schemas -- this is the key insight: the TypeScript type
// is DERIVED from the runtime schema, so they can never go out of sync.
// Change the schema, and the type updates automatically.
export type CreateUserInput = z.infer<typeof createUserSchema>['body'];
export type UpdateUserInput = z.infer<typeof updateUserSchema>['body'];

// Validation middleware
import { AnyZodObject, ZodError } from 'zod';

export const validate = (schema: AnyZodObject) => 
  async (req: Request, res: Response, next: NextFunction) => {
    try {
      await schema.parseAsync({
        body: req.body,
        query: req.query,
        params: req.params
      });
      next();
    } catch (error) {
      if (error instanceof ZodError) {
        res.status(400).json({
          success: false,
          errors: error.errors.map(e => ({
            path: e.path.join('.'),
            message: e.message
          }))
        });
      } else {
        next(error);
      }
    }
  };

// src/utils/errors.ts
export class AppError extends Error {
  public readonly statusCode: number;
  public readonly isOperational: boolean;

  constructor(message: string, statusCode: number, isOperational = true) {
    super(message);
    this.statusCode = statusCode;
    this.isOperational = isOperational;

    Error.captureStackTrace(this, this.constructor);
  }
}

export class NotFoundError extends AppError {
  constructor(resource = 'Resource') {
    super(`${resource} not found`, 404);
  }
}

export class ValidationError extends AppError {
  public readonly errors: Array<{ field: string; message: string }>;

  constructor(errors: Array<{ field: string; message: string }>) {
    super('Validation failed', 400);
    this.errors = errors;
  }
}

export class UnauthorizedError extends AppError {
  constructor(message = 'Unauthorized') {
    super(message, 401);
  }
}

// src/middleware/errorHandler.ts
import { Request, Response, NextFunction } from 'express';
import { AppError } from '../utils/errors';

interface ErrorResponse {
  success: false;
  error: string;
  stack?: string;
  errors?: Array<{ field: string; message: string }>;
}

export const errorHandler = (
  err: Error,
  req: Request,
  res: Response<ErrorResponse>,
  next: NextFunction
): void => {
  if (err instanceof AppError) {
    res.status(err.statusCode).json({
      success: false,
      error: err.message,
      ...(err instanceof ValidationError && { errors: err.errors })
    });
    return;
  }

  console.error('Unhandled error:', err);
  
  res.status(500).json({
    success: false,
    error: process.env.NODE_ENV === 'production' 
      ? 'Internal server error' 
      : err.message,
    ...(process.env.NODE_ENV !== 'production' && { stack: err.stack })
  });
};

npm install @prisma/client
npm install prisma -D
npx prisma init

// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        String   @id @default(uuid())
  email     String   @unique
  name      String
  password  String
  role      Role     @default(USER)
  posts     Post[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        String   @id @default(uuid())
  title     String
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  String
  createdAt DateTime @default(now())
}

enum Role {
  USER
  ADMIN
}

// src/services/userService.ts
import { PrismaClient, User, Prisma } from '@prisma/client';
import bcrypt from 'bcrypt';
import { CreateUserInput, UpdateUserInput } from '../schemas/userSchema';
import { NotFoundError } from '../utils/errors';

const prisma = new PrismaClient();

// Omit<T, K> is a built-in TypeScript utility type that creates a new type
// with all properties of T except K. Here, SafeUser is a User without the
// password field -- perfect for API responses where you must never leak password hashes.
type SafeUser = Omit<User, 'password'>;

const userSelect: Prisma.UserSelect = {
  id: true,
  email: true,
  name: true,
  role: true,
  createdAt: true,
  updatedAt: true
};

export const findAll = async (): Promise<SafeUser[]> => {
  return prisma.user.findMany({ select: userSelect });
};

export const findById = async (id: string): Promise<SafeUser | null> => {
  return prisma.user.findUnique({
    where: { id },
    select: userSelect
  });
};

export const findByEmail = async (email: string): Promise<User | null> => {
  return prisma.user.findUnique({ where: { email } });
};

export const create = async (data: CreateUserInput): Promise<SafeUser> => {
  const hashedPassword = await bcrypt.hash(data.password, 12);
  
  return prisma.user.create({
    data: {
      ...data,
      password: hashedPassword
    },
    select: userSelect
  });
};

export const update = async (
  id: string, 
  data: UpdateUserInput
): Promise<SafeUser> => {
  const user = await prisma.user.update({
    where: { id },
    data,
    select: userSelect
  });

  if (!user) {
    throw new NotFoundError('User');
  }

  return user;
};

export const remove = async (id: string): Promise<void> => {
  await prisma.user.delete({ where: { id } });
};

// src/middleware/auth.ts
import { Request, Response, NextFunction } from 'express';
import jwt from 'jsonwebtoken';
import { UnauthorizedError } from '../utils/errors';

// Define the exact shape of your JWT payload.
// This interface is the contract between token creation and token consumption.
interface JwtPayload {
  userId: string;
  role: string;
}

export const auth = async (
  req: Request,
  res: Response,
  next: NextFunction
): Promise<void> => {
  try {
    const token = req.headers.authorization?.replace('Bearer ', '');

    if (!token) {
      throw new UnauthorizedError('No token provided');
    }

    // The ! (non-null assertion) tells TypeScript "I know this is defined."
    // This is safe only because we validate required env vars at startup (see env.ts).
    // Without that validation, this could crash at runtime with "undefined" as the secret.
    const decoded = jwt.verify(
      token, 
      process.env.JWT_SECRET!
    ) as JwtPayload;

    req.user = {
      id: decoded.userId,
      role: decoded.role
    } as any;

    next();
  } catch (error) {
    if (error instanceof jwt.JsonWebTokenError) {
      next(new UnauthorizedError('Invalid token'));
    } else {
      next(error);
    }
  }
};

export const authorize = (...roles: string[]) => {
  return (req: Request, res: Response, next: NextFunction): void => {
    if (!req.user) {
      next(new UnauthorizedError());
      return;
    }

    if (!roles.includes(req.user.role)) {
      next(new UnauthorizedError('Insufficient permissions'));
      return;
    }

    next();
  };
};

// src/__tests__/userService.test.ts
import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
import * as userService from '../services/userService';
import { prisma } from '../lib/prisma';

describe('UserService', () => {
  beforeEach(async () => {
    await prisma.user.deleteMany();
  });

  describe('create', () => {
    it('should create a new user', async () => {
      const userData = {
        email: 'test@example.com',
        password: 'password123',
        name: 'Test User'
      };

      const user = await userService.create(userData);

      expect(user).toMatchObject({
        email: userData.email,
        name: userData.name
      });
      expect(user).toHaveProperty('id');
      expect(user).not.toHaveProperty('password');
    });

    it('should hash the password', async () => {
      const userData = {
        email: 'test@example.com',
        password: 'password123',
        name: 'Test User'
      };

      await userService.create(userData);

      const dbUser = await prisma.user.findUnique({
        where: { email: userData.email }
      });

      expect(dbUser?.password).not.toBe(userData.password);
    });
  });
});

src/
├── config/
│   ├── database.ts
│   └── env.ts
├── controllers/
│   └── userController.ts
├── middleware/
│   ├── auth.ts
│   ├── errorHandler.ts
│   └── validate.ts
├── models/
│   └── (Prisma handles this)
├── routes/
│   ├── index.ts
│   └── userRoutes.ts
├── schemas/
│   └── userSchema.ts
├── services/
│   └── userService.ts
├── types/
│   ├── express.d.ts
│   └── user.ts
├── utils/
│   ├── errors.ts
│   └── helpers.ts
├── __tests__/
│   └── userService.test.ts
├── app.ts
└── server.ts