@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/core-node/worker/create-worker.md

@@ -0,0 +1,85 @@
+# createWorker
+
+Worker thread 파일에서 메서드와 이벤트 전송 함수를 등록하는 팩토리 함수. 메인 스레드의 [`Worker.create()`](./worker.md)와 쌍으로 사용한다.
+
+## When to use
+
+- ✅ 워커 파일에서 메인 스레드에 노출할 메서드를 정의할 때
+- ✅ 워커에서 메인 스레드로 타입 안전한 이벤트를 보낼 때
+- ❌ 메인 스레드에서 워커 호출 → [`Worker.create()`](./worker.md) 사용
+
+```typescript
+export function createWorker<
+  TMethods extends Record<string, (...args: any[]) => unknown>,
+  TEvents extends Record<string, unknown> = Record<string, never>,
+>(
+  methods: TMethods,
+): {
+  send<TEventName extends keyof TEvents & string>(event: TEventName, data?: TEvents[TEventName]): void;
+  __methods: TMethods;
+  __events: TEvents;
+}
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `methods` | `TMethods` | 워커가 노출할 메서드 객체. 동기/비동기 모두 지원 |
+
+## Type Parameters
+
+| Param | Constraint | Description |
+|-------|-----------|-------------|
+| `TMethods` | `Record<string, (...args: any[]) => unknown>` | 메서드 정의 타입 |
+| `TEvents` | `Record<string, unknown>` | 이벤트 데이터 타입. 기본값: `Record<string, never>` |
+
+## Returns
+
+반환 객체:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `send` | `<TEventName>(event, data?) => void` | 메인 스레드로 이벤트 전송 |
+| `__methods` | `TMethods` | 등록된 메서드 (타입 추론용) |
+| `__events` | `TEvents` | 이벤트 타입 정보 (타입 추론용) |
+
+## stdout 처리
+
+`createWorker()` 호출 시 `process.stdout.write`를 가로채서 워커의 로그 출력을 메인 스레드 stdout으로 전달한다.
+
+## 실행 조건
+
+`parentPort`가 `null`이면 (= 메인 스레드에서 실행) `SdError`를 throw한다. 반드시 worker thread에서 호출해야 한다.
+
+## Usage
+
+```typescript
+// worker.ts (워커 파일)
+import { createWorker } from "@simplysm/core-node";
+
+// 이벤트가 없는 워커
+export default createWorker({
+  add: (a: number, b: number) => a + b,
+  greet: (name: string) => `Hello, ${name}!`,
+});
+
+// 이벤트가 있는 워커
+interface MyEvents {
+  progress: number;
+  done: { result: number };
+}
+
+const methods = {
+  calc: async (x: number) => {
+    sender.send("progress", 50);
+    await new Promise((r) => setTimeout(r, 100));
+    sender.send("progress", 100);
+    sender.send("done", { result: x * 2 });
+    return x * 2;
+  },
+};
+
+const sender = createWorker<typeof methods, MyEvents>(methods);
+export default sender;
+```

package/claude/references/sd-simplysm-v14/core-node/worker/worker.md

@@ -0,0 +1,160 @@
+# Worker
+
+타입 안전한 Worker thread 프록시를 생성하는 팩토리 객체. `Worker.create()`로 워커 파일의 메서드를 메인 스레드에서 직접 호출할 수 있다.
+
+## When to use
+
+- ✅ CPU 집약적 작업을 별도 스레드로 분리하면서 타입 안전한 메서드 호출이 필요할 때
+- ✅ 워커에서 메인 스레드로 이벤트(진행률 등)를 보내야 할 때
+- ❌ 외부 프로세스 실행 → [`cpx.spawn`](../utils/cpx.md) 사용
+
+```typescript
+export const Worker: {
+  create<TModule extends WorkerModule>(
+    filePath: string,
+    opt?: Omit<WorkerRawOptions, "stdout" | "stderr">,
+  ): WorkerProxy<TModule>
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `create` | static method | `<TModule extends WorkerModule>(filePath: string, opt?: ...) => WorkerProxy<TModule>` | 타입 안전한 Worker Proxy 생성 |
+
+## `create` Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `filePath` | `string` | 워커 파일 경로. `file://` URL 또는 절대 경로 |
+| `opt` | `Omit<WorkerRawOptions, "stdout" \| "stderr">` (optional) | Node.js Worker thread 옵션. `stdout`/`stderr`는 내부에서 자동 처리 |
+
+## 환경별 동작
+
+- **개발 환경(`.ts` 파일)**: `lib/worker-dev-proxy.js`를 통해 tsx로 TypeScript 워커 파일을 실행
+- **프로덕션(`.js` 파일)**: Worker를 직접 생성
+
+## Related Types
+
+### `WorkerProxy<TModule>`
+
+`Worker.create()`가 반환하는 프록시 타입. 워커 메서드를 Promise 버전으로 제공하고, `on()`/`off()`/`terminate()`를 추가로 지원한다.
+
+```typescript
+export type WorkerProxy<TModule extends WorkerModule> = PromisifyMethods<
+  TModule["default"]["__methods"]
+> & {
+  on<TEventName extends keyof TModule["default"]["__events"] & string>(
+    event: TEventName,
+    listener: (data: TModule["default"]["__events"][TEventName]) => void,
+  ): void;
+  off<TEventName extends keyof TModule["default"]["__events"] & string>(
+    event: TEventName,
+    listener: (data: TModule["default"]["__events"][TEventName]) => void,
+  ): void;
+  terminate(): Promise<void>;
+}
+```
+
+| Member | Description |
+|--------|-------------|
+| 워커 메서드들 | 동기 메서드도 항상 `Promise<Awaited<R>>`로 변환됨 |
+| `on(event, listener)` | 워커 이벤트 리스너 등록 |
+| `off(event, listener)` | 워커 이벤트 리스너 해제 |
+| `terminate()` | 워커 종료. 대기 중인 모든 요청을 즉시 거부 |
+
+### `WorkerModule`
+
+```typescript
+export interface WorkerModule {
+  default: {
+    __methods: Record<string, (...args: any[]) => unknown>;
+    __events: Record<string, unknown>;
+  };
+}
+```
+
+`createWorker()`가 반환하는 워커 모듈의 타입 구조. `Worker.create<typeof import("./worker")>()`에서 타입 추론에 사용된다.
+
+### `PromisifyMethods<TMethods>`
+
+```typescript
+export type PromisifyMethods<TMethods> = {
+  [K in keyof TMethods]: TMethods[K] extends (...args: infer P) => infer R
+    ? (...args: P) => Promise<Awaited<R>>
+    : never;
+};
+```
+
+메서드 반환값을 `Promise`로 감싸는 매핑 타입. 워커 메서드는 postMessage 기반으로 동작하여 항상 비동기다.
+
+### `WorkerRequest`
+
+```typescript
+export interface WorkerRequest {
+  id: string;
+  method: string;
+  params: unknown[];
+}
+```
+
+내부 워커 요청 메시지. `Worker.create()`와 `createWorker()` 사이의 통신 프로토콜.
+
+### `WorkerResponse`
+
+```typescript
+export type WorkerResponse =
+  | { request: WorkerRequest; type: "return"; body?: unknown }
+  | { request: WorkerRequest; type: "error"; body: Error }
+  | { type: "event"; event: string; body?: unknown }
+  | { type: "log"; body: string };
+```
+
+내부 워커 응답 메시지.
+
+| Variant | `type` | Description |
+|---------|--------|-------------|
+| 반환 | `"return"` | 메서드 정상 반환값 |
+| 오류 | `"error"` | 메서드 실행 오류 |
+| 이벤트 | `"event"` | 워커에서 메인 스레드로 보내는 이벤트 |
+| 로그 | `"log"` | 워커 stdout 내용 (메인 스레드 stdout으로 전달) |
+
+## Usage
+
+```typescript
+// main.ts
+import { Worker } from "@simplysm/core-node";
+import type * as MyWorkerModule from "./worker";
+
+const worker = Worker.create<typeof MyWorkerModule>("./worker.ts");
+
+// 타입 안전한 메서드 호출
+const result = await worker.add(10, 20); // 30
+
+// 이벤트 리스너
+worker.on("progress", (value) => {
+  // value 타입이 자동 추론됨
+});
+
+// 종료
+await worker.terminate();
+```
+
+## 🚫 Anti-patterns
+
+### terminate() 누락
+
+```typescript
+// ❌ terminate하지 않으면 워커 스레드가 계속 실행됨
+const worker = Worker.create<typeof MyWorkerModule>("./worker.ts");
+const result = await worker.add(10, 20);
+// 프로세스 행
+
+// ✅ 작업 완료 후 반드시 terminate
+const worker = Worker.create<typeof MyWorkerModule>("./worker.ts");
+const result = await worker.add(10, 20);
+await worker.terminate();
+```
+
+**근거**: 워커 스레드는 명시적으로 종료하지 않으면 프로세스가 끝나지 않는다.

package/claude/references/sd-simplysm-v14/excel/README.md

@@ -0,0 +1,66 @@
+# @simplysm/excel
+
+> Excel 워크북(xlsx) 읽기/쓰기 라이브러리. DOM 의존성이 없어 Node.js와 브라우저 양쪽에서 동작하는 neutral 패키지다.
+> Lazy Loading 아키텍처로 대용량 파일도 메모리 효율적으로 처리한다.
+> 의존성: `@simplysm/core-common`, `mime`, `zod`
+
+## Installation
+
+```bash
+npm install @simplysm/excel
+```
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| Excel 파일 생성/읽기/저장 | [ExcelWorkbook](./core-classes/excel-workbook.md) |
+| 셀 값/수식/스타일 설정 | [ExcelCell](./core-classes/excel-cell.md) |
+| 행/열 복사, 데이터 테이블, 이미지 삽입 | [ExcelWorksheet](./core-classes/excel-worksheet.md) |
+| Zod 스키마 기반 타입 안전한 읽기/쓰기 | [ExcelWrapper](./wrapper/excel-wrapper.md) |
+| 셀 주소 변환, 날짜↔숫자 변환 | [ExcelUtils](./utilities/excel-utils.md) |
+
+## API Overview
+
+### Core Classes
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`ExcelWorkbook`](./core-classes/excel-workbook.md) | class | xlsx 파일을 열거나 새로 만들 때. 워크시트 조회/생성, 바이트 내보내기의 진입점 |
+| [`ExcelWorksheet`](./core-classes/excel-worksheet.md) | class | 시트 내 셀/행/열 접근, 행 복사, 데이터 테이블 읽기/쓰기, 이미지 삽입이 필요할 때 |
+| [`ExcelCell`](./core-classes/excel-cell.md) | class | 개별 셀의 값/수식/스타일/병합을 조작할 때 |
+| [`ExcelRow`](./core-classes/excel-row.md) | class | 특정 행의 셀들을 일괄 접근할 때 |
+| [`ExcelCol`](./core-classes/excel-col.md) | class | 특정 열의 셀들을 일괄 접근하거나 열 너비를 설정할 때 |
+
+### Wrapper
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`ExcelWrapper`](./wrapper/excel-wrapper.md) | class | Zod 스키마로 타입 안전한 Excel 읽기/쓰기가 필요할 때. 헤더 자동 생성, 유효성 검사 포함 |
+
+### Utilities
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`ExcelUtils`](./utilities/excel-utils.md) | class | 셀 주소 문자열↔좌표 변환, Excel 날짜 숫자↔JS 타임스탬프 변환이 필요할 때 |
+
+### Types
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`ExcelValueType`](./types/excel-value-type.md) | type | 셀 값의 타입을 지정할 때. `ExcelCellType`, `ExcelNumberFormat` 포함 |
+| [`ExcelAddressPoint`](./types/excel-address-point.md) | interface | 셀 좌표를 전달할 때. `ExcelAddressRangePoint` 포함 |
+| [`ExcelStyleOptions`](./types/excel-style-options.md) | interface | 셀 스타일(배경색, 테두리, 정렬, 숫자 형식)을 설정할 때 |
+| [`ExcelXml`](./types/excel-xml.md) | interface | 내부 XML 처리 클래스의 공통 인터페이스 (직접 사용하지 않음) |
+| [`ExcelXmlContentTypeData`](./types/excel-xml-content-type-data.md) | interface | 내부 `[Content_Types].xml` 데이터 구조 (직접 사용하지 않음) |
+| [`ExcelXmlRelationshipData`](./types/excel-xml-relationship-data.md) | interface | 내부 `*.rels` 데이터 구조 (직접 사용하지 않음) |
+| [`ExcelXmlWorkbookData`](./types/excel-xml-workbook-data.md) | interface | 내부 `workbook.xml` 데이터 구조 (직접 사용하지 않음) |
+| [`ExcelXmlWorksheetData`](./types/excel-xml-worksheet-data.md) | interface | 내부 `worksheet*.xml` 데이터 구조 (직접 사용하지 않음) |
+| [`ExcelXmlDrawingData`](./types/excel-xml-drawing-data.md) | interface | 내부 `drawing*.xml` 데이터 구조 (직접 사용하지 않음) |
+| [`ExcelXmlSharedStringData`](./types/excel-xml-shared-string-data.md) | interface | 내부 `sharedStrings.xml` 데이터 구조 (직접 사용하지 않음) |
+| [`ExcelXmlStyleData`](./types/excel-xml-style-data.md) | interface | 내부 `styles.xml` 데이터 구조 (직접 사용하지 않음) |
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- xls(구형 바이너리 포맷) 파일 처리가 필요한 경우 -- xlsx만 지원한다
+- CSV 파일만 처리하면 되는 경우 -- 별도 CSV 파서가 더 적합하다

