@simplysm/excel 13.0.99 → 14.0.1

package/docs/types.md

@@ -1,297 +0,0 @@
-# Types
-
-All type exports from the excel package.
-
-```typescript
-import type {
-  ExcelValueType,
-  ExcelNumberFormat,
-  ExcelCellType,
-  ExcelAddressPoint,
-  ExcelAddressRangePoint,
-  ExcelStyleOptions,
-  ExcelBorderPosition,
-  ExcelHorizontalAlign,
-  ExcelVerticalAlign,
-  ExcelXml,
-  // XML data types (internal)
-  ExcelXmlContentTypeData,
-  ExcelXmlRelationshipData,
-  ExcelXmlWorkbookData,
-  ExcelXmlWorksheetData,
-  ExcelRowData,
-  ExcelCellData,
-  ExcelXmlDrawingData,
-  ExcelXmlSharedStringData,
-  ExcelXmlSharedStringDataSi,
-  ExcelXmlSharedStringDataText,
-  ExcelXmlStyleData,
-  ExcelXmlStyleDataXf,
-  ExcelXmlStyleDataFill,
-  ExcelXmlStyleDataBorder,
-} from "@simplysm/excel";
-```
-
-## Value Types
-
-### `ExcelValueType`
-
-Union of supported cell value types.
-
-```typescript
-type ExcelValueType = number | string | DateOnly | DateTime | Time | boolean | undefined;
-```
-
-### `ExcelNumberFormat`
-
-Number format name.
-
-```typescript
-type ExcelNumberFormat = "number" | "string" | "DateOnly" | "DateTime" | "Time";
-```
-
-### `ExcelCellType`
-
-Excel cell type identifier.
-
-```typescript
-type ExcelCellType = "s" | "b" | "str" | "n" | "inlineStr" | "e";
-```
-
-- `s` -- shared string (SharedString)
-- `b` -- boolean
-- `str` -- formula result string
-- `n` -- number
-- `inlineStr` -- inline string (rich text)
-- `e` -- error
-
-## Address Types
-
-### `ExcelAddressPoint`
-
-Cell coordinate (0-based).
-
-```typescript
-interface ExcelAddressPoint {
-  r: number;
-  c: number;
-}
-```
-
-### `ExcelAddressRangePoint`
-
-Range of cell coordinates (start and end).
-
-```typescript
-interface ExcelAddressRangePoint {
-  s: ExcelAddressPoint;
-  e: ExcelAddressPoint;
-}
-```
-
-## Style Types
-
-### `ExcelBorderPosition`
-
-```typescript
-type ExcelBorderPosition = "left" | "right" | "top" | "bottom";
-```
-
-### `ExcelHorizontalAlign`
-
-```typescript
-type ExcelHorizontalAlign = "center" | "left" | "right";
-```
-
-### `ExcelVerticalAlign`
-
-```typescript
-type ExcelVerticalAlign = "center" | "top" | "bottom";
-```
-
-### `ExcelStyleOptions`
-
-Cell style options.
-
-```typescript
-interface ExcelStyleOptions {
-  /** Background color (ARGB format, e.g. "00FF0000") */
-  background?: string;
-  /** Border positions */
-  border?: ExcelBorderPosition[];
-  /** Horizontal alignment */
-  horizontalAlign?: ExcelHorizontalAlign;
-  /** Vertical alignment */
-  verticalAlign?: ExcelVerticalAlign;
-  /** Number format */
-  numberFormat?: ExcelNumberFormat;
-}
-```
-
-**Example:**
-```typescript
-await cell.setStyle({
-  background: "00FF0000",
-  border: ["left", "right", "top", "bottom"],
-  horizontalAlign: "center",
-  verticalAlign: "center",
-  numberFormat: "number",
-});
-```
-
-## Excel XML Interface
-
-### `ExcelXml`
-
-```typescript
-interface ExcelXml {
-  readonly data: unknown;
-  cleanup(): void;
-}
-```
-
-## XML Data Types
-
-These types represent the internal XML structure of `.xlsx` files. They are used internally by the library but exported for advanced use cases.
-
-### `ExcelXmlContentTypeData`
-
-Content type definitions (`[Content_Types].xml`).
-
-```typescript
-interface ExcelXmlContentTypeData {
-  Types: {
-    $: { xmlns: string };
-    Default: { $: { Extension: string; ContentType: string } }[];
-    Override: { $: { PartName: string; ContentType: string } }[];
-  };
-}
-```
-
-### `ExcelXmlRelationshipData`
-
-Relationship definitions (`.rels` files).
-
-```typescript
-interface ExcelXmlRelationshipData {
-  Relationships: {
-    $: { xmlns: string };
-    Relationship?: ExcelRelationshipData[];
-  };
-}
-```
-
-### `ExcelXmlWorkbookData`
-
-Workbook XML data.
-
-```typescript
-interface ExcelXmlWorkbookData {
-  workbook: {
-    $: { "xmlns": string; "xmlns:r"?: string };
-    bookViews?: [{ workbookView: [{}] }];
-    sheets?: [{ sheet: { $: { "name": string; "sheetId": string; "r:id": string } }[] }];
-  };
-}
-```
-
-### `ExcelXmlWorksheetData`
-
-Worksheet XML data. Contains sheet data, dimensions, views, columns, merge cells, and drawing references.
-
-### `ExcelRowData`
-
-```typescript
-interface ExcelRowData {
-  $: { r: string }; // row address (1-based)
-  c?: ExcelCellData[];
-}
-```
-
-### `ExcelCellData`
-
-```typescript
-interface ExcelCellData {
-  $: {
-    r: string;          // cell address (e.g. "A1")
-    s?: string;         // styleId
-    t?: ExcelCellType;  // type
-  };
-  v?: [string];          // value
-  f?: [string];          // formula
-  is?: { t?: (string | { _?: string })[] }[];  // inline string
-}
-```
-
-### `ExcelXmlDrawingData`
-
-Drawing XML data (embedded images).
-
-### `ExcelXmlSharedStringData`
-
-Shared strings table.
-
-```typescript
-interface ExcelXmlSharedStringData {
-  sst: {
-    $: { xmlns: string };
-    si?: ExcelXmlSharedStringDataSi[];
-  };
-}
-```
-
-### `ExcelXmlSharedStringDataSi`
-
-```typescript
-type ExcelXmlSharedStringDataSi =
-  | { t: ExcelXmlSharedStringDataText }
-  | { r: { t: ExcelXmlSharedStringDataText }[] };
-```
-
-### `ExcelXmlSharedStringDataText`
-
-```typescript
-type ExcelXmlSharedStringDataText = [
-  string | { $: { space?: "preserve" }; _?: string },
-];
-```
-
-### `ExcelXmlStyleData`
-
-Style definitions (styles.xml). Contains number formats, fonts, fills, borders, and cell formats.
-
-### `ExcelXmlStyleDataXf`
-
-Cell format definition.
-
-```typescript
-interface ExcelXmlStyleDataXf {
-  $: {
-    numFmtId?: string;
-    fontId?: string;
-    fillId?: string;
-    borderId?: string;
-    xfId?: string;
-    applyNumberFormat?: string;
-    applyFont?: string;
-    applyAlignment?: string;
-    applyFill?: string;
-    applyBorder?: string;
-  };
-  alignment?: [{ $: { horizontal?: "center" | "left" | "right"; vertical?: "center" | "top" | "bottom" } }];
-}
-```
-
-### `ExcelXmlStyleDataFill`
-
-Fill style definition.
-
-```typescript
-interface ExcelXmlStyleDataFill {
-  patternFill: [{ $: { patternType: "none" | "solid" | "gray125" }; fgColor?: [{ $: { rgb: string } }] }];
-}
-```
-
-### `ExcelXmlStyleDataBorder`
-
-Border style definition. Each side (`top`, `left`, `right`, `bottom`) has `style` (`"thin"` | `"medium"`) and optional `color`.

