Bun.js + Docker Mastery

"Simplicity is the ultimate sophistication." — Leonardo da Vinci

Filosofi Inti (20 Tahun Wisdom)

KISS - Keep It Stupid Simple

// ❌ Over-engineering
class UserServiceFactoryAbstractSingletonProxyDecorator { ... }

// ✅ Simple & Clear
const userService = { create, update, delete, findById }

Less is More

• 1 file = 1 tanggung jawab (max 200 lines)
• 1 function = 1 task (max 20 lines)
• Jika butuh komentar panjang, refactor kodenya
• Nama yang jelas > komentar yang panjang

Red Flags (Warning Signs)

• File > 300 lines → split
• Function > 30 lines → extract
• Nested callback > 2 level → refactor
• Cyclomatic complexity > 10 → simplify
• any type → define proper types

Quick Start

Inisialisasi Project Baru

# Gunakan script init
./scripts/init-project.sh my-app

# Atau manual
bun init
bun add hono zod drizzle-orm pino
bun add -d @types/bun vitest

Struktur Folder Production-Ready

src/
├── index.ts              # Entry point ONLY (max 20 lines)
├── app.ts                # App setup & middleware registration
├── config/
│   ├── index.ts          # Export semua config
│   ├── env.ts            # Environment validation dengan Zod
│   └── database.ts       # Database config
├── routes/
│   ├── index.ts          # Route aggregator
│   ├── user.route.ts     # User routes
│   └── auth.route.ts     # Auth routes
├── controllers/          # HTTP layer ONLY
├── services/             # Business logic
├── repositories/         # Data access layer
├── middlewares/
│   ├── auth.ts           # Authentication
│   ├── validate.ts       # Request validation
│   └── error.ts          # Error handler
├── utils/
│   ├── response.ts       # Standard response helper
│   ├── logger.ts         # Pino logger setup
│   └── errors.ts         # Custom error classes
└── types/
    ├── index.d.ts        # Global types
    └── api.types.ts      # API request/response types

Core Patterns

1. Entry Point yang Bersih

// src/index.ts - HANYA INI
import { app } from "./app"
import { env } from "./config/env"
import { logger } from "./utils/logger"

const server = Bun.serve({
  port: env.PORT,
  fetch: app.fetch,
})

logger.info(`🚀 Server running on ${server.url}`)

2. Environment Validation (WAJIB)

// src/config/env.ts
import { z } from "zod"

const envSchema = z.object({
  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  REDIS_URL: z.string().url().optional(),
})

export const env = envSchema.parse(process.env)
export type Env = z.infer<typeof envSchema>

3. Layered Architecture

HTTP Request → Controller → Service → Repository → Database
                  ↓            ↓           ↓
              Validation   Business    Data Access
                          Logic        (Drizzle)

4. Error Handling yang Proper

// src/utils/errors.ts
export class AppError extends Error {
  constructor(
    public message: string,
    public statusCode: number = 500,
    public code: string = "INTERNAL_ERROR"
  ) {
    super(message)
    Error.captureStackTrace(this, this.constructor)
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string) {
    super(`${resource} not found`, 404, "NOT_FOUND")
  }
}

export class ValidationError extends AppError {
  constructor(message: string) {
    super(message, 400, "VALIDATION_ERROR")
  }
}

5. Response Standard

// src/utils/response.ts
export const ok = <T>(data: T) => ({ success: true, data })
export const created = <T>(data: T) => ({ success: true, data })
export const error = (message: string, code: string) => ({
  success: false,
  error: { message, code }
})

Docker Best Practices

Multi-stage Build (Production)

# Build stage
FROM oven/bun:1-alpine AS builder
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile --production=false
COPY . .
RUN bun run build

# Production stage
FROM oven/bun:1-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production

# Security: Non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S bunjs -u 1001
USER bunjs

COPY --from=builder --chown=bunjs:nodejs /app/dist ./dist
COPY --from=builder --chown=bunjs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=bunjs:nodejs /app/package.json ./

EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

CMD ["bun", "run", "dist/index.js"]

Docker Compose (Development)

Lihat assets/project-template/docker/docker-compose.yml

Debugging Mastery

Common Crash Points & Solutions

Issue	Penyebab	Solusi
Memory leak	Uncleared intervals/listeners	Cleanup di graceful shutdown
Connection pool exhausted	Tidak release connection	Gunakan using atau finally
Race condition	Async tanpa proper await	Promise.all dengan error handling
Uncaught Promise rejection	Missing try-catch	Global error handler

Debugging Tools

// Bun native debugger
bun --inspect src/index.ts

// Memory profiling
bun --smol src/index.ts  // Low memory mode

// Trace async operations
process.on("unhandledRejection", (reason, promise) => {
  logger.error({ reason, promise }, "Unhandled Rejection")
})

References (Detailed Guides)

• Clean Code Patterns: See references/clean-code-patterns.md
• Debugging Deep Dive: See references/debugging-guide.md
• Library Arsenal (20+ recommended): See references/library-arsenal.md
• Docker Advanced Patterns: See references/docker-patterns.md
• Testing Strategy: See references/testing-strategy.md

Scripts

• scripts/init-project.sh - Initialize new project dengan template
• scripts/healthcheck.ts - Healthcheck endpoint template

Assets

• assets/project-template/ - Full project boilerplate siap pakai

Checklist Sebelum Production

• Environment variables validated dengan Zod
• Graceful shutdown implemented
• Health check endpoint /health
• Structured logging dengan Pino
• Error handling global
• Rate limiting
• CORS configured
• Security headers (helmet)
• Database connection pooling
• Docker multi-stage build
• CI/CD pipeline
• Monitoring & alerting ready