package/claude/references/sd-simplysm-v14/excel/core-classes/excel-cell.md

@@ -0,0 +1,79 @@
+# ExcelCell
+
+Excel 셀을 나타내는 클래스. 값 읽기/쓰기, 수식, 스타일, 셀 병합 기능을 제공한다.
+
+## When to use
+
+- ✅ 개별 셀의 값, 수식, 스타일, 병합을 조작할 때
+- ✅ `ws.cell(r, c)`로 얻은 인스턴스를 통해 사용
+- ❌ 대량 데이터를 한번에 쓸 때는 [`ExcelWorksheet.setDataMatrix()`](./excel-worksheet.md) 또는 [`ExcelWorksheet.setRecords()`](./excel-worksheet.md) -- 내부에서 동기 최적화를 수행한다
+
+모든 메서드가 `async`인 이유는 셀 타입에 따라 필요한 XML만 선택적으로 로드하는 Lazy Loading 아키텍처 때문이다. 문자열 셀은 `sharedStrings.xml`을 로드하고, 숫자 셀은 로드하지 않는다.
+
+```typescript
+export class ExcelCell {
+  readonly addr: ExcelAddressPoint;
+
+  constructor(zipCache: ZipCache, targetFileName: string, r: number, c: number);
+
+  // Value
+  async setValue(val: ExcelValueType): Promise<void>;
+  async getValue(): Promise<ExcelValueType>;
+  async setFormula(val: string | undefined): Promise<void>;
+  async getFormula(): Promise<string | undefined>;
+
+  // Merge
+  async merge(r: number, c: number): Promise<void>;
+
+  // Style
+  async getStyleId(): Promise<string | undefined>;
+  async setStyleId(styleId: string | undefined): Promise<void>;
+  async setStyle(opts: ExcelStyleOptions): Promise<void>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `addr` | property | `ExcelAddressPoint` | 셀 주소 (0 기반 행/열 인덱스, read-only) |
+| `setValue` | method | `(val: ExcelValueType) => Promise<void>` | 셀 값 설정. `undefined` 전달 시 셀 삭제. `DateOnly`/`DateTime`/`Time`은 Excel 날짜 숫자로 변환하고 numFmt 설정 |
+| `getValue` | method | `() => Promise<ExcelValueType>` | 셀 값 반환. 비어있는 셀은 `undefined` 반환. 셀 타입과 스타일에 따라 적절한 JS 타입으로 변환 |
+| `setFormula` | method | `(val: string \| undefined) => Promise<void>` | 셀 수식 설정. `undefined` 전달 시 수식 제거 |
+| `getFormula` | method | `() => Promise<string \| undefined>` | 셀 수식 반환. 수식 없으면 `undefined` 반환 |
+| `merge` | method | `(r: number, c: number) => Promise<void>` | 현재 셀에서 지정된 끝 좌표까지 셀 병합 |
+| `getStyleId` | method | `() => Promise<string \| undefined>` | 셀의 스타일 ID 반환. 스타일 없으면 `undefined` 반환 |
+| `setStyleId` | method | `(styleId: string \| undefined) => Promise<void>` | 셀의 스타일 ID 직접 설정 |
+| `setStyle` | method | `(opts: ExcelStyleOptions) => Promise<void>` | 셀 스타일 설정. 기존 스타일이 있으면 클론 후 병합 |
+
+## Usage
+
+```typescript
+// 값 설정/읽기
+await ws.cell(0, 0).setValue("텍스트");
+await ws.cell(0, 1).setValue(42);
+await ws.cell(0, 2).setValue(new DateOnly(2024, 6, 15));
+await ws.cell(0, 3).setValue(true);
+await ws.cell(0, 4).setValue(undefined); // 셀 삭제
+
+const val = await ws.cell(0, 0).getValue(); // "텍스트"
+
+// 수식
+await ws.cell(1, 0).setFormula("SUM(A1:A10)");
+const formula = await ws.cell(1, 0).getFormula(); // "SUM(A1:A10)"
+
+// 셀 병합 (A1:C3 병합)
+await ws.cell(0, 0).merge(2, 2);
+
+// 스타일
+await ws.cell(0, 0).setStyle({
+  background: "00FFFF00",                    // 노란색 배경
+  border: ["left", "right", "top", "bottom"],
+  horizontalAlign: "center",
+  verticalAlign: "center",
+  numberFormat: "number",
+});
+
+// 커스텀 formatCode
+await ws.cell(0, 0).setStyle({ numberFormatCode: "0.000000" });
+```

package/claude/references/sd-simplysm-v14/excel/core-classes/excel-col.md

@@ -0,0 +1,36 @@
+# ExcelCol
+
+Excel 워크시트의 열을 나타내는 클래스. 셀 접근 및 열 너비 설정 기능을 제공한다.
+
+```typescript
+export class ExcelCol {
+  constructor(zipCache: ZipCache, targetFileName: string, c: number, cellFactory: (r: number) => ExcelCell);
+
+  cell(r: number): ExcelCell;
+  async getCells(): Promise<ExcelCell[]>;
+  async setWidth(size: number): Promise<void>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `cell` | method | `(r: number) => ExcelCell` | 지정된 행 인덱스의 셀 반환 (0 기반) |
+| `getCells` | method | `() => Promise<ExcelCell[]>` | 열의 모든 셀 반환. 데이터 범위 내의 모든 행에 대한 셀이 포함된다 |
+| `setWidth` | method | `(size: number) => Promise<void>` | 열 너비 설정 |
+
+## Usage
+
+```typescript
+const col = ws.col(1); // B열
+
+// 특정 셀 접근
+const cell = col.cell(0); // B1 셀
+
+// 열의 모든 셀
+const cells = await col.getCells();
+
+// 열 너비 설정
+await ws.col(0).setWidth(20);
+```

package/claude/references/sd-simplysm-v14/excel/core-classes/excel-row.md

@@ -0,0 +1,34 @@
+# ExcelRow
+
+Excel 워크시트의 행을 나타내는 클래스. 셀 접근 기능을 제공한다.
+
+```typescript
+export class ExcelRow {
+  constructor(zipCache: ZipCache, targetFileName: string, r: number, cellFactory: (c: number) => ExcelCell);
+
+  cell(c: number): ExcelCell;
+  async getCells(): Promise<ExcelCell[]>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `cell` | method | `(c: number) => ExcelCell` | 지정된 열 인덱스의 셀 반환 (0 기반) |
+| `getCells` | method | `() => Promise<ExcelCell[]>` | 행의 모든 셀 반환. 데이터 범위 내의 모든 열에 대한 셀이 포함된다 |
+
+## Usage
+
+```typescript
+const row = ws.row(0);
+
+// 특정 셀 접근
+const cell = row.cell(2); // C열 셀
+
+// 행의 모든 셀
+const cells = await row.getCells();
+for (const cell of cells) {
+  const val = await cell.getValue();
+}
+```

package/claude/references/sd-simplysm-v14/excel/core-classes/excel-workbook.md

@@ -0,0 +1,93 @@
+# ExcelWorkbook
+
+Excel 워크북 처리 클래스. 내부적으로 ZIP 리소스를 관리하므로 사용 후 반드시 `try-finally` 블록에서 `close()`를 호출해야 한다.
+
+대용량 Excel 파일의 메모리 효율을 위해 Lazy Loading 아키텍처를 채택한다. ZIP 내부의 XML은 접근 시점에만 읽고 파싱한다.
+
+## When to use
+
+- ✅ xlsx 파일을 새로 생성하거나 기존 파일을 읽고 수정할 때
+- ✅ 워크시트를 추가/조회하고 결과를 바이트 배열이나 Blob으로 내보낼 때
+- ❌ Zod 스키마 기반 타입 안전한 읽기/쓰기가 필요하면 [`ExcelWrapper`](../wrapper/excel-wrapper.md) -- 내부적으로 `ExcelWorkbook`을 사용하므로 직접 관리할 필요 없음
+
+## Signature
+
+```typescript
+export class ExcelWorkbook {
+  readonly zipCache: ZipCache;
+
+  constructor(arg?: Blob | Bytes);
+
+  async getWorksheetNames(): Promise<string[]>;
+  async addWorksheet(name: string): Promise<ExcelWorksheet>;
+  async getWorksheet(nameOrIndex: string | number): Promise<ExcelWorksheet>;
+  async toBytes(): Promise<Bytes>;
+  async toBlob(): Promise<Blob>;
+  async close(): Promise<void>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `zipCache` | property | `ZipCache` | ZIP 캐시 인스턴스 (read-only) |
+| `constructor` | method | `(arg?: Blob \| Bytes) => ExcelWorkbook` | `arg` 생략 시 새 워크북 생성, 전달 시 기존 파일 읽기 |
+| `getWorksheetNames` | method | `() => Promise<string[]>` | 워크북의 모든 워크시트 이름 반환 |
+| `addWorksheet` | method | `(name: string) => Promise<ExcelWorksheet>` | 새 워크시트 생성하여 반환 |
+| `getWorksheet` | method | `(nameOrIndex: string \| number) => Promise<ExcelWorksheet>` | 이름 또는 0 기반 인덱스로 워크시트 조회. 찾을 수 없으면 에러 발생 |
+| `toBytes` | method | `() => Promise<Bytes>` | 워크북을 `Bytes`(Uint8Array)로 내보내기 |
+| `toBlob` | method | `() => Promise<Blob>` | 워크북을 `Blob`으로 내보내기. MIME 타입: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
+| `close` | method | `() => Promise<void>` | ZIP 리더와 내부 캐시 정리. 이미 닫힌 워크북에 대해 호출해도 안전하다 (no-op). 닫힌 후 메서드 호출 시 에러 발생 |
+
+## 🚫 Anti-patterns
+
+### close() 누락
+
+```typescript
+// ❌ close() 없이 사용 -- ZIP 리소스 누수
+const wb = new ExcelWorkbook(bytes);
+const ws = await wb.getWorksheet(0);
+
+// ✅ try-finally로 반드시 close()
+const wb = new ExcelWorkbook(bytes);
+try {
+  const ws = await wb.getWorksheet(0);
+} finally {
+  await wb.close();
+}
+```
+
+**근거**: `ExcelWorkbook`은 내부적으로 ZIP 아카이브를 보유하며, `close()` 없이 방치하면 메모리 누수가 발생한다.
+
+## Usage
+
+### 최소 예제
+
+```typescript
+import { ExcelWorkbook } from "@simplysm/excel";
+
+// 신규 생성
+const wb = new ExcelWorkbook();
+try {
+  const ws = await wb.addWorksheet("Sheet1");
+  await ws.cell(0, 0).setValue("값");
+  const bytes = await wb.toBytes();
+} finally {
+  await wb.close();
+}
+
+### 전형 예제
+
+```typescript
+// 기존 파일 읽기 (Uint8Array 또는 Blob)
+const wb2 = new ExcelWorkbook(bytes);
+try {
+  const ws = await wb2.getWorksheet(0);       // 0 기반 인덱스
+  const ws2 = await wb2.getWorksheet("Sheet1"); // 시트명으로도 조회 가능
+  const names = await wb2.getWorksheetNames();
+} finally {
+  await wb2.close();
+}
+```
+```