graph TB
    A[JavaScript ライブラリ<br/>実装コード] -->|型情報なし| B[TypeScript プロジェクト]
    C[宣言ファイル .d.ts<br/>型情報のみ] -->|型情報を提供| D[TypeScript コンパイラ]
    B --> D
    D -->|型チェック実行| E[コンパイル結果<br/>JavaScript]
    A -->|実行時に使用| F[ランタイム]
    E --> F
 
    style C fill:#e1f5ff
    style D fill:#fff4e1
    style A fill:#f0f0f0

// types/math-utils.d.ts
 
// 関数の宣言
declare function add(a: number, b: number): number;
declare function multiply(a: number, b: number): number;
declare function divide(a: number, b: number): number | null;
 
// 変数の宣言
declare const PI: number;
declare const E: number;
declare let debugMode: boolean;
 
// クラスの宣言
declare class Calculator {
  constructor(initial?: number);
  add(n: number): this;
  subtract(n: number): this;
  multiply(n: number): this;
  divide(n: number): this;
  result(): number;
  reset(): this;
}
 
// インターフェース（declare 不要）
interface MathOptions {
  precision: number;
  roundingMode: "ceil" | "floor" | "round" | "trunc";
  useRadians?: boolean;
}
 
// 型エイリアス（declare 不要）
type MathOperation = "add" | "subtract" | "multiply" | "divide";
 
// 列挙型の宣言
declare enum MathMode {
  Strict,
  Loose,
  Scientific
}
 
// 名前空間の宣言
declare namespace MathUtils {
  function randomInt(min: number, max: number): number;
  function clamp(value: number, min: number, max: number): number;
 
  namespace Advanced {
    function factorial(n: number): number;
    function fibonacci(n: number): number;
  }
}

// math-utils.ts （実装ファイル）
export const PI = 3.14159;
 
export function add(a: number, b: number): number {
  return a + b;  // 実装コードあり
}
 
export class Calculator {
  private value = 0;
 
  constructor(initial: number = 0) {
    this.value = initial;
  }
 
  add(n: number): this {
    this.value += n;
    return this;
  }
 
  result(): number {
    return this.value;
  }
}

// math-utils.d.ts （自動生成または手書き）
export declare const PI: number;
 
export declare function add(a: number, b: number): number;
// 実装コードなし、型シグネチャのみ
 
export declare class Calculator {
  constructor(initial?: number);
  add(n: number): this;
  result(): number;
  // private フィールドは公開APIでないので省略されることも
}

// declare なし → エラー: 実装が必要
function add(a: number, b: number): number;  // ❌ 実装がない
 
// declare あり → OK: 外部に存在することを宣言
declare function add(a: number, b: number): number;  // ✅ 型情報のみ

// types/api.d.ts
 
// 単純な関数
declare function fetchData(url: string): Promise<unknown>;
 
// オーバーロードも可能
declare function parse(data: string): object;
declare function parse(data: Buffer): object;
declare function parse(data: string | Buffer): object;
 
// ジェネリック関数
declare function request<T = unknown>(
  url: string,
  options?: RequestOptions
): Promise<T>;
 
// デフォルト引数（型レベルでは ? で表現）
declare function log(message: string, level?: "info" | "warn" | "error"): void;
 
// Rest パラメータ
declare function sum(...numbers: number[]): number;
 
// コールバック
declare function addEventListener(
  event: string,
  handler: (e: Event) => void
): void;

// types/globals.d.ts
 
// 定数（最も一般的）
declare const APP_VERSION: string;
declare const API_ENDPOINT: string;
declare const MAX_RETRY: number;
 
// let（変更可能な値）
declare let currentUser: User | null;
declare let debugEnabled: boolean;
 
// var（古い JavaScript コード向け）
declare var jQuery: JQueryStatic;
declare var $: JQueryStatic;
 
// オブジェクト
declare const config: {
  readonly apiKey: string;
  timeout: number;
  retries: number;
};

// 実行時に変更されない値 → const
declare const BUILD_TIME: string;
 
// 実行時に変更される可能性がある値 → let
declare let isLoggedIn: boolean;

// types/database.d.ts
 
declare class Database {
  // コンストラクタ
  constructor(config: DatabaseConfig);
 
  // メソッド（実装なし）
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
 
  // プロパティ
  readonly isConnected: boolean;
  timeout: number;
 
  // 静的メンバー
  static create(config: DatabaseConfig): Database;
  static readonly defaultTimeout: number;
}
 
// 継承関係も表現可能
declare class SQLDatabase extends Database {
  beginTransaction(): Promise<Transaction>;
  commit(): Promise<void>;
  rollback(): Promise<void>;
}
 
// 抽象クラス（実際は interface として使う方が一般的）
declare abstract class BaseRepository<T> {
  abstract findById(id: string): Promise<T | null>;
  abstract save(entity: T): Promise<void>;
  abstract delete(id: string): Promise<void>;
}

