---
url: /ko/api-reference/workbook.md
---
## 워크북 입출력

워크북의 생성, 열기, 저장 및 시트 이름 조회를 다루는 기본 API입니다.

### `Workbook::new()` / `new Workbook()`

빈 워크북을 생성합니다. 기본적으로 "Sheet1"이라는 시트 하나가 포함됩니다.

**Rust:**

```rust
use sheetkit::Workbook;

let wb = Workbook::new();
```

**TypeScript:**

```typescript
import { Workbook } from "@sheetkit/node";

const wb = new Workbook();
```

### `Workbook::open(path)` / `Workbook.open(path)`

기존 .xlsx 파일을 열어 메모리에 로드합니다.

**Rust:**

```rust
let wb = Workbook::open("report.xlsx")?;
```

**TypeScript:**

```typescript
const wb = await Workbook.open("report.xlsx");
```

> 파일이 존재하지 않거나 유효한 .xlsx 형식이 아니면 오류가 발생합니다.
> Node.js에서 `Workbook.open(path)`는 비동기이며 `Promise<Workbook>`을 반환합니다. 동기 동작이 필요하면 `Workbook.openSync(path)`를 사용합니다.

### `wb.save(path)`

워크북을 .xlsx 파일로 저장합니다.

**Rust:**

```rust
wb.save("output.xlsx")?;
```

**TypeScript:**

```typescript
await wb.save("output.xlsx");
```

> ZIP 압축은 Deflate 방식을 사용합니다.
> Node.js에서 `wb.save(path)`는 비동기이며 `Promise<void>`를 반환합니다. 동기 동작이 필요하면 `wb.saveSync(path)`를 사용합니다.

### `wb.save_with_options(path, limits, options)` / `wb.save(path, limits, options)`

Path 저장은 대상 디렉터리에 `.sheetkit-*` 임시 파일을 쓴 뒤 대상 파일 위로 rename합니다. 저장이 실패하거나 rename 전에 application이 비정상 종료되면 기존 파일은 그대로 유지됩니다. 강제 종료된 경우에는 `.sheetkit-*` 임시 파일이 남을 수 있습니다. 기본값에서는 운영체제에 storage flush를 요청하지 않습니다. 따라서 저장이 성공한 직후 전원이 끊기거나 OS가 비정상 종료되면 대상 파일에 이전 버전이나 새 버전이 남거나, 파일 시스템과 mount option에 따라 비어 있거나 불완전한 파일이 남을 수 있습니다.

전원이 끊겨도 저장 결과가 남아야 하면 `durable: true`를 전달하세요. 이 경우 rename 전에 임시 파일을 storage에 flush하고, Unix에서는 rename 후 상위 디렉터리를 sync합니다. macOS에서는 flush에 `F_FULLFSYNC`를 사용하므로 저장마다 수 밀리초가 추가됩니다. Windows에는 디렉터리 sync가 없으므로 파일만 flush합니다. 디렉터리 sync가 실패하면 새 파일이 이미 대상 위치에 있다는 내용의 오류를 반환합니다. Network file system이나 flush 요청을 무시하는 드라이브에서는 두 보장 모두 약해질 수 있습니다.

**Rust:**

```rust
use sheetkit::{SaveLimits, SaveOptions};

wb.save_with_options("output.xlsx", SaveLimits::default(), SaveOptions { durable: true })?;
```

**TypeScript:**

```typescript
// 동기
wb.saveSync("output.xlsx", undefined, { durable: true });

// 비동기
await wb.save("output.xlsx", undefined, { durable: true });
```

암호화 저장도 같은 옵션을 지원합니다. Rust에서는 `save_with_password_with_options`를, Node.js에서는 `saveWithPasswordSync`와 `saveWithPassword`의 마지막 `options` 인수를 사용하세요.

### `Workbook::open_from_buffer(data)` / `Workbook.openBufferSync(data)`

파일 경로 대신 메모리 내 바이트 버퍼에서 워크북을 엽니다. 업로드된 파일이나 네트워크를 통해 수신한 데이터를 처리할 때 유용합니다.

**Rust:**

```rust
let data: Vec<u8> = std::fs::read("report.xlsx")?;
let wb = Workbook::open_from_buffer(&data)?;
```

**TypeScript:**

```typescript
// 동기
const data: Buffer = fs.readFileSync("report.xlsx");
const wb = Workbook.openBufferSync(data);

// 비동기
const wb2 = await Workbook.openBuffer(data);
```

> Node.js에서 `Workbook.openBuffer(data)`는 비동기이며 `Promise<Workbook>`을 반환합니다. 동기 동작이 필요하면 `Workbook.openBufferSync(data)`를 사용합니다.

### `wb.save_to_buffer()` / `wb.writeBufferSync()`

