// math-utils.d.ts

// Declare exported functions (no implementation)
export declare function add(a: number, b: number): number;
export declare function multiply(a: number, b: number): number;
export declare function clamp(value: number, min: number, max: number): number;

// Declare exported constants
export declare const PI: number;
export declare const TAU: number;

// Declare exported types (these already have no runtime presence)
export type Vector2 = { x: number; y: number };
export type Matrix2x2 = [[number, number], [number, number]];

// Declare exported classes
export declare class Complex {
  readonly real: number;
  readonly imag: number;
  constructor(real: number, imag: number);
  add(other: Complex): Complex;
  magnitude(): number;
  toString(): string;
}
      

// tsconfig.json — for a library that ships types
{
  "compilerOptions": {
    "declaration": true,         // generate .d.ts files
    "declarationMap": true,      // generate .d.ts.map files (source maps)
    "declarationDir": "./types", // output .d.ts files here (optional)
    "sourceMap": true,
    "outDir": "./dist"
  },
  "include": ["src"]
}
      

// old-lib.d.ts — types for a CJS library
declare class OldLib {
  constructor(options: OldLib.Options);
  connect(): Promise<void>;
  disconnect(): void;
}

declare namespace OldLib {
  interface Options {
    host: string;
    port: number;
    timeout?: number;
  }

  interface ConnectionEvent {
    timestamp: Date;
    host: string;
  }
}

export = OldLib;
      

// Consumer — must use require-style import with export =
import OldLib = require('old-lib');
// OR with esModuleInterop:
import OldLib from 'old-lib';

const lib = new OldLib({ host: 'localhost', port: 3000 });
      

// globals.d.ts — adds to global TypeScript scope (no import/export!)

declare const __DEV__: boolean;
declare const __APP_VERSION__: string;
declare const __BUILD_DATE__: string;

// Extend the Window interface
interface Window {
  analytics: {
    track(event: string, props?: Record<string, unknown>): void;
    identify(userId: string): void;
  };
  __REDUX_DEVTOOLS_EXTENSION__?: () => unknown;
}

// Extend NodeJS ProcessEnv
declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: 'development' | 'production' | 'test';
    NEXT_PUBLIC_API_URL: string;
    DATABASE_URL: string;
  }
}
      

// express-extension.d.ts
import 'express';  // must be a module — import something

declare module 'express' {
  interface Request {
    user?: {
      id: string;
      email: string;
      roles: string[];
    };
    correlationId: string;
  }
}

// Now req.user and req.correlationId are typed in every Express handler
      

// jest-matchers.d.ts — add custom Jest matchers
import '@jest/globals';

declare module '@jest/globals' {
  interface Matchers<R> {
    toBeWithinRange(min: number, max: number): R;
    toBeValidEmail(): R;
    toMatchSnapshot(hint?: string): R;
  }
}
      

// assets.d.ts — tell TypeScript how to type asset imports

// CSS modules
declare module '*.module.css' {
  const styles: Record<string, string>;
  export default styles;
}

declare module '*.module.scss' {
  const styles: Record<string, string>;
  export default styles;
}

// Image files
declare module '*.png' {
  const src: string;
  export default src;
}

declare module '*.jpg' {
  const src: string;
  export default src;
}

declare module '*.webp' {
  const src: string;
  export default src;
}

// SVG (as React component — Vite/SVGR convention)
declare module '*.svg' {
  import type { FC, SVGProps } from 'react';
  const ReactComponent: FC<SVGProps<SVGSVGElement>>;
  export default ReactComponent;
}

// Text / data files
declare module '*.txt' {
  const content: string;
  export default content;
}

declare module '*.json' {
  const data: unknown;
  export default data;
}
      

// package.json — library package
{
  "name": "my-utils",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.mjs"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.js"
      }
    }
  },
  "files": [
    "dist"
  ]
}
      

// tsconfig.json
{
  "compilerOptions": {
    "declaration": true,
    "isolatedDeclarations": true
  }
}
      

// ❌ Error with isolatedDeclarations — return type inferred from another file
export function getUser() {
  return fetchUserFromDB(); // return type depends on fetchUserFromDB's type
}

// ✓ Explicit return type — declaration can be generated from this file alone
export function getUser(): Promise<User> {
  return fetchUserFromDB();
}