// types/custom-library.d.ts
 
// モジュール全体の型を宣言
declare module "custom-library" {
  // エクスポートされる型
  export interface Config {
    host: string;
    port: number;
    ssl?: boolean;
  }
 
  // エクスポートされる関数
  export function createClient(config: Config): Client;
  export function parseUrl(url: string): ParsedUrl;
 
  // エクスポートされるクラス
  export class Client {
    constructor(config: Config);
    connect(): Promise<void>;
    disconnect(): Promise<void>;
    send(data: string): Promise<Response>;
  }
 
  // 型エイリアス
  export type ConnectionStatus = "connected" | "disconnected" | "connecting";
 
  // デフォルトエクスポート
  export default createClient;
}
 
// 使用側
import customLib, { Client, Config } from "custom-library";
// ↑ 型情報が効く

// types/assets.d.ts
 
// 画像ファイル全般
declare module "*.png" {
  const src: string;
  export default src;
}
 
declare module "*.jpg" {
  const src: string;
  export default src;
}
 
declare module "*.svg" {
  const src: string;
  export default src;
}
 
// SVG を React コンポーネントとして扱う場合
declare module "*.svg?component" {
  import { FC, SVGProps } from "react";
  const Component: FC<SVGProps<SVGSVGElement>>;
  export default Component;
}
 
// CSS Modules
declare module "*.module.css" {
  const classes: { readonly [key: string]: string };
  export default classes;
}
 
declare module "*.module.scss" {
  const classes: { readonly [key: string]: string };
  export default classes;
}
 
// JSON ファイル
declare module "*.json" {
  const value: unknown;
  export default value;
}
 
// YAML ファイル
declare module "*.yaml" {
  const data: Record<string, unknown>;
  export default data;
}
 
// Web Workers
declare module "*.worker.ts" {
  class WebpackWorker extends Worker {
    constructor();
  }
  export default WebpackWorker;
}

// types/jquery.d.ts
 
declare namespace jQuery {
  // ネストした名前空間
  namespace fn {
    interface JQuery {
      customPlugin(options?: CustomPluginOptions): this;
    }
  }
 
  // インターフェース
  interface AjaxSettings {
    url?: string;
    method?: "GET" | "POST" | "PUT" | "DELETE";
    data?: unknown;
    success?: (data: unknown) => void;
  }
 
  // 関数
  function ajax(settings: AjaxSettings): void;
  function get(url: string): Promise<unknown>;
 
  // 定数
  const version: string;
}
 
// グローバル変数としても使える
declare const jQuery: typeof jQuery;

// 古いスタイル（namespace）
declare namespace MyLib {
  function doSomething(): void;
}
 
// 新しいスタイル（module）
declare module "my-lib" {
  export function doSomething(): void;
}

// types/global.d.ts
 
// グローバル変数を追加
declare global {
  // Window オブジェクトの拡張
  interface Window {
    __INITIAL_STATE__: {
      user: User | null;
      config: AppConfig;
    };
    gtag: (command: string, ...args: unknown[]) => void;
    dataLayer: unknown[];
  }
 
  // グローバル関数
  function gtag(command: "event", action: string, params?: object): void;
  function gtag(command: "config", targetId: string, params?: object): void;
 
  // グローバル型
  type JsonValue = string | number | boolean | null | JsonObject | JsonArray;
  interface JsonObject { [key: string]: JsonValue }
  interface JsonArray extends Array<JsonValue> {}
 
  // Array の拡張（プロトタイプメソッド追加を想定）
  interface Array<T> {
    last(): T | undefined;
    first(): T | undefined;
  }
 
  // String の拡張
  interface String {
    capitalize(): string;
    truncate(length: number): string;
  }
}
 
// モジュールとして認識させるためのダミーエクスポート
export {};

// types/enums.d.ts
 
// 通常の enum
declare enum LogLevel {
  Debug,
  Info,
  Warn,
  Error
}
 
// 文字列 enum
declare enum Status {
  Pending = "PENDING",
  InProgress = "IN_PROGRESS",
  Completed = "COMPLETED",
  Failed = "FAILED"
}
 
// const enum（コンパイル時にインライン化される）
declare const enum Direction {
  Up,
  Down,
  Left,
  Right
}

// このファイル全体が ambient context
// types/example.d.ts
 
declare const foo: string;  // OK: ambient context
 
const bar = "hello";  // これは OK だが、実装コードは .d.ts では無視される
 
export function baz(): void {
  // ❌ エラー: ambient context では実装を書けない
  console.log("test");
}
 
export declare function qux(): void;  // ✅ OK: 型宣言のみ

// types/external-libs.d.ts
 