워크북을 디스크에 쓰지 않고 메모리 내 바이트 버퍼로 직렬화합니다. HTTP 응답으로 파일을 전송하거나 서비스 간 데이터를 전달할 때 유용합니다.

**Rust:**

```rust
let buf: Vec<u8> = wb.save_to_buffer()?;
// buf에 유효한 .xlsx 데이터가 들어 있다
```

**TypeScript:**

```typescript
// 동기
const buf: Buffer = wb.writeBufferSync();

// 비동기
const buf2: Buffer = await wb.writeBuffer();
```

> Node.js에서 `wb.writeBuffer()`는 비동기이며 `Promise<Buffer>`를 반환합니다. 동기 동작이 필요하면 `wb.writeBufferSync()`를 사용합니다.

### `wb.sheet_names()` / `wb.sheetNames`

워크북에 포함된 모든 시트의 이름을 순서대로 반환합니다.

**Rust:**

```rust
let names: Vec<&str> = wb.sheet_names();
// ["Sheet1", "Sheet2"]
```

**TypeScript:**

```typescript
const names: string[] = wb.sheetNames;
// ["Sheet1", "Sheet2"]
```

> TypeScript에서는 getter 프로퍼티로 접근합니다.

### `wb.format()` / `wb.format`

워크북 형식을 반환합니다. 파일을 열 때 패키지의 콘텐츠 타입에서 자동으로 감지됩니다. 이 형식은 저장 시 `xl/workbook.xml`에 사용되는 OOXML 콘텐츠 타입을 결정합니다.

**Rust:**

```rust
use sheetkit::{Workbook, WorkbookFormat};

let wb = Workbook::open("report.xlsm")?;
let fmt: WorkbookFormat = wb.format();
assert_eq!(fmt, WorkbookFormat::Xlsm);
```

**TypeScript:**

```typescript
const wb = await Workbook.open("report.xlsm");
const fmt: string = wb.format; // "xlsm"
```

### `wb.set_format(format)` / `wb.format = ...`

워크북 형식을 명시적으로 설정합니다. 자동 감지된 형식을 덮어쓰며 저장 시 출력되는 콘텐츠 타입을 제어합니다.

**Rust:**

```rust
use sheetkit::{Workbook, WorkbookFormat};

let mut wb = Workbook::new();
wb.set_format(WorkbookFormat::Xlsm);
wb.save("macros.xlsm")?;
```

**TypeScript:**

```typescript
const wb = new Workbook();
wb.format = "xlsm";
await wb.save("macros.xlsm");
```

### WorkbookFormat

| Rust | TypeScript | 확장자 | 설명 |
|---|---|---|---|
| `WorkbookFormat::Xlsx` | `"xlsx"` | `.xlsx` | 표준 스프레드시트 (기본값) |
| `WorkbookFormat::Xlsm` | `"xlsm"` | `.xlsm` | 매크로 사용 스프레드시트 |
| `WorkbookFormat::Xltx` | `"xltx"` | `.xltx` | 템플릿 |
| `WorkbookFormat::Xltm` | `"xltm"` | `.xltm` | 매크로 사용 템플릿 |
| `WorkbookFormat::Xlam` | `"xlam"` | `.xlam` | 매크로 사용 추가 기능 |

### 확장자 기반 저장

저장 시 파일 확장자에서 대상 형식이 자동으로 유추됩니다. 인식되는 확장자(`.xlsx`, `.xlsm`, `.xltx`, `.xltm`, `.xlam`)가 있으면 워크북 형식이 쓰기 전에 업데이트됩니다. 인식되지 않는 확장자는 오류를 반환합니다.

**Rust:**

```rust
let mut wb = Workbook::new();
// ".xlsm" 확장자에서 형식이 유추됩니다
wb.save("output.xlsm")?;
assert_eq!(wb.format(), WorkbookFormat::Xlsm);
```

**TypeScript:**

```typescript
const wb = new Workbook();
await wb.save("output.xlsm"); // 형식이 자동으로 xlsm으로 설정됩니다
```

`save_to_buffer()` / `writeBufferSync()` 사용 시에는 파일 확장자가 없으므로 저장된 형식이 그대로 사용됩니다. Buffer 저장 전에 `set_format()`으로 형식을 명시적으로 설정하세요.

### VBA 보존

매크로 사용 워크북(`.xlsm`, `.xltm`)에는 VBA 프로젝트 blob(`xl/vbaProject.bin`)이 포함됩니다. 이러한 파일을 열고 다시 저장하면 VBA 프로젝트가 투명하게 보존됩니다. 추가 API 호출이 필요하지 않습니다.