package/docs/utilities.md

@@ -1,128 +0,0 @@
-# Utilities
-
-## `ExcelUtils`
-
-Collection of Excel utility functions. Provides cell address conversion, date/number conversion, and number format processing.
-
-```typescript
-import { ExcelUtils } from "@simplysm/excel";
-```
-
-### Address Conversion
-
-#### `stringifyAddr`
-
-Convert cell coordinates to "A1" format string.
-
-```typescript
-static stringifyAddr(point: ExcelAddressPoint): string;
-```
-
-#### `stringifyRowAddr`
-
-Convert row index (0-based) to row address string (e.g. `0` -> `"1"`).
-
-```typescript
-static stringifyRowAddr(r: number): string;
-```
-
-#### `stringifyColAddr`
-
-Convert column index (0-based) to column address string (e.g. `0` -> `"A"`, `26` -> `"AA"`).
-
-```typescript
-static stringifyColAddr(c: number): string;
-```
-
-**Throws:** `Error` if column index is outside range `0-16383`.
-
-#### `parseRowAddr`
-
-Extract row index from cell address (e.g. `"A3"` -> `2`).
-
-```typescript
-static parseRowAddr(addr: string): number;
-```
-
-#### `parseColAddr`
-
-Extract column index from cell address (e.g. `"B3"` -> `1`).
-
-```typescript
-static parseColAddr(addr: string): number;
-```
-
-#### `parseCellAddr`
-
-Convert cell address to coordinates (e.g. `"B3"` -> `{r: 2, c: 1}`).
-
-```typescript
-static parseCellAddr(addr: string): ExcelAddressPoint;
-```
-
-#### `parseRangeAddr`
-
-Convert range address to coordinates (e.g. `"A1:C3"` -> `{s: {r:0,c:0}, e: {r:2,c:2}}`).
-
-```typescript
-static parseRangeAddr(rangeAddr: string): ExcelAddressRangePoint;
-```
-
-#### `stringifyRangeAddr`
-
-Convert range coordinates to address string.
-
-```typescript
-static stringifyRangeAddr(point: ExcelAddressRangePoint): string;
-```
-
-### Date/Number Conversion
-
-#### `convertTimeTickToNumber`
-
-Convert JavaScript timestamp (ms) to Excel date number. Excel counts 1900-01-01 as 1 (1899-12-30 is date 0).
-
-```typescript
-static convertTimeTickToNumber(tick: number): number;
-```
-
-#### `convertNumberToTimeTick`
-
-Convert Excel date number to JavaScript timestamp (ms).
-
-```typescript
-static convertNumberToTimeTick(value: number): number;
-```
-
-### Number Format
-
-#### `convertNumFmtCodeToName`
-
-Convert number format code to format name.
-
-```typescript
-static convertNumFmtCodeToName(numFmtCode: string): ExcelNumberFormat;
-```
-
-#### `convertNumFmtIdToName`
-
-Convert number format ID to format name.
-
-```typescript
-static convertNumFmtIdToName(numFmtId: number): ExcelNumberFormat;
-```
-
-Built-in format ID ranges:
-- `0-13, 37-40, 48`: number/general/currency/percent formats
-- `14-17, 27-31, 34-36, 50-58`: date formats (including localized)
-- `22`: date+time format
-- `18-21, 32-33, 45-47`: time formats
-- `49`: text format
-
-#### `convertNumFmtNameToId`
-
-Convert number format name to format ID.
-
-```typescript
-static convertNumFmtNameToId(numFmtName: ExcelNumberFormat): number;
-```

