// ✅ Interfaces with the same name merge into a single combined type
interface Window {
  analytics: AnalyticsClient
}
interface Window {
  featureFlags: FeatureFlags
}
// Result: Window now has both `analytics` and `featureFlags` properties

// ❌ Type aliases with the same name produce an error — no merging
type Config = { host: string }
type Config = { port: number }  // ❌ Error: Duplicate identifier 'Config'

// ❌ The common "fix" — silences the compiler, lies to the type system
app.get('/profile', (req, res) => {
  const user = (req as any).user  // No type safety — any property name compiles
  res.json(user.name)
})

// ✅ Module augmentation — extend Express's Request type safely
// File: src/types/express.d.ts
import { User } from '../models/user'  // The import makes this a module file

declare module 'express-serve-static-core' {
  interface Request {
    user?: User  // Now `req.user` is typed as `User | undefined`
  }
}

// Usage — fully typed, no cast required
app.get('/profile', (req, res) => {
  if (!req.user) return res.status(401).send('Unauthorized')
  res.json(req.user.name)  // ✅ req.user is User — .name is safe
})

// ✅ Correct pattern — `declare global` extends the global scope from a module file
// File: src/types/globals.d.ts
import { AnalyticsClient } from './analytics'  // This import makes the file a module

declare global {
  interface Window {
    analytics: AnalyticsClient
  }

  // Extend NodeJS global (for server-side code)
  namespace NodeJS {
    interface ProcessEnv {
      NODE_ENV: 'development' | 'production' | 'test'
      DATABASE_URL: string
      API_KEY: string
    }
  }
}

export {}  // Necessary if there are no other imports — ensures the file is a module

// Usage
const env = process.env.NODE_ENV  // 'development' | 'production' | 'test' — not string
const dbUrl = process.env.DATABASE_URL  // string — required, will error if missing from .env

// ambient.d.ts — NO imports or exports — this file is globally scoped
interface GlobalUser {
  id: string
  name: string
}
// GlobalUser is now available everywhere without any import

// module.d.ts — HAS an export — this file is module scoped
export interface ModuleUser {
  id: string
  name: string
}
// ModuleUser must be explicitly imported — it is not globally available

// Without ambient declarations — TypeScript errors
import logo from './logo.svg'      // ❌ Cannot find module './logo.svg'
import styles from './app.module.css'  // ❌ Cannot find module

// ✅ Wildcard ambient module declarations (place in a .d.ts file)
// src/types/assets.d.ts
declare module '*.svg' {
  const content: string  // SVGs are typically inlined as a URL string
  export default content
}

declare module '*.png' {
  const content: string
  export default content
}

declare module '*.module.css' {
  const styles: { readonly [className: string]: string }
  export default styles
}

// Now fully typed:
import logo from './logo.svg'    // string
import styles from './app.module.css'  // { [className: string]: string }

# Read the source of any @types package
cat node_modules/@types/express/index.d.ts
cat node_modules/@types/node/globals.d.ts