```rust
// 매크로 사용 파일을 열고 데이터를 수정한 후 저장하면 VBA 매크로가 보존됩니다
let mut wb = Workbook::open("with_macros.xlsm")?;
wb.set_cell_value("Sheet1", "A1", CellValue::String("Updated".into()))?;
wb.save("with_macros.xlsm")?;
```

```typescript
const wb = await Workbook.open("with_macros.xlsm");
wb.setCellValue("Sheet1", "A1", "Updated");
await wb.save("with_macros.xlsm"); // VBA가 보존됩니다
```

### `OpenOptions`

워크북을 열 때 파싱 방식을 제어하는 옵션입니다. 모든 필드는 선택 사항입니다.

| 필드 | Rust 타입 | TypeScript 타입 | 기본값 | 설명 |
|---|---|---|---|---|
| `read_mode` / `readMode` | `ReadMode` | `'lazy' \| 'eager' \| 'stream'?` | `'lazy'` | open 시 파싱 범위를 제어합니다. |
| `aux_parts` / `auxParts` | `AuxParts` | `'deferred' \| 'eager'?` | `'deferred'` | 보조 파트(comments, charts, images)의 파싱 시점을 제어합니다. |
| `sheet_rows` / `sheetRows` | `Option<u32>` | `number?` | 무제한 | 시트당 읽을 최대 행 수입니다. 초과 행은 무시됩니다. |
| `sheets` | `Option<Vec<String>>` | `string[]?` | 전체 | 이 목록에 포함된 시트만 파싱합니다. 선택되지 않은 시트는 워크북에 존재하지만 데이터가 없습니다. |
| `max_unzip_size` / `maxUnzipSize` | `Option<u64>` | `number?` | 무제한 | ZIP 아카이브의 전체 압축 해제 크기 제한(바이트)입니다. zip bomb을 방지합니다. |
| `max_zip_entries` / `maxZipEntries` | `Option<usize>` | `number?` | 무제한 | ZIP 아카이브의 최대 엔트리 수입니다. zip bomb을 방지합니다. |
| `date_interpretation` / `dateInterpretation` | `DateInterpretation` | `'cellType' \| 'numFmt'?` | `'numFmt'` | 날짜 서식이 적용된 숫자 셀을 어떻게 해석할지 제어합니다. |

#### ReadMode

| 값 | 설명 |
|------|------|
| `'lazy'` | ZIP 인덱스와 메타데이터만 파싱합니다. 시트 XML은 첫 접근 시 파싱됩니다. Node.js 기본값입니다. |
| `'eager'` | open 시 모든 시트와 보조 파트를 파싱합니다. 이전 버전과 동일한 동작입니다. |
| `'stream'` | 현재 Rust 구현에서는 `'lazy'`와 동일한 open 경로로 동작합니다: 시트 XML hydrate 지연과 보조 파트 eager 파싱 생략이 동일하게 적용됩니다. 향후 호환성과 streaming 의도를 위해 이 모드를 유지하고, 필요 시 `openSheetReader()`와 함께 사용하면 됩니다. |

#### AuxParts

| 값 | 설명 |
|------|------|
| `'deferred'` | 보조 파트는 첫 접근 시 로드됩니다. 기본값입니다. |
| `'eager'` | open 시 모든 보조 파트를 파싱합니다. |

#### DateInterpretation

OOXML은 날짜를 `t="n"` 숫자 셀 + 날짜 number format 조합으로 저장하기 때문에, 셀 타입만으로는 값이 날짜인지 알 수 없습니다. 이 모호성을 reader가 어떻게 해석할지 선택합니다. 모든 읽기 경로(`get_cell_value`, `get_rows` / `get_cols`, streaming reader)가 이 옵션을 동일하게 따릅니다.

| 값 | 설명 |
|------|------|
| `'numFmt'` | 기본값입니다. `t="n"` 셀 중 스타일이 built-in 날짜 서식 ID(14-22, 45-47)를 참조하거나 커스텀 서식 코드에 날짜/시간 토큰(`y`, `m`, `d`, `h`, `s`)이 포함된 경우를 날짜 셀로 승격합니다. Microsoft Excel이 실제로 날짜를 저장하는 방식과 일치합니다. |
| `'cellType'` | 스펙 그대로입니다. `t="d"` 셀만 날짜가 되고, `t="n"` 셀은 서식과 무관하게 숫자로 남습니다. raw cell type을 source of truth로 써야 할 때 opt-in 합니다. |

```rust
use sheetkit::{DateInterpretation, OpenOptions, Workbook};

// 스펙 엄격 해석으로 opt-in (기본은 NumFmt).
let opts = OpenOptions::new().date_interpretation(DateInterpretation::CellType);
let wb = Workbook::open_with_options("strict.xlsx", &opts)?;
```

