{
  "name": "@example/sdk",
  "version": "1.0.0",
  "description": "Official SDK for Example API - Type-safe, zero-dependency client",
  "license": "MIT",
  "author": {
    "name": "Example Team",
    "email": "sdk@example.com",
    "url": "https://example.com"
  },
  "contributors": [
    { "name": "Alice", "email": "alice@example.com" }
  ],
 
  "type": "module",
 
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    },
    "./users": {
      "import": {
        "types": "./dist/users/index.d.ts",
        "default": "./dist/users/index.js"
      },
      "require": {
        "types": "./dist/users/index.d.cts",
        "default": "./dist/users/index.cjs"
      }
    },
    "./billing": {
      "import": {
        "types": "./dist/billing/index.d.ts",
        "default": "./dist/billing/index.js"
      },
      "require": {
        "types": "./dist/billing/index.d.cts",
        "default": "./dist/billing/index.cjs"
      }
    },
    "./package.json": "./package.json"
  },
 
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
 
  "typesVersions": {
    "*": {
      "users": ["./dist/users/index.d.ts"],
      "billing": ["./dist/billing/index.d.ts"]
    }
  },
 
  "files": ["dist", "README.md", "LICENSE", "CHANGELOG.md"],
 
  "engines": { "node": ">=18.0.0" },
  "os": ["!win32"],
  "cpu": ["x64", "arm64"],
 
  "sideEffects": false,
 
  "keywords": ["api", "sdk", "example", "typescript", "rest-client"],
  "repository": {
    "type": "git",
    "url": "https://github.com/example/sdk",
    "directory": "packages/sdk"
  },
  "homepage": "https://example.com/docs/sdk",
  "bugs": {
    "url": "https://github.com/example/sdk/issues",
    "email": "bugs@example.com"
  },
  "funding": {
    "type": "github",
    "url": "https://github.com/sponsors/example"
  },
 
  "scripts": {
    "build": "tsup",
    "build:watch": "tsup --watch",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage",
    "lint": "eslint src/",
    "lint:fix": "eslint src/ --fix",
    "typecheck": "tsc --noEmit",
    "format": "prettier --write 'src/**/*.ts'",
    "format:check": "prettier --check 'src/**/*.ts'",
    "prepublishOnly": "npm run build && npm run test && npm run typecheck",
    "release": "changeset publish",
    "size": "size-limit",
    "clean": "rm -rf dist",
    "prepack": "clean-pkg-json"
  },
 
  "devDependencies": {
    "tsup": "^8.0.0",
    "typescript": "^5.4.0",
    "vitest": "^2.0.0",
    "@changesets/cli": "^2.27.0",
    "eslint": "^9.0.0",
    "prettier": "^3.2.0",
    "@size-limit/preset-small-lib": "^11.0.0",
    "size-limit": "^11.0.0",
    "clean-pkg-json": "^1.2.0"
  },
 
  "peerDependencies": {},
  "peerDependenciesMeta": {},
  "dependencies": {},
  "overrides": {},
  "publishConfig": {
    "access": "public",
    "registry": "https://registry.npmjs.org"
  },
  "size-limit": [
    {
      "path": "dist/index.js",
      "limit": "10 KB"
    }
  ]
}

{
  "exports": {
    ".": "./dist/index.js",
 
    "./utils": "./dist/utils/index.js",
    "./utils/*": "./dist/utils/*.js",
 
    "./internal/*": null,
 
    "./package.json": "./package.json"
  }
}

// tsup.config.ts - 基本設定
import { defineConfig } from 'tsup';
 