// JavaScript ライブラリに型を付ける
declare module "legacy-lib" {
  export function doSomething(arg: string): number;
  export const version: string;
}
 
// CSS Modules
declare module "*.css" {
  const content: { [className: string]: string };
  export default content;
}
 
// JSON imports
declare module "*.json" {
  const value: unknown;
  export default value;
}
 
// バンドラー固有の機能（Vite の ?url import など）
declare module "*?url" {
  const url: string;
  export default url;
}
 
declare module "*?raw" {
  const content: string;
  export default content;
}
 
// Web Assembly
declare module "*.wasm" {
  const moduleFactory: () => Promise<WebAssembly.Instance>;
  export default moduleFactory;
}

// types/vendor.d.ts
 
// jQuery プラグインの型定義
declare module "jquery-validation" {
  interface JQuery {
    validate(options?: ValidationOptions): Validator;
  }
 
  interface ValidationOptions {
    rules?: Record<string, unknown>;
    messages?: Record<string, string>;
    submitHandler?: (form: HTMLFormElement) => void;
  }
 
  interface Validator {
    form(): boolean;
    element(element: HTMLElement): boolean;
    resetForm(): void;
  }
}
 
// Webpack の require.context
declare module "*.worker.js" {
  class WebpackWorker extends Worker {
    constructor();
  }
  export default WebpackWorker;
}
 
// Vite の import.meta.env
declare module "vite/client" {
  interface ImportMetaEnv {
    readonly VITE_APP_TITLE: string;
    readonly VITE_API_URL: string;
    readonly VITE_ENABLE_ANALYTICS: string;
  }
 
  interface ImportMeta {
    readonly env: ImportMetaEnv;
  }
}

// global-script.d.ts （スクリプト）
// export/import がない → スクリプトとして扱われる
 
interface User {
  id: string;
  name: string;
}
 
declare const currentUser: User;  // グローバルに追加される
 
// このファイルは全プロジェクトで User と currentUser が使える

// module-types.d.ts （モジュール）
// export がある → モジュールとして扱われる
 
export interface Product {
  id: string;
  name: string;
}
 
// グローバルに追加したい場合は declare global が必要
declare global {
  interface Window {
    products: Product[];
  }
}

flowchart TD
    A[TypeScript コード] --> B{import/require がある?}
    B -->|Yes| C[モジュール解決]
    B -->|No| D[グローバル解決]
 
    C --> E{パッケージ内に型定義?}
    E -->|Yes| F[package.json の types フィールド]
    E -->|No| G{@types パッケージ?}
    G -->|Yes| H[@types/xxx から読み込み]
    G -->|No| I[declare module で宣言]
 
    D --> J[.d.ts ファイルから検索]
    J --> K[tsconfig.json の include/files]
    K --> L[typeRoots からグローバル型を読み込み]
 
    F --> M[型チェック実行]
    H --> M
    I --> M
    L --> M
 
    style C fill:#e1f5ff
    style D fill:#ffe1e1
    style M fill:#e1ffe1

# 型定義のインストール
npm install --save-dev @types/node
npm install --save-dev @types/express
npm install --save-dev @types/lodash
npm install --save-dev @types/jest
npm install --save-dev @types/react
npm install --save-dev @types/react-dom
 
# 型定義の検索（TypeSearch CLI）
npx typesearch express
npx typesearch moment
npx typesearch socket.io
 
# 特定バージョンの型定義をインストール
npm install --save-dev @types/express@4.17.13

// @types/express がインストールされていれば型が効く
import express, { Request, Response, NextFunction } from "express";
 
const app = express();
 
// Request, Response の型が正確に推論される
app.get("/users/:id", (req: Request, res: Response) => {
  const id = req.params.id;  // 型: string
  const query = req.query;    // 型: qs.ParsedQs
  res.json({ id, query });
});
 
// Middleware の型も正確
app.use((req: Request, res: Response, next: NextFunction) => {
  console.log(`${req.method} ${req.path}`);
  next();
});
 
app.listen(3000);

{
  "compilerOptions": {
    // 型定義を探すルートディレクトリ
    "typeRoots": [
      "./types",              // プロジェクト独自の型定義
      "./node_modules/@types" // npm の @types パッケージ
    ],
 
    // 特定の @types のみ使用（指定しない場合は全て読み込む）
    "types": [
      "node",    // @types/node のみ
      "jest",    // @types/jest のみ
      "express"  // @types/express のみ
    ],
 
    // カスタムパスマッピング
    "paths": {
      "@/*": ["./src/*"],
      "@types/*": ["./types/*"],
      "~/*": ["./"]
    },
 
    // 暗黙的な any を禁止（型定義がない場合エラー）
    "noImplicitAny": true,
 
    // 型定義の自動生成
    "declaration": true,
    "declarationMap": true,
    "emitDeclarationOnly": false
  },
 
  "include": [
    "src/**/*",
    "types/**/*.d.ts"
  ],
 
  "exclude": [
    "node_modules",
    "dist"
  ]
}