package/docs/wrapper.md

@@ -1,100 +0,0 @@
-# ExcelWrapper
-
-Zod schema-based Excel wrapper. Infers type information from schema to provide type-safe read/write.
-
-```typescript
-import { ExcelWrapper } from "@simplysm/excel";
-```
-
-## Class: `ExcelWrapper<TSchema>`
-
-### Constructor
-
-```typescript
-constructor(schema: TSchema)
-```
-
-- `schema` -- Zod object schema. Defines the record structure. Use `.describe()` on fields to specify Excel header names.
-
-### `read`
-
-Read Excel file into record array.
-
-```typescript
-async read(
-  file: Bytes | Blob,
-  wsNameOrIndex?: string | number,
-  options?: { excludes?: (keyof z.infer<TSchema>)[] },
-): Promise<z.infer<TSchema>[]>;
-```
-
-**Parameters:**
-- `file` -- Excel file data (Uint8Array or Blob)
-- `wsNameOrIndex` -- Worksheet name or index (default: `0`)
-- `options.excludes` -- Field keys to exclude from reading
-
-Values are automatically converted based on the Zod schema type:
-- `ZodString` -- converts to string
-- `ZodNumber` -- converts to number
-- `ZodBoolean` -- converts to boolean (`"1"`, `"true"` -> `true`)
-- `DateOnly`, `DateTime`, `Time` -- preserved as-is from Excel
-
-Each row is validated against the Zod schema. Rows where all values are empty are skipped.
-
-### `write`
-
-Record array to Excel workbook.
-
-The caller is responsible for managing the returned workbook's resources. Use `await using` or call `close()` after use.
-
-```typescript
-async write(
-  wsName: string,
-  records: Partial<z.infer<TSchema>>[],
-  options?: { excludes?: (keyof z.infer<TSchema>)[] },
-): Promise<ExcelWorkbook>;
-```
-
-**Parameters:**
-- `wsName` -- Worksheet name
-- `records` -- Record array to write
-- `options.excludes` -- Field keys to exclude from writing
-
-**Behavior:**
-- Headers are written in the first row using `.describe()` names (or field keys if no description)
-- Data rows follow from row index 1
-- All cells get border styling (`left`, `right`, `top`, `bottom`)
-- Required field headers (non-optional, non-nullable, non-default, non-boolean) are highlighted in yellow (`00FFFF00`)
-- Zoom is set to 85%
-- First row is frozen
-
-## Example
-
-```typescript
-import { z } from "zod";
-import { ExcelWrapper } from "@simplysm/excel";
-
-const schema = z.object({
-  name: z.string().describe("Name"),
-  age: z.number().describe("Age"),
-  email: z.string().optional().describe("Email"),
-  active: z.boolean().default(false).describe("Active"),
-});
-
-const wrapper = new ExcelWrapper(schema);
-
-// Read Excel file
-const records = await wrapper.read(fileBytes);
-// records: { name: string; age: number; email?: string; active: boolean }[]
-
-// Write to Excel
-await using wb = await wrapper.write("Users", [
-  { name: "Alice", age: 30, email: "alice@example.com" },
-  { name: "Bob", age: 25 },
-]);
-const bytes = await wb.toBytes();
-
-// Exclude specific fields
-const records2 = await wrapper.read(fileBytes, 0, { excludes: ["email"] });
-await using wb2 = await wrapper.write("Users", records2, { excludes: ["email"] });
-```