export default defineConfig({
  // エントリポイント
  entry: [
    'src/index.ts',
    'src/users/index.ts',
    'src/billing/index.ts',
  ],
 
  // 出力フォーマット
  format: ['esm', 'cjs'],
 
  // 型定義ファイルの生成
  dts: true,
 
  // コード分割（ESMのみ有効）
  splitting: true,
 
  // ソースマップ
  sourcemap: true,
 
  // ビルド前にdistをクリーンアップ
  clean: true,
 
  // minify設定（SDKはminifyしない）
  minify: false,
 
  // ターゲット環境
  target: 'es2022',
 
  // 出力ディレクトリ
  outDir: 'dist',
 
  // 外部依存（バンドルしない）
  external: [],
 
  // バナー（ライセンスヘッダー等）
  banner: {
    js: '/* @example/sdk - MIT License */',
  },
 
  // shims（import.meta.url等のCJS互換）
  shims: true,
 
  // 環境変数の定義
  define: {
    'process.env.SDK_VERSION': JSON.stringify('1.0.0'),
  },
 
  // ビルド後のフック
  onSuccess: 'echo "Build completed successfully"',
});

// tsup.config.ts - 高度な設定（環境別ビルド）
import { defineConfig } from 'tsup';
 
export default defineConfig([
  // Node.js向けビルド
  {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    dts: true,
    platform: 'node',
    target: 'node18',
    outDir: 'dist',
    clean: true,
    splitting: true,
    sourcemap: true,
    external: ['ws'],
  },
  // ブラウザ向けビルド
  {
    entry: ['src/index.browser.ts'],
    format: ['esm'],
    dts: true,
    platform: 'browser',
    target: 'es2022',
    outDir: 'dist/browser',
    globalName: 'ExampleSDK',
    minify: true,
    sourcemap: true,
    noExternal: [/.*/],  // 全依存をバンドル
  },
]);

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2022"],
 
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
 
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
 
    "outDir": "dist",
    "rootDir": "src",
 
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "resolveJsonModule": true,
 
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
}

// src/types.ts - 丁寧な型定義の例
 
/**
 * SDK クライアントの設定オプション。
 *
 * @example
 * ```typescript
 * const client = new ExampleClient({
 *   apiKey: 'sk-xxx',
 *   baseURL: 'https://api.example.com',
 *   timeout: 30_000,
 * });
 * ```
 */
export interface ClientOptions {
  /**
   * APIキー。環境変数 `EXAMPLE_API_KEY` からも読み取り可能。
   * @see https://example.com/docs/authentication
   */
  apiKey: string;
 
  /**
   * APIのベースURL。デフォルトは `https://api.example.com/v1`。
   * @default "https://api.example.com/v1"
   */
  baseURL?: string;
 
  /**
   * リクエストのタイムアウト（ミリ秒）。
   * @default 30000
   */
  timeout?: number;
 
  /**
   * リトライの最大回数。0 でリトライ無効。
   * @default 3
   */
  maxRetries?: number;
 
  /**
   * カスタムfetch関数。テスト時のモック注入等に使用。
   */
  fetch?: typeof globalThis.fetch;
 
  /**
   * カスタムヘッダー。全リクエストに付与される。
   */
  defaultHeaders?: Record<string, string>;
}
 
/**
 * ページネーションされたレスポンスの共通型。
 * @typeParam T - リスト内の要素の型
 */
export interface PaginatedResponse<T> {
  /** データの配列 */
  data: T[];
  /** 次のページが存在するか */
  hasMore: boolean;
  /** 次ページ取得用のカーソル */
  cursor?: string;
  /** 結果の総数（取得可能な場合） */
  totalCount?: number;
}
 
/**
 * APIエラーレスポンスの型。
 */
export interface APIError {
  /** エラーコード（例: "NOT_FOUND", "RATE_LIMITED"） */
  code: string;
  /** 人間が読めるエラーメッセージ */
  message: string;
  /** エラーの詳細情報 */
  details?: Record<string, unknown>;
  /** リクエストID（サポート問い合わせ時に使用） */
  requestId?: string;
}

// ゼロ依存で実現するユーティリティ集
 
// --- UUID生成（uuid パッケージ不要） ---
function generateId(): string {
  return crypto.randomUUID();
}
 
// --- ディープクローン（lodash.cloneDeep 不要） ---
function deepClone<T>(obj: T): T {
  return structuredClone(obj);
}
 