# フォーク後にクローン
git clone https://github.com/YOUR_USERNAME/DefinitelyTyped.git
cd DefinitelyTyped
 
# ブランチを作成
git checkout -b add-types-for-my-library

# 新しいパッケージの型定義を追加
mkdir -p types/my-library
cd types/my-library

// types/my-library/index.d.ts
 
// Type definitions for my-library 1.2
// Project: https://github.com/author/my-library
// Definitions by: Your Name <https://github.com/your-username>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 
export interface Config {
  apiKey: string;
  endpoint?: string;
}
 
export function initialize(config: Config): void;
 
export class Client {
  constructor(config: Config);
  request<T>(path: string): Promise<T>;
}
 
export as namespace MyLibrary;  // UMD global も対応

// types/my-library/tsconfig.json
{
  "compilerOptions": {
    "module": "commonjs",
    "lib": ["es6"],
    "noImplicitAny": true,
    "noImplicitThis": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "baseUrl": "../",
    "typeRoots": ["../"],
    "types": [],
    "noEmit": true,
    "forceConsistentCasingInFileNames": true
  },
  "files": [
    "index.d.ts",
    "my-library-tests.ts"
  ]
}

// types/my-library/my-library-tests.ts
 
import { initialize, Client, Config } from "my-library";
 
// 型テスト: これがコンパイルエラーにならなければOK
const config: Config = {
  apiKey: "test"
};
 
initialize(config);
 
const client = new Client(config);
client.request<string>("/api/data");

# 型定義のテストを実行
npm test -- my-library

git add types/my-library
git commit -m "Add type definitions for my-library"
git push origin add-types-for-my-library
 
# GitHub で Pull Request を作成

// types/express-extension.d.ts
 
import "express";
 
// Express の既存インターフェースを拡張
declare module "express" {
  // Request インターフェースにカスタムプロパティを追加
  interface Request {
    userId?: string;
    role?: "admin" | "user" | "guest";
    startTime: number;
    correlationId: string;
  }
 
  // Response インターフェースも拡張可能
  interface Response {
    sendSuccess<T>(data: T): void;
    sendError(message: string, code?: number): void;
  }
}
 
// 実装側（別ファイル）
import { Request, Response, NextFunction } from "express";
 
// ミドルウェアで拡張したプロパティを設定
function authMiddleware(req: Request, res: Response, next: NextFunction) {
  req.userId = "user-123";     // ✅ OK: 拡張されている
  req.role = "admin";          // ✅ OK
  req.startTime = Date.now();  // ✅ OK
  req.correlationId = crypto.randomUUID();  // ✅ OK
  next();
}
 
// Response の拡張メソッドを実装
function setupResponseHelpers(req: Request, res: Response, next: NextFunction) {
  res.sendSuccess = function<T>(data: T) {
    this.json({ success: true, data });
  };
 
  res.sendError = function(message: string, code = 500) {
    this.status(code).json({ success: false, error: message });
  };
 
  next();
}
 
// 使用例
app.get("/api/data", (req, res) => {
  res.sendSuccess({ items: [] });  // ✅ 型安全
});

// types/global-extensions.d.ts
 
// Window オブジェクトの拡張
declare global {
  interface Window {
    __REDUX_DEVTOOLS_EXTENSION__?: {
      connect(): void;
    };
 
    gtag?: (
      command: "event" | "config" | "set",
      ...args: unknown[]
    ) => void;
 
    analytics?: {
      track(event: string, properties?: object): void;
      identify(userId: string, traits?: object): void;
      page(name?: string, properties?: object): void;
    };
 
    Stripe?: {
      (apiKey: string): StripeInstance;
    };
  }
 
  // Array の拡張（プロトタイプメソッド追加を想定）
  interface Array<T> {
    /**
     * 配列の最後の要素を取得
     */
    last(): T | undefined;
 
    /**
     * 配列の最初の要素を取得
     */
    first(): T | undefined;
 
    /**
     * ランダムな要素を取得
     */
    random(): T | undefined;
 
    /**
     * 重複を除去
     */
    unique(): T[];
  }
 
  // String の拡張
  interface String {
    /**
     * 最初の文字を大文字に
     */
    capitalize(): string;
 
    /**
     * 指定された長さで切り詰める
     */
    truncate(length: number, suffix?: string): string;
 
    /**
     * kebab-case に変換
     */
    toKebabCase(): string;
  }
 
  // Number の拡張
  interface Number {
    /**
     * 通貨形式にフォーマット
     */
    toCurrency(locale?: string): string;
 
    /**
     * パーセント形式にフォーマット
     */
    toPercent(decimals?: number): string;
  }
 
  // グローバル型エイリアスの追加
  type Nullable<T> = T | null;
  type Optional<T> = T | undefined;
  type Maybe<T> = T | null | undefined;
 
  type DeepPartial<T> = {
    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
  };
 
  type DeepReadonly<T> = {
    readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
  };
}
 
