@simplysm/excel 14.0.46 → 14.0.48

package/docs/wrapper.md

@@ -0,0 +1,73 @@
+# Wrapper
+
+## `ExcelWrapper`
+
+Zod 스키마 기반 타입 안전한 Excel 읽기/쓰기 래퍼. 스키마에서 타입 정보를 추론하여 타입 안전한 읽기/쓰기를 제공한다.
+
+```typescript
+export class ExcelWrapper<TSchema extends z.ZodObject<z.ZodRawShape>> {
+  constructor(schema: TSchema);
+
+  async read(
+    file: Bytes | Blob,
+    wsNameOrIndex?: string | number,
+    options?: { excludes?: (keyof z.infer<TSchema>)[] },
+  ): Promise<z.infer<TSchema>[]>;
+
+  async write(
+    wsName: string,
+    records: Partial<z.infer<TSchema>>[],
+    options?: { excludes?: (keyof z.infer<TSchema>)[] },
+  ): Promise<ExcelWorkbook>;
+}
+```
+
+### Constructor
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `schema` | `TSchema extends z.ZodObject<z.ZodRawShape>` | Zod 스키마. `.describe()`로 Excel 헤더 이름을 지정한다 |
+
+### Methods
+
+#### `read(file, wsNameOrIndex?, options?)`
+
+Excel 파일을 레코드 배열로 읽는다. 헤더 행의 텍스트를 스키마의 `.describe()` 값과 매칭하여 필드를 연결한다. Zod 스키마로 유효성 검사를 수행하며, 실패 시 에러를 던진다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `file` | `Bytes \| Blob` | Excel 파일 데이터 |
+| `wsNameOrIndex` | `string \| number` | 워크시트 이름 또는 0 기반 인덱스 (기본값: `0`) |
+| `options.excludes` | `(keyof z.infer<TSchema>)[]` | 읽기에서 제외할 필드 키 배열 |
+
+**반환값:** `z.infer<TSchema>[]` - 스키마 타입으로 추론된 레코드 배열
+
+**타입 변환 규칙:**
+
+| 스키마 타입 | 변환 동작 |
+|------------|-----------|
+| `z.string()` | 문자열로 변환 (`String(rawValue)`) |
+| `z.number()` | 숫자로 파싱 (`num.parseFloat`) |
+| `z.boolean()` | `"1"`, `"true"` -> `true`, `"0"`, `"false"` -> `false` |
+| `z.optional()` / `z.nullable()` | 빈 셀을 `undefined`로 반환 |
+| `z.default(value)` | 빈 셀에 기본값 적용 |
+| `DateOnly` / `DateTime` / `Time` | `instanceof`로 직접 전달 |
+
+#### `write(wsName, records, options?)`
+
+레코드 배열을 Excel 워크북으로 변환한다. 반환된 `ExcelWorkbook`의 리소스 관리는 호출자의 책임이다. 내부에서 에러 발생 시 워크북이 자동으로 `close()`된다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `wsName` | `string` | 워크시트 이름 |
+| `records` | `Partial<z.infer<TSchema>>[]` | 레코드 배열 |
+| `options.excludes` | `(keyof z.infer<TSchema>)[]` | 쓰기에서 제외할 필드 키 배열 |
+
+**반환값:** `ExcelWorkbook` - 호출자가 `try-finally` 블록에서 `close()`를 호출하여 리소스를 관리해야 한다
+
+**쓰기 동작:**
+
+- 첫 번째 행에 헤더 자동 생성 (스키마의 `.describe()` 값 사용)
+- 모든 셀에 테두리 스타일 자동 적용
+- 필수 비boolean 필드의 헤더에 노란색 배경(`00FFFF00`) 강조
+- 확대/축소 85%, 첫 번째 행 틀 고정 자동 설정

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/excel",
-  "version": "14.0.46",
+  "version": "14.0.48",
   "description": "심플리즘 패키지 - 엑셀 (neutral)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -14,7 +14,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "docs"
   ],
   "sideEffects": false,
   "devDependencies": {
@@ -23,6 +24,6 @@
   "dependencies": {
     "mime": "^4.1.0",
     "zod": "^4.3.6",
-    "@simplysm/core-common": "14.0.46"
+    "@simplysm/core-common": "14.0.48"
   }
 }

package/src/excel-cell.ts

@@ -231,7 +231,8 @@ export class ExcelCell {
    * @param opts.border 테두리 위치 배열 (예: ["left", "right", "top", "bottom"])
    * @param opts.horizontalAlign 가로 정렬 ("left", "center", "right")
    * @param opts.verticalAlign 세로 정렬 ("top", "center", "bottom")
-   * @param opts.numberFormat 숫자 형식 ("number", "DateOnly", "DateTime", "Time", "string")
+   * @param opts.numberFormat 숫자 형식 프리셋 ("number", "DateOnly", "DateTime", "Time", "string")
+   * @param opts.numberFormatCode 커스텀 Excel formatCode (예: "0.000000"). `numberFormat`과 동시 지정 시 이 필드가 우선한다.
    */
   async setStyle(opts: ExcelStyleOptions): Promise<void> {
     const style: ExcelStyle = {};
@@ -255,7 +256,9 @@ export class ExcelCell {
       style.verticalAlign = opts.verticalAlign;
     }
 
-    if (opts.numberFormat != null) {
+    if (opts.numberFormatCode != null) {
+      style.numFmtCode = opts.numberFormatCode;
+    } else if (opts.numberFormat != null) {
       style.numFmtId = ExcelUtils.convertNumFmtNameToId(opts.numberFormat).toString();
     }
 

package/src/types.ts

@@ -376,6 +376,9 @@ export type ExcelVerticalAlign = "center" | "top" | "bottom";
  *   verticalAlign: "center",
  *   numberFormat: "number",
  * });
+ *
+ * // 임의의 Excel formatCode 지정
+ * await cell.setStyle({ numberFormatCode: "0.000000" });
  * ```
  */
 export interface ExcelStyleOptions {
@@ -387,8 +390,13 @@ export interface ExcelStyleOptions {
   horizontalAlign?: ExcelHorizontalAlign;
   /** 세로 정렬 */
   verticalAlign?: ExcelVerticalAlign;
-  /** 숫자 형식 */
+  /** 숫자 형식 프리셋 */
   numberFormat?: ExcelNumberFormat;
+  /**
+   * 커스텀 Excel formatCode 문자열 (예: "0.000000", "#,##0.00", "0.00%").
+   * `numberFormat`과 동시 지정 시 이 필드가 우선 적용된다.
+   */
+  numberFormatCode?: string;
 }
 
 //#endregion