// --- クエリ文字列（qs パッケージ不要） ---
function buildQueryString(params: Record<string, string>): string {
  return new URLSearchParams(params).toString();
}
 
// --- Base64エンコード（buffer パッケージ不要） ---
function toBase64(str: string): string {
  return btoa(str);
}
 
// --- SHA-256ハッシュ（crypto-js パッケージ不要） ---
async function sha256(message: string): Promise<string> {
  const encoder = new TextEncoder();
  const data = encoder.encode(message);
  const hash = await crypto.subtle.digest('SHA-256', data);
  return Array.from(new Uint8Array(hash))
    .map(b => b.toString(16).padStart(2, '0'))
    .join('');
}
 
// --- リトライ（p-retry パッケージ不要） ---
async function withRetry<T>(
  fn: () => Promise<T>,
  options: { maxRetries: number; baseDelay: number } = {
    maxRetries: 3,
    baseDelay: 1000,
  },
): Promise<T> {
  let lastError: Error | undefined;
  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error as Error;
      if (attempt < options.maxRetries) {
        const delay = options.baseDelay * Math.pow(2, attempt);
        const jitter = delay * 0.1 * Math.random();
        await new Promise(r => setTimeout(r, delay + jitter));
      }
    }
  }
  throw lastError;
}
 
// --- タイムアウト付きfetch（node-fetch 不要、Node.js 18+） ---
async function fetchWithTimeout(
  url: string,
  options: RequestInit & { timeout?: number } = {},
): Promise<Response> {
  const { timeout = 30_000, ...fetchOptions } = options;
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), timeout);
 
  try {
    return await fetch(url, {
      ...fetchOptions,
      signal: controller.signal,
    });
  } finally {
    clearTimeout(timeoutId);
  }
}

# Changesets の初期設定
npx changeset init
# → .changeset/ ディレクトリが作成される
 
# 変更を記録（PRごとに実行）
npx changeset
# インタラクティブに:
#   1. 変更があるパッケージを選択
#   2. 変更の種類を選択（major / minor / patch）
#   3. 変更の説明を記入
 
# バージョンアップ + CHANGELOG 更新
npx changeset version
# → package.json の version が更新される
# → CHANGELOG.md が自動生成される
 
# npm に公開
npx changeset publish
# → npm publish が実行される
# → git tag が作成される

// vitest.config.ts
import { defineConfig } from 'vitest/config';
 
export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    include: ['src/**/*.test.ts', 'src/**/*.spec.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'lcov', 'html'],
      include: ['src/**/*.ts'],
      exclude: [
        'src/**/*.test.ts',
        'src/**/*.spec.ts',
        'src/**/types.ts',
        'src/**/index.ts',  // re-exports のみのファイル
      ],
      thresholds: {
        branches: 80,
        functions: 80,
        lines: 80,
        statements: 80,
      },
    },
    testTimeout: 10_000,
    hookTimeout: 10_000,
  },
});

// src/__tests__/client.test.ts
import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest';
import { http, HttpResponse } from 'msw';
import { setupServer } from 'msw/node';
import { ExampleClient } from '../index';
 
// MSWサーバーのセットアップ
const server = setupServer();
 
beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
 