// モジュールとして認識させる
export {};

// types/env.d.ts
 
declare global {
  namespace NodeJS {
    interface ProcessEnv {
      // 必須の環境変数（undefined にならない）
      NODE_ENV: "development" | "production" | "test";
      PORT: string;
      DATABASE_URL: string;
      JWT_SECRET: string;
 
      // オプショナルな環境変数
      REDIS_URL?: string;
      SENTRY_DSN?: string;
      LOG_LEVEL?: "debug" | "info" | "warn" | "error";
 
      // 外部サービスのキー
      STRIPE_SECRET_KEY?: string;
      SENDGRID_API_KEY?: string;
      AWS_ACCESS_KEY_ID?: string;
      AWS_SECRET_ACCESS_KEY?: string;
    }
  }
}
 
export {};
 
// 使用側
const port = parseInt(process.env.PORT);      // 型: number（string を parse）
const redis = process.env.REDIS_URL;          // 型: string | undefined
const nodeEnv = process.env.NODE_ENV;         // 型: "development" | "production" | "test"
 
// 環境変数のバリデーション関数（型安全）
function validateEnv(): void {
  const required: (keyof NodeJS.ProcessEnv)[] = [
    "NODE_ENV",
    "PORT",
    "DATABASE_URL",
    "JWT_SECRET"
  ];
 
  for (const key of required) {
    if (!process.env[key]) {
      throw new Error(`Missing required environment variable: ${key}`);
    }
  }
}

// types/assets.d.ts
 
// 画像ファイル
declare module "*.png" {
  const src: string;
  export default src;
}
 
declare module "*.jpg" {
  const src: string;
  export default src;
}
 
declare module "*.jpeg" {
  const src: string;
  export default src;
}
 
declare module "*.gif" {
  const src: string;
  export default src;
}
 
declare module "*.webp" {
  const src: string;
  export default src;
}
 
declare module "*.svg" {
  const src: string;
  export default src;
}
 
// SVG を React コンポーネントとしてインポート（Vite, CRA など）
declare module "*.svg?component" {
  import { FC, SVGProps } from "react";
  const Component: FC<SVGProps<SVGSVGElement>>;
  export default Component;
}
 
// CSS / SCSS
declare module "*.css" {
  const classes: { readonly [key: string]: string };
  export default classes;
}
 
declare module "*.scss" {
  const classes: { readonly [key: string]: string };
  export default classes;
}
 
declare module "*.sass" {
  const classes: { readonly [key: string]: string };
  export default classes;
}
 
declare module "*.less" {
  const classes: { readonly [key: string]: string };
  export default classes;
}
 
// CSS Modules（明示的に .module.* を使う場合）
declare module "*.module.css" {
  const classes: { readonly [key: string]: string };
  export default classes;
}
 
declare module "*.module.scss" {
  const classes: { readonly [key: string]: string };
  export default classes;
}
 
// JSON
declare module "*.json" {
  const value: unknown;
  export default value;
}
 
// Text files
declare module "*.txt" {
  const content: string;
  export default content;
}
 
declare module "*.md" {
  const content: string;
  export default content;
}
 
// YAML
declare module "*.yaml" {
  const data: Record<string, unknown>;
  export default data;
}
 
declare module "*.yml" {
  const data: Record<string, unknown>;
  export default data;
}
 
// TOML
declare module "*.toml" {
  const data: Record<string, unknown>;
  export default data;
}
 
// Web Workers
declare module "*.worker.ts" {
  class WebpackWorker extends Worker {
    constructor();
  }
  export default WebpackWorker;
}
 
declare module "*.worker.js" {
  class WebpackWorker extends Worker {
    constructor();
  }
  export default WebpackWorker;
}
 
// WebAssembly
declare module "*.wasm" {
  const moduleFactory: () => Promise<WebAssembly.Module>;
  export default moduleFactory;
}
 
// Vite 固有の import suffixes
declare module "*?raw" {
  const content: string;
  export default content;
}
 
declare module "*?url" {
  const url: string;
  export default url;
}
 
declare module "*?inline" {
  const content: string;
  export default content;
}
 
// 使用例
import logo from "./logo.png";                    // 型: string
import styles from "./App.module.css";            // 型: { readonly [key: string]: string }
import IconComponent from "./icon.svg?component"; // 型: FC<SVGProps<SVGSVGElement>>
import data from "./config.json";                 // 型: unknown
import readme from "./README.md";                 // 型: string
import Worker from "./compute.worker.ts";         // 型: typeof WebpackWorker

// types/axios-extension.d.ts
 
import "axios";
 
