워크북 입출력

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

Workbook::new() / new Workbook()

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

Rust:

use sheetkit::Workbook;

let wb = Workbook::new();

TypeScript:

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

const wb = new Workbook();

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

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

Rust:

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

TypeScript:

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

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

wb.save(path)

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

Rust:

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

TypeScript:

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

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

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

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

Rust:

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

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:

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

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:

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

TypeScript:

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

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

wb.format() / wb.format

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

Rust:

use sheetkit::{Workbook, WorkbookFormat};

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

TypeScript:

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

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

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

Rust:

use sheetkit::{Workbook, WorkbookFormat};

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

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:

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

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 호출이 필요하지 않습니다.

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

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 합니다.

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)?;

// 기본 동작이 이미 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:

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:

// "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:

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:

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'과 함께 사용하는 것이 가장 좋습니다.

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가 제공됩니다.

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 형식은 전역 문자열 테이블을 제거하여 점진적인 행 단위 디코딩을 가능하게 합니다.

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

반환값: Buffer

---