describe('ExampleClient', () => {
  const client = new ExampleClient({
    apiKey: 'test-key-xxx',
    baseURL: 'https://api.example.com/v1',
  });
 
  describe('users.get()', () => {
    it('IDを指定してユーザーを取得できる', async () => {
      server.use(
        http.get('https://api.example.com/v1/users/123', ({ request }) => {
          // 認証ヘッダーの検証
          expect(request.headers.get('Authorization')).toBe(
            'Bearer test-key-xxx',
          );
          return HttpResponse.json({
            id: '123',
            name: 'Tanaka Taro',
            email: 'taro@example.com',
            role: 'admin',
            createdAt: '2024-01-01T00:00:00Z',
          });
        }),
      );
 
      const user = await client.users.get('123');
 
      expect(user.id).toBe('123');
      expect(user.name).toBe('Tanaka Taro');
      expect(user.role).toBe('admin');
    });
 
    it('存在しないユーザーで404エラーが返る', async () => {
      server.use(
        http.get('https://api.example.com/v1/users/999', () => {
          return HttpResponse.json(
            {
              code: 'NOT_FOUND',
              message: 'User not found',
              requestId: 'req-abc-123',
            },
            { status: 404 },
          );
        }),
      );
 
      await expect(client.users.get('999')).rejects.toMatchObject({
        code: 'NOT_FOUND',
        status: 404,
      });
    });
 
    it('500エラー時にリトライが行われる', async () => {
      let attempts = 0;
      server.use(
        http.get('https://api.example.com/v1/users/123', () => {
          attempts++;
          if (attempts < 3) {
            return HttpResponse.json(
              { code: 'INTERNAL_ERROR', message: 'Server error' },
              { status: 500 },
            );
          }
          return HttpResponse.json({
            id: '123',
            name: 'Tanaka Taro',
          });
        }),
      );
 
      const user = await client.users.get('123');
      expect(user.name).toBe('Tanaka Taro');
      expect(attempts).toBe(3);
    });
 
    it('タイムアウト時に適切なエラーが返る', async () => {
      server.use(
        http.get('https://api.example.com/v1/users/123', async () => {
          // 意図的に遅延を入れる
          await new Promise(resolve => setTimeout(resolve, 15_000));
          return HttpResponse.json({ id: '123' });
        }),
      );
 
      const timeoutClient = new ExampleClient({
        apiKey: 'test-key',
        timeout: 1000,
        maxRetries: 0,
      });
 
      await expect(timeoutClient.users.get('123')).rejects.toThrow(
        'Request timed out',
      );
    });
  });
 
  describe('users.list()', () => {
    it('ページネーション付きでユーザー一覧を取得できる', async () => {
      server.use(
        http.get('https://api.example.com/v1/users', ({ request }) => {
          const url = new URL(request.url);
          const limit = url.searchParams.get('limit') ?? '20';
          const cursor = url.searchParams.get('cursor');
 
          return HttpResponse.json({
            data: [
              { id: '1', name: 'User 1' },
              { id: '2', name: 'User 2' },
            ],
            hasMore: cursor === null,
            cursor: cursor === null ? 'cursor-abc' : undefined,
          });
        }),
      );
 
      const page1 = await client.users.list({ limit: 2 });
      expect(page1.data).toHaveLength(2);
      expect(page1.hasMore).toBe(true);
 
      const page2 = await client.users.list({
        limit: 2,
        cursor: page1.cursor,
      });
      expect(page2.hasMore).toBe(false);
    });
  });
});

# 含まれるファイルの確認
npm pack --dry-run
 
# 出力例:
# npm notice Tarball Contents
# npm notice 1.2kB  package.json
# npm notice 4.5kB  README.md
# npm notice 1.1kB  LICENSE
# npm notice 12.3kB dist/index.js
# npm notice 11.8kB dist/index.cjs
# npm notice 8.4kB  dist/index.d.ts
# npm notice 8.2kB  dist/index.d.cts
# npm notice === Tarball Details ===
# npm notice name:          @example/sdk
# npm notice version:       1.0.0
# npm notice filename:      example-sdk-1.0.0.tgz
# npm notice package size:  15.2 kB
# npm notice unpacked size: 47.5 kB
# npm notice total files:   8
 
# 実際にtarballを作成して検証
npm pack
tar -xzf example-sdk-1.0.0.tgz
ls package/
# → dist/  LICENSE  package.json  README.md

# .github/workflows/release.yml
name: Release
 
on:
  push:
    branches: [main]
 
concurrency: ${{ github.workflow }}-${{ github.ref }}
 
jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      id-token: write  # npm provenance
 
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
          registry-url: 'https://registry.npmjs.org'
 
      - name: Install dependencies
        run: npm ci
 
      - name: Build
        run: npm run build
 
      - name: Test
        run: npm test
 
      - name: Type check
        run: npm run typecheck
 
      - name: Create Release PR or Publish
        id: changesets
        uses: changesets/action@v1
        with:
          publish: npx changeset publish
          version: npx changeset version
          commit: 'chore: release packages'
          title: 'chore: release packages'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

# pnpm-workspace.yaml
packages:
  - 'packages/*'
  - 'apps/*'
  - 'tooling/*'

// ルート package.json
{
  "name": "my-sdk-monorepo",
  "private": true,
  "scripts": {
    "build": "turbo build",
    "test": "turbo test",
    "lint": "turbo lint",
    "typecheck": "turbo typecheck",
    "dev": "turbo dev",
    "clean": "turbo clean",
    "format": "prettier --write '**/*.{ts,tsx,json,md}'"
  },
  "devDependencies": {
    "turbo": "^2.0.0",
    "prettier": "^3.2.0",
    "@changesets/cli": "^2.27.0"
  },
  "packageManager": "pnpm@9.0.0"
}

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "tsup.config.ts", "tsconfig.json"],
      "outputs": ["dist/**"],
      "cache": true
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["src/**", "vitest.config.ts"],
      "outputs": [],
      "cache": true
    },
    "lint": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "eslint.config.js"],
      "outputs": [],
      "cache": true
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "tsconfig.json"],
      "outputs": [],
      "cache": true
    },
    "dev": {
      "dependsOn": ["^build"],
      "cache": false,
      "persistent": true
    },
    "clean": {
      "cache": false
    }
  }
}

// packages/react/package.json
{
  "name": "@my-sdk/react",
  "version": "1.0.0",
  "dependencies": {
    "@my-sdk/core": "workspace:*"
  },
  "peerDependencies": {
    "react": "^18.0.0 || ^19.0.0",
    "react-dom": "^18.0.0 || ^19.0.0"
  },
  "peerDependenciesMeta": {
    "react-dom": {
      "optional": true
    }
  }
}

// tooling/tsconfig/base.json - 共有TypeScript設定
{
  "$schema": "https://json.schemastore.org/tsconfig",
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2022"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "resolveJsonModule": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true
  },
  "exclude": ["node_modules", "dist"]
}