```typescript
// 기본 동작이 이미 Excel이 저장한 날짜 셀을 승격합니다.
const wb = await Workbook.open("excel_report.xlsx");

// 스펙 엄격 해석으로 opt-in.
const strict = await Workbook.open("strict.xlsx", {
  dateInterpretation: "cellType",
});
```

### `Workbook::open_with_options(path, options)` / `Workbook.open(path, options?)`

커스텀 파싱 옵션으로 `.xlsx` 파일을 엽니다. 옵션을 생략하면 `Workbook::open`과 동일하게 동작합니다.

**Rust:**

```rust
use sheetkit::{Workbook, OpenOptions};

// "Sales" 시트의 처음 100행만 읽기
let opts = OpenOptions::new()
    .sheet_rows(100)
    .sheets(vec!["Sales".to_string()]);
let wb = Workbook::open_with_options("report.xlsx", &opts)?;
```

**TypeScript:**

```typescript
// "Sales" 시트의 처음 100행만 읽기
const wb = Workbook.openSync("report.xlsx", {
  sheetRows: 100,
  sheets: ["Sales"],
});

// ZIP 안전 제한 설정
const wb2 = await Workbook.open("untrusted.xlsx", {
  maxUnzipSize: 500_000_000,  // 500 MB
  maxZipEntries: 5000,
});
```

### `Workbook::open_from_buffer_with_options(data, options)` / `Workbook.openBufferSync(data, options?)`

메모리 내 버퍼에서 커스텀 파싱 옵션으로 워크북을 엽니다.

**Rust:**

```rust
let data = std::fs::read("report.xlsx")?;
let opts = OpenOptions::new().sheet_rows(50);
let wb = Workbook::open_from_buffer_with_options(&data, &opts)?;
```

**TypeScript:**

```typescript
const data = fs.readFileSync("report.xlsx");
const wb = Workbook.openBufferSync(data, { sheetRows: 50 });
```

> Node.js에서 옵션 매개변수는 모든 open 메서드에서 선택 사항입니다. 생략하면 기존 동작과 동일합니다.

### `wb.openSheetReader(sheet, opts?)` (TypeScript 전용)

지정한 시트에 대한 순방향 전용 streaming reader를 엽니다. 전체 시트를 메모리에 로드하지 않고 배치 단위로 행을 읽습니다. `readMode: 'stream'`과 함께 사용하는 것이 가장 좋습니다.

```typescript
const wb = await Workbook.open("large.xlsx", { readMode: "stream" });
const reader = await wb.openSheetReader("Sheet1", { batchSize: 500 });

// 비동기 반복자: JsRowData[] 배치를 yield합니다
for await (const batch of reader) {
  for (const row of batch) {
    console.log(row);
  }
}
```

**옵션:**

| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| `batchSize` | `number?` | `1000` | 배치당 행 수입니다. |

**반환값:** `Promise<SheetStreamReader>`

### `wb.open_sheet_reader(sheet)` / `wb.open_sheet_reader_owned(sheet)` (Rust)

Rust에서는 `Workbook`에 대응되는 streaming reader API가 제공됩니다.

```rust
use sheetkit::Workbook;

let wb = Workbook::open("large.xlsx")?;

// Borrowed reader (`wb` 수명에 종속)
let mut reader = wb.open_sheet_reader("Sheet1")?;

// Owned reader (FFI 친화적, `wb` 수명에 비종속)
let mut owned_reader = wb.open_sheet_reader_owned("Sheet1")?;
```

일반 Rust 워크로드에서는 `open_sheet_reader`를 사용하고, 독립적인 reader 객체가 필요한 경우에는 `open_sheet_reader_owned`를 사용하면 됩니다.

### `SheetStreamReader`

워크시트 데이터를 위한 순방향 전용 streaming reader입니다. `Workbook.openSheetReader()`를 통해 생성됩니다.

**메서드:**

| 메서드 | 반환 타입 | 설명 |
|---|---|---|
| `next(batchSize?)` | `Promise<JsRowData[] \| null>` | 다음 배치를 읽습니다. 완료되면 `null`을 반환합니다. |
| `close()` | `Promise<void>` | 리소스를 해제합니다. `for await`에서 자동으로 호출됩니다. |
| `[Symbol.asyncIterator]()` | `AsyncGenerator<JsRowData[]>` | 배치를 yield하는 비동기 반복자입니다. |

### `wb.getRowsBufferV2(sheet)` (TypeScript 전용)

시트의 셀 데이터를 인라인 문자열이 포함된 v2 바이너리 buffer로 직렬화합니다. v1 형식(`getRowsBuffer`)과 달리, v2 형식은 전역 문자열 테이블을 제거하여 점진적인 행 단위 디코딩을 가능하게 합니다.

```typescript
const bufV2 = wb.getRowsBufferV2("Sheet1");
```

**반환값:** `Buffer`

***