declare module "axios" {
  export interface AxiosRequestConfig {
    // カスタムプロパティを追加
    skipAuthRefresh?: boolean;
    retryCount?: number;
    cacheKey?: string;
  }
}

// types/jest-extension.d.ts
 
import "@testing-library/jest-dom";
 
declare global {
  namespace jest {
    interface Matchers<R> {
      // カスタムマッチャーを追加
      toBeWithinRange(floor: number, ceiling: number): R;
      toHaveBeenCalledOnceWith(...args: unknown[]): R;
    }
  }
}
 
export {};

/// <reference path="..." />
/// <reference types="..." />
/// <reference lib="..." />
/// <reference no-default-lib="true" />

// types/global.d.ts
 
/// <reference path="./custom-types.d.ts" />
/// <reference path="./vendor-types.d.ts" />
 
declare const APP_VERSION: string;

// tsconfig.json
{
  "include": [
    "types/**/*.d.ts"  // これで全ての .d.ts を自動読み込み
  ]
}

// types/global.d.ts
 
/// <reference types="node" />
/// <reference types="jest" />
 
// これで Node.js と Jest の型が使える
declare const buffer: Buffer;  // Node.js の Buffer 型

// types/modern-features.d.ts
 
/// <reference lib="es2020" />
/// <reference lib="dom" />
/// <reference lib="webworker" />
 
// ES2020 の機能が使える
declare function useBigInt(value: bigint): void;
 
// DOM の型が使える
declare function useDocument(doc: Document): void;
 
// Web Worker の型が使える
declare function setupWorker(worker: Worker): void;

/// <reference no-default-lib="true" />
/// <reference lib="es2020" />
 
// これで ES2020 の型のみが使える（デフォルトの型は使えない）

// types/polyfills.d.ts
 
/// <reference lib="es2015.promise" />
/// <reference lib="es2015.iterable" />
 
// Promise と Iterable の機能を使ったカスタム型定義
declare function customAsyncIterator<T>(
  items: Iterable<T>
): AsyncIterableIterator<T>;

// types/vendor.d.ts
 
/// <reference types="jquery" />
/// <reference types="bootstrap" />
 
// jQuery プラグインの型定義
declare module "jquery-custom-plugin" {
  interface JQuery {
    customPlugin(options?: CustomPluginOptions): JQuery;
  }
 
  interface CustomPluginOptions {
    theme?: string;
    animation?: boolean;
  }
}

{
  "compilerOptions": {
    // /// <reference lib="..." /> の代わり
    "lib": ["es2020", "dom", "dom.iterable"],
 
    // /// <reference types="..." /> の代わり
    "types": ["node", "jest", "testing-library__jest-dom"],
 
    // /// <reference path="..." /> の代わり
    // include で管理
  },
 
  "include": [
    "src/**/*",
    "types/**/*.d.ts"
  ]
}

# 型定義を生成しながらコンパイル
tsc --declaration
 
# 型定義のみ生成（JavaScript は生成しない）
tsc --emitDeclarationOnly
 
# ソースマップも生成
tsc --declaration --declarationMap

// tsconfig.json
{
  "compilerOptions": {
    "declaration": true,           // .d.ts ファイルを生成
    "declarationMap": true,        // .d.ts.map を生成（デバッグ用）
    "emitDeclarationOnly": false,  // true にすると .js を生成しない
    "outDir": "./dist",
    "declarationDir": "./dist/types"  // 型定義の出力先を分ける場合
  }
}

// src/calculator.ts
 
/**
 * 計算機クラス
 */
export class Calculator {
  private value: number;
 
  /**
   * コンストラクタ
   * @param initial 初期値
   */
  constructor(initial: number = 0) {
    this.value = initial;
  }
 
  /**
   * 加算
   * @param n 加算する値
   * @returns this（メソッドチェーン用）
   */
  add(n: number): this {
    this.value += n;
    return this;
  }
 
  /**
   * 減算
   */
  subtract(n: number): this {
    this.value -= n;
    return this;
  }
 
  /**
   * 結果を取得
   */
  result(): number {
    return this.value;
  }
}
 
/**
 * 設定オプション
 */
export interface CalculatorOptions {
  /** 精度 */
  precision: number;
  /** デバッグモード */
  debug?: boolean;
}
 
/**
 * ファクトリ関数
 */
export function createCalculator(options?: CalculatorOptions): Calculator {
  const calc = new Calculator();
  if (options?.debug) {
    console.log("Calculator created with options:", options);
  }
  return calc;
}

// dist/calculator.d.ts
 
/**
 * 計算機クラス
 */
export declare class Calculator {
  private value;
  /**
   * コンストラクタ
   * @param initial 初期値
   */
  constructor(initial?: number);
  /**
   * 加算
   * @param n 加算する値
   * @returns this（メソッドチェーン用）
   */
  add(n: number): this;
  /**
   * 減算
   */
  subtract(n: number): this;
  /**
   * 結果を取得
   */
  result(): number;
}
 