// packages/core/tsconfig.json - 各パッケージのTypeScript設定
{
  "extends": "../../tooling/tsconfig/base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

// package.json に追加
{
  "size-limit": [
    {
      "path": "dist/index.js",
      "import": "{ ExampleClient }",
      "limit": "10 KB"
    },
    {
      "path": "dist/users/index.js",
      "import": "{ UsersResource }",
      "limit": "3 KB"
    },
    {
      "path": "dist/index.js",
      "import": "*",
      "limit": "15 KB"
    }
  ]
}

# .github/workflows/size.yml - PRごとにサイズを測定
name: Size Check
 
on: [pull_request]
 
jobs:
  size:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - uses: andresz1/size-limit-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          # PRコメントにサイズ変更を表示

// 悪い例: バレルファイルで全てを再エクスポート
// src/index.ts
export * from './users';
export * from './billing';
export * from './analytics';
export * from './utils';
// → import { Users } from '@example/sdk' で
//   billing, analytics, utils もバンドルされる可能性
 
// 良い例: サブパスエクスポートで分割
// package.json の exports で個別にエントリポイントを定義
// → import { Users } from '@example/sdk/users'
//   users モジュールのみがバンドルされる
 
// Tree-shaking を妨げるパターン:
// 1. クラスの static プロパティへの副作用のある代入
class Client {
  // 悪い: 副作用がある
  static instances = new Map();  // モジュール読み込み時に実行される
}
 
// 2. トップレベルの副作用
console.log('SDK loaded');  // 副作用あり → Tree-shake不可
const config = loadConfig(); // 関数呼び出し → 副作用の可能性
 
// 3. enumの使用
enum Status { Active, Inactive }
// → コンパイル後に即時実行関数(IIFE)になる → Tree-shake不可
 
// 良い代替: const object + as const
const Status = {
  Active: 'active',
  Inactive: 'inactive',
} as const;
type Status = typeof Status[keyof typeof Status];
// → 純粋なオブジェクトリテラル → Tree-shake可能

# provenance付きで公開
npm publish --provenance
 
# GitHub Actionsで自動化する場合:
# permissions に id-token: write が必要
# registry-url の設定が必要

# .github/workflows/quality.yml
name: Quality
 
on: [push, pull_request]
 
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
 
      # テストカバレッジ
      - run: npm run test:coverage
      - uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
 
      # バンドルサイズ
      - run: npx size-limit
 
      # 型チェック
      - run: npm run typecheck
 
      # lint
      - run: npm run lint
 
      # セキュリティ監査
      - run: npm audit --production
 
      # ライセンスチェック
      - run: npx license-checker --onlyAllow 'MIT;Apache-2.0;BSD-2-Clause;BSD-3-Clause;ISC'

// [アンチパターン] 巨大なバレルファイル
// src/index.ts
export * from './users';
export * from './billing';
export * from './analytics';
export * from './notifications';
export * from './webhooks';
export * from './admin';
export * from './utils';
export * from './errors';
export * from './types';
export * from './constants';
// → 全モジュールが1つのエントリポイントに集約
// → Tree-shakingが効きにくくなる
// → 利用者のバンドルサイズが肥大化
// → 循環参照のリスクが増大
// → IDE の自動補完が遅くなる
 
// [対策] サブパスエクスポートで分割
// package.json
// {
//   "exports": {
//     ".":           "./dist/index.js",      ← コアのみ
//     "./users":     "./dist/users/index.js",
//     "./billing":   "./dist/billing/index.js",
//     "./analytics": "./dist/analytics/index.js"
//   }
// }
 
// src/index.ts - コアのみエクスポート
export { ExampleClient } from './client';
export type { ClientOptions, APIError } from './types';
 
// 利用者側:
// import { ExampleClient } from '@example/sdk';
// import { UsersResource } from '@example/sdk/users';
// → 必要なモジュールのみがバンドルされる

// エッジケース: CJSからESMモジュールをrequireする
 
// ESMのみを提供するパッケージをCJSプロジェクトから使う場合
// → require() は使えない（ERR_REQUIRE_ESM エラー）
 
// Node.js 22 以降:
// require(esm) がサポートされつつあるが、
// トップレベル await を含むモジュールは依然として require 不可
 
// 対処法1: 動的 import() を使う（CJSでも利用可能）
// cjs-consumer.cjs
async function main() {
  // 動的 import() は CJS でも使える
  const { ExampleClient } = await import('@example/sdk');
  const client = new ExampleClient({ apiKey: 'xxx' });
}
main();
 
// 対処法2: パッケージ側でCJSビルドを提供する（推奨）
// → tsup で format: ['esm', 'cjs'] を設定
 
// 対処法3: ラッパーファイルを提供
// dist/index.cjs
// const mod = await import('./index.js');
// module.exports = mod;
// → ただしトップレベル await が必要なので Node.js 14+ のみ
 
// 注意: default export の扱いが異なる
// ESM: export default class Client {}
// CJS: const { default: Client } = require('@example/sdk');
//      ← ".default" が必要になる場合がある
// → named export を推奨（default export を避ける）

// 演習1: package.json
{
  "name": "@yourname/utils",
  "version": "0.1.0",
  "description": "A collection of utility functions",
  "license": "MIT",
  "type": "module",
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    }
  },
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "tsup",
    "test": "vitest run",
    "prepublishOnly": "npm run build && npm run test"
  }
}

// 演習1: src/index.ts
/**
 * 文字列の先頭を大文字にする。
 * @param str - 変換する文字列
 * @returns 先頭が大文字の文字列
 */
export function capitalize(str: string): string {
  if (str.length === 0) return str;
  return str.charAt(0).toUpperCase() + str.slice(1);
}
 
