TypeScript + Tools

// npm i -D @types/node
import { readFile } from "node:fs"

// argv is ALWAYS string[] — argv[0] is the node binary, argv[1] the script
const [, , command, ...rest] = process.argv
const target: string = rest[0] ?? "."

function loadConfig(
  path: string,
  cb: (err: NodeJS.ErrnoException | null, data?: string) => void,
): void {
  readFile(path, "utf8", (err, data) => {
    if (err) return cb(err)
    cb(null, data)
  })
}

loadConfig(`${target}/config.json`, (err, data) => {
  if (err) {
    console.error("failed to read config:", err.message)
    process.exitCode = 1
    return
  }
  console.log("config:", data)
})

// package.json
{
  "name": "slugify-lite",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "tsc -p tsconfig.build.json",
    "prepublishOnly": "npm run build"
  },
  "devDependencies": { "typescript": "^5" }
}

// dist/index.d.ts — generated by tsc --declaration, never hand-edited
export declare function slugify(input: string): string

// a consumer's code — zero extra install, TypeScript sees this automatically
import { slugify } from "slugify-lite"
slugify("Hello World")

// npm i express && npm i -D @types/express
import express, { Request, Response } from "express"

interface Task {
  id: number
  text: string
  done: boolean
}

const app = express()
app.use(express.json())

const tasks: Task[] = [{ id: 1, text: "learn typescript", done: false }]

app.get(
  "/api/tasks/:id",
  (req: Request<{ id: string }>, res: Response<Task | { error: string }>) => {
    const task = tasks.find(t => t.id === Number(req.params.id))
    if (!task) return res.status(404).json({ error: "task not found" })
    res.json(task)
  },
)

app.post(
  "/api/tasks",
  (req: Request<{}, Task, { text: string }>, res: Response<Task>) => {
    const task: Task = { id: tasks.length + 1, text: req.body.text, done: false }
    tasks.push(task)
    res.status(201).json(task)
  },
)

app.listen(3000)

import { useState } from "react"

interface TaskItemProps {
  text: string
  done: boolean
  onToggle: () => void
}

function TaskItem({ text, done, onToggle }: TaskItemProps) {
  return (
    <li onClick={onToggle} style={{ textDecoration: done ? "line-through" : "none" }}>
      {text}
    </li>
  )
}

function TaskForm({ onAdd }: { onAdd: (text: string) => void }) {
  const [text, setText] = useState<string>("")

  function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
    setText(e.target.value)
  }

  function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault()
    if (!text.trim()) return
    onAdd(text.trim())
    setText("")
  }

  return (
    <form onSubmit={handleSubmit}>
      <input value={text} onChange={handleChange} />
      <button type="submit">Add</button>
    </form>
  )
}

import { Pool, QueryResult } from "pg"

interface TaskRow {
  id: number
  text: string
  done: boolean
}

const pool = new Pool({ connectionString: process.env.DATABASE_URL })

async function getTask(id: number): Promise<TaskRow | undefined> {
  const result: QueryResult<TaskRow> = await pool.query(
    "SELECT id, text, done FROM tasks WHERE id = $1",
    [id],
  )
  return result.rows[0]
}

class Repository<T extends { id: number }> {
  constructor(private pool: Pool, private table: string) {}

  async findById(id: number): Promise<T | undefined> {
    const { rows } = await this.pool.query<T>(
      `SELECT * FROM ${this.table} WHERE id = $1`,
      [id],
    )
    return rows[0]
  }

  async insert(row: Omit<T, "id">): Promise<T> {
    const cols = Object.keys(row)
    const values = Object.values(row)
    const placeholders = cols.map((_, i) => `$${i + 1}`).join(", ")
    const { rows } = await this.pool.query<T>(
      `INSERT INTO ${this.table} (${cols.join(", ")}) VALUES (${placeholders}) RETURNING *`,
      values,
    )
    return rows[0]
  }
}

const tasks = new Repository<TaskRow>(pool, "tasks")

FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src ./src
RUN npx tsc -p tsconfig.json

FROM node:22-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev

FROM node:22-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

import { describe, test, expect, jest } from "@jest/globals"
import { Pool } from "pg"
import { getTask } from "../src/tasks"

jest.mock("pg")

interface TaskRow {
  id: number
  text: string
}

describe("getTask", () => {
  test("returns the row for a matching id", async () => {
    const mockQuery: jest.Mock<Promise<{ rows: TaskRow[] }>, [string, unknown[]]> = jest.fn()
    mockQuery.mockResolvedValue({ rows: [{ id: 1, text: "ship it" }] })
    ;(Pool as jest.Mock).mockImplementation(() => ({ query: mockQuery }))

    const task = await getTask(1)

    expect(task).toEqual({ id: 1, text: "ship it" })
    expect(mockQuery).toHaveBeenCalledWith(
      "SELECT id, text, done FROM tasks WHERE id = $1",
      [1],
    )
  })
})

# .gitignore — a TypeScript app
node_modules/
dist/
*.tsbuildinfo
.env
coverage/

# .gitignore — a PUBLISHED PACKAGE keeps dist/ out of GIT the same way,
# but package.json ships it anyway via "files", built fresh at publish time:
#
#   { "files": ["dist"], "scripts": { "prepublishOnly": "tsc -p tsconfig.build.json" } }
#
# The rule either way: dist/ is either reproducible from source in CI (an app),
# or reproduced right before every publish (a package) — never hand-edited,
# never relied on as the source of truth, so committing it to GIT specifically
# is rarely the right call even for a package; "files" solves the same problem.