/**
 * 設定オプション
 */
export interface CalculatorOptions {
  /** 精度 */
  precision: number;
  /** デバッグモード */
  debug?: boolean;
}
 
/**
 * ファクトリ関数
 */
export declare function createCalculator(options?: CalculatorOptions): Calculator;

npm install --save-dev dts-bundle-generator

# 単一の .d.ts ファイルを生成
npx dts-bundle-generator -o dist/index.d.ts src/index.ts
 
# 設定ファイルを使う
npx dts-bundle-generator --config dts-bundle.config.js

// dts-bundle.config.js
module.exports = {
  entries: [
    {
      filePath: "./src/index.ts",
      outFile: "./dist/index.d.ts",
      libraries: {
        // 外部ライブラリをインライン化するか
        inlinedLibraries: ["lib-a"]
      },
      output: {
        // 型の並び替え
        sortNodes: true,
        // export = の形式を使う（CommonJS 用）
        exportReferencedTypes: true
      }
    }
  ]
};

npm install --save-dev @microsoft/api-extractor

// api-extractor.json
{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 
  "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
 
  "bundledPackages": [],
 
  "compiler": {
    "tsconfigFilePath": "<projectFolder>/tsconfig.json"
  },
 
  "dtsRollup": {
    "enabled": true,
    "untrimmedFilePath": "<projectFolder>/dist/index.d.ts",
    "publicTrimmedFilePath": "<projectFolder>/dist/index.d.ts"
  },
 
  "apiReport": {
    "enabled": true,
    "reportFolder": "<projectFolder>/etc/"
  },
 
  "docModel": {
    "enabled": true,
    "apiJsonFilePath": "<projectFolder>/etc/api.json"
  }
}

# API レポートを生成
npx api-extractor run --local

// src/public-api.ts
 
/**
 * 公開 API のエントリポイント
 * これを index.ts から re-export する
 */
 
// 公開する型・関数のみエクスポート
export { Calculator, CalculatorOptions } from "./calculator";
export { formatNumber } from "./utils/format";
export type { FormatOptions } from "./utils/format";
 
// 内部型は export しない
// import { InternalHelper } from "./internal";  // これは export しない

// src/index.ts
 
// 全ての公開 API を re-export
export * from "./public-api";
 
// デフォルトエクスポートも必要なら
export { default } from "./main";

{
  "name": "my-library",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./utils": {
      "import": "./dist/utils.mjs",
      "require": "./dist/utils.js",
      "types": "./dist/utils.d.ts"
    }
  },
  "files": [
    "dist/**/*.js",
    "dist/**/*.mjs",
    "dist/**/*.d.ts",
    "dist/**/*.d.ts.map"
  ],
  "scripts": {
    "build": "tsc && tsc -p tsconfig.esm.json",
    "build:types": "tsc --emitDeclarationOnly",
    "prepublishOnly": "npm run build"
  }
}

// package.json
{
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"]
}

// package.json
{
  "main": "./src/index.js",
  "types": "./src/index.d.ts"
}

// ❌ BAD: any を使う
export function processData(data: any): any;
 
// ✅ GOOD: 具体的な型を書く
export function processData<T>(data: T[]): ProcessedData<T>;
 
// ❌ BAD: オーバーロードが多すぎて混乱
export function request(url: string): Promise<unknown>;
export function request(url: string, options: RequestOptions): Promise<unknown>;
export function request(url: string, method: string): Promise<unknown>;
export function request(url: string, method: string, body: unknown): Promise<unknown>;
// ... （10個以上続く）
 
// ✅ GOOD: オプションオブジェクトでまとめる
export interface RequestOptions {
  method?: string;
  body?: unknown;
  headers?: Record<string, string>;
}
export function request(url: string, options?: RequestOptions): Promise<unknown>;
 
// ❌ BAD: 内部実装の詳細を露出
export class DatabaseConnection {
  private _socket: Socket;
  private _buffer: Buffer;
  private _internalState: ComplexInternalState;
  // 外部から見る必要のない詳細
}
 
// ✅ GOOD: 公開 API のみ型定義に含める
export declare class DatabaseConnection {
  connect(): Promise<void>;
  query<T>(sql: string): Promise<T[]>;
  close(): Promise<void>;
  // 内部実装は隠す
}

/**
 * ユーザーを作成します
 *
 * @param name - ユーザー名
 * @param email - メールアドレス
 * @returns 作成されたユーザー
 * @throws {ValidationError} バリデーションエラーが発生した場合
 * @example
 * ```ts
 * const user = await createUser("Alice", "alice@example.com");
 * console.log(user.id);
 * ```
 */
export declare function createUser(
  name: string,
  email: string
): Promise<User>;
 