/**
 * 配列をチャンクに分割する。
 * @param array - 分割する配列
 * @param size - チャンクサイズ
 * @returns チャンクの配列
 */
export function chunk<T>(array: T[], size: number): T[][] {
  if (size <= 0) throw new Error('Chunk size must be greater than 0');
  const result: T[][] = [];
  for (let i = 0; i < array.length; i += size) {
    result.push(array.slice(i, i + size));
  }
  return result;
}
 
/**
 * オブジェクトから指定したキーのみを抽出する。
 * @param obj - 元のオブジェクト
 * @param keys - 抽出するキーの配列
 * @returns 抽出されたオブジェクト
 */
export function pick<T extends Record<string, unknown>, K extends keyof T>(
  obj: T,
  keys: K[],
): Pick<T, K> {
  const result = {} as Pick<T, K>;
  for (const key of keys) {
    if (key in obj) {
      result[key] = obj[key];
    }
  }
  return result;
}

// 演習1: src/index.test.ts
import { describe, it, expect } from 'vitest';
import { capitalize, chunk, pick } from './index';
 
describe('capitalize', () => {
  it('先頭を大文字にする', () => {
    expect(capitalize('hello')).toBe('Hello');
  });
 
  it('空文字列を処理する', () => {
    expect(capitalize('')).toBe('');
  });
 
  it('既に大文字の場合はそのまま', () => {
    expect(capitalize('Hello')).toBe('Hello');
  });
});
 
describe('chunk', () => {
  it('配列をチャンクに分割する', () => {
    expect(chunk([1, 2, 3, 4, 5], 2)).toEqual([[1, 2], [3, 4], [5]]);
  });
 
  it('チャンクサイズが配列長以上の場合', () => {
  });
 
  it('チャンクサイズが0以下でエラー', () => {
    expect(() => chunk([1], 0)).toThrow('Chunk size must be greater than 0');
  });
});
 
describe('pick', () => {
  it('指定したキーのみを抽出する', () => {
    const obj = { a: 1, b: 2, c: 3 };
    expect(pick(obj, ['a', 'c'])).toEqual({ a: 1, c: 3 });
  });
 
  it('存在しないキーは無視する', () => {
    const obj = { a: 1, b: 2 };
    expect(pick(obj, ['a', 'c' as keyof typeof obj])).toEqual({ a: 1 });
  });
});

// 演習2: src/client.ts
import type { ClientOptions } from './types';
import { APIError, TimeoutError } from './errors';
 
export class BaseClient {
  protected readonly baseURL: string;
  protected readonly apiKey: string;
  protected readonly timeout: number;
  protected readonly maxRetries: number;
  private readonly fetchFn: typeof globalThis.fetch;
 
  constructor(options: ClientOptions) {
    this.apiKey = options.apiKey;
    this.baseURL = options.baseURL ?? 'https://api.example.com/v1';
    this.timeout = options.timeout ?? 30_000;
    this.maxRetries = options.maxRetries ?? 3;
    this.fetchFn = options.fetch ?? globalThis.fetch;
  }
 