/**
 * ユーザー情報
 * @public
 */
export interface User {
  /** ユーザーID */
  readonly id: string;
 
  /** ユーザー名 */
  name: string;
 
  /** メールアドレス */
  email: string;
 
  /**
   * 作成日時
   * @remarks ISO 8601 形式の文字列
   */
  createdAt: string;
}

// v1.0.0
export interface Config {
  host: string;
  port: number;
}
 
// v1.1.0 - 後方互換性を保ちながら拡張
export interface Config {
  host: string;
  port: number;
  timeout?: number;  // オプショナルなので既存コードは動く
}
 
// v2.0.0 - Breaking change
export interface Config {
  host: string;
  port: number;
  timeout: number;  // 必須に変更（breaking）
  ssl: boolean;     // 新しい必須フィールド（breaking）
}

/**
 * @deprecated Use `newFunction` instead. This will be removed in v3.0.0.
 */
export declare function oldFunction(data: string): void;
 
/**
 * 新しい推奨関数
 */
export declare function newFunction(data: string, options?: NewOptions): void;

// package.json - Node.js の ESM/CJS 両対応
{
  "name": "my-library",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.cjs",      // CommonJS
  "module": "./dist/index.mjs",    // ESM
  "types": "./dist/index.d.ts",    // 型定義
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.mts",
        "default": "./dist/index.mjs"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    },
    "./utils": {
      "import": "./dist/utils.mjs",
      "require": "./dist/utils.cjs",
      "types": "./dist/utils.d.ts"
    }
  }
}

// dist/index.d.ts (共通の型定義)
export declare class MyClass { /* ... */ }
export declare function myFunction(): void;
 
// dist/index.d.mts (ESM 用、必要な場合)
export { MyClass, myFunction } from "./index.js";
 
// dist/index.d.cts (CJS 用、必要な場合)
export = MyLibrary;
declare namespace MyLibrary {
  class MyClass { /* ... */ }
  function myFunction(): void;
}

import express from "express";  // ❌ エラー

# @types パッケージをインストール
npm install --save-dev @types/express
 
# または自前の型定義を作成
# types/express.d.ts
declare module "express" {
  const express: any;
  export default express;
}

// ❌ BAD: types を指定すると、それ以外の @types が読み込まれない
{
  "compilerOptions": {
    "types": ["node"]  // @types/jest などが読み込まれなくなる
  }
}
 
// ✅ GOOD: types を指定しない（全ての @types を読み込む）
{
  "compilerOptions": {
    // types フィールドを削除
  }
}

{
  "compilerOptions": {
    "typeRoots": [
      "./types",              // 自前の型定義を優先
      "./node_modules/@types"
    ]
  }
}

import { Request as ExpressRequest } from "express";
import { IncomingMessage as NodeRequest } from "http";
 
// 明示的に使い分ける
function handleExpress(req: ExpressRequest) { /* ... */ }
function handleNode(req: NodeRequest) { /* ... */ }

// types/unified.d.ts
import "express";
 
declare module "express" {
  // Express の Request を拡張して統一
  interface Request extends NodeJS.IncomingMessage {
    // 追加プロパティ
  }
}

// types/global.d.ts
declare global {
  interface Window {
    myGlobal: string;
  }
}
 
// ❌ エラー: Property 'myGlobal' does not exist on type 'Window'
window.myGlobal = "test";

// types/global.d.ts
declare global {
  interface Window {
    myGlobal: string;
  }
}
 
export {};  // ✅ これでモジュールになる

// tsconfig.json
{
  "include": [
    "src/**/*",
    "types/**/*.d.ts"  // ✅ これがあるか確認
  ],
 
  "exclude": [
    "node_modules",
    "dist"
  ]
}

# TypeScript がどのファイルを読み込んでいるか確認
npx tsc --listFiles | grep ".d.ts"
 
# トレースログでデバッグ
npx tsc --traceResolution | grep "my-module"

{
  "compilerOptions": {
    "types": ["node", "jest"]  // 必要な型だけ指定
  }
}

{
  "compilerOptions": {
    "skipLibCheck": true  // .d.ts のチェックをスキップ（高速化）
  }
}

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./.tsbuildinfo"
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@types/*": ["types/*"]
    }
  }
}

import { User } from "@/models/user";  // ❌ エラー

{
  "compilerOptions": {
    "moduleResolution": "node",  // または "bundler" (TS 5.0+)
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

// math-lib.js (実装コード)
 
function add(a, b) {
  return a + b;
}
 
function multiply(a, b) {
  return a * b;
}
 
class Calculator {
  constructor(initial = 0) {
    this.value = initial;
  }
 
  add(n) {
    this.value += n;
    return this;
  }
 
  result() {
    return this.value;
  }
}
 
module.exports = { add, multiply, Calculator };