  protected async request<T>(
    method: string,
    path: string,
    options: {
      body?: unknown;
      params?: Record<string, string>;
      headers?: Record<string, string>;
    } = {},
  ): Promise<T> {
    const url = new URL(path, this.baseURL);
    if (options.params) {
      for (const [key, value] of Object.entries(options.params)) {
        url.searchParams.set(key, value);
      }
    }
 
    let lastError: Error | undefined;
 
    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
      const controller = new AbortController();
      const timeoutId = setTimeout(
        () => controller.abort(),
        this.timeout,
      );
 
      try {
        const response = await this.fetchFn(url.toString(), {
          method,
          headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${this.apiKey}`,
            ...options.headers,
          },
          body: options.body ? JSON.stringify(options.body) : undefined,
          signal: controller.signal,
        });
 
        clearTimeout(timeoutId);
 
        if (!response.ok) {
          const errorBody = await response.json().catch(() => ({}));
          const apiError = new APIError(
            errorBody.message ?? 'Unknown error',
            response.status,
            errorBody.code,
            errorBody.requestId,
          );
 
          // 5xx エラーはリトライ対象
          if (response.status >= 500 && attempt < this.maxRetries) {
            lastError = apiError;
            const delay = 1000 * Math.pow(2, attempt);
            await new Promise(r => setTimeout(r, delay));
            continue;
          }
 
          throw apiError;
        }
 
        return (await response.json()) as T;
      } catch (error) {
        clearTimeout(timeoutId);
 
        if (error instanceof APIError) throw error;
 
        if ((error as Error).name === 'AbortError') {
          throw new TimeoutError(
            `Request timed out after ${this.timeout}ms`,
          );
        }
 
        lastError = error as Error;
        if (attempt < this.maxRetries) {
          const delay = 1000 * Math.pow(2, attempt);
          await new Promise(r => setTimeout(r, delay));
          continue;
        }
      }
    }
 
    throw lastError ?? new Error('Request failed');
  }
}

// 演習2: src/errors.ts
export class APIError extends Error {
  readonly status: number;
  readonly code?: string;
  readonly requestId?: string;
 
  constructor(
    message: string,
    status: number,
    code?: string,
    requestId?: string,
  ) {
    super(message);
    this.name = 'APIError';
    this.status = status;
    this.code = code;
    this.requestId = requestId;
  }
}
 
export class TimeoutError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'TimeoutError';
  }
}
 
export class ValidationError extends Error {
  readonly field: string;
 
  constructor(message: string, field: string) {
    super(message);
    this.name = 'ValidationError';
    this.field = field;
  }
}

<!-- CHANGELOG.md の例 -->
# @example/sdk
 
## 2.0.0
 
### Breaking Changes
 
- `Client` コンストラクタのオプションから `apiUrl` を削除。
  代わりに `baseURL` を使用してください。
- 最小 Node.js バージョンを 18 に引き上げ。
- `users.delete()` の戻り値を `void` から `{ deleted: boolean }` に変更。
 
### Migration Guide
 
  // Before (v1)
  const client = new Client({ apiUrl: 'https://...' });
 
  // After (v2)
  const client = new Client({ baseURL: 'https://...' });
 
## 1.3.0
 
### Features
 
- `users.list()` にフィルタオプションを追加。
- `billing.invoices()` メソッドを新規追加。
- レスポンスに `requestId` フィールドを追加。
 
### Bug Fixes
 
- リトライ時にタイムアウトがリセットされない問題を修正。
- ページネーションの `cursor` が `null` の場合にエラーになる問題を修正。

// Step 1: JSDoc で @deprecated を付与（MINOR リリース）
/**
 * ユーザーを名前で検索する。
 * @deprecated v1.3.0 で非推奨。代わりに `users.list({ filter: { name } })` を使用してください。
 * v2.0.0 で削除予定。
 */
export function findUserByName(name: string): Promise<User> {
  // 実行時の警告（Node.js環境）
  if (typeof process !== 'undefined') {
    process.emitWarning(
      'findUserByName() is deprecated. Use users.list({ filter: { name } }) instead.',
      'DeprecationWarning',
    );
  }
  // 既存の実装をそのまま維持
  return this.users.list({ filter: { name } }).then(res => res.data[0]);
}
 
// Step 2: README と CHANGELOG に非推奨を明記
// Step 3: 1-2 MINOR バージョン後に MAJOR リリースで削除

// renovate.json - Renovate Bot の設定
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:recommended",
    ":semanticCommits",
    ":automergeMinor",
    ":automergeDigest"
  ],
  "labels": ["dependencies"],
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "matchCurrentVersion": "!/^0/",
      "automerge": true
    },
    {
      "matchUpdateTypes": ["major"],
      "automerge": false,
      "labels": ["dependencies", "breaking"]
    },
    {
      "matchPackageNames": ["typescript"],
      "automerge": false,
      "labels": ["dependencies", "typescript"]
    }
  ],
  "schedule": ["before 9